OneTree/ShopTRAINING
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
ShopTRAINING/xz系统API注解和swagger访问.md
xz2000 87cc7b4d03 测试修改了的功能
2025-07-23 17:25:06 +08:00

13 KiB
Raw Blame History

访问Swagger UI：

服务启动后，在您的浏览器中打开以下地址即可查看交互式API文档：

http://localhost:5173/swagger/

文件路径：C:\WorkSpace\ShopTRAINING\server\swagger.json

药店销售预测系统 API 文档

版本: 1.0.0 联系方式: API开发团队

本文档详细描述了用于药店销售预测的RESTful API。

数据管理

数据上传和查询相关接口。

GET /api/products

摘要: 获取所有产品列表

描述: 返回系统中所有产品的ID和名称。

响应:

  • 200: 成功获取产品列表。 
    {
  "status": "success",
  "data": [
    {
      "product_id": "P001",
      "product_name": "产品A"
    },
    {
      "product_id": "P002",
      "product_name": "产品B"
    }
  ]
}
  • 500: 服务器内部错误。

GET /api/products/{product_id}

摘要: 获取单个产品详情

描述: 返回指定产品ID的详细信息。

路径参数:

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

响应:

  • 200: 成功获取产品详情。 
    {
    "status": "success",
    "data": {
        "product_id": "P001",
        "product_name": "产品A",
        "data_points": 365,
        "date_range": {
            "start": "2023-01-01",
            "end": "2023-12-31"
        }
    }
}
  • 404: 产品不存在。
  • 500: 服务器内部错误。

GET /api/products/{product_id}/sales

摘要: 获取产品销售数据

描述: 返回指定产品在特定日期范围内的销售数据。

路径参数:

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

查询参数:

  • start_date (string): 开始日期，格式为YYYY-MM-DD。
  • end_date (string): 结束日期，格式为YYYY-MM-DD。

响应:

  • 200: 成功获取销售数据。 
    {
    "status": "success",
    "data": [
        {
            "date": "2023-12-01",
            "sales": 150
        },
        {
            "date": "2023-12-02",
            "sales": 155
        }
    ]
}
  • 404: 产品不存在。
  • 500: 服务器内部错误。

POST /api/data/upload

摘要: 上传销售数据

描述: 上传新的销售数据文件(Excel格式)。

请求体: multipart/form-data

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

响应:

  • 200: 数据上传成功。 
    {
    "status": "success",
    "message": "数据上传成功",
    "data": {
        "products": 10,
        "rows": 3650
    }
}
  • 400: 请求错误。
  • 500: 服务器内部错误。

GET /api/stores

摘要: 获取所有店铺列表

响应:

  • 200: 获取成功。 
    {
    "status": "success",
    "data": [
        {
            "store_id": "S001",
            "store_name": "第一分店"
        },
        {
            "store_id": "S002",
            "store_name": "第二分店"
        }
    ],
    "count": 2
}

POST /api/stores

摘要: 创建新店铺

响应:

  • 200: 创建成功。 
    {
    "status": "success",
    "message": "店铺创建成功",
    "data": {
        "store_id": "S003"
    }
}

GET /api/stores/{store_id}

摘要: 获取单个店铺信息

路径参数:

  • store_id (string, required): 店铺ID。

响应:

  • 200: 获取成功。 
    {
    "status": "success",
    "data": {
        "store_id": "S001",
        "store_name": "第一分店",
        "location": "市中心",
        "size": 120.5,
        "type": "旗舰店",
        "opening_date": "2022-01-01",
        "status": "active"
    }
}
  • 404: 店铺不存在。

PUT /api/stores/{store_id}

摘要: 更新店铺信息

路径参数:

  • store_id (string, required): 店铺ID。

响应:

  • 200: 更新成功。 
    {
    "status": "success",
    "message": "店铺更新成功"
}
  • 404: 店铺不存在。

DELETE /api/stores/{store_id}

摘要: 删除店铺

路径参数:

  • store_id (string, required): 店铺ID。

响应:

  • 200: 删除成功。 
    {
    "status": "success",
    "message": "店铺删除成功"
}
  • 404: 店铺不存在。

GET /api/stores/{store_id}/products

摘要: 获取店铺的产品列表

路径参数:

  • store_id (string, required): 店铺ID。

响应:

  • 200: 获取成功。 
    {
    "status": "success",
    "data": [
        {
            "product_id": "P001",
            "product_name": "产品A"
        }
    ],
    "count": 1
}

GET /api/stores/{store_id}/statistics

摘要: 获取店铺销售统计信息

路径参数:

  • store_id (string, required): 店铺ID。

响应:

  • 200: 获取成功。 
    {
    "status": "success",
    "data": {
        "total_sales": 150000.0,
        "total_quantity": 7500,
        "products_count": 50
    }
}

GET /api/sales/data

摘要: 获取销售数据列表

响应:

  • 200: 获取成功。 
    {
    "status": "success",
    "data": [
        {
            "date": "2023-12-01",
            "store_id": "S001",
            "product_id": "P001",
            "sales": 150,
            "price": 25.5
        }
    ],
    "total": 100,
    "page": 1,
    "page_size": 1
}

模型训练

模型训练相关接口。

GET /api/training

摘要: 获取所有训练任务列表

描述: 返回所有正在进行、已完成或失败的训练任务。

响应:

  • 200: 成功获取任务列表。 
    {
    "status": "success",
    "data": [
        {
            "task_id": "uuid-1234",
            "product_id": "P001",
            "model_type": "mlstm",
            "status": "completed",
            "start_time": "2023-12-25T10:00:00Z",
            "metrics": {"R2": 0.95, "RMSE": 5.5},
            "error": null,
            "model_path": "/path/to/model.pth"
        }
    ]
}

