From 54f3fc6f61d9be6df817cabc88a962f1fd7a125d Mon Sep 17 00:00:00 2001
From: xz2000 <xz20000522@163.com>
Date: Wed, 23 Jul 2025 17:09:33 +0800
Subject: [PATCH] =?UTF-8?q?=E7=B3=BB=E7=BB=9FAPI=E6=B3=A8=E8=A7=A3?=
 =?UTF-8?q?=E5=92=8Cswagger=E8=AE=BF=E9=97=AE?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 server/swagger.json | 581 ++++++++++++++++++++++++++++++++++++++++++--
 1 file changed, 554 insertions(+), 27 deletions(-)

diff --git a/server/swagger.json b/server/swagger.json
index cbbe573..08d786d 100644
--- a/server/swagger.json
+++ b/server/swagger.json
@@ -41,14 +41,14 @@
                 "schema": {
                   "type": "object",
                   "properties": {
-                    "status": {"type": "string"},
+                    "status": {"type": "string", "example": "success"},
                     "data": {
                       "type": "array",
                       "items": {
                         "type": "object",
                         "properties": {
-                          "product_id": {"type": "string"},
-                          "product_name": {"type": "string"}
+                          "product_id": {"type": "string", "example": "P001"},
+                          "product_name": {"type": "string", "example": "产品A"}
                         }
                       }
                     }
@@ -76,7 +76,34 @@
           }
         ],
         "responses": {
-          "200": {"description": "成功获取产品详情"},
+          "200": {
+            "description": "成功获取产品详情",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "status": {"type": "string", "example": "success"},
+                    "data": {
+                      "type": "object",
+                      "properties": {
+                        "product_id": {"type": "string", "example": "P001"},
+                        "product_name": {"type": "string", "example": "产品A"},
+                        "data_points": {"type": "integer", "example": 365},
+                        "date_range": {
+                          "type": "object",
+                          "properties": {
+                            "start": {"type": "string", "example": "2023-01-01"},
+                            "end": {"type": "string", "example": "2023-12-31"}
+                          }
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
           "404": {"description": "产品不存在"},
           "500": {"description": "服务器内部错误"}
         }
@@ -109,7 +136,29 @@
           }
         ],
         "responses": {
-          "200": {"description": "成功获取销售数据"},
+          "200": {
+            "description": "成功获取销售数据",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "status": {"type": "string", "example": "success"},
+                    "data": {
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "properties": {
+                          "date": {"type": "string", "example": "2023-12-01"},
+                          "sales": {"type": "integer", "example": 150}
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
           "404": {"description": "产品不存在"},
           "500": {"description": "服务器内部错误"}
         }
@@ -136,7 +185,27 @@
           }
         },
         "responses": {
-          "200": {"description": "数据上传成功"},
+          "200": {
+            "description": "数据上传成功",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "status": {"type": "string", "example": "success"},
+                    "message": {"type": "string", "example": "数据上传成功"},
+                    "data": {
+                      "type": "object",
+                      "properties": {
+                        "products": {"type": "integer", "example": 10},
+                        "rows": {"type": "integer", "example": 3650}
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
           "400": {"description": "请求错误"},
           "500": {"description": "服务器内部错误"}
         }
@@ -148,7 +217,35 @@
         "summary": "获取所有训练任务列表",
         "description": "返回所有正在进行、已完成或失败的训练任务",
         "responses": {
-          "200": {"description": "成功获取任务列表"}
+          "200": {
+            "description": "成功获取任务列表",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "status": {"type": "string", "example": "success"},
+                    "data": {
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "properties": {
+                          "task_id": {"type": "string", "example": "uuid-1234"},
+                          "product_id": {"type": "string", "example": "P001"},
+                          "model_type": {"type": "string", "example": "mlstm"},
+                          "status": {"type": "string", "example": "completed"},
+                          "start_time": {"type": "string", "example": "2023-12-25T10:00:00Z"},
+                          "metrics": {"type": "object", "example": {"R2": 0.95, "RMSE": 5.5}},
+                          "error": {"type": "string", "nullable": true},
+                          "model_path": {"type": "string", "example": "/path/to/model.pth"}
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
         }
       },
       "post": {
@@ -173,7 +270,20 @@
           }
         },
         "responses": {
-          "200": {"description": "训练任务已启动"},
+          "200": {
+            "description": "训练任务已启动",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "message": {"type": "string", "example": "模型训练已开始"},
+                    "task_id": {"type": "string", "example": "new-uuid-5678"}
+                  }
+                }
+              }
+            }
+          },
           "400": {"description": "请求错误"}
         }
       }
@@ -193,7 +303,29 @@
           }
         ],
         "responses": {
-          "200": {"description": "成功获取任务状态"},
+          "200": {
+            "description": "成功获取任务状态",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "status": {"type": "string", "example": "success"},
+                    "data": {
+                      "type": "object",
+                      "properties": {
+                        "product_id": {"type": "string", "example": "P001"},
+                        "model_type": {"type": "string", "example": "mlstm"},
+                        "status": {"type": "string", "example": "running"},
+                        "progress": {"type": "number", "example": 50.5},
+                        "created_at": {"type": "string", "example": "2023-12-25T10:00:00Z"}
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
           "404": {"description": "任务不存在"},
           "500": {"description": "服务器内部错误"}
         }
@@ -225,7 +357,38 @@
           }
         },
         "responses": {
-          "200": {"description": "预测成功"},
+          "200": {
+            "description": "预测成功",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "status": {"type": "string", "example": "success"},
+                    "data": {
+                      "type": "object",
+                      "properties": {
+                        "product_id": {"type": "string", "example": "P001"},
+                        "product_name": {"type": "string", "example": "产品A"},
+                        "model_type": {"type": "string", "example": "mlstm"},
+                        "predictions": {
+                          "type": "array",
+                          "items": {
+                            "type": "object",
+                            "properties": {
+                              "date": {"type": "string", "example": "2024-01-01"},
+                              "predicted_sales": {"type": "integer", "example": 100}
+                            }
+                          }
+                        },
+                        "visualization": {"type": "string", "example": "base64-encoded-image-string"}
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
           "400": {"description": "请求错误"},
           "404": {"description": "产品或模型不存在"},
           "500": {"description": "服务器内部错误"}
@@ -255,7 +418,37 @@
           }
         },
         "responses": {
-          "200": {"description": "比较成功"},
+          "200": {
+            "description": "比较成功",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "status": {"type": "string", "example": "success"},
+                    "data": {
+                      "type": "object",
+                      "properties": {
+                        "product_id": {"type": "string", "example": "P001"},
+                        "comparison": {
+                          "type": "array",
+                          "items": {
+                            "type": "object",
+                            "properties": {
+                              "date": {"type": "string", "example": "2024-01-01"},
+                              "mlstm": {"type": "integer", "example": 100},
+                              "transformer": {"type": "integer", "example": 102}
+                            }
+                          }
+                        },
+                        "visualization": {"type": "string", "example": "base64-encoded-image-string"}
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
           "400": {"description": "请求错误"},
           "404": {"description": "产品或模型不存在"},
           "500": {"description": "服务器内部错误"}
@@ -267,7 +460,31 @@
         "tags": ["模型预测"],
         "summary": "获取历史预测记录",
         "responses": {
-          "200": {"description": "获取成功"}
+          "200": {
+            "description": "获取成功",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "status": {"type": "string", "example": "success"},
+                    "data": {
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "properties": {
+                          "prediction_id": {"type": "string", "example": "pred-uuid-1"},
+                          "product_id": {"type": "string", "example": "P001"},
+                          "model_type": {"type": "string", "example": "mlstm"},
+                          "created_at": {"type": "string", "example": "2023-12-20T11:00:00Z"}
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
         }
       }
     },
@@ -284,7 +501,38 @@
           }
         ],
         "responses": {
-          "200": {"description": "获取成功"},
+          "200": {
+            "description": "获取成功",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "status": {"type": "string", "example": "success"},
+                    "data": {
+                      "type": "object",
+                      "properties": {
+                        "prediction_id": {"type": "string", "example": "pred-uuid-1"},
+                        "product_id": {"type": "string", "example": "P001"},
+                        "model_type": {"type": "string", "example": "mlstm"},
+                        "predictions": {
+                          "type": "array",
+                          "items": {
+                            "type": "object",
+                            "properties": {
+                              "date": {"type": "string", "example": "2023-12-21"},
+                              "predicted_sales": {"type": "integer", "example": 110}
+                            }
+                          }
+                        },
+                        "analysis": {"type": "object", "example": {"trend": "upward"}}
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
           "404": {"description": "记录不存在"}
         }
       },
@@ -300,7 +548,20 @@
           }
         ],
         "responses": {
-          "200": {"description": "删除成功"},
+          "200": {
+            "description": "删除成功",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "status": {"type": "string", "example": "success"},
+                    "message": {"type": "string", "example": "预测记录已删除"}
+                  }
+                }
+              }
+            }
+          },
           "404": {"description": "记录不存在"}
         }
       }
@@ -314,7 +575,32 @@
           {"name": "model_type", "in": "query", "schema": {"type": "string"}}
         ],
         "responses": {
-          "200": {"description": "获取成功"}
+          "200": {
+            "description": "获取成功",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "status": {"type": "string", "example": "success"},
+                    "data": {
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "properties": {
+                          "model_id": {"type": "string", "example": "P001_mlstm_v1"},
+                          "product_id": {"type": "string", "example": "P001"},
+                          "model_type": {"type": "string", "example": "mlstm"},
+                          "version": {"type": "string", "example": "v1"},
+                          "created_at": {"type": "string", "example": "2023-12-15T09:00:00Z"}
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
         }
       }
     },
@@ -326,7 +612,29 @@
           {"name": "model_id", "in": "path", "required": true, "schema": {"type": "string"}}
         ],
         "responses": {
-          "200": {"description": "获取成功"},
+          "200": {
+            "description": "获取成功",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "status": {"type": "string", "example": "success"},
+                    "data": {
+                      "type": "object",
+                      "properties": {
+                        "model_id": {"type": "string", "example": "P001_mlstm_v1"},
+                        "product_id": {"type": "string", "example": "P001"},
+                        "model_type": {"type": "string", "example": "mlstm"},
+                        "version": {"type": "string", "example": "v1"},
+                        "metrics": {"type": "object", "example": {"R2": 0.95, "RMSE": 5.5}}
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
           "404": {"description": "模型不存在"}
         }
       },
@@ -337,7 +645,20 @@
           {"name": "model_id", "in": "path", "required": true, "schema": {"type": "string"}}
         ],
         "responses": {
-          "200": {"description": "删除成功"},
+          "200": {
+            "description": "删除成功",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "status": {"type": "string", "example": "success"},
+                    "message": {"type": "string", "example": "模型已删除"}
+                  }
+                }
+              }
+            }
+          },
           "404": {"description": "模型不存在"}
         }
       }
