ShopTRAINING/docs/输出文档/API参考手册.md

# 药店单品销售预测系统 - API参考手册

## 1. API概述

药店销售预测系统提供了完整的RESTful API服务，支持药店销售数据管理、模型训练、销售预测和模型管理等功能。API使用JSON格式进行数据交换，并通过Swagger UI提供交互式文档。

## 2. API基础信息

- **基础URL**: `http://localhost:5000/api`
- **内容类型**: `application/json`
- **认证方式**: 无认证(仅适用于测试环境)
- **状态码**:
  - `200 OK`: 请求成功
  - `400 Bad Request`: 请求参数错误
  - `404 Not Found`: 资源不存在
  - `500 Internal Server Error`: 服务器内部错误

## 3. 启动API服务

```bash
# 基本启动
python api.py

# 指定主机和端口
python api.py --host 127.0.0.1 --port 8080

# 禁用Swagger UI
python api.py --swagger false

# 禁用调试模式
python api.py --debug false
```

## 4. 数据管理API

### 4.1 获取所有产品列表

获取系统中所有产品的ID和名称。

- **URL**: `/products`
- **方法**: `GET`
- **URL参数**: 无

**响应示例**:

```json
{
  "status": "success",
  "data": [
    {
      "product_id": "P001",
      "product_name": "布洛芬片"
    },
    {
      "product_id": "P002",
      "product_name": "阿司匹林"
    }
  ]
}
```

### 4.2 获取单个产品详情

获取特定产品的详细信息。

- **URL**: `/products/{product_id}`
- **方法**: `GET`
- **URL参数**:
  - `product_id`: 产品ID，例如"P001"

**响应示例**:

```json
{
  "status": "success",
  "data": {
    "product_id": "P001",
    "product_name": "布洛芬片",
    "data_points": 365,
    "date_range": {
      "start": "2023-01-01",
      "end": "2023-12-31"
    }
  }
}
```

### 4.3 获取产品销售数据

获取指定产品在特定日期范围内的销售数据。

- **URL**: `/products/{product_id}/sales`
- **方法**: `GET`
- **URL参数**:
  - `product_id`: 产品ID，例如"P001"
- **查询参数**:
  - `start_date`: 开始日期，格式为YYYY-MM-DD（可选）
  - `end_date`: 结束日期，格式为YYYY-MM-DD（可选）

**响应示例**:

```json
{
  "status": "success",
  "data": [
    {
      "date": "2023-01-01",
      "product_id": "P001",
      "product_name": "布洛芬片",
      "sales": 120,
      "price": 15.5,
      "weekday": 6,
      "month": 1,
      "is_holiday": 1,
      "is_weekend": 1,
      "is_promotion": 0,
      "temperature": 5.2
    },
    {
      "date": "2023-01-02",
      "product_id": "P001",
      "product_name": "布洛芬片",
      "sales": 85,
      "price": 15.5,
      "weekday": 0,
      "month": 1,
      "is_holiday": 0,
      "is_weekend": 0,
      "is_promotion": 0,
      "temperature": 4.8
    }
  ]
}
```

### 4.4 上传销售数据

上传新的销售数据文件。

- **URL**: `/data/upload`
- **方法**: `POST`
- **内容类型**: `multipart/form-data`
- **参数**:
  - `file`: Excel文件(.xlsx)，包含销售数据

**响应示例**:

```json
{
  "status": "success",
  "message": "数据上传成功",
  "data": {
    "products": 5,
    "rows": 1825
  }
}
```

## 5. 模型训练API

### 5.1 启动模型训练任务

启动一个新的模型训练任务。

- **URL**: `/training`
- **方法**: `POST`
- **请求体**:

```json
{
  "product_id": "P001",
  "model_type": "mlstm",
  "parameters": {
    "look_back": 14,
    "future_days": 7,
    "batch_size": 64,
    "epochs": 100,
    "learning_rate": 0.001
  }
}
```

- **参数说明**:
  - `product_id`: 产品ID
  - `model_type`: 模型类型，可选值：`mlstm`, `transformer`, `kan`
  - `parameters`: 训练参数（可选）
    - `look_back`: 回看天数，默认14
    - `future_days`: 预测天数，默认7
    - `batch_size`: 批大小，默认32
    - `epochs`: 训练轮次，默认50
    - `learning_rate`: 学习率，默认0.001

**响应示例**:

```json
{
  "status": "success",
  "task_id": "train_P001_mlstm_20230615123456",
  "message": "模型训练任务已启动"
}
```

### 5.2 查询训练任务状态

查询训练任务的状态。

- **URL**: `/training/{task_id}`
- **方法**: `GET`
- **URL参数**:
  - `task_id`: 任务ID，由启动训练任务时返回

**响应示例**:

```json
{
  "status": "success",
  "data": {
    "task_id": "train_P001_mlstm_20230615123456",
    "product_id": "P001",
    "model_type": "mlstm",
    "status": "completed",
    "progress": 100,
    "created_at": "2023-06-15T12:34:56",
    "completed_at": "2023-06-15T12:45:23",
    "metrics": {
      "mse": 35.67,
      "rmse": 5.97,
      "mae": 4.21,
      "r2": 0.87
    }
  }
}
```

