ShopTRAINING/docs/药店销售预测系统API文档.md

# 药店销售预测系统API文档

## 目录

- [概述](#概述)
- [API基础信息](#api基础信息)
- [数据管理API](#数据管理api)
  - [获取所有产品列表](#获取所有产品列表)
  - [获取单个产品详情](#获取单个产品详情)
  - [获取产品销售数据](#获取产品销售数据)
  - [上传销售数据](#上传销售数据)
- [模型训练API](#模型训练api)
  - [启动模型训练任务](#启动模型训练任务)
  - [查询训练任务状态](#查询训练任务状态)
- [模型预测API](#模型预测api)
  - [使用模型预测](#使用模型预测)
  - [比较不同模型预测结果](#比较不同模型预测结果)
- [模型管理API](#模型管理api)
  - [获取模型列表](#获取模型列表)
  - [获取模型详情](#获取模型详情)
  - [删除模型](#删除模型)
  - [导出模型](#导出模型)
  - [导入模型](#导入模型)
- [API调用示例](#api调用示例)

## 概述

药店销售预测系统API提供了完整的RESTful接口，支持药店销售数据管理、模型训练、销售预测和模型管理等功能。API使用JSON格式进行数据交换，所有API响应都包含`status`字段，用于表示请求是否成功。

## API基础信息

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

## 数据管理API

### 获取所有产品列表

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

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

**响应**:

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

### 获取单个产品详情

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

- **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"
    }
  }
}
```

### 获取产品销售数据

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

- **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
    }
  ]
}
```

### 上传销售数据

上传新的销售数据文件。

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

**响应**:

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

## 模型训练API

### 启动模型训练任务

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

- **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",
  "message": "模型训练任务已启动",
  "data": {
    "task_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}
```

### 查询训练任务状态

查询特定训练任务的状态。

- **URL**: `/training/{task_id}`
- **方法**: `GET`
- **URL参数**:
  - `task_id`: 训练任务ID

**响应**:

```json
{
  "status": "success",
  "data": {
    "product_id": "P001",
    "model_type": "mlstm",
    "parameters": {
      "look_back": 14,
      "future_days": 7
    },
    "status": "completed",
    "created_at": "2023-06-15 14:30:25",
    "model_path": "models/P001_mlstm_model_v20230615_143025.pt",
    "metrics": {
      "MSE": 12.45,
      "RMSE": 3.52,
      "MAE": 2.85,
      "R2": 0.92,
      "MAPE": 5.67
    },
    "model_details_url": "/api/models?product_id=P001&model_type=mlstm"
  }
}
```

- **可能的状态值**:
  - `pending`: 等待开始
  - `running`: 正在训练
  - `completed`: 训练完成
  - `failed`: 训练失败

## 模型预测API

### 使用模型预测

使用指定模型进行预测。

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

```json
{
  "product_id": "P001",
  "model_type": "mlstm",
  "version": "20230615_143025",
  "future_days": 7,
  "include_visualization": true
}
```

- **参数说明**:
  - `product_id`: 产品ID
  - `model_type`: 模型类型，可选值：`mlstm`, `transformer`, `kan`
  - `version`: 模型版本（可选，不指定则使用最新版本）
  - `future_days`: 预测天数（可选，默认为7）
  - `include_visualization`: 是否包含可视化结果（可选，默认为false）

**响应**:

```json
{
  "status": "success",
  "data": {
    "product_id": "P001",
    "product_name": "布洛芬片",
    "model_type": "mlstm",
    "predictions": [
      {
        "date": "2023-07-01",
        "predicted_sales": 105.8
      },
      {
        "date": "2023-07-02",
        "predicted_sales": 98.3
      },
      {
        "date": "2023-07-03",
        "predicted_sales": 112.5
      },
      {
        "date": "2023-07-04",
        "predicted_sales": 120.1
      },
      {
        "date": "2023-07-05",
        "predicted_sales": 125.6
      },
      {
        "date": "2023-07-06",
        "predicted_sales": 118.9
      },
      {
        "date": "2023-07-07",
        "predicted_sales": 130.4
      }
    ],
    "visualization": "base64_encoded_image_data"
  }
}
```

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

比较不同模型的预测结果。

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

```json
{
  "product_id": "P001",
  "model_types": ["mlstm", "transformer", "kan"],
  "versions": ["20230615_143025", null, null],
  "include_visualization": true
}
```

- **参数说明**:
  - `product_id`: 产品ID
  - `model_types`: 要比较的模型类型列表
  - `versions`: 对应每个模型的版本列表（可选，不指定则使用最新版本）
  - `include_visualization`: 是否包含可视化结果（可选，默认为false）

**响应**:

```json
{
  "status": "success",
  "data": {
    "product_id": "P001",
    "product_name": "布洛芬片",
    "model_types": ["mlstm", "transformer", "kan"],
    "comparison": [
      {
        "date": "2023-07-01",
        "mlstm_prediction": 105.8,
        "transformer_prediction": 108.2,
        "kan_prediction": 107.1
      },
      {
        "date": "2023-07-02",
        "mlstm_prediction": 98.3,
        "transformer_prediction": 101.5,
        "kan_prediction": 100.6
      },
      {
        "date": "2023-07-03",
        "mlstm_prediction": 112.5,
        "transformer_prediction": 115.8,
        "kan_prediction": 114.2
      },
      {
        "date": "2023-07-04",
        "mlstm_prediction": 120.1,
        "transformer_prediction": 122.4,
        "kan_prediction": 121.8
      },
      {
        "date": "2023-07-05",
        "mlstm_prediction": 125.6,
        "transformer_prediction": 127.3,
        "kan_prediction": 126.9
      },
      {
        "date": "2023-07-06",
        "mlstm_prediction": 118.9,
        "transformer_prediction": 121.2,
        "kan_prediction": 120.5
      },
      {
        "date": "2023-07-07",
        "mlstm_prediction": 130.4,
        "transformer_prediction": 132.8,
        "kan_prediction": 131.6
      }
    ],
    "visualization": "base64_encoded_image_data"
  }
}
```

## 模型管理API

### 获取模型列表

获取系统中的模型列表，可按产品ID和模型类型筛选。

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

**响应**:

```json
{
  "status": "success",
  "data": [
    {
      "product_id": "P001",
      "model_type": "mlstm",
      "version": "20230615_143025",
      "file_path": "models/P001_mlstm_model_v20230615_143025.pt",
      "created_at": "2023-06-15 14:30:25",
      "file_size": "2.45 MB",
      "metrics": {
        "MSE": 12.45,
        "RMSE": 3.52,
        "MAE": 2.85,
        "R2": 0.92,
        "MAPE": 5.67
      }
    },
    {
      "product_id": "P001",
      "model_type": "transformer",
      "version": "20230615_150512",
      "file_path": "models/P001_transformer_model_v20230615_150512.pt",
      "created_at": "2023-06-15 15:05:12",
      "file_size": "3.12 MB",
      "metrics": {
        "MSE": 10.82,
        "RMSE": 3.29,
        "MAE": 2.73,
        "R2": 0.93,
        "MAPE": 5.21
      }
    }
  ]
}
```

### 获取模型详情

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

- **URL**: `/models/{model_id}`
- **方法**: `GET`
- **URL参数**:
  - `model_id`: 模型ID，格式为`{product_id}_{model_type}_v{version}`，例如`P001_mlstm_v20230615_143025`

**响应**:

```json
{
  "status": "success",
  "data": {
    "product_id": "P001",
    "model_type": "mlstm",
    "version": "20230615_143025",
    "created_at": "2023-06-15 14:30:25",
    "file_path": "models/P001_mlstm_model_v20230615_143025.pt",
    "file_size": "2.45 MB",
    "features": ["sales", "price", "weekday", "month", "is_holiday", "is_weekend", "is_promotion", "temperature"],
    "look_back": 14,
    "T": 7,
    "metrics": {
      "MSE": 12.45,
      "RMSE": 3.52,
      "MAE": 2.85,
      "R2": 0.92,
      "MAPE": 5.67
    }
  }
}
```

### 删除模型

删除特定模型。

- **URL**: `/models/{model_id}`
- **方法**: `DELETE`
- **URL参数**:
  - `model_id`: 模型ID，格式为`{product_id}_{model_type}_v{version}`，例如`P001_mlstm_v20230615_143025`

**响应**:

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

### 导出模型

导出特定模型文件。

- **URL**: `/models/{model_id}/export`
- **方法**: `GET`
- **URL参数**:
  - `model_id`: 模型ID，格式为`{product_id}_{model_type}_v{version}`，例如`P001_mlstm_v20230615_143025`

**响应**: 直接下载模型文件

### 导入模型

导入模型文件。

- **URL**: `/models/import`
- **方法**: `POST`
- **内容类型**: `multipart/form-data`
- **参数**:
  - `file`: PyTorch模型文件(.pt)

**响应**:

```json
{
  "status": "success",
  "message": "模型已成功导入",
  "data": {
    "model_path": "models/P001_mlstm_model_v20230615_143025.pt"
  }
}
```

## API调用示例

以下是使用Python和requests库调用API的示例代码：

```python
import requests
import json
import matplotlib.pyplot as plt
import base64
from io import BytesIO

# API基础URL
API_BASE_URL = 'http://localhost:5000/api'

# 获取所有产品
def get_products():
    response = requests.get(f'{API_BASE_URL}/products')
    return response.json()

# 训练模型
def train_model(product_id, model_type='mlstm'):
    data = {
        'product_id': product_id,
        'model_type': model_type,
        'parameters': {
            'look_back': 14,
            'future_days': 7,
            'epochs': 50
        }
    }
    response = requests.post(f'{API_BASE_URL}/training', json=data)
    return response.json()

# 查询训练状态
def check_training_status(task_id):
    response = requests.get(f'{API_BASE_URL}/training/{task_id}')
    return response.json()

# 使用模型预测
def predict_sales(product_id, model_type='mlstm', include_visualization=True):
    data = {
        'product_id': product_id,
        'model_type': model_type,
        'future_days': 7,
        'include_visualization': include_visualization
    }
    response = requests.post(f'{API_BASE_URL}/prediction', json=data)
    result = response.json()
    
    # 如果包含可视化图表，显示它
    if include_visualization and 'data' in result and 'visualization' in result['data']:
        img_data = base64.b64decode(result['data']['visualization'])
        img = plt.imread(BytesIO(img_data))
        plt.figure(figsize=(12, 6))
        plt.imshow(img)
        plt.axis('off')
        plt.show()
    
    return result

# 比较不同模型
def compare_models(product_id, model_types=['mlstm', 'transformer', 'kan']):
    data = {
        'product_id': product_id,
        'model_types': model_types,
        'include_visualization': True
    }
    response = requests.post(f'{API_BASE_URL}/prediction/compare', json=data)
    return response.json()

# 调用示例
if __name__ == '__main__':
    # 获取所有产品
    products = get_products()
    print(json.dumps(products, indent=2))
    
    if products['status'] == 'success' and len(products['data']) > 0:
        # 选择第一个产品
        product_id = products['data'][0]['product_id']
        
        # 训练模型
        training_result = train_model(product_id, 'mlstm')
        print(json.dumps(training_result, indent=2))
        
        # 如果训练任务启动成功，检查状态
        if training_result['status'] == 'success':
            task_id = training_result['data']['task_id']
            
            # 这里实际使用时可以轮询检查状态
            status = check_training_status(task_id)
            print(json.dumps(status, indent=2))
            
            # 使用模型预测（实际使用时应等待训练完成）
            predictions = predict_sales(product_id)
            print(json.dumps(predictions, indent=2))