gdtiti 441bbdcc56 v2.1.0: 建立LLM编程文档体系与API规范化 - 重大更新：建立完整的.codelf/文档体系，为LLM编程提供准确的知识库 - 创建详细的API参考文档，防止意外修改破坏API设计 - 规范化25+个API端点，包含6大分类和完整的请求/响应示例 - 新增功能：LLM编程文档体系、API保护文档、开发工具配置 - 问题修复：修复HistoryView.vue前端错误，改善数据访问安全性 - 架构改进：清理项目根目录，统一文档格式和API响应规范 - 技术价值：提升AI辅助开发效率，建立标准化开发流程，改善可维护性 - 此更新为未来的AI编程奠定坚实基础，确保系统架构稳定性

2025-06-18 06:39:41 +08:00

13 KiB

Raw Permalink Blame History

药店单品销售预测系统 - 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服务

# 基本启动
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参数: 无

响应示例:

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

响应示例:

{
  "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（可选）

响应示例:

{
  "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)，包含销售数据

响应示例:

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

5. 模型训练API

5.1 启动模型训练任务

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

URL: /training
方法: POST
请求体:

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

响应示例:

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

5.2 查询训练任务状态

查询训练任务的状态。

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

响应示例:

{
  "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
请求体:

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

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

响应示例:

{
  "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
请求体:

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

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

响应示例:

{
  "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: 按模型类型筛选（可选）

响应示例:

{
  "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: 模型版本（可选，默认为最新版本）

响应示例:

{
  "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: 模型版本（可选，默认为最新版本）

响应示例:

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

响应示例:

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

8. 系统信息API

8.1 获取系统状态

获取系统当前状态。

URL: /system/status
方法: GET

响应示例:

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

响应示例:

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

获取产品列表

curl -X GET "http://localhost:5000/api/products"

获取特定产品销售数据

curl -X GET "http://localhost:5000/api/products/P001/sales?start_date=2023-01-01&end_date=2023-01-31"

启动模型训练

curl -X POST "http://localhost:5000/api/training" \
     -H "Content-Type: application/json" \
     -d '{"product_id": "P001", "model_type": "mlstm", "parameters": {"epochs": 100}}'

使用模型预测

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

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字段，用于表示请求是否成功。如果请求失败，将返回一个包含错误信息的响应：

{
  "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: 系统内部错误

13 KiB Raw Permalink Blame History Unescape Escape

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

1. API概述

2. API基础信息

3. 启动API服务

4. 数据管理API

4.1 获取所有产品列表

4.2 获取单个产品详情

4.3 获取产品销售数据

4.4 上传销售数据

5. 模型训练API

5.1 启动模型训练任务

5.2 查询训练任务状态

6. 模型预测API

6.1 使用模型预测

6.2 比较不同模型预测结果

7. 模型管理API

7.1 获取模型列表

7.2 获取模型详情

7.3 删除模型

7.4 导出模型

7.5 导入模型

8. 系统信息API

8.1 获取系统状态

8.2 获取正在进行的任务

9. API调用示例

9.1 使用curl调用API

获取产品列表

获取特定产品销售数据

启动模型训练

使用模型预测

9.2 使用Python requests库调用API

10. 错误处理

13 KiB

Raw Permalink Blame History