{
  "openapi": "3.0.0",
  "info": {
    "title": "化工商品分类树API",
    "description": "提供SMM和Mysteel化工商品数据的分类树状结构API接口。\n\n## 功能特点\n- 树状数据在服务启动时加载到内存,响应速度快\n- 支持获取完整分类树或按路径查询特定节点\n- SMM数据: 127,509个指标, 最大深度8层\n- Mysteel数据: 272,450个指标, 最大深度10层\n\n## 数据结构\n每个树节点包含:\n- name: 节点名称\n- path: 完整路径(用|分隔)\n- level: 层级深度\n- children: 子节点数组\n- metrics: 该节点下的指标列表(仅叶子节点)\n",
    "version": "1.0.0",
    "contact": {
      "name": "API Support"
    }
  },
  "servers": [
    {
      "url": "http://localhost:18827",
      "description": "本地开发服务器"
    },
    {
      "url": "http://222.128.1.157:18827",
      "description": "生产服务器"
    }
  ],
  "tags": [
    {
      "name": "分类树",
      "description": "分类树状结构相关接口"
    }
  ],
  "paths": {
    "/api/category-tree": {
      "get": {
        "tags": [
          "分类树"
        ],
        "summary": "获取完整分类树",
        "description": "获取指定数据源的完整分类树状结构。\n\n## 使用场景\n- 前端树形组件初始化\n- 构建完整的分类导航\n- 级联选择器数据源\n\n## 注意事项\n- SMM树约53MB,Mysteel树约152MB\n- 建议前端实现懒加载或缓存策略\n- 响应时间取决于网络带宽\n",
        "operationId": "getCategoryTree",
        "parameters": [
          {
            "name": "source",
            "in": "query",
            "description": "数据源类型",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "SMM",
                "Mysteel"
              ]
            },
            "example": "SMM"
          }
        ],
        "responses": {
          "200": {
            "description": "成功返回分类树",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CategoryTreeResponse"
                },
                "examples": {
                  "SMM示例": {
                    "value": {
                      "source": "SMM",
                      "total_metrics": 127509,
                      "tree": [
                        {
                          "name": "农业食品农资",
                          "path": "农业食品农资",
                          "level": 1,
                          "children": [
                            {
                              "name": "饲料",
                              "path": "农业食品农资|饲料",
                              "level": 2,
                              "children": [],
                              "metrics": []
                            }
                          ]
                        }
                      ]
                    }
                  },
                  "Mysteel示例": {
                    "value": {
                      "source": "Mysteel",
                      "total_metrics": 272450,
                      "tree": [
                        {
                          "name": "钢铁产业",
                          "path": "钢铁产业",
                          "level": 1,
                          "children": []
                        }
                      ]
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "未找到指定数据源",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "example": {
                  "detail": "未找到数据源 'XXX' 的树状数据。可用数据源: SMM, Mysteel"
                }
              }
            }
          },
          "500": {
            "description": "服务器内部错误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/category-tree/node": {
      "get": {
        "tags": [
          "分类树"
        ],
        "summary": "获取特定节点及其子树",
        "description": "根据路径获取树中的特定节点及其所有子节点。\n\n## 使用场景\n- 懒加载:用户点击节点时动态加载子节点\n- 子树查询:获取某个分类下的所有数据\n- 面包屑导航:根据路径定位节点\n\n## 路径格式\n使用竖线(|)分隔层级,例如:\n- 一级: \"钴\"\n- 二级: \"钴|钴化合物\"\n- 三级: \"钴|钴化合物|硫酸钴\"\n",
        "operationId": "getCategoryTreeNode",
        "parameters": [
          {
            "name": "path",
            "in": "query",
            "description": "节点完整路径,用竖线(|)分隔",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "钴|钴化合物|硫酸钴"
          },
          {
            "name": "source",
            "in": "query",
            "description": "数据源类型",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "SMM",
                "Mysteel"
              ]
            },
            "example": "SMM"
          }
        ],
        "responses": {
          "200": {
            "description": "成功返回节点数据",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TreeNode"
                },
                "example": {
                  "name": "硫酸钴",
                  "path": "钴|钴化合物|硫酸钴",
                  "level": 3,
                  "children": [
                    {
                      "name": "产量",
                      "path": "钴|钴化合物|硫酸钴|产量",
                      "level": 4,
                      "children": [],
                      "metrics": [
                        {
                          "metric_id": "12345",
                          "metric_name": "SMM中国硫酸钴月度产量",
                          "source": "SMM",
                          "frequency": "月",
                          "unit": "吨",
                          "description": ""
                        }
                      ]
                    }
                  ]
                }
              }
            }
          },
          "404": {
            "description": "未找到指定路径的节点或数据源",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                },
                "examples": {
                  "节点不存在": {
                    "value": {
                      "detail": "未找到路径 '钴|不存在的节点' 对应的节点"
                    }
                  },
                  "数据源不存在": {
                    "value": {
                      "detail": "未找到数据源 'XXX' 的树状数据。可用数据源: SMM, Mysteel"
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "服务器内部错误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "CategoryTreeResponse": {
        "type": "object",
        "description": "分类树响应对象",
        "required": [
          "source",
          "total_metrics",
          "tree"
        ],
        "properties": {
          "source": {
            "type": "string",
            "description": "数据源名称",
            "enum": [
              "SMM",
              "Mysteel"
            ],
            "example": "SMM"
          },
          "total_metrics": {
            "type": "integer",
            "description": "总指标数量",
            "example": 127509
          },
          "tree": {
            "type": "array",
            "description": "树的根节点列表",
            "items": {
              "$ref": "#/components/schemas/TreeNode"
            }
          }
        }
      },
      "TreeNode": {
        "type": "object",
        "description": "树节点对象",
        "required": [
          "name",
          "path",
          "level"
        ],
        "properties": {
          "name": {
            "type": "string",
            "description": "节点名称",
            "example": "钴"
          },
          "path": {
            "type": "string",
            "description": "节点完整路径,用竖线分隔",
            "example": "钴|钴化合物|硫酸钴"
          },
          "level": {
            "type": "integer",
            "description": "节点层级深度(从1开始)",
            "minimum": 1,
            "example": 3
          },
          "children": {
            "type": "array",
            "description": "子节点列表",
            "items": {
              "$ref": "#/components/schemas/TreeNode"
            }
          },
          "metrics": {
            "type": "array",
            "description": "该节点下的指标列表(通常只有叶子节点有)",
            "items": {
              "$ref": "#/components/schemas/TreeMetric"
            }
          }
        }
      },
      "TreeMetric": {
        "type": "object",
        "description": "树节点中的指标信息",
        "required": [
          "metric_id",
          "metric_name",
          "source",
          "frequency",
          "unit"
        ],
        "properties": {
          "metric_id": {
            "type": "string",
            "description": "指标唯一ID",
            "example": "12345"
          },
          "metric_name": {
            "type": "string",
            "description": "指标名称",
            "example": "SMM中国硫酸钴月度产量"
          },
          "source": {
            "type": "string",
            "description": "数据源",
            "enum": [
              "SMM",
              "Mysteel"
            ],
            "example": "SMM"
          },
          "frequency": {
            "type": "string",
            "description": "数据频率",
            "enum": [
              "日",
              "周",
              "月"
            ],
            "example": "月"
          },
          "unit": {
            "type": "string",
            "description": "指标单位",
            "example": "吨"
          },
          "description": {
            "type": "string",
            "description": "指标描述",
            "example": ""
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "description": "错误响应对象",
        "required": [
          "detail"
        ],
        "properties": {
          "detail": {
            "type": "string",
            "description": "错误详细信息",
            "example": "未找到数据源 'XXX' 的树状数据"
          }
        }
      }
    },
    "examples": {
      "SMM完整树示例": {
        "summary": "SMM完整树结构示例",
        "value": {
          "source": "SMM",
          "total_metrics": 127509,
          "tree": [
            {
              "name": "农业食品农资",
              "path": "农业食品农资",
              "level": 1,
              "children": [
                {
                  "name": "饲料",
                  "path": "农业食品农资|饲料",
                  "level": 2,
                  "children": []
                }
              ]
            },
            {
              "name": "小金属",
              "path": "小金属",
              "level": 1,
              "children": [
                {
                  "name": "钴",
                  "path": "小金属|钴",
                  "level": 2,
                  "children": [
                    {
                      "name": "钴化合物",
                      "path": "小金属|钴|钴化合物",
                      "level": 3,
                      "children": []
                    }
                  ]
                }
              ]
            }
          ]
        }
      },
      "Mysteel完整树示例": {
        "summary": "Mysteel完整树结构示例",
        "value": {
          "source": "Mysteel",
          "total_metrics": 272450,
          "tree": [
            {
              "name": "钢铁产业",
              "path": "钢铁产业",
              "level": 1,
              "children": [
                {
                  "name": "原材料",
                  "path": "钢铁产业|原材料",
                  "level": 2,
                  "children": []
                }
              ]
            }
          ]
        }
      },
      "节点查询示例": {
        "summary": "节点查询返回示例",
        "value": {
          "name": "钴化合物",
          "path": "小金属|钴|钴化合物",
          "level": 3,
          "children": [
            {
              "name": "硫酸钴",
              "path": "小金属|钴|钴化合物|硫酸钴",
              "level": 4,
              "metrics": [
                {
                  "metric_id": "12345",
                  "metric_name": "SMM中国硫酸钴月度产量",
                  "source": "SMM",
                  "frequency": "月",
                  "unit": "吨",
                  "description": ""
                }
              ]
            }
          ]
        }
      }
    }
  }
}