{ "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": "指标搜索相关接口" }, { "name": "分类树", "description": "分类树状结构相关接口" }, { "name": "数据查询", "description": "指标时间序列数据查询接口" } ], "paths": { "/api/search": { "get": { "tags": [ "搜索" ], "summary": "搜索化工商品指标", "description": "基于Elasticsearch的多关键词模糊搜索,支持智能分词和相关度排序。\n\n## 功能特点\n- **多关键词搜索**: 支持空格分隔多个关键词,自动AND逻辑组合\n- **模糊匹配**: 自动容错1-2个字符的拼写错误\n- **多字段匹配**: 同时搜索指标名称、分类路径等多个字段\n- **相关度排序**: 自动按匹配度评分排序,最相关的结果排在前面\n- **灵活过滤**: 支持按数据源(SMM/Mysteel)和频率(日/周/月)过滤\n\n## 搜索字段权重\n- 指标名称(metric_name): 权重最高 (3x)\n- 分类层级(category_levels): 权重中等 (2x)\n- 分类路径(category_path): 权重中等 (2x)\n\n## 使用场景\n- 用户输入关键词快速查找指标\n- 自动补全和搜索建议\n- 按类别和数据源筛选指标\n\n## 搜索示例\n- 搜索\"电解液 产量\": 查找包含\"电解液\"和\"产量\"的指标\n- 搜索\"硫酸钴\": 查找所有硫酸钴相关指标\n- 搜索\"焦炭 价格 日\": 查找焦炭日度价格数据\n", "operationId": "searchMetrics", "parameters": [ { "name": "keywords", "in": "query", "description": "搜索关键词,支持空格分隔多个词。\n\n示例:\n- \"电解液 产量\" - 查找同时包含这两个词的指标\n- \"硫酸钴\" - 查找硫酸钴相关指标\n- \"焦炭 价格\" - 查找焦炭价格数据\n", "required": true, "schema": { "type": "string" }, "example": "电解液 产量" }, { "name": "source", "in": "query", "description": "数据源过滤(可选)。\n\n- SMM: 上海有色网数据\n- Mysteel: 我的钢铁网数据\n- 不指定: 搜索所有数据源\n", "required": false, "schema": { "type": "string", "enum": [ "SMM", "Mysteel" ] }, "example": "SMM" }, { "name": "frequency", "in": "query", "description": "数据频率过滤(可选)。\n\n- 日: 日度数据\n- 周: 周度数据\n- 月: 月度数据\n- 不指定: 搜索所有频率\n", "required": false, "schema": { "type": "string", "enum": [ "日", "周", "月" ] }, "example": "日" }, { "name": "size", "in": "query", "description": "返回结果数量限制", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 1000, "default": 100 }, "example": 10 } ], "responses": { "200": { "description": "成功返回搜索结果", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" }, "examples": { "基础搜索示例": { "value": { "total": 50, "query": "电解液 产量", "results": [ { "source": "SMM", "metric_id": "12345", "metric_name": "SMM中国电解液月度产量", "unit": "吨", "frequency": "月", "category_path": "新能源|电解液|产量|SMM中国电解液月度产量", "description": "", "score": 15.8 }, { "source": "SMM", "metric_id": "12346", "metric_name": "SMM中国电解液周度产量", "unit": "吨", "frequency": "周", "category_path": "新能源|电解液|产量|SMM中国电解液周度产量", "description": "", "score": 14.2 } ] } }, "过滤搜索示例": { "value": { "total": 15, "query": "硫酸钴", "results": [ { "source": "SMM", "metric_id": "23456", "metric_name": "SMM中国硫酸钴月度产量", "unit": "吨", "frequency": "月", "category_path": "小金属|钴|钴化合物|硫酸钴|产量|SMM中国硫酸钴月度产量", "description": "", "score": 18.5 } ] } } } } } }, "400": { "description": "请求参数错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "keywords参数不能为空" } } } }, "500": { "description": "服务器内部错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "搜索服务暂时不可用" } } } } } } }, "/api/category-tree": { "get": { "tags": [ "分类树" ], "summary": "获取分类树(支持深度控制)", "description": "获取指定数据源的分类树状结构,支持深度控制。\n\n## 使用场景\n- 前端树形组件初始化(默认只加载第一层)\n- 懒加载:用户展开时再加载下一层\n- 级联选择器数据源\n\n## 默认行为\n- **默认只返回第一层** (max_depth=1),大幅减少数据传输量\n- SMM第一层约43个节点,Mysteel第一层约2个节点\n- 完整树数据量: SMM约53MB, Mysteel约152MB\n\n## 推荐用法\n1. 首次加载:不传max_depth(默认1层)\n2. 用户点击节点:调用 /api/category-tree/node 获取子节点\n", "operationId": "getCategoryTree", "parameters": [ { "name": "source", "in": "query", "description": "数据源类型", "required": true, "schema": { "type": "string", "enum": [ "SMM", "Mysteel" ] }, "example": "SMM" }, { "name": "max_depth", "in": "query", "description": "返回的最大层级深度\n- 1: 只返回第一层(默认,推荐)\n- 2: 返回前两层\n- 999: 返回完整树(不推荐,数据量大)\n", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 20, "default": 1 }, "example": 1 } ], "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## 返回数据说明\n- 返回该节点的基本信息\n- 返回该节点的直接子节点列表\n- 每个子节点的`children`数组为空`[]`\n- 通过`has_children`字段判断子节点是否可继续展开\n\n## 路径格式\n使用竖线(|)分隔层级,例如:\n- 第1层: \"小金属\"\n- 第2层: \"小金属|钴\"\n- 第3层: \"小金属|钴|钴化合物\"\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" }, "examples": { "展开第1层节点": { "value": { "name": "小金属", "path": "小金属", "level": 1, "has_children": true, "children": [ { "name": "钴", "path": "小金属|钴", "level": 2, "has_children": true, "children": [], "metrics": [] }, { "name": "锂", "path": "小金属|锂", "level": 2, "has_children": true, "children": [], "metrics": [] }, { "name": "镍", "path": "小金属|镍", "level": 2, "has_children": true, "children": [], "metrics": [] } ], "metrics": [] } }, "展开第2层节点": { "value": { "name": "钴", "path": "小金属|钴", "level": 2, "has_children": true, "children": [ { "name": "钴化合物", "path": "小金属|钴|钴化合物", "level": 3, "has_children": true, "children": [], "metrics": [] }, { "name": "钴矿", "path": "小金属|钴|钴矿", "level": 3, "has_children": true, "children": [], "metrics": [] } ], "metrics": [] } }, "叶子节点(含指标)": { "value": { "name": "产量", "path": "小金属|钴|钴化合物|硫酸钴|产量", "level": 5, "has_children": false, "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" } } } } } } }, "/api/metric-data": { "get": { "tags": [ "数据查询" ], "summary": "获取指标时间序列数据", "description": "根据指标ID查询历史时间序列数据,自动识别数据源(SMM或Mysteel)。\n\n## 功能特点\n- **自动识别数据源**: 无需指定source参数,系统自动查找\n- **灵活的日期范围**: 支持可选的开始/结束日期过滤\n- **数据限制**: 支持limit参数控制返回数据量\n\n## 日期格式支持\n- YYYY-MM-DD (推荐): \"2024-01-01\"\n- YYYYMMDD: \"20240101\"\n- YYYYMMDDHHmmss: \"20240101000000\"(只取日期部分)\n\n## 使用场景\n- 用户点击树节点查看指标数据\n- 图表展示时间序列数据\n- 数据导出和分析\n", "operationId": "getMetricData", "parameters": [ { "name": "metric_id", "in": "query", "description": "指标唯一ID", "required": true, "schema": { "type": "string" }, "example": "12345" }, { "name": "start_date", "in": "query", "description": "开始日期(可选),格式 YYYY-MM-DD 或 YYYYMMDD", "required": false, "schema": { "type": "string" }, "example": "2024-01-01" }, { "name": "end_date", "in": "query", "description": "结束日期(可选),格式 YYYY-MM-DD 或 YYYYMMDD", "required": false, "schema": { "type": "string" }, "example": "2024-12-31" }, { "name": "limit", "in": "query", "description": "返回数据条数限制(1-10000)", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 10000, "default": 100 }, "example": 100 } ], "responses": { "200": { "description": "成功返回指标数据", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetricDataResponse" }, "examples": { "SMM数据示例": { "value": { "metric_id": "12345", "metric_name": "SMM中国硫酸钴月度产量", "source": "SMM", "frequency": "月", "unit": "吨", "data": [ { "date": "2024-12-01", "value": 12500.5 }, { "date": "2024-11-01", "value": 12300.0 }, { "date": "2024-10-01", "value": 12100.8 } ], "total_count": 120 } }, "Mysteel数据示例": { "value": { "metric_id": "A0101010", "metric_name": "唐山焦炭价格", "source": "MYSTEEL", "frequency": "日", "unit": "元/吨", "data": [ { "date": "2024-12-20", "value": 2350.0 }, { "date": "2024-12-19", "value": 2340.0 } ], "total_count": 365 } } } } } }, "404": { "description": "未找到指定指标", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "未找到指标: metric_id=99999" } } } }, "400": { "description": "请求参数错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "limit参数必须在1-10000之间" } } } }, "500": { "description": "服务器内部错误", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "example": { "detail": "查询数据失败: [具体错误信息]" } } } } } } } }, "components": { "schemas": { "SearchResponse": { "type": "object", "description": "搜索结果响应对象", "required": [ "total", "query", "results" ], "properties": { "total": { "type": "integer", "description": "搜索结果总数", "example": 50 }, "query": { "type": "string", "description": "查询关键词", "example": "电解液 产量" }, "results": { "type": "array", "description": "指标列表(按相关度评分降序)", "items": { "$ref": "#/components/schemas/MetricInfo" } } } }, "MetricInfo": { "type": "object", "description": "指标信息对象", "required": [ "source", "metric_id", "metric_name", "unit", "frequency", "category_path" ], "properties": { "source": { "type": "string", "description": "数据源", "enum": [ "SMM", "Mysteel" ], "example": "SMM" }, "metric_id": { "type": "string", "description": "指标唯一ID", "example": "12345" }, "metric_name": { "type": "string", "description": "指标名称", "example": "SMM中国硫酸钴月度产量" }, "unit": { "type": "string", "description": "数据单位", "example": "吨" }, "frequency": { "type": "string", "description": "数据频率", "enum": [ "日", "周", "月" ], "example": "月" }, "category_path": { "type": "string", "description": "完整分类路径(用|分隔)", "example": "小金属|钴|钴化合物|硫酸钴|产量|SMM中国硫酸钴月度产量" }, "description": { "type": "string", "description": "指标描述备注", "example": "" }, "score": { "type": "number", "description": "搜索相关度评分(仅搜索结果返回)", "nullable": true, "example": 15.8 } } }, "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", "has_children" ], "properties": { "name": { "type": "string", "description": "节点名称", "example": "钴" }, "path": { "type": "string", "description": "节点完整路径,用竖线分隔", "example": "钴|钴化合物|硫酸钴" }, "level": { "type": "integer", "description": "节点层级深度(从1开始)", "minimum": 1, "example": 3 }, "has_children": { "type": "boolean", "description": "是否有子节点(用于前端判断是否可展开)", "example": true }, "children": { "type": "array", "description": "子节点列表(根据max_depth可能为空数组)", "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": "" } } }, "MetricDataResponse": { "type": "object", "description": "指标数据查询响应对象", "required": [ "metric_id", "metric_name", "source", "frequency", "unit", "data", "total_count" ], "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": "吨" }, "data": { "type": "array", "description": "时间序列数据点列表(按日期倒序)", "items": { "$ref": "#/components/schemas/DataPoint" } }, "total_count": { "type": "integer", "description": "符合条件的数据总条数", "example": 120 } } }, "DataPoint": { "type": "object", "description": "单个数据点", "required": [ "date", "value" ], "properties": { "date": { "type": "string", "description": "日期,格式 YYYY-MM-DD", "example": "2024-01-01" }, "value": { "type": "number", "description": "数值(可能为null)", "nullable": true, "example": 1234.56 } } }, "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": "" } ] } ] } } } } }