OneTree/ShopTRAINING
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
ShopTRAINING/.codelf/api-reference.md

13 KiB
Raw Permalink Blame History

药店销售预测系统 API 详细参考文档

概述

本文档详细描述了药店销售预测系统中所有API端点的完整规范，包括请求格式、响应格式、参数说明和示例。此文档旨在防止意外修改破坏API设计，确保API的一致性和稳定性。

API基础信息：

  • 基础URL：http://localhost:5000
  • 协议：HTTP/HTTPS
  • 格式：JSON
  • 认证：暂无（内部系统）
  • API文档：/swagger/

API端点分类

1. 系统导航API

1.1 根路由

GET /

功能： 重定向到UI界面 响应： 302重定向到 /ui/

1.2 Swagger文档

GET /swagger

功能： 重定向到Swagger UI文档页面 响应： 302重定向到 /swagger/

2. 数据管理API

2.1 获取所有产品列表

GET /api/products

功能： 返回系统中所有产品的ID和名称

响应示例：

{
  "status": "success",
  "data": [
    {
      "product_id": "P001",
      "product_name": "感冒灵颗粒"
    },
    {
      "product_id": "P002", 
      "product_name": "布洛芬片"
    }
  ]
}

错误响应：

{
  "status": "error",
  "message": "错误详细信息"
}

2.2 获取单个产品详情

GET /api/products/{product_id}

功能： 返回指定产品ID的详细信息

路径参数：

  • product_id (string, required): 产品ID，例如P001

响应示例：

{
  "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 获取产品销售数据

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

响应示例：

{
  "status": "success",
  "data": [
    {
      "date": "2023-01-01",
      "product_id": "P001",
      "product_name": "感冒灵颗粒",
      "sales": 125,
      "price": 15.8
    }
  ]
}

2.4 上传销售数据

POST /api/data/upload

功能： 上传新的销售数据文件(Excel格式)

请求类型： multipart/form-data

参数：

  • file (file, required): Excel文件(.xlsx)，包含销售数据

必要字段：

  • date: 日期
  • product_id: 产品ID
  • product_name: 产品名称
  • sales: 销售量
  • price: 价格

响应示例：

{
  "status": "success",
  "message": "数据上传成功",
  "data": {
    "products": 10,
    "rows": 3650
  }
}

3. 模型训练API

3.1 获取所有训练任务列表

GET /api/training

功能： 返回所有正在进行、已完成或失败的训练任务

响应示例：

{
  "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 启动模型训练任务

POST /api/training

功能： 为指定产品启动一个新的模型训练任务

请求体：

{
  "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

响应示例：

{
  "message": "模型训练已开始",
  "task_id": "uuid-string"
}

3.3 查询训练任务状态

GET /api/training/{task_id}

功能： 获取特定训练任务的当前状态和详情

路径参数：

  • task_id (string, required): 训练任务ID

响应示例：

{
  "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 使用模型进行预测

POST /api/prediction

功能： 使用指定模型预测未来销售数据

请求体：

{
  "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

响应示例：

{
  "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 比较不同模型预测结果

POST /api/prediction/compare

功能： 比较不同模型对同一产品的预测结果

请求体：

{
  "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): 是否包含可视化

响应示例：

{
  "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 分析预测结果

POST /api/prediction/analyze

功能： 对预测结果进行深度分析

请求体：

{
  "prediction_data": {...},
  "analysis_type": "trend"
}

4.4 获取预测历史记录

GET /api/prediction/history

功能： 获取预测历史记录列表

查询参数：

  • product_id (string, optional): 按产品ID筛选
  • model_type (string, optional): 按模型类型筛选
  • limit (integer, optional): 限制返回数量
  • offset (integer, optional): 分页偏移量

响应示例：

{
  "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 获取特定预测详情

GET /api/prediction/history/{prediction_id}

功能： 获取特定预测的详细信息

路径参数：

  • prediction_id (string, required): 预测记录ID

4.6 删除预测记录

DELETE /api/prediction/history/{prediction_id}

功能： 删除特定的预测记录

路径参数：

  • prediction_id (string, required): 预测记录ID

5. 模型管理API

5.1 获取模型列表

GET /api/models

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

查询参数：

  • product_id (string, optional): 按产品ID筛选
  • model_type (string, optional): 按模型类型筛选

响应示例：

{
  "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 获取模型详情

GET /api/models/{model_id}

功能： 获取特定模型的详细信息

路径参数：

  • model_id (string, required): 模型ID，格式为{product_id}_{model_type}_v{version}

响应示例：

{
  "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 删除模型

DELETE /api/models/{model_id}

功能： 删除特定模型

路径参数：

  • model_id (string, required): 模型ID

响应示例：

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

5.4 导出模型

GET /api/models/{model_id}/export

功能： 导出特定模型文件

路径参数：

  • model_id (string, required): 模型ID

响应： 模型文件下载 (application/octet-stream)

5.5 获取模型详情（兼容格式）

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 分析模型性能指标

POST /api/models/analyze-metrics

功能： 根据模型的评估指标进行性能分析

请求体：

{
  "RMSE": 0.045,
  "MAE": 0.032,
  "R2": 0.89,
  "MAPE": 0.078
}

响应示例：

{
  "status": "success",
  "data": {
    "overall_score": 0.85,
    "performance_level": "excellent",
    "recommendations": [
      "模型表现优秀，可以用于生产环境",
      "R2值较高，模型拟合效果良好"
    ]
  }
}

5.7 获取系统支持的模型类型

GET /api/model_types

功能： 返回系统中支持的所有模型类型及其描述

响应示例：

{
  "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 获取图表文件

GET /api/plots/{filename}

功能： 提供图表文件访问服务

路径参数：

  • filename (string, required): 文件名

响应： 图片文件

通用响应格式

成功响应

{
  "status": "success",
  "data": { ... }
}

错误响应

{
  "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必须更新此文档