POST /api/training

摘要: 启动模型训练任务

描述: 为指定产品启动一个新的模型训练任务。

请求体: application/json

{
  "product_id": "P001",
  "model_type": "mlstm",
  "store_id": "S001",
  "epochs": 50
}

响应:

  • 200: 训练任务已启动。 
    {
    "message": "模型训练已开始",
    "task_id": "new-uuid-5678"
}
  • 400: 请求错误。

GET /api/training/{task_id}

摘要: 查询训练任务状态

描述: 获取特定训练任务的当前状态和详情。

路径参数:

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

响应:

  • 200: 成功获取任务状态。 
    {
    "status": "success",
    "data": {
        "product_id": "P001",
        "model_type": "mlstm",
        "status": "running",
        "progress": 50.5,
        "created_at": "2023-12-25T10:00:00Z"
    }
}
  • 404: 任务不存在。
  • 500: 服务器内部错误。

模型预测

预测销售数据相关接口。

POST /api/prediction

摘要: 使用模型进行预测

描述: 使用指定模型预测未来销售数据。

请求体: application/json

{
  "product_id": "string",
  "model_type": "mlstm",
  "store_id": "string",
  "version": "string",
  "future_days": 7,
  "include_visualization": true,
  "start_date": "2024-01-01"
}

响应:

  • 200: 预测成功。 
    {
    "status": "success",
    "data": {
        "product_id": "P001",
        "product_name": "产品A",
        "model_type": "mlstm",
        "predictions": [
            {"date": "2024-01-01", "predicted_sales": 100},
            {"date": "2024-01-02", "predicted_sales": 105}
        ],
        "visualization": "base64-encoded-image-string"
    }
}
  • 400: 请求错误。
  • 404: 产品或模型不存在。
  • 500: 服务器内部错误。

POST /api/prediction/compare

摘要: 比较不同模型预测结果

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

请求体: application/json

{
  "product_id": "string",
  "model_types": ["mlstm", "transformer"],
  "versions": ["v1", "v2"],
  "include_visualization": true
}

响应:

  • 200: 比较成功。 
    {
    "status": "success",
    "data": {
        "product_id": "P001",
        "comparison": [
            {"date": "2024-01-01", "mlstm": 100, "transformer": 102},
            {"date": "2024-01-02", "mlstm": 105, "transformer": 106}
        ],
        "visualization": "base64-encoded-image-string"
    }
}
  • 400: 请求错误。
  • 404: 产品或模型不存在。
  • 500: 服务器内部错误。

GET /api/prediction/history

摘要: 获取历史预测记录

响应:

  • 200: 获取成功。 
    {
    "status": "success",
    "data": [
        {
            "prediction_id": "pred-uuid-1",
            "product_id": "P001",
            "model_type": "mlstm",
            "created_at": "2023-12-20T11:00:00Z"
        }
    ]
}

GET /api/prediction/history/{prediction_id}

摘要: 获取特定预测记录的详情

路径参数:

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

响应:

  • 200: 获取成功。 
    {
    "status": "success",
    "data": {
        "prediction_id": "pred-uuid-1",
        "product_id": "P001",
        "model_type": "mlstm",
        "predictions": [{"date": "2023-12-21", "predicted_sales": 110}],
        "analysis": {"trend": "upward"}
    }
}
  • 404: 记录不存在。

DELETE /api/prediction/history/{prediction_id}

摘要: 删除预测记录

路径参数:

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

响应:

  • 200: 删除成功。 
    {
    "status": "success",
    "message": "预测记录已删除"
}
  • 404: 记录不存在。

模型管理

模型查询、导出和删除接口。

GET /api/models

摘要: 获取模型列表

查询参数:

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

响应:

  • 200: 获取成功。 
    {
    "status": "success",
    "data": [
        {
            "model_id": "P001_mlstm_v1",
            "product_id": "P001",
            "model_type": "mlstm",
            "version": "v1",
            "created_at": "2023-12-15T09:00:00Z"
        }
    ]
}

GET /api/models/{model_id}

摘要: 获取模型详情

路径参数:

  • model_id (string, required): 模型ID。

响应:

  • 200: 获取成功。 
    {
    "status": "success",
    "data": {
        "model_id": "P001_mlstm_v1",
        "product_id": "P001",
        "model_type": "mlstm",
        "version": "v1",
        "metrics": {"R2": 0.95, "RMSE": 5.5}
    }
}
  • 404: 模型不存在。

DELETE /api/models/{model_id}

摘要: 删除模型

路径参数:

  • model_id (string, required): 模型ID。

响应:

  • 200: 删除成功。 
    {
    "status": "success",
    "message": "模型已删除"
}
  • 404: 模型不存在。

GET /api/models/{model_id}/export

摘要: 导出模型

路径参数:

  • model_id (string, required): 模型ID。

响应:

  • 200: 模型文件下载 (二进制流)。
  • 404: 模型不存在。

GET /api/model_types

摘要: 获取系统支持的所有模型类型

响应:

  • 200: 获取成功。 
    {
    "status": "success",
    "data": [
        {"id": "mlstm", "name": "mLSTM"},
        {"id": "transformer", "name": "Transformer"}
    ]
}

GET /api/models/{product_id}/{model_type}/versions

摘要: 获取模型版本列表

路径参数:

  • product_id (string, required): 产品ID。
  • model_type (string, required): 模型类型。

响应:

  • 200: 获取成功。 
    {
    "status": "success",
    "data": {
        "product_id": "P001",
        "model_type": "mlstm",
        "versions": ["v1", "v2"],
        "latest_version": "v2"
    }
}