## 6. 模型预测API

### 6.1 使用模型预测

使用指定的模型进行预测。

- **URL**: `/prediction`
- **方法**: `POST`
- **请求体**:

```json
{
  "product_id": "P001",
  "model_type": "mlstm",
  "days": 7,
  "version": "latest"
}
```

- **参数说明**:
  - `product_id`: 产品ID
  - `model_type`: 模型类型，可选值：`mlstm`, `transformer`, `kan`
  - `days`: 预测天数，默认7
  - `version`: 模型版本，默认"latest"

**响应示例**:

```json
{
  "status": "success",
  "data": {
    "product_id": "P001",
    "product_name": "布洛芬片",
    "model_type": "mlstm",
    "version": "20230615123456",
    "prediction_dates": ["2023-07-01", "2023-07-02", "2023-07-03", "2023-07-04", "2023-07-05", "2023-07-06", "2023-07-07"],
    "predicted_sales": [125.4, 118.2, 130.1, 142.3, 138.7, 129.5, 145.2],
    "metrics": {
      "mse": 35.67,
      "rmse": 5.97,
      "mae": 4.21,
      "r2": 0.87
    }
  }
}
```

### 6.2 比较不同模型预测结果

比较不同模型对同一产品的预测结果。

- **URL**: `/prediction/compare`
- **方法**: `POST`
- **请求体**:

```json
{
  "product_id": "P001",
  "model_types": ["mlstm", "transformer", "kan"],
  "days": 7
}
```

- **参数说明**:
  - `product_id`: 产品ID
  - `model_types`: 要比较的模型类型列表
  - `days`: 预测天数，默认7

**响应示例**:

```json
{
  "status": "success",
  "data": {
    "product_id": "P001",
    "product_name": "布洛芬片",
    "prediction_dates": ["2023-07-01", "2023-07-02", "2023-07-03", "2023-07-04", "2023-07-05", "2023-07-06", "2023-07-07"],
    "predictions": {
      "mlstm": {
        "version": "20230615123456",
        "predicted_sales": [125.4, 118.2, 130.1, 142.3, 138.7, 129.5, 145.2],
        "metrics": {
          "mse": 35.67,
          "rmse": 5.97,
          "mae": 4.21,
          "r2": 0.87
        }
      },
      "transformer": {
        "version": "20230614152345",
        "predicted_sales": [127.8, 119.5, 132.3, 139.7, 141.2, 130.8, 143.1],
        "metrics": {
          "mse": 38.24,
          "rmse": 6.18,
          "mae": 4.35,
          "r2": 0.85
        }
      },
      "kan": {
        "version": "20230613110012",
        "predicted_sales": [124.1, 117.6, 128.9, 143.5, 139.2, 128.7, 146.3],
        "metrics": {
          "mse": 33.21,
          "rmse": 5.76,
          "mae": 4.12,
          "r2": 0.89
        }
      }
    }
  }
}
```

## 7. 模型管理API

### 7.1 获取模型列表

获取系统中所有可用的模型。

- **URL**: `/models`
- **方法**: `GET`
- **查询参数**:
  - `product_id`: 按产品ID筛选（可选）
  - `model_type`: 按模型类型筛选（可选）

**响应示例**:

```json
{
  "status": "success",
  "data": [
    {
      "product_id": "P001",
      "model_type": "mlstm",
      "version": "20230615123456",
      "created_at": "2023-06-15T12:45:23",
      "metrics": {
        "mse": 35.67,
        "rmse": 5.97,
        "mae": 4.21,
        "r2": 0.87
      }
    },
    {
      "product_id": "P001",
      "model_type": "transformer",
      "version": "20230614152345",
      "created_at": "2023-06-14T15:32:11",
      "metrics": {
        "mse": 38.24,
        "rmse": 6.18,
        "mae": 4.35,
        "r2": 0.85
      }
    }
  ]
}
```

### 7.2 获取模型详情

获取特定模型的详细信息。

- **URL**: `/models/{product_id}/{model_type}`
- **方法**: `GET`
- **URL参数**:
  - `product_id`: 产品ID
  - `model_type`: 模型类型
- **查询参数**:
  - `version`: 模型版本（可选，默认为最新版本）

**响应示例**:

```json
{
  "status": "success",
  "data": {
    "product_id": "P001",
    "product_name": "布洛芬片",
    "model_type": "mlstm",
    "version": "20230615123456",
    "created_at": "2023-06-15T12:45:23",
    "file_size": "2.3 MB",
    "parameters": {
      "look_back": 14,
      "future_days": 7,
      "batch_size": 64,
      "epochs": 100,
      "learning_rate": 0.001
    },
    "metrics": {
      "mse": 35.67,
      "rmse": 5.97,
      "mae": 4.21,
      "r2": 0.87,
      "mape": 3.45
    }
  }
}
```

