# 药店销售预测系统 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必须更新此文档