# 装备成本估算系统 API 文档

这个 API 文档提供了完整的接口说明，包括：

- 每个端点的详细描述
- 请求和响应的具体示例
- 清晰的参数格式要求
- 统一的错误处理说明
- 重要的注意事项

文档使用 Markdown 格式编写，请使用支持 Markdown 的工具查看。

## 基本信息

- 基础URL: `http://localhost:5001/api`
- 版本: 1.0.0
- 响应格式: JSON

## API 端点列表

### 1. 获取 API 信息

获取 API 版本信息和可用端点列表。

- **URL**: `/`
- **方法**: `GET`
- **响应示例**:
json
{
"name": "装备成本估算系统 API",
"version": "1.0.0",
"endpoints": {
"predict": {
"url": "/api/predict",
"method": "POST",
"description": "成本预测"
},
"analyze-features": {
"url": "/api/analyze-features",
"method": "POST",
"description": "特征分析"
},
"train": {
"url": "/api/train",
"method": "POST",
"description": "模型训练"
},
"evaluate": {
"url": "/api/evaluate",
"method": "POST",
"description": "模型评估"
}
}
}

### 2. 单模型预测

使用当前激活的最优模型进行成本预测。

- **URL**: `/predict`
- **方法**: `POST`
- **请求体示例** (巡飞弹):

```json
{
    "type": "巡飞弹",
    "length_m": 1.3,
    "width_m": 0.23,
    "height_m": 0.23,
    "weight_kg": 12.5,
    "max_range_km": 40,
    "max_speed_ms": 50,
    "cruise_speed_kmh": 100,
    "flight_time_min": 60,
    "folded_length_mm": 1300,
    "folded_width_mm": 230,
    "folded_height_mm": 230,
    "warhead_type": "破片杀伤战斗部",
    "launch_mode": "凭自身动力起飞"
}
```

- **响应示例**:

```json
{
    "predicted_cost": 150000.0,
    "model_info": {
        "type": "xgboost",
        "name": "巡飞弹_20241111_model",
        "r2_score": 0.95,
        "mae": 5000.0,
        "rmse": 7500.0
    },
    "confidence_interval": {
        "lower": 135000.0,
        "upper": 165000.0
    }
}
```

### 3. PLS 模型预测

使用 PLS 回归模型进行预测。

- **URL**: `/pls/predict`
- **方法**: `POST`
- **请求体**: 与单模型预测相同
- **响应示例**:

```json
{
    "predicted_cost": 148000.0,
    "confidence_interval": {
        "lower": 133000.0,
        "upper": 163000.0
    }
}
```

### 4. 多模型预测

使用所有激活的模型进行预测并返回综合结果。

- **URL**: `/predict/all`
- **方法**: `POST`
- **请求体**: 与单模型预测相同
- **响应示例**:

```json
{
    "individual_predictions": {
        "xgboost": {
            "predicted_cost": 150000.0,
            "model_info": {
                "name": "巡飞弹_xgboost_model",
                "type": "xgboost",
                "r2_score": 0.95,
                "mae": 5000.0,
                "rmse": 7500.0
            },
            "confidence_interval": {
                "lower": 135000.0,
                "upper": 165000.0
            }
        },
        "pls": {
            "predicted_cost": 148000.0,
            "model_info": {
                "name": "巡飞弹_pls_model",
                "type": "pls",
                "r2_score": 0.92,
                "mae": 5500.0,
                "rmse": 8000.0
            },
            "confidence_interval": {
                "lower": 133000.0,
                "upper": 163000.0
            }
        }
    },
    "ensemble_prediction": {
        "predicted_cost": 149000.0,
        "standard_deviation": 1414.21,
        "confidence_interval": {
            "lower": 146228.15,
            "upper": 151771.85
        }
    }
}
```

### 5. 特征分析

分析数据集中特征的重要性和相关性。

- **URL**: `/analyze-features`
- **方法**: `POST`
- **请求体示例**:

```json
{
    "dataset_id": 1,
    "equipment_type": "巡飞弹"
}
```

- **响应示例**:

```json
{
    "important_features": [
        {
            "name": "最大射程(km)",
            "importance": 0.35
        },
        {
            "name": "重量(kg)",
            "importance": 0.25
        }
    ],
    "correlation_analysis": {
        "features": ["最大射程(km)", "重量(kg)"],
        "matrix": [[1.0, 0.8], [0.8, 1.0]]
    }
}
```

### 6. 模型训练

训练新的模型。

- **URL**: `/train`
- **方法**: `POST`
- **请求体示例**:

```json
{
    "type": "巡飞弹",
    "train_dataset_id": 1,
    "validation_dataset_id": 2,
    "models": ["xgboost", "lightgbm", "rf"]
}
```

- **响应示例**:

