## 访问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"
        }
    }