{
  "openapi": "3.0.0",
  "info": {
    "title": "Steel Prices Service API",
    "version": "1.0.0",
    "description": "\n        钢材价格查询与分析服务平台 API 文档\n\n        ## 功能特性\n        - 📊 **价格查询** - 按地区、材质、规格等多维度查询钢材价格\n        - 🔍 **智能搜索** - 支持多条件组合搜索和分页\n        - 📈 **统计分析** - 价格统计、趋势分析、均价计算\n        - 💾 **数据导入** - 批量导入钢材价格数据\n        - 🚀 **高性能** - 数据库索引优化，查询响应快速\n\n        ## 数据源\n        - 我的钢铁网（重庆、成都、广州、南宁）\n        - 德钢指导价（云南地区）\n        - 云南钢协（昆明、玉溪、楚雄、大理）\n\n        ## 认证\n        当前版本无需认证，后续版本将添加 API Key 认证。\n      ",
    "contact": {
      "name": "Steel Prices Service",
      "email": "support@example.com"
    },
    "license": {
      "name": "MIT",
      "url": "https://opensource.org/licenses/MIT"
    }
  },
  "servers": [
    {
      "url": "http://localhost:3000",
      "description": "开发服务器"
    },
    {
      "url": "https://api.steel-prices.com",
      "description": "生产服务器"
    }
  ],
  "tags": [
    {
      "name": "Health",
      "description": "健康检查和系统状态"
    },
    {
      "name": "Prices",
      "description": "价格查询、搜索和统计分析"
    },
    {
      "name": "Data",
      "description": "数据导入和管理"
    }
  ],
  "components": {
    "schemas": {
      "Price": {
        "type": "object",
        "description": "钢材价格数据模型",
        "properties": {
          "id": {
            "type": "integer",
            "description": "价格记录ID",
            "example": 1
          },
          "region": {
            "type": "string",
            "description": "地区",
            "example": "昆明"
          },
          "city": {
            "type": "string",
            "description": "城市",
            "example": "昆明",
            "nullable": true
          },
          "material": {
            "type": "string",
            "description": "材质",
            "example": "HPB300"
          },
          "specification": {
            "type": "string",
            "description": "规格型号",
            "example": "Φ8",
            "nullable": true
          },
          "price": {
            "type": "number",
            "format": "decimal",
            "description": "价格（元/吨）",
            "example": 3840
          },
          "unit": {
            "type": "string",
            "description": "单位",
            "example": "元/吨"
          },
          "date": {
            "type": "string",
            "format": "date",
            "description": "价格日期",
            "example": "2026-01-05"
          },
          "source": {
            "type": "string",
            "description": "数据来源",
            "example": "云南钢协",
            "nullable": true
          },
          "warehouse": {
            "type": "string",
            "description": "仓库/厂家",
            "example": "玉昆",
            "nullable": true
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "description": "创建时间"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "description": "更新时间"
          }
        },
        "required": [
          "region",
          "material",
          "price",
          "date"
        ]
      },
      "SuccessResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": true
          },
          "data": {
            "type": "object"
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": false
          },
          "message": {
            "type": "string",
            "description": "错误信息",
            "example": "参数验证失败"
          },
          "statusCode": {
            "type": "integer",
            "description": "HTTP 状态码",
            "example": 400
          }
        }
      },
      "Pagination": {
        "type": "object",
        "properties": {
          "page": {
            "type": "integer",
            "description": "当前页码",
            "example": 1
          },
          "pageSize": {
            "type": "integer",
            "description": "每页数量",
            "example": 20
          },
          "total": {
            "type": "integer",
            "description": "总记录数",
            "example": 100
          },
          "totalPages": {
            "type": "integer",
            "description": "总页数",
            "example": 5
          }
        }
      },
      "PriceStats": {
        "type": "object",
        "properties": {
          "count": {
            "type": "integer",
            "description": "记录数量",
            "example": 150
          },
          "avgPrice": {
            "type": "number",
            "description": "平均价格",
            "example": 3950.5
          },
          "minPrice": {
            "type": "number",
            "description": "最低价格",
            "example": 3500
          },
          "maxPrice": {
            "type": "number",
            "description": "最高价格",
            "example": 4500
          },
          "stdDev": {
            "type": "number",
            "description": "标准差",
            "example": 250.3
          },
          "trend": {
            "type": "string",
            "enum": [
              "up",
              "down",
              "stable"
            ],
            "description": "价格趋势",
            "example": "up"
          },
          "changeRate": {
            "type": "string",
            "description": "变化率",
            "example": "+2.5%"
          }
        }
      },
      "TrendData": {
        "type": "object",
        "properties": {
          "date": {
            "type": "string",
            "format": "date",
            "description": "日期",
            "example": "2026-01-05"
          },
          "avgPrice": {
            "type": "number",
            "description": "当日平均价格",
            "example": 3950.5
          },
          "minPrice": {
            "type": "number",
            "description": "当日最低价格",
            "example": 3800
          },
          "maxPrice": {
            "type": "number",
            "description": "当日最高价格",
            "example": 4100
          }
        }
      }
    },
    "parameters": {
      "RegionParam": {
        "name": "region",
        "in": "query",
        "description": "地区名称（如：昆明、玉溪、大理等）",
        "required": true,
        "schema": {
          "type": "string"
        },
        "example": "昆明"
      },
      "DateParam": {
        "name": "date",
        "in": "query",
        "description": "价格日期（格式：YYYY-MM-DD）",
        "required": false,
        "schema": {
          "type": "string",
          "format": "date"
        },
        "example": "2026-01-05"
      },
      "MaterialParam": {
        "name": "material",
        "in": "query",
        "description": "材质（如：HPB300、HRB400、HRB500E 等）",
        "required": false,
        "schema": {
          "type": "string"
        },
        "example": "HPB300"
      },
      "DaysParam": {
        "name": "days",
        "in": "query",
        "description": "统计天数（1-3650天）",
        "required": false,
        "schema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 3650
        },
        "example": 30
      },
      "PageParam": {
        "name": "page",
        "in": "query",
        "description": "页码（从1开始）",
        "required": false,
        "schema": {
          "type": "integer",
          "minimum": 1,
          "default": 1
        },
        "example": 1
      },
      "PageSizeParam": {
        "name": "pageSize",
        "in": "query",
        "description": "每页数量（1-1000）",
        "required": false,
        "schema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 1000,
          "default": 20
        },
        "example": 20
      }
    }
  },
  "paths": {
    "/api/health": {
      "get": {
        "tags": [
          "Health"
        ],
        "summary": "健康检查",
        "description": "检查服务是否正常运行",
        "responses": {
          "200": {
            "description": "服务正常",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "success": {
                      "type": "boolean",
                      "example": true
                    },
                    "message": {
                      "type": "string",
                      "example": "Steel Prices Service is running"
                    },
                    "timestamp": {
                      "type": "string",
                      "format": "date-time"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/prices/region": {
      "get": {
        "tags": [
          "Prices"
        ],
        "summary": "按地区查询价格",
        "description": "根据地区和日期查询钢材价格数据，支持按日期筛选或查询该地区所有价格数据",
        "parameters": [
          {
            "$ref": "#/components/parameters/RegionParam"
          },
          {
            "$ref": "#/components/parameters/DateParam"
          }
        ],
        "responses": {
          "200": {
            "description": "查询成功",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessResponse"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/Price"
                          }
                        },
                        "total": {
                          "type": "integer",
                          "description": "返回的记录数量",
                          "example": 50
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "参数错误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "服务器错误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        },
        "examples": {
          "query_by_region_and_date": {
            "summary": "查询昆明地区 2026-01-05 的价格",
            "value": {
              "region": "昆明",
              "date": "2026-01-05"
            }
          },
          "query_by_region_only": {
            "summary": "查询昆明地区所有价格数据",
            "value": {
              "region": "昆明"
            }
          }
        }
      }
    },
    "/api/prices/search": {
      "get": {
        "tags": [
          "Prices"
        ],
        "summary": "搜索价格数据",
        "description": "根据多个条件组合搜索钢材价格数据，支持分页返回结果。\n\n**搜索条件：**\n- material: 材质（支持模糊搜索）\n- specification: 规格型号（支持模糊搜索）\n- startDate: 开始日期\n- endDate: 结束日期\n- region: 地区\n\n**分页参数：**\n- page: 页码（默认 1）\n- pageSize: 每页数量（默认 20，最大 1000）\n",
        "parameters": [
          {
            "name": "material",
            "in": "query",
            "description": "材质（支持模糊搜索，如：HPB300、HRB400、HRB500E）",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "HPB300"
          },
          {
            "name": "specification",
            "in": "query",
            "description": "规格型号（支持模糊搜索，如：Φ8、Φ16、HRB400）",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "Φ8"
          },
          {
            "name": "startDate",
            "in": "query",
            "description": "开始日期（格式：YYYY-MM-DD）",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date"
            },
            "example": "2026-01-01"
          },
          {
            "name": "endDate",
            "in": "query",
            "description": "结束日期（格式：YYYY-MM-DD）",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date"
            },
            "example": "2026-01-05"
          },
          {
            "name": "region",
            "in": "query",
            "description": "地区",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "昆明"
          },
          {
            "$ref": "#/components/parameters/PageParam"
          },
          {
            "$ref": "#/components/parameters/PageSizeParam"
          }
        ],
        "responses": {
          "200": {
            "description": "搜索成功",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessResponse"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/Price"
                          }
                        },
                        "pagination": {
                          "$ref": "#/components/schemas/Pagination"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "参数错误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "服务器错误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        },
        "examples": {
          "search_by_material": {
            "summary": "按材质搜索",
            "value": {
              "material": "HPB300",
              "page": 1,
              "pageSize": 20
            }
          },
          "search_by_date_range": {
            "summary": "按日期范围搜索",
            "value": {
              "material": "HRB400",
              "startDate": "2026-01-01",
              "endDate": "2026-01-05",
              "page": 1,
              "pageSize": 50
            }
          }
        }
      }
    },
    "/api/prices/stats": {
      "get": {
        "tags": [
          "Prices"
        ],
        "summary": "获取价格统计",
        "description": "获取钢材价格的统计数据，包括平均值、最大值、最小值、标准差等。\n\n**筛选条件：**\n- region: 指定地区\n- material: 指定材质\n- days: 统计最近 N 天的数据\n- startDate/endDate: 指定日期范围\n\n**统计指标：**\n- count: 记录数量\n- avgPrice: 平均价格\n- minPrice: 最低价格\n- maxPrice: 最高价格\n- stdDev: 标准差\n- trend: 价格趋势（up/down/stable）\n- changeRate: 变化率（相对于上一周期）\n",
        "parameters": [
          {
            "name": "region",
            "in": "query",
            "description": "地区（可选）",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "昆明"
          },
          {
            "name": "material",
            "in": "query",
            "description": "材质（可选，支持模糊搜索）",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "HPB300"
          },
          {
            "$ref": "#/components/parameters/DaysParam"
          },
          {
            "name": "startDate",
            "in": "query",
            "description": "开始日期（格式：YYYY-MM-DD）",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date"
            },
            "example": "2026-01-01"
          },
          {
            "name": "endDate",
            "in": "query",
            "description": "结束日期（格式：YYYY-MM-DD）",
            "required": false,
            "schema": {
              "type": "string",
              "format": "date"
            },
            "example": "2026-01-05"
          }
        ],
        "responses": {
          "200": {
            "description": "统计成功",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessResponse"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/PriceStats"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "参数错误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "服务器错误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        },
        "examples": {
          "stats_by_region_and_days": {
            "summary": "统计昆明地区最近 30 天的 HPB300 价格",
            "value": {
              "region": "昆明",
              "material": "HPB300",
              "days": 30
            }
          },
          "stats_by_date_range": {
            "summary": "统计指定日期范围内的价格",
            "value": {
              "startDate": "2026-01-01",
              "endDate": "2026-01-05"
            }
          }
        }
      }
    },
    "/api/prices/trend": {
      "get": {
        "tags": [
          "Prices"
        ],
        "summary": "获取价格趋势",
        "description": "获取钢材价格的时间序列趋势数据，按日期分组统计。\n\n**筛选条件：**\n- region: 指定地区\n- material: 指定材质\n- days: 统计最近 N 天的数据\n\n**返回数据：**\n- date: 日期\n- avgPrice: 当日平均价格\n- minPrice: 当日最低价格\n- maxPrice: 当日最高价格\n\n**适用场景：**\n- 绘制价格走势图\n- 分析价格波动规律\n- 预测价格趋势\n",
        "parameters": [
          {
            "name": "region",
            "in": "query",
            "description": "地区（可选）",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "昆明"
          },
          {
            "name": "material",
            "in": "query",
            "description": "材质（可选，支持模糊搜索）",
            "required": false,
            "schema": {
              "type": "string"
            },
            "example": "HPB300"
          },
          {
            "$ref": "#/components/parameters/DaysParam"
          }
        ],
        "responses": {
          "200": {
            "description": "查询成功",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessResponse"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "data": {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/TrendData"
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "参数错误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "服务器错误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        },
        "examples": {
          "trend_by_region": {
            "summary": "获取昆明地区最近 30 天的价格趋势",
            "value": {
              "region": "昆明",
              "days": 30
            }
          },
          "trend_by_material": {
            "summary": "获取 HPB300 最近 60 天的价格趋势",
            "value": {
              "material": "HPB300",
              "days": 60
            }
          }
        }
      }
    },
    "/api/prices/import": {
      "post": {
        "tags": [
          "Data"
        ],
        "summary": "导入价格数据",
        "description": "批量导入钢材价格数据到数据库。\n\n**请求体格式：**\n```json\n{\n  \"prices\": [\n    {\n      \"region\": \"昆明\",\n      \"city\": \"昆明\",\n      \"material\": \"HPB300\",\n      \"specification\": \"Φ8\",\n      \"price\": 3840.00,\n      \"unit\": \"元/吨\",\n      \"date\": \"2026-01-05\",\n      \"source\": \"云南钢协\",\n      \"warehouse\": \"玉昆\"\n    }\n  ]\n}\n```\n\n**注意事项：**\n- 必填字段：region, material, price, date\n- price 必须为数字类型\n- date 格式必须为 YYYY-MM-DD\n- 重复数据会自动更新\n",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "prices"
                ],
                "properties": {
                  "prices": {
                    "type": "array",
                    "description": "价格数据数组",
                    "items": {
                      "type": "object",
                      "required": [
                        "region",
                        "material",
                        "price",
                        "date"
                      ],
                      "properties": {
                        "region": {
                          "type": "string",
                          "description": "地区",
                          "example": "昆明"
                        },
                        "city": {
                          "type": "string",
                          "description": "城市",
                          "example": "昆明"
                        },
                        "material": {
                          "type": "string",
                          "description": "材质",
                          "example": "HPB300"
                        },
                        "specification": {
                          "type": "string",
                          "description": "规格型号",
                          "example": "Φ8"
                        },
                        "price": {
                          "type": "number",
                          "format": "decimal",
                          "description": "价格",
                          "example": 3840
                        },
                        "unit": {
                          "type": "string",
                          "description": "单位",
                          "example": "元/吨"
                        },
                        "date": {
                          "type": "string",
                          "format": "date",
                          "description": "日期",
                          "example": "2026-01-05"
                        },
                        "source": {
                          "type": "string",
                          "description": "数据来源",
                          "example": "云南钢协"
                        },
                        "warehouse": {
                          "type": "string",
                          "description": "仓库/厂家",
                          "example": "玉昆"
                        }
                      }
                    }
                  }
                }
              },
              "examples": {
                "single_record": {
                  "summary": "单条记录",
                  "value": {
                    "prices": [
                      {
                        "region": "昆明",
                        "city": "昆明",
                        "material": "HPB300",
                        "specification": "Φ8",
                        "price": 3840,
                        "unit": "元/吨",
                        "date": "2026-01-05",
                        "source": "云南钢协",
                        "warehouse": "玉昆"
                      }
                    ]
                  }
                },
                "multiple_records": {
                  "summary": "多条记录",
                  "value": {
                    "prices": [
                      {
                        "region": "昆明",
                        "material": "HPB300",
                        "price": 3840,
                        "date": "2026-01-05",
                        "source": "云南钢协"
                      },
                      {
                        "region": "玉溪",
                        "material": "HRB400",
                        "price": 3750,
                        "date": "2026-01-05",
                        "source": "德钢指导价"
                      }
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "导入成功",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/SuccessResponse"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "message": {
                          "type": "string",
                          "example": "成功导入 100 条数据"
                        },
                        "data": {
                          "type": "object",
                          "properties": {
                            "imported": {
                              "type": "integer",
                              "description": "实际导入的记录数",
                              "example": 100
                            }
                          }
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "参数错误或数据格式错误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "500": {
            "description": "服务器错误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  }
}