```json
{
    "metrics": {
        "xgboost": {
            "train": {
                "r2": 0.95,
                "mae": 5000.0,
                "rmse": 7500.0
            },
            "validation": {
                "r2": 0.92,
                "mae": 5500.0,
                "rmse": 8000.0
            }
        }
    },
    "best_model": {
        "type": "xgboost",
        "r2": 0.92,
        "mae": 5500.0,
        "rmse": 8000.0
    }
}
```

### 7. 数据集管理

#### 7.1 获取数据集列表

- **URL**: `/datasets`
- **方法**: `GET`
- **响应示例**:

```json
[
    {
        "id": 1,
        "name": "训练数据集",
        "description": "用于训练的数据集",
        "equipment_type": "巡飞弹",
        "equipment_count": 10,
        "equipment_names": ["设备1", "设备2"],
        "purpose": "训练",
        "created_at": "2024-11-11T10:00:00"
    }
]
```

#### 7.2 获取数据集详情

- **URL**: `/datasets/{id}`
- **方法**: `GET`
- **响应示例**:

```json
{
    "id": 1,
    "name": "训练数据集",
    "description": "用于训练的数据集",
    "equipment_type": "巡飞弹",
    "purpose": "训练",
    "created_at": "2024-11-11T10:00:00",
    "equipment": [
        {
            "id": 1,
            "name": "设备1",
            "type": "巡飞弹",
            "manufacturer": "制造商1",
            "actual_cost": 150000
        }
    ],
    "statistics": {
        "equipment_count": 10,
        "total_cost": 1500000,
        "average_cost": 150000
    }
}
```

#### 7.3 创建数据集

- **URL**: `/datasets`
- **方法**: `POST`
- **请求体示例**:

```json
{
    "name": "测试数据集",
    "description": "用于测试的数据集",
    "equipment_type": "巡飞弹",
    "purpose": "训练",
    "equipment_ids": [1, 2, 3]
}
```

- **响应示例**:

```json
{
    "id": 2,
    "message": "数据集创建成功"
}
```

#### 7.4 更新数据集

- **URL**: `/datasets/{id}`
- **方法**: `PUT`
- **请求体示例**:

```json
{
    "name": "更新后的数据集名称",
    "description": "更新后的描述",
    "equipment_type": "巡飞弹",
    "purpose": "验证",
    "equipment_ids": [1, 2, 3, 4]
}
```

- **响应示例**:

```json
{
    "success": true,
    "message": "数据集更新成功"
}
```

#### 7.5 删除数据集

- **URL**: `/datasets/{id}`
- **方法**: `DELETE`
- **描述**: 删除指定的数据集及其关联关系
- **响应示例**:

```json
{
    "success": true,
    "message": "数据集删除成功"
}
```

注意事项：

1. 数据集删除后不会删除关联的装备数据
2. 不能删除正在被模型使用的数据集
3. 更新数据集时会重新计算统计信息
4. 数据集的装备类型一旦创建后不能更改

### 8. 模型管理

#### 8.1 获取模型列表

- **URL**: `/models`
- **方法**: `GET`
- **响应示例**:

```json
[
    {
        "id": 1,
        "model_name": "巡飞弹_xgboost_model",
        "model_type": "xgboost",
        "equipment_type": "巡飞弹",
        "r2_score": 0.95,
        "mae": 5000.0,
        "rmse": 7500.0,
        "is_active": true,
        "training_date": "2024-11-11T10:00:00"
    }
]
```

#### 8.2 获取最新模型

- **URL**: `/models/{equipment_type}/latest`
- **方法**: `GET`
- **响应示例**: 与模型列表的单个模型格式相同

#### 8.3 获取模型详情

- **URL**: `/models/{id}`
- **方法**: `GET`
- **响应示例**:

```json
{
    "id": 1,
    "model_name": "巡飞弹_xgboost_model",
    "model_type": "xgboost",
    "equipment_type": "巡飞弹",
    "r2_score": 0.95,
    "mae": 5000.0,
    "rmse": 7500.0,
    "is_active": true,
    "training_date": "2024-11-11T10:00:00",
    "feature_importance": {
        "max_range_km": 0.35,
        "weight_kg": 0.25,
        "length_m": 0.20
    },
    "training_data_size": 100,
    "created_by": "system"
}
```

#### 8.4 激活模型

- **URL**: `/models/{id}/activate`
- **方法**: `POST`
- **描述**: 激活指定模型，同时会将同类型的其他模型设置为非激活状态
- **响应示例**:

```json
{
    "success": true,
    "message": "模型已激活"
}
```

#### 8.5 删除模型

- **URL**: `/models/{id}`
- **方法**: `DELETE`
- **描述**: 删除指定模型，包括模型文件和数据库记录
- **响应示例**:

