1028 lines
33 KiB
JSON
1028 lines
33 KiB
JSON
{
|
|
"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": ""
|
|
}
|
|
]
|
|
}
|
|
]
|
|
}
|
|
}
|
|
}
|
|
}
|
|
} |