666 lines
13 KiB
Markdown
666 lines
13 KiB
Markdown
# 药店销售预测系统 API 详细参考文档
|
||
|
||
## 概述
|
||
|
||
本文档详细描述了药店销售预测系统中所有API端点的完整规范，包括请求格式、响应格式、参数说明和示例。此文档旨在防止意外修改破坏API设计，确保API的一致性和稳定性。
|
||
|
||
**API基础信息：**
|
||
- 基础URL：`http://localhost:5000`
|
||
- 协议：HTTP/HTTPS
|
||
- 格式：JSON
|
||
- 认证：暂无（内部系统）
|
||
- API文档：`/swagger/`
|
||
|
||
## API端点分类
|
||
|
||
### 1. 系统导航API
|
||
|
||
#### 1.1 根路由
|
||
```http
|
||
GET /
|
||
```
|
||
**功能：** 重定向到UI界面
|
||
**响应：** 302重定向到 `/ui/`
|
||
|
||
#### 1.2 Swagger文档
|
||
```http
|
||
GET /swagger
|
||
```
|
||
**功能：** 重定向到Swagger UI文档页面
|
||
**响应：** 302重定向到 `/swagger/`
|
||
|
||
---
|
||
|
||
### 2. 数据管理API
|
||
|
||
#### 2.1 获取所有产品列表
|
||
```http
|
||
GET /api/products
|
||
```
|
||
**功能：** 返回系统中所有产品的ID和名称
|
||
|
||
**响应示例：**
|
||
```json
|
||
{
|
||
"status": "success",
|
||
"data": [
|
||
{
|
||
"product_id": "P001",
|
||
"product_name": "感冒灵颗粒"
|
||
},
|
||
{
|
||
"product_id": "P002",
|
||
"product_name": "布洛芬片"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
**错误响应：**
|
||
```json
|
||
{
|
||
"status": "error",
|
||
"message": "错误详细信息"
|
||
}
|
||
```
|
||
|
||
#### 2.2 获取单个产品详情
|
||
```http
|
||
GET /api/products/{product_id}
|
||
```
|
||
**功能：** 返回指定产品ID的详细信息
|
||
|
||
**路径参数：**
|
||
- `product_id` (string, required): 产品ID，例如P001
|
||
|
||
**响应示例：**
|
||
```json
|
||
{
|
||
"status": "success",
|
||
"data": {
|
||
"product_id": "P001",
|
||
"product_name": "感冒灵颗粒",
|
||
"data_points": 365,
|
||
"date_range": {
|
||
"start": "2023-01-01",
|
||
"end": "2023-12-31"
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**错误响应：**
|
||
- 404: 产品不存在
|
||
- 500: 服务器内部错误
|
||
|
||
#### 2.3 获取产品销售数据
|
||
```http
|
||
GET /api/products/{product_id}/sales
|
||
```
|
||
**功能：** 返回指定产品在特定日期范围内的销售数据
|
||
|
||
**路径参数：**
|
||
- `product_id` (string, required): 产品ID
|
||
|
||
**查询参数：**
|
||
- `start_date` (string, optional): 开始日期，格式YYYY-MM-DD
|
||
- `end_date` (string, optional): 结束日期，格式YYYY-MM-DD
|
||
|
||
**响应示例：**
|
||
```json
|
||
{
|
||
"status": "success",
|
||
"data": [
|
||
{
|
||
"date": "2023-01-01",
|
||
"product_id": "P001",
|
||
"product_name": "感冒灵颗粒",
|
||
"sales": 125,
|
||
"price": 15.8
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
#### 2.4 上传销售数据
|
||
```http
|
||
POST /api/data/upload
|
||
```
|
||
**功能：** 上传新的销售数据文件(Excel格式)
|
||
|
||
**请求类型：** multipart/form-data
|
||
|
||
**参数：**
|
||
- `file` (file, required): Excel文件(.xlsx)，包含销售数据
|
||
|
||
**必要字段：**
|
||
- date: 日期
|
||
- product_id: 产品ID
|
||
- product_name: 产品名称
|
||
- sales: 销售量
|
||
- price: 价格
|
||
|
||
**响应示例：**
|
||
```json
|
||
{
|
||
"status": "success",
|
||
"message": "数据上传成功",
|
||
"data": {
|
||
"products": 10,
|
||
"rows": 3650
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 3. 模型训练API
|
||
|
||
#### 3.1 获取所有训练任务列表
|
||
```http
|
||
GET /api/training
|
||
```
|
||
**功能：** 返回所有正在进行、已完成或失败的训练任务
|
||
|
||
**响应示例：**
|
||
```json
|
||
{
|
||
"status": "success",
|
||
"data": [
|
||
{
|
||
"task_id": "uuid-string",
|
||
"product_id": "P001",
|
||
"model_type": "mlstm",
|
||
"status": "completed",
|
||
"start_time": "2024-01-01T10:00:00",
|
||
"metrics": {
|
||
"RMSE": 0.045,
|
||
"MAE": 0.032,
|
||
"R2": 0.89,
|
||
"MAPE": 0.078
|
||
},
|
||
"error": null,
|
||
"model_path": "/path/to/model.pth"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
#### 3.2 启动模型训练任务
|
||
```http
|
||
POST /api/training
|
||
```
|
||
**功能：** 为指定产品启动一个新的模型训练任务
|
||
|
||
**请求体：**
|
||
```json
|
||
{
|
||
"product_id": "P001",
|
||
"model_type": "mlstm",
|
||
"epochs": 50
|
||
}
|
||
```
|
||
|
||
**参数说明：**
|
||
- `product_id` (string, required): 产品ID，例如P001
|
||
- `model_type` (string, required): 模型类型，可选值：mlstm, transformer, kan, optimized_kan, tcn
|
||
- `epochs` (integer, optional): 训练轮次，默认50
|
||
|
||
**响应示例：**
|
||
```json
|
||
{
|
||
"message": "模型训练已开始",
|
||
"task_id": "uuid-string"
|
||
}
|
||
```
|
||
|
||
#### 3.3 查询训练任务状态
|
||
```http
|
||
GET /api/training/{task_id}
|
||
```
|
||
**功能：** 获取特定训练任务的当前状态和详情
|
||
|
||
**路径参数：**
|
||
- `task_id` (string, required): 训练任务ID
|
||
|
||
**响应示例：**
|
||
```json
|
||
{
|
||
"status": "success",
|
||
"data": {
|
||
"product_id": "P001",
|
||
"model_type": "mlstm",
|
||
"parameters": {
|
||
"epochs": 50
|
||
},
|
||
"status": "completed",
|
||
"created_at": "2024-01-01T10:00:00",
|
||
"model_path": "/path/to/model.pth",
|
||
"metrics": {
|
||
"RMSE": 0.045,
|
||
"MAE": 0.032,
|
||
"R2": 0.89,
|
||
"MAPE": 0.078
|
||
},
|
||
"model_details_url": "/api/models/mlstm_P001"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 4. 模型预测API
|
||
|
||
#### 4.1 使用模型进行预测
|
||
```http
|
||
POST /api/prediction
|
||
```
|
||
**功能：** 使用指定模型预测未来销售数据
|
||
|
||
**请求体：**
|
||
```json
|
||
{
|
||
"product_id": "P001",
|
||
"model_type": "mlstm",
|
||
"future_days": 7,
|
||
"include_visualization": true,
|
||
"start_date": "2024-01-01"
|
||
}
|
||
```
|
||
|
||
**参数说明：**
|
||
- `product_id` (string, required): 产品ID
|
||
- `model_type` (string, required): 模型类型，可选值：mlstm, transformer, kan, optimized_kan, tcn
|
||
- `version` (string, optional): 模型版本
|
||
- `future_days` (integer, optional): 预测天数，默认7
|
||
- `include_visualization` (boolean, optional): 是否包含可视化，默认false
|
||
- `start_date` (string, optional): 预测起始日期，格式YYYY-MM-DD
|
||
|
||
**响应示例：**
|
||
```json
|
||
{
|
||
"status": "success",
|
||
"data": {
|
||
"product_id": "P001",
|
||
"product_name": "感冒灵颗粒",
|
||
"model_type": "mlstm",
|
||
"predictions": [
|
||
{
|
||
"date": "2024-01-08",
|
||
"predicted_sales": 125.5,
|
||
"confidence_interval": [120.2, 130.8]
|
||
}
|
||
],
|
||
"visualization": "data:image/png;base64,..."
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 4.2 比较不同模型预测结果
|
||
```http
|
||
POST /api/prediction/compare
|
||
```
|
||
**功能：** 比较不同模型对同一产品的预测结果
|
||
|
||
**请求体：**
|
||
```json
|
||
{
|
||
"product_id": "P001",
|
||
"model_types": ["mlstm", "transformer", "kan"],
|
||
"versions": ["v1", "v1", "v1"],
|
||
"include_visualization": true
|
||
}
|
||
```
|
||
|
||
**参数说明：**
|
||
- `product_id` (string, required): 产品ID
|
||
- `model_types` (array, required): 模型类型列表
|
||
- `versions` (array, optional): 模型版本列表
|
||
- `include_visualization` (boolean, optional): 是否包含可视化
|
||
|
||
**响应示例：**
|
||
```json
|
||
{
|
||
"status": "success",
|
||
"data": {
|
||
"product_id": "P001",
|
||
"product_name": "感冒灵颗粒",
|
||
"model_types": ["mlstm", "transformer", "kan"],
|
||
"comparison": [
|
||
{
|
||
"model_type": "mlstm",
|
||
"predictions": [...],
|
||
"metrics": {...}
|
||
}
|
||
],
|
||
"visualization": "data:image/png;base64,..."
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 4.3 分析预测结果
|
||
```http
|
||
POST /api/prediction/analyze
|
||
```
|
||
**功能：** 对预测结果进行深度分析
|
||
|
||
**请求体：**
|
||
```json
|
||
{
|
||
"prediction_data": {...},
|
||
"analysis_type": "trend"
|
||
}
|
||
```
|
||
|
||
#### 4.4 获取预测历史记录
|
||
```http
|
||
GET /api/prediction/history
|
||
```
|
||
**功能：** 获取预测历史记录列表
|
||
|
||
**查询参数：**
|
||
- `product_id` (string, optional): 按产品ID筛选
|
||
- `model_type` (string, optional): 按模型类型筛选
|
||
- `limit` (integer, optional): 限制返回数量
|
||
- `offset` (integer, optional): 分页偏移量
|
||
|
||
**响应示例：**
|
||
```json
|
||
{
|
||
"status": "success",
|
||
"data": [
|
||
{
|
||
"id": "prediction-uuid",
|
||
"product_id": "P001",
|
||
"product_name": "感冒灵颗粒",
|
||
"model_type": "mlstm",
|
||
"created_at": "2024-01-01T10:00:00",
|
||
"future_days": 7,
|
||
"file_path": "/path/to/prediction.json"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
#### 4.5 获取特定预测详情
|
||
```http
|
||
GET /api/prediction/history/{prediction_id}
|
||
```
|
||
**功能：** 获取特定预测的详细信息
|
||
|
||
**路径参数：**
|
||
- `prediction_id` (string, required): 预测记录ID
|
||
|
||
#### 4.6 删除预测记录
|
||
```http
|
||
DELETE /api/prediction/history/{prediction_id}
|
||
```
|
||
**功能：** 删除特定的预测记录
|
||
|
||
**路径参数：**
|
||
- `prediction_id` (string, required): 预测记录ID
|
||
|
||
---
|
||
|
||
### 5. 模型管理API
|
||
|
||
#### 5.1 获取模型列表
|
||
```http
|
||
GET /api/models
|
||
```
|
||
**功能：** 获取系统中的模型列表，可按产品ID和模型类型筛选
|
||
|
||
**查询参数：**
|
||
- `product_id` (string, optional): 按产品ID筛选
|
||
- `model_type` (string, optional): 按模型类型筛选
|
||
|
||
**响应示例：**
|
||
```json
|
||
{
|
||
"status": "success",
|
||
"data": [
|
||
{
|
||
"model_id": "mlstm_P001",
|
||
"product_id": "P001",
|
||
"product_name": "感冒灵颗粒",
|
||
"model_type": "mlstm",
|
||
"created_at": "2024-01-01T10:00:00",
|
||
"metrics": {
|
||
"RMSE": 0.045,
|
||
"MAE": 0.032,
|
||
"R2": 0.89
|
||
}
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
#### 5.2 获取模型详情
|
||
```http
|
||
GET /api/models/{model_id}
|
||
```
|
||
**功能：** 获取特定模型的详细信息
|
||
|
||
**路径参数：**
|
||
- `model_id` (string, required): 模型ID，格式为{product_id}_{model_type}_v{version}
|
||
|
||
**响应示例：**
|
||
```json
|
||
{
|
||
"status": "success",
|
||
"data": {
|
||
"product_id": "P001",
|
||
"model_type": "mlstm",
|
||
"version": "v1",
|
||
"created_at": "2024-01-01T10:00:00",
|
||
"file_path": "/path/to/model.pth",
|
||
"file_size": "2.5MB",
|
||
"features": ["sales", "price", "date"],
|
||
"look_back": 30,
|
||
"T": 7,
|
||
"metrics": {
|
||
"RMSE": 0.045,
|
||
"MAE": 0.032,
|
||
"R2": 0.89,
|
||
"MAPE": 0.078
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 5.3 删除模型
|
||
```http
|
||
DELETE /api/models/{model_id}
|
||
```
|
||
**功能：** 删除特定模型
|
||
|
||
**路径参数：**
|
||
- `model_id` (string, required): 模型ID
|
||
|
||
**响应示例：**
|
||
```json
|
||
{
|
||
"status": "success",
|
||
"message": "模型删除成功"
|
||
}
|
||
```
|
||
|
||
#### 5.4 导出模型
|
||
```http
|
||
GET /api/models/{model_id}/export
|
||
```
|
||
**功能：** 导出特定模型文件
|
||
|
||
**路径参数：**
|
||
- `model_id` (string, required): 模型ID
|
||
|
||
**响应：** 模型文件下载 (application/octet-stream)
|
||
|
||
#### 5.5 获取模型详情（兼容格式）
|
||
```http
|
||
GET /api/models/{model_type}/{product_id}/details
|
||
```
|
||
**功能：** 获取特定模型的详细信息（使用模型类型和产品ID）
|
||
|
||
**路径参数：**
|
||
- `model_type` (string, required): 模型类型，例如mlstm, kan, transformer, tcn, optimized_kan
|
||
- `product_id` (string, required): 产品ID
|
||
|
||
#### 5.6 分析模型性能指标
|
||
```http
|
||
POST /api/models/analyze-metrics
|
||
```
|
||
**功能：** 根据模型的评估指标进行性能分析
|
||
|
||
**请求体：**
|
||
```json
|
||
{
|
||
"RMSE": 0.045,
|
||
"MAE": 0.032,
|
||
"R2": 0.89,
|
||
"MAPE": 0.078
|
||
}
|
||
```
|
||
|
||
**响应示例：**
|
||
```json
|
||
{
|
||
"status": "success",
|
||
"data": {
|
||
"overall_score": 0.85,
|
||
"performance_level": "excellent",
|
||
"recommendations": [
|
||
"模型表现优秀，可以用于生产环境",
|
||
"R2值较高，模型拟合效果良好"
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 5.7 获取系统支持的模型类型
|
||
```http
|
||
GET /api/model_types
|
||
```
|
||
**功能：** 返回系统中支持的所有模型类型及其描述
|
||
|
||
**响应示例：**
|
||
```json
|
||
{
|
||
"status": "success",
|
||
"data": [
|
||
{
|
||
"id": "mlstm",
|
||
"name": "mLSTM",
|
||
"description": "矩阵长短期记忆网络，适合处理多变量时序数据",
|
||
"tag_type": "primary"
|
||
},
|
||
{
|
||
"id": "transformer",
|
||
"name": "Transformer",
|
||
"description": "基于注意力机制的序列模型，适合捕捉长期依赖关系",
|
||
"tag_type": "success"
|
||
},
|
||
{
|
||
"id": "kan",
|
||
"name": "KAN",
|
||
"description": "Kolmogorov-Arnold网络，能够逼近任意连续函数",
|
||
"tag_type": "warning"
|
||
},
|
||
{
|
||
"id": "optimized_kan",
|
||
"name": "优化版KAN",
|
||
"description": "经过优化的KAN模型，提供更高的预测精度和训练效率",
|
||
"tag_type": "info"
|
||
},
|
||
{
|
||
"id": "tcn",
|
||
"name": "TCN",
|
||
"description": "时间卷积网络，适合处理长序列和平行计算",
|
||
"tag_type": "danger"
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### 6. 静态资源API
|
||
|
||
#### 6.1 获取图表文件
|
||
```http
|
||
GET /api/plots/{filename}
|
||
```
|
||
**功能：** 提供图表文件访问服务
|
||
|
||
**路径参数：**
|
||
- `filename` (string, required): 文件名
|
||
|
||
**响应：** 图片文件
|
||
|
||
---
|
||
|
||
## 通用响应格式
|
||
|
||
### 成功响应
|
||
```json
|
||
{
|
||
"status": "success",
|
||
"data": { ... }
|
||
}
|
||
```
|
||
|
||
### 错误响应
|
||
```json
|
||
{
|
||
"status": "error",
|
||
"message": "错误描述",
|
||
"error": "详细错误信息"
|
||
}
|
||
```
|
||
|
||
## HTTP状态码
|
||
|
||
- `200 OK`: 请求成功
|
||
- `400 Bad Request`: 请求参数错误
|
||
- `404 Not Found`: 资源不存在
|
||
- `500 Internal Server Error`: 服务器内部错误
|
||
|
||
## 数据类型说明
|
||
|
||
### 模型类型枚举
|
||
- `mlstm`: 矩阵长短期记忆网络
|
||
- `transformer`: Transformer模型
|
||
- `kan`: KAN网络
|
||
- `optimized_kan`: 优化版KAN
|
||
- `tcn`: 时间卷积网络
|
||
|
||
### 任务状态枚举
|
||
- `pending`: 等待中
|
||
- `running`: 运行中
|
||
- `completed`: 已完成
|
||
- `failed`: 失败
|
||
|
||
### 评估指标说明
|
||
- `RMSE`: 均方根误差
|
||
- `MAE`: 平均绝对误差
|
||
- `R2`: 决定系数
|
||
- `MAPE`: 平均绝对百分比误差
|
||
|
||
## 注意事项
|
||
|
||
1. **API稳定性**: 此API设计已确定，不建议随意修改端点路径、参数名称或响应格式
|
||
2. **向后兼容**: 新版本API应保持向后兼容，避免破坏现有客户端
|
||
3. **错误处理**: 所有端点都应包含统一的错误处理机制
|
||
4. **参数验证**: 必须对所有输入参数进行验证
|
||
5. **安全考虑**: 对文件上传和模型操作进行安全检查
|
||
6. **性能优化**: 大数据量请求应考虑分页和缓存机制
|
||
|
||
## 扩展API开发规范
|
||
|
||
在添加新的API端点时，请遵循以下规范：
|
||
|
||
1. **路径命名**: 使用RESTful风格，动词用HTTP方法表示
|
||
2. **参数命名**: 使用snake_case命名风格
|
||
3. **响应格式**: 统一使用本文档定义的响应格式
|
||
4. **错误代码**: 使用标准HTTP状态码
|
||
5. **文档更新**: 新API必须更新此文档 |