### 7.3 删除模型

删除指定的模型。

- **URL**: `/models/{product_id}/{model_type}`
- **方法**: `DELETE`
- **URL参数**:
  - `product_id`: 产品ID
  - `model_type`: 模型类型
- **查询参数**:
  - `version`: 模型版本（可选，默认为最新版本）

**响应示例**:

```json
{
  "status": "success",
  "message": "模型已成功删除"
}
```

### 7.4 导出模型

导出指定的模型。

- **URL**: `/models/{product_id}/{model_type}/export`
- **方法**: `GET`
- **URL参数**:
  - `product_id`: 产品ID
  - `model_type`: 模型类型
- **查询参数**:
  - `version`: 模型版本（可选，默认为最新版本）

**响应**:
文件下载（模型文件）

### 7.5 导入模型

导入模型文件。

- **URL**: `/models/import`
- **方法**: `POST`
- **内容类型**: `multipart/form-data`
- **参数**:
  - `file`: 模型文件
  - `overwrite`: 是否覆盖同名模型（可选，默认为false）

**响应示例**:

```json
{
  "status": "success",
  "message": "模型已成功导入",
  "data": {
    "product_id": "P001",
    "model_type": "mlstm",
    "version": "20230615123456"
  }
}
```

## 8. 系统信息API

### 8.1 获取系统状态

获取系统当前状态。

- **URL**: `/system/status`
- **方法**: `GET`

**响应示例**:

```json
{
  "status": "success",
  "data": {
    "version": "1.0.0",
    "uptime": "3 days, 4 hours",
    "gpu_available": true,
    "models_count": 15,
    "products_count": 5,
    "system_load": {
      "cpu": "32%",
      "memory": "48%",
      "gpu": "15%"
    }
  }
}
```

### 8.2 获取正在进行的任务

获取当前正在进行的任务列表。

- **URL**: `/system/tasks`
- **方法**: `GET`

**响应示例**:

```json
{
  "status": "success",
  "data": [
    {
      "task_id": "train_P003_mlstm_20230618091234",
      "type": "training",
      "product_id": "P003",
      "model_type": "mlstm",
      "status": "in_progress",
      "progress": 65,
      "created_at": "2023-06-18T09:12:34"
    },
    {
      "task_id": "predict_P002_kan_20230618093012",
      "type": "prediction",
      "product_id": "P002",
      "model_type": "kan",
      "status": "in_progress",
      "progress": 80,
      "created_at": "2023-06-18T09:30:12"
    }
  ]
}
```

## 9. API调用示例

### 9.1 使用curl调用API

#### 获取产品列表
```bash
curl -X GET "http://localhost:5000/api/products"
```

#### 获取特定产品销售数据
```bash
curl -X GET "http://localhost:5000/api/products/P001/sales?start_date=2023-01-01&end_date=2023-01-31"
```

#### 启动模型训练
```bash
curl -X POST "http://localhost:5000/api/training" \
     -H "Content-Type: application/json" \
     -d '{"product_id": "P001", "model_type": "mlstm", "parameters": {"epochs": 100}}'
```

#### 使用模型预测
```bash
curl -X POST "http://localhost:5000/api/prediction" \
     -H "Content-Type: application/json" \
     -d '{"product_id": "P001", "model_type": "mlstm", "days": 7}'
```

### 9.2 使用Python requests库调用API

```python
import requests
import json

# 基础URL
base_url = "http://localhost:5000/api"

# 获取产品列表
response = requests.get(f"{base_url}/products")
products = response.json()
print(json.dumps(products, indent=2))

# 启动模型训练
train_data = {
    "product_id": "P001",
    "model_type": "mlstm",
    "parameters": {
        "epochs": 100,
        "batch_size": 64
    }
}
response = requests.post(f"{base_url}/training", json=train_data)
result = response.json()
print(json.dumps(result, indent=2))

# 使用模型预测
predict_data = {
    "product_id": "P001",
    "model_type": "mlstm",
    "days": 7
}
response = requests.post(f"{base_url}/prediction", json=predict_data)
predictions = response.json()
print(json.dumps(predictions, indent=2))
```

## 10. 错误处理

所有API响应都包含`status`字段，用于表示请求是否成功。如果请求失败，将返回一个包含错误信息的响应：

```json
{
  "status": "error",
  "error": {
    "code": "MODEL_NOT_FOUND",
    "message": "找不到指定的模型"
  }
}
```

常见错误代码：

- `INVALID_PARAMETERS`: 请求参数无效
- `PRODUCT_NOT_FOUND`: 找不到指定的产品
- `MODEL_NOT_FOUND`: 找不到指定的模型
- `TASK_NOT_FOUND`: 找不到指定的任务
- `FILE_UPLOAD_ERROR`: 文件上传失败
- `TRAINING_ERROR`: 模型训练失败
- `PREDICTION_ERROR`: 模型预测失败
- `SYSTEM_ERROR`: 系统内部错误