```json
{
    "success": true,
    "message": "模型已删除"
}
```

注意事项：

1. 删除模型时会同时删除相关的文件和数据库记录
2. 不能删除当前正在使用（已激活）的模型
3. 激活模型时会自动取消同类型其他模型的激活状态
4. 模型详情包含了更多的训练相关信息，如特征重要性等

### 9. 数据管理

#### 9.1 获取装备数据列表

- **URL**: `/data`
- **方法**: `GET`
- **响应示例**:

```json
{
    "rocket_artillery": [
        {
            "id": 1,
            "name": "BM-21",
            "type": "火箭炮",
            "manufacturer": "俄罗斯",
            "length_m": 7.35,
            "width_m": 2.4,
            "height_m": 3.1,
            "weight_kg": 13700,
            "max_range_km": 20.4,
            "actual_cost": 800000
        }
    ],
    "loitering_munition": [
        {
            "id": 8,
            "name": "Hero-120",
            "type": "巡飞弹",
            "manufacturer": "以色列",
            "length_m": 1.3,
            "width_m": 0.23,
            "height_m": 0.23,
            "weight_kg": 12.5,
            "max_range_km": 40,
            "actual_cost": 150000
        }
    ]
}
```

#### 9.2 获取装备详情

- **URL**: `/data/details/{id}`
- **方法**: `GET`
- **响应示例**:

```json
{
    "id": 8,
    "name": "Hero-120",
    "type": "巡飞弹",
    "manufacturer": "以色列",
    "common_params": {
        "length_m": 1.3,
        "width_m": 0.23,
        "height_m": 0.23,
        "weight_kg": 12.5,
        "max_range_km": 40
    },
    "specific_params": {
        "wingspan_m": 2.1,
        "warhead_weight_kg": 3.5,
        "max_speed_ms": 50,
        "cruise_speed_kmh": 100,
        "flight_time_min": 60,
        "warhead_type": "破片杀伤战斗部",
        "launch_mode": "箱式发射",
        "power_system": "电动机",
        "guidance_system": "GPS/INS"
    },
    "cost_data": {
        "actual_cost": 150000,
        "prediction_date": "2024-11-11T10:00:00",
        "predicted_cost": 148000
    },
    "custom_params": [
        {
            "id": 1,
            "param_name": "续航时间",
            "param_value": "2小时",
            "param_unit": "小时",
            "description": "最大续航时间"
        }
    ]
}
```

#### 9.3 更新装备数据

- **URL**: `/data/{id}`
- **方法**: `PUT`
- **请求体示例**:

```json
{
    "name": "Hero-120",
    "manufacturer": "以色列",
    "length_m": 1.3,
    "width_m": 0.23,
    "height_m": 0.23,
    "weight_kg": 12.5,
    "max_range_km": 40,
    "wingspan_m": 2.1,
    "warhead_weight_kg": 3.5,
    "max_speed_ms": 50,
    "cruise_speed_kmh": 100,
    "flight_time_min": 60,
    "actual_cost": 150000,
    "custom_params": [
        {
            "id": 1,
            "param_value": "2.5小时"
        }
    ]
}
```

- **响应示例**:

```json
{
    "success": true,
    "message": "装备数据更新成功"
}
```

#### 9.4 删除装备数据

- **URL**: `/data/{id}`
- **方法**: `DELETE`
- **响应示例**:

```json
{
    "success": true,
    "message": "装备数据删除成功"
}
```

#### 9.5 下载数据模板

- **URL**: `/data/template`
- **方法**: `GET`
- **描述**: 下载Excel格式的数据导入模板
- **响应**: Excel文件下载

#### 9.6 导入数据

- **URL**: `/data/import`
- **方法**: `POST`
- **请求体**:
  - Content-Type: multipart/form-data
  - 参数名: file
  - 文件类型: .xlsx 或 .xls
- **响应示例**:

```json
{
    "success": true,
    "message": "数据导入成功",
    "imported_count": {
        "rocket_artillery": 3,
        "loitering_munition": 5
    }
}
```

注意事项：

1. 导入数据时必须使用系统提供的模板
2. 更新装备数据时会同时更新关联的参数表
3. 删除装备数据会同时删除相关的参数和成本数据
4. 导入的Excel文件大小不应超过10MB
5. 所有数值字段必须符合指定的单位和范围要求
6. 特殊参数的值必须包含单位信息

## 错误响应

所有接口在发生错误时都会返回以下格式的响应：

```json
{
    "error": "错误描述信息"
}
```

## 注意事项

1. 所有数值参数必须大于0
2. 所有单位必须按照参数名称中指定的单位提供
3. 预测结果中的成本单位为元
4. 置信区间表示预测结果的95%置信水平范围
5. 所有请求和响应的编码均为 UTF-8