@@ -360,7 +681,29 @@
         "tags": ["模型管理"],
         "summary": "获取系统支持的所有模型类型",
         "responses": {
-          "200": {"description": "获取成功"}
+          "200": {
+            "description": "获取成功",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "status": {"type": "string", "example": "success"},
+                    "data": {
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "properties": {
+                          "id": {"type": "string", "example": "mlstm"},
+                          "name": {"type": "string", "example": "mLSTM"}
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
         }
       }
     },
@@ -373,7 +716,28 @@
           {"name": "model_type", "in": "path", "required": true, "schema": {"type": "string"}}
         ],
         "responses": {
-          "200": {"description": "获取成功"}
+          "200": {
+            "description": "获取成功",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "status": {"type": "string", "example": "success"},
+                    "data": {
+                      "type": "object",
+                      "properties": {
+                        "product_id": {"type": "string", "example": "P001"},
+                        "model_type": {"type": "string", "example": "mlstm"},
+                        "versions": {"type": "array", "items": {"type": "string"}, "example": ["v1", "v2"]},
+                        "latest_version": {"type": "string", "example": "v2"}
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
         }
       }
     },
@@ -382,14 +746,56 @@
         "tags": ["数据管理"],
         "summary": "获取所有店铺列表",
         "responses": {
-          "200": {"description": "获取成功"}
+          "200": {
+            "description": "获取成功",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "status": {"type": "string", "example": "success"},
+                    "data": {
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "properties": {
+                          "store_id": {"type": "string", "example": "S001"},
+                          "store_name": {"type": "string", "example": "第一分店"}
+                        }
+                      }
+                    },
+                    "count": {"type": "integer", "example": 2}
+                  }
+                }
+              }
+            }
+          }
         }
       },
       "post": {
         "tags": ["数据管理"],
         "summary": "创建新店铺",
         "responses": {
-          "200": {"description": "创建成功"}
+          "200": {
+            "description": "创建成功",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "status": {"type": "string", "example": "success"},
+                    "message": {"type": "string", "example": "店铺创建成功"},
+                    "data": {
+                      "type": "object",
+                      "properties": {
+                        "store_id": {"type": "string", "example": "S003"}
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
         }
       }
     },
@@ -401,7 +807,31 @@
           {"name": "store_id", "in": "path", "required": true, "schema": {"type": "string"}}
         ],
         "responses": {
-          "200": {"description": "获取成功"},
+          "200": {
+            "description": "获取成功",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "status": {"type": "string", "example": "success"},
+                    "data": {
+                      "type": "object",
+                      "properties": {
+                        "store_id": {"type": "string", "example": "S001"},
+                        "store_name": {"type": "string", "example": "第一分店"},
+                        "location": {"type": "string", "example": "市中心"},
+                        "size": {"type": "number", "example": 120.5},
+                        "type": {"type": "string", "example": "旗舰店"},
+                        "opening_date": {"type": "string", "example": "2022-01-01"},
+                        "status": {"type": "string", "example": "active"}
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          },
           "404": {"description": "店铺不存在"}
         }
       },
@@ -412,7 +842,20 @@
           {"name": "store_id", "in": "path", "required": true, "schema": {"type": "string"}}
         ],
         "responses": {
-          "200": {"description": "更新成功"},
+          "200": {
+            "description": "更新成功",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "status": {"type": "string", "example": "success"},
+                    "message": {"type": "string", "example": "店铺更新成功"}
+                  }
+                }
+              }
+            }
+          },
           "404": {"description": "店铺不存在"}
         }
       },
