679 lines
13 KiB
Markdown
679 lines
13 KiB
Markdown
## 访问Swagger UI：
|
||
## 服务启动后，在您的浏览器中打开以下地址即可查看交互式API文档：
|
||
## http://localhost:5173/swagger/
|
||
## 文件路径：C:\WorkSpace\ShopTRAINING\server\swagger.json
|
||
|
||
# 药店销售预测系统 API 文档
|
||
|
||
**版本:** 1.0.0
|
||
**联系方式:** [API开发团队](mailto:support@example.com)
|
||
|
||
本文档详细描述了用于药店销售预测的RESTful API。
|
||
|
||
---
|
||
|
||
## 数据管理
|
||
|
||
数据上传和查询相关接口。
|
||
|
||
### `GET /api/products`
|
||
|
||
**摘要:** 获取所有产品列表
|
||
|
||
**描述:** 返回系统中所有产品的ID和名称。
|
||
|
||
**响应:**
|
||
* `200`: 成功获取产品列表。
|
||
```json
|
||
{
|
||
"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`: 成功获取产品详情。
|
||
```json
|
||
{
|
||
"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`: 成功获取销售数据。
|
||
```json
|
||
{
|
||
"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`: 数据上传成功。
|
||
```json
|
||
{
|
||
"status": "success",
|
||
"message": "数据上传成功",
|
||
"data": {
|
||
"products": 10,
|
||
"rows": 3650
|
||
}
|
||
}
|
||
```
|
||
* `400`: 请求错误。
|
||
* `500`: 服务器内部错误。
|
||
|
||
---
|
||
|
||
### `GET /api/stores`
|
||
|
||
**摘要:** 获取所有店铺列表
|
||
|
||
**响应:**
|
||
* `200`: 获取成功。
|
||
```json
|
||
{
|
||
"status": "success",
|
||
"data": [
|
||
{
|
||
"store_id": "S001",
|
||
"store_name": "第一分店"
|
||
},
|
||
{
|
||
"store_id": "S002",
|
||
"store_name": "第二分店"
|
||
}
|
||
],
|
||
"count": 2
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### `POST /api/stores`
|
||
|
||
**摘要:** 创建新店铺
|
||
|
||
**响应:**
|
||
* `200`: 创建成功。
|
||
```json
|
||
{
|
||
"status": "success",
|
||
"message": "店铺创建成功",
|
||
"data": {
|
||
"store_id": "S003"
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### `GET /api/stores/{store_id}`
|
||
|
||
**摘要:** 获取单个店铺信息
|
||
|
||
**路径参数:**
|
||
* `store_id` (string, required): 店铺ID。
|
||
|
||
**响应:**
|
||
* `200`: 获取成功。
|
||
```json
|
||
{
|
||
"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`: 更新成功。
|
||
```json
|
||
{
|
||
"status": "success",
|
||
"message": "店铺更新成功"
|
||
}
|
||
```
|
||
* `404`: 店铺不存在。
|
||
|
||
---
|
||
|
||
### `DELETE /api/stores/{store_id}`
|
||
|
||
**摘要:** 删除店铺
|
||
|
||
**路径参数:**
|
||
* `store_id` (string, required): 店铺ID。
|
||
|
||
**响应:**
|
||
* `200`: 删除成功。
|
||
```json
|
||
{
|
||
"status": "success",
|
||
"message": "店铺删除成功"
|
||
}
|
||
```
|
||
* `404`: 店铺不存在。
|
||
|
||
---
|
||
|
||
### `GET /api/stores/{store_id}/products`
|
||
|
||
**摘要:** 获取店铺的产品列表
|
||
|
||
**路径参数:**
|
||
* `store_id` (string, required): 店铺ID。
|
||
|
||
**响应:**
|
||
* `200`: 获取成功。
|
||
```json
|
||
{
|
||
"status": "success",
|
||
"data": [
|
||
{
|
||
"product_id": "P001",
|
||
"product_name": "产品A"
|
||
}
|
||
],
|
||
"count": 1
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### `GET /api/stores/{store_id}/statistics`
|
||
|
||
**摘要:** 获取店铺销售统计信息
|
||
|
||
**路径参数:**
|
||
* `store_id` (string, required): 店铺ID。
|
||
|
||
**响应:**
|
||
* `200`: 获取成功。
|
||
```json
|
||
{
|
||
"status": "success",
|
||
"data": {
|
||
"total_sales": 150000.0,
|
||
"total_quantity": 7500,
|
||
"products_count": 50
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
### `GET /api/sales/data`
|
||
|
||
**摘要:** 获取销售数据列表
|
||
|
||
**响应:**
|
||
* `200`: 获取成功。
|
||
```json
|
||
{
|
||
"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`: 成功获取任务列表。
|
||
```json
|
||
{
|
||
"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`
|
||
```json
|
||
{
|
||
"product_id": "P001",
|
||
"model_type": "mlstm",
|
||
"store_id": "S001",
|
||
"epochs": 50
|
||
}
|
||
```
|
||
|
||
**响应:**
|
||
* `200`: 训练任务已启动。
|
||
```json
|
||
{
|
||
"message": "模型训练已开始",
|
||
"task_id": "new-uuid-5678"
|
||
}
|
||
```
|
||
* `400`: 请求错误。
|
||
|
||
---
|
||
|
||
### `GET /api/training/{task_id}`
|
||
|
||
**摘要:** 查询训练任务状态
|
||
|
||
**描述:** 获取特定训练任务的当前状态和详情。
|
||
|
||
**路径参数:**
|
||
* `task_id` (string, required): 训练任务ID。
|
||
|
||
**响应:**
|
||
* `200`: 成功获取任务状态。
|
||
```json
|
||
{
|
||
"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`
|
||
```json
|
||
{
|
||
"product_id": "string",
|
||
"model_type": "mlstm",
|
||
"store_id": "string",
|
||
"version": "string",
|
||
"future_days": 7,
|
||
"include_visualization": true,
|
||
"start_date": "2024-01-01"
|
||
}
|
||
```
|
||
|
||
**响应:**
|
||
* `200`: 预测成功。
|
||
```json
|
||
{
|
||
"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`
|
||
```json
|
||
{
|
||
"product_id": "string",
|
||
"model_types": ["mlstm", "transformer"],
|
||
"versions": ["v1", "v2"],
|
||
"include_visualization": true
|
||
}
|
||
```
|
||
|
||
**响应:**
|
||
* `200`: 比较成功。
|
||
```json
|
||
{
|
||
"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`: 获取成功。
|
||
```json
|
||
{
|
||
"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`: 获取成功。
|
||
```json
|
||
{
|
||
"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`: 删除成功。
|
||
```json
|
||
{
|
||
"status": "success",
|
||
"message": "预测记录已删除"
|
||
}
|
||
```
|
||
* `404`: 记录不存在。
|
||
|
||
---
|
||
|
||
## 模型管理
|
||
|
||
模型查询、导出和删除接口。
|
||
|
||
### `GET /api/models`
|
||
|
||
**摘要:** 获取模型列表
|
||
|
||
**查询参数:**
|
||
* `product_id` (string): 按产品ID筛选。
|
||
* `model_type` (string): 按模型类型筛选。
|
||
|
||
**响应:**
|
||
* `200`: 获取成功。
|
||
```json
|
||
{
|
||
"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`: 获取成功。
|
||
```json
|
||
{
|
||
"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`: 删除成功。
|
||
```json
|
||
{
|
||
"status": "success",
|
||
"message": "模型已删除"
|
||
}
|
||
```
|
||
* `404`: 模型不存在。
|
||
|
||
---
|
||
|
||
### `GET /api/models/{model_id}/export`
|
||
|
||
**摘要:** 导出模型
|
||
|
||
**路径参数:**
|
||
* `model_id` (string, required): 模型ID。
|
||
|
||
**响应:**
|
||
* `200`: 模型文件下载 (二进制流)。
|
||
* `404`: 模型不存在。
|
||
|
||
---
|
||
|
||
### `GET /api/model_types`
|
||
|
||
**摘要:** 获取系统支持的所有模型类型
|
||
|
||
**响应:**
|
||
* `200`: 获取成功。
|
||
```json
|
||
{
|
||
"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`: 获取成功。
|
||
```json
|
||
{
|
||
"status": "success",
|
||
"data": {
|
||
"product_id": "P001",
|
||
"model_type": "mlstm",
|
||
"versions": ["v1", "v2"],
|
||
"latest_version": "v2"
|
||
}
|
||
} |