API 参考

接口文档 V1.0.0

展示数据模型试算沙箱系统的公开能力，供外部访客浏览产品目录、场景目录、行业分类等信息

一、接口总览

模块	前缀	接口数	说明
🛍️ 产品目录	/products	4	浏览已上架数据产品
🎯 场景目录	/scene-info	5	浏览公开场景
🤖 场景推荐	/scene-recommendations	3	产品→场景 AI 匹配
📂 行业分类	/industry/category	3	国民经济行业分类树
📊 模型管理	/model-info	2	公开模型浏览
📐 效用公式	/utility-formula	1	公开效用公式浏览

二、通用说明

2.1 基础 URL

text

生产环境：https://playground.tsingresource.cn

所有接口通过 Spring Cloud Gateway 统一入口，路径前缀由网关路由转发至 data-pricing 服务。

2.2 统一响应格式

json

{
  "code": 200,
  "msg": "操作成功",
  "data": { ... }
}

字段	类型	说明
code	int	200 成功，其他为错误码
msg	string	提示信息
data	object/array/null	响应数据

2.3 分页参数

请求参数

参数	类型	默认值	说明
current / pageNum	int	1	当前页码
size / pageSize	int	10	每页条数

响应格式

json

{
  "code": 200,
  "data": {
    "records": [ ... ],
    "total": 100,
    "size": 10,
    "current": 1,
    "pages": 10
  }
}

2.4 安全认证

当前所有接口走 Sa-Token 统一认证（Gateway 层）。

三、接口详情

3.1 产品目录

GET/products/catalog

产品目录分页列表

浏览已上架的数据产品，支持多条件筛选。

参数	类型	必填	说明
pageNum	int	否	页码，默认 1
pageSize	int	否	每页条数，默认 10
keyword	string	否	关键词搜索（产品名称/描述）
industryCategory	string	否	行业分类代码
dataType	string	否	数据类型（结构化/文本/图片）
dataSource	string	否	数据来源
priceMin	decimal	否	最低价格
priceMax	decimal	否	最高价格
sortField	string	否	排序字段（createTime/price）
sortOrder	string	否	排序方向（asc/desc）

响应字段（IPage<ProductCatalogVO>）

字段	类型	说明
productId	string	产品 ID
productName	string	产品名称
productDesc	string	产品描述
dataType	string	数据类型
industryCategory	string	行业分类
dataSource	string	数据来源
coverImage	string	封面图 URL
price	decimal	参考价格
providerName	string	供给方名称
status	int	状态（3=已上架）
createTime	datetime	创建时间
tags	array[string]	标签列表

bash

curl "https://playground.tsingresource.cn/products/catalog?pageNum=1&pageSize=10&keyword=金融&sortField=createTime&sortOrder=desc"

GET/products/{id}

产品详情

获取指定产品的完整信息。

路径参数

参数	类型	必填	说明
id	string	是	产品 ID

响应字段（Product）

字段	类型	说明
id	string	产品 ID
productName	string	产品名称
productDesc	string	产品描述
dataType	string	数据类型
industryCategory	string	行业分类
dataSource	string	数据来源
coverImage	string	封面图 URL
price	decimal	参考价格
providerName	string	供给方名称
dataVolume	long	数据量
updateFrequency	string	更新频率
status	int	状态
createTime	datetime	创建时间

GET/products/{id}/features

产品特征列（数据字段）

获取产品的字段列表，展示数据有哪些列、什么类型。

字段	类型	说明
paramName	string	字段名
paramType	string	字段类型（String/Integer/Double/Date）
sampleValue	string	样例值
description	string	字段描述

GET/products/{id}/metadata

产品元数据

获取产品的元数据配置信息。

字段	类型	说明
attributeName	string	属性名
attributeValue	string	属性值
attributeType	string	属性类型

3.2 场景目录

GET/scene-info/page

场景分页列表

浏览公开的应用场景，了解数据可以用于哪些业务场景。

参数	类型	必填	说明
pageNum	int	否	页码，默认 1
pageSize	int	否	每页条数，默认 10
sceneName	string	否	场景名称搜索
sceneCategory	int	否	场景分类
industryCategory	string	否	行业分类
isPublic	int	否	公开标记（官网固定传 1）

响应字段（IPage<SceneInfoVo>）

字段	类型	说明
id	long	场景 ID
sceneName	string	场景名称
sceneDesc	string	场景描述
sceneCategory	int	场景分类
industryCategory	string	行业分类
isPublic	int	是否公开
modelName	string	关联模型名
formulaName	string	关联效用公式名
productCount	int	关联产品数
createTime	datetime	创建时间