@@ -423,7 +866,20 @@
           {"name": "store_id", "in": "path", "required": true, "schema": {"type": "string"}}
         ],
         "responses": {
-          "200": {"description": "删除成功"},
+          "200": {
+            "description": "删除成功",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "status": {"type": "string", "example": "success"},
+                    "message": {"type": "string", "example": "店铺删除成功"}
+                  }
+                }
+              }
+            }
+          },
           "404": {"description": "店铺不存在"}
         }
       }
@@ -436,7 +892,30 @@
           {"name": "store_id", "in": "path", "required": true, "schema": {"type": "string"}}
         ],
         "responses": {
-          "200": {"description": "获取成功"}
+          "200": {
+            "description": "获取成功",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "status": {"type": "string", "example": "success"},
+                    "data": {
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "properties": {
+                          "product_id": {"type": "string", "example": "P001"},
+                          "product_name": {"type": "string", "example": "产品A"}
+                        }
+                      }
+                    },
+                    "count": {"type": "integer", "example": 1}
+                  }
+                }
+              }
+            }
+          }
         }
       }
     },
@@ -448,7 +927,27 @@
           {"name": "store_id", "in": "path", "required": true, "schema": {"type": "string"}}
         ],
         "responses": {
-          "200": {"description": "获取成功"}
+          "200": {
+            "description": "获取成功",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "status": {"type": "string", "example": "success"},
+                    "data": {
+                      "type": "object",
+                      "properties": {
+                        "total_sales": {"type": "number", "example": 150000.0},
+                        "total_quantity": {"type": "integer", "example": 7500},
+                        "products_count": {"type": "integer", "example": 50}
+                      }
+                    }
+                  }
+                }
+              }
+            }
+          }
         }
       }
     },
@@ -457,7 +956,35 @@
         "tags": ["数据管理"],
         "summary": "获取销售数据列表",
         "responses": {
-          "200": {"description": "获取成功"}
+          "200": {
+            "description": "获取成功",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "type": "object",
+                  "properties": {
+                    "status": {"type": "string", "example": "success"},
+                    "data": {
+                      "type": "array",
+                      "items": {
+                        "type": "object",
+                        "properties": {
+                          "date": {"type": "string", "example": "2023-12-01"},
+                          "store_id": {"type": "string", "example": "S001"},
+                          "product_id": {"type": "string", "example": "P001"},
+                          "sales": {"type": "integer", "example": 150},
+                          "price": {"type": "number", "example": 25.5}
+                        }
+                      }
+                    },
+                    "total": {"type": "integer", "example": 100},
+                    "page": {"type": "integer", "example": 1},
+                    "page_size": {"type": "integer", "example": 1}
+                  }
+                }
+              }
+            }
+          }
         }
       }
     }