GET/scene-info/{id}

场景详情

参数	类型	必填	说明
id	long	是	场景 ID

响应字段（SceneInfoVo）

字段	类型	说明
id	long	场景 ID
sceneName	string	场景名称
sceneDesc	string	场景描述
sceneCategory	int	场景分类
industryCategory	string	行业分类
isPublic	int	是否公开
sceneFields	array[SceneParamVo]	场景字段列表

GET/scene-info/list/public

公开场景列表（简易）

返回所有公开场景的简要列表，适合下拉框、首页展示。

参数	类型	必填	说明
sceneCategory	int	否	场景分类筛选

GET/scene-info/{id}/features

场景特征列

获取场景定义的字段列表。

字段	类型	说明
paramName	string	字段名
paramType	string	字段类型
required	boolean	是否必填
description	string	字段描述

GET/scene-info/statistics

场景统计

获取场景分类统计数据。

参数	类型	必填	说明
moduleName	string	否	scene-directory=公开场景；默认个人

响应示例

json

{
  "totalScenes": 128,
  "publicScenes": 85,
  "categoryMap": {
    "信用评估": 35,
    "精准营销": 42,
    "风险控制": 28
  }
}

POST/scene-recommendations/matchTask

触发产品→场景 AI 匹配

根据产品 ID 触发 AI 推荐匹配的场景（异步任务）。

请求体（ProductSceneRecCriteria）

json

{
  "productId": "PROD123456",
  "topK": 5,
  "async": true
}

字段	类型	必填	说明
productId	string	是	产品 ID
topK	int	否	返回 Top K 个推荐，默认 3
async	boolean	否	是否异步，默认 true

响应字段（MatchTaskInfoDto）

字段	类型	说明
taskId	string	任务 ID，用于后续查询状态
status	string	PENDING / RUNNING / COMPLETED / FAILED
progress	int	进度百分比

GET/scene-recommendations/tasks/{taskId}

查询匹配任务状态

轮询 AI 匹配任务进度。

字段	类型	说明
taskId	string	任务 ID
status	string	PENDING / RUNNING / COMPLETED / FAILED
progress	int	进度百分比（0-100）
result	array	匹配完成后的推荐结果列表

GET/scene-recommendations/products/{productId}/statistics

产品场景推荐统计

获取某产品的场景推荐统计数据。

字段	类型	说明
totalCount	int	推荐总数
highMatchCount	int	高匹配度数量
mediumMatchCount	int	中匹配度数量
lowMatchCount	int	低匹配度数量
highRatio	double	高匹配占比
mediumRatio	double	中匹配占比
lowRatio	double	低匹配占比

3.4 行业分类

GET/industry/category/tree

行业分类树

获取完整的启用的行业分类树结构。

json

[
  {
    "id": 1,
    "code": "A",
    "name": "农、林、牧、渔业",
    "parentCode": "0",
    "level": 1,
    "children": [
      {
        "id": 2,
        "code": "A01",
        "name": "农业",
        "parentCode": "A",
        "level": 2,
        "children": [ ... ]
      }
    ]
  }
]

字段	类型	说明
id	long	主键
code	string	行业代码（GB/T 4754）
name	string	行业名称
parentCode	string	父级代码
level	int	层级
children	array	子级列表

GET/industry/category/children

查询子分类

查询指定父级下的直接子分类。

参数	类型	必填	说明
parentCode	string	否	父级代码，默认 '0' 查顶级

GET/industry/category/page

行业分类分页

标准分页查询，返回 IPage<IndustryCategoryVo>。

3.5 模型管理

GET/model-info/publicPage

公开模型分页列表

浏览公开的 AI 模型（与公开场景关联的模型）。

参数	类型	必填	说明
pageNum	int	否	页码
pageSize	int	否	每页条数
modelName	string	否	模型名称搜索
dataType	string	否	数据类型
taskType	string	否	任务类型

响应字段（IPage<ModelInfoVo>）

字段	类型	说明
id	long	模型 ID
modelName	string	模型名称
modelDesc	string	模型描述
dataType	string	数据类型
taskType	string	任务类型（分类/回归）
algorithmName	string	算法名称
framework	string	框架（PyTorch/TensorFlow）

GET/model-info/{id}

模型详情

完整模型信息，含超参数配置。

3.6 效用公式

GET/utility-formula/page

公开效用公式分页

浏览公开的定价效用公式。

参数	类型	必填	说明
pageNum	int	否	页码
pageSize	int	否	每页条数
formulaName	string	否	公式名称搜索
formulaType	string	否	公式类型
sceneType	string	否	适用场景类型

响应字段（IPage<UtilityFormulaVo>）

字段	类型	说明
id	long	公式 ID
formulaName	string	公式名称
formulaDesc	string	公式描述
expression	string	公式表达式
formulaType	string	公式类型
sceneType	string	适用场景类型
params	array	参数列表

四、排除的接口（不对外暴露）

以下接口涉及用户认证、写操作或内部业务逻辑，不应在外网暴露：

接口	排除原因
POST/PUT/DELETE /products/*	写操作 + 需认证
POST/PUT/DELETE /scene-info/*	写操作 + 需认证
/scene/*	已废弃
/evaluation/*	核心业务逻辑，需双方登录
/negotiations/*	价格协商，涉及敏感商业信息
/invitations/*	邀约管理，需登录
/model/*	已废弃
/model-info POST/PUT/DELETE	写操作
/utility-formula POST/PUT/DELETE	写操作 + 需认证
/utility-formula/metric/*	内部配置
/dataset/*	数据集管理，需登录
/negotiation-templates/*	合同模板管理
/board/*	看板数据，内部运营
/feature/*	空壳 Controller
/smartUpload/*	文件上传，内部功能
/examine-tasks/*	审核流程，内部功能
/model-info/data-task-mapping/*	字典联动，仅供前端表单使用

五、接口调用流程图

官网访客
  │
  ├── 首页
  │   ├── GET /scene-info/statistics          → 统计数据卡片
  │   └── GET /scene-info/list/public         → 热门场景推荐
  │
  ├── 产品目录页
  │   ├── GET /industry/category/tree         → 左侧行业筛选树
  │   └── GET /products/catalog?keyword=&industry=  → 产品列表
  │
  ├── 产品详情页
  │   ├── GET /products/{id}                  → 基本信息
  │   ├── GET /products/{id}/features         → 数据字段表格
  │   ├── GET /products/{id}/metadata         → 元数据信息
  │   └── POST /scene-recommendations/matchTask → 「AI 推荐场景」按钮
  │       └── GET /scene-recommendations/tasks/{taskId} → 轮询结果
  │
  ├── 场景目录页
  │   ├── GET /scene-info/page               → 场景列表
  │   └── GET /scene-info/{id}               → 点击查看场景详情
  │
  ├── 模型展示页
  │   └── GET /model-info/publicPage          → 公开模型列表
  │
  └── 效用公式页
      └── GET /utility-formula/page           → 公式展示

附录

附录 A：数据库表与接口映射

数据库表	对应 Controller	暴露的 GET 接口
product	ProductController	/products/catalog, /{id}, /{id}/features, /{id}/metadata
scene_info	SceneInfoController	/scene-info/page, /{id}, /list/public, /{id}/features, /statistics
scene_recommendation	SceneRecommendationController	/matchTask, /tasks/{id}, /products/{id}/statistics
industry_category	IndustryCategoryController	/industry/category/tree, /children, /page
model_info	ModelInfoController	/model-info/publicPage, /{id}
utility_formula	UtilityFormulaController	/utility-formula/page

附录 B：与现有前端路由的对应关系

官网页面	调用的接口	对应系统内菜单
产品目录页	/products/catalog	数据市场 > 产品目录
产品详情页	/products/{id}	产品目录 Drawer 详情
场景目录页	/scene-info/page	数据市场 > 场景目录
场景详情页	/scene-info/{id}	场景目录 Drawer
AI 匹配	/scene-recommendations/matchTask	场景推荐
行业筛选	/industry/category/tree	（无直接对应）
模型展示	/model-info/publicPage	（无直接对应）

接口文档 V1.0.0

一、接口总览

二、通用说明

2.1 基础 URL

2.2 统一响应格式

2.3 分页参数

请求参数

响应格式

2.4 安全认证

三、接口详情

3.1 产品目录

产品目录分页列表

产品详情

产品特征列（数据字段）

产品元数据

3.2 场景目录

场景分页列表

场景详情

公开场景列表（简易）

场景特征列

场景统计

3.3 场景推荐（AI 匹配）

触发产品→场景 AI 匹配

查询匹配任务状态

产品场景推荐统计

3.4 行业分类

行业分类树

查询子分类

行业分类分页

3.5 模型管理

公开模型分页列表

模型详情

3.6 效用公式

公开效用公式分页

四、排除的接口（不对外暴露）

五、接口调用流程图

附录

附录 A：数据库表与接口映射

附录 B：与现有前端路由的对应关系