# 千方医数集 · 开放接口文档

> 站点公开接口：免登录 · GET · 明文 JSON。
> HTML 版（含在线调试）：https://www.qianfanghub.com/api-docs
> 更新时间以数据文件为准；接口清单随站点迭代追加。

## 通用约定

统一响应包装：`{ "yesenc": false, "code": "E0", "message": "执行操作成功", "data": <业务数据> }`

| 错误码 | 含义 |
|---|---|
| E0 | 成功，业务数据在 data |
| E1 | 一般错误 / 无数据记录（slug 反查不到、必填参数缺失等），详见 message |

**请求头**：`Accept-Language` 控制本地化（en → 英文主名；zh/ko/缺省 → 中文，韩文走中文兜底）。

## 医疗数据集

### URL地址反查ID

- 提交方式：GET
- 接口地址：`https://www.qianfanghub.com/medical-api/medicalDataset/queryRecordIdBySlug`
- 表单类型：application/x-www-form-urlencoded（Query 参数传输）
- 说明：提交数据集详情页 URL（或仅末段 slug），反查该详情页对应的数据集记录 ID。用于数据维护人员按 sitemap/页面 URL 定位记录后做更新操作。slug 撞车（多条同名）时返回全部命中，由调用方按分类/名称核对认领。请求头须携带维护令牌 X-Maintenance-Token（固定值，由站点方单独提供）；缺失或不匹配返回 E1「鉴权失败：令牌无效」。

**提交参数**

| 名称 | 类型 | 长度 | 必填 | 说明 |
|---|---|---|---|---|
| （请求头）X-Maintenance-Token | String | — | 是 | 维护令牌请求头（固定值，由站点方单独提供）；缺失或不匹配返回 E1「鉴权失败：令牌无效」 |
| url | String | 1024 | 是 | 详情页完整 URL 或仅末段数据集 slug，两种形态都收；兼容 % 编码形态与携带 query 串 |

**响应参数**

| 名称 | 类型 | 说明 |
|---|---|---|
| recordId | Long | 记录 ID（数据集主表 cs_medical_disease_dataset 主键） |
| datasetNameCn | String | 数据集中文名（核对用） |
| datasetNameEn | String | 数据集英文名 |
| firstLevelName | String | 所属一级分类（中文） |
| secondLevelName | String | 所属二级分类（中文） |

**样例说明**

请求：

```bash
curl -G 'https://www.qianfanghub.com/medical-api/medicalDataset/queryRecordIdBySlug' \
  -H 'X-Maintenance-Token: <维护令牌>' \
  --data-urlencode 'url=https://www.qianfanghub.com/dataset/cardiovascular-diseases/cardiovascular-diseases-other/bp-monitor-reading-medical-device-images-血压计读数-医疗设备图像'
```

响应：

```json
{
  "yesenc": false,
  "code": "E0",
  "data": [
    {
      "recordId": 20697,
      "datasetNameCn": "血压计读数 | 医疗设备图像",
      "datasetNameEn": "BP Monitor Reading | Medical Device Images",
      "secondLevelName": "其他",
      "firstLevelName": "心血管系统疾病"
    }
  ],
  "message": "执行操作成功"
}
```

### 记录ID查详情

- 提交方式：GET
- 接口地址：`https://www.qianfanghub.com/medical-api/medicalDataset/queryDatasetById`
- 表单类型：application/x-www-form-urlencoded（Query 参数传输）
- 说明：按记录 ID 直查数据集完整详情（全部业务字段双语原值，不做本地化切换）。用于维护人员更新前核对当前记录内容；不增加阅读数计数。请求头须携带维护令牌 X-Maintenance-Token（固定值，由站点方单独提供）；缺失或不匹配返回 E1「鉴权失败：令牌无效」。

**提交参数**

| 名称 | 类型 | 长度 | 必填 | 说明 |
|---|---|---|---|---|
| （请求头）X-Maintenance-Token | String | — | 是 | 维护令牌请求头（固定值，由站点方单独提供）；缺失或不匹配返回 E1「鉴权失败：令牌无效」 |
| recordId | Long | — | 是 | 数据集记录 ID（可由「URL地址反查ID」接口获得） |

**响应参数**

| 名称 | 类型 | 说明 |
|---|---|---|
| recordId | Long | 记录 ID |
| slug | String | 详情页 URL 末段 slug（Java 回填，供核对页面地址） |
| datasetNameCn | String | 数据集中文名称 |
| datasetNameEn | String | 数据集英文名称 |
| datasetDescriptionCn | String | 详细描述（中文） |
| datasetDescriptionEn | String | 详细描述（英文） |
| datasetShortDesc | String | 数据集简介（短描述） |
| datasetProvider | String | 提供机构 |
| datasetSiteName | String | 来源站点名称 |
| datasetUrl | String | 数据集原始链接 |
| downloadUrl | String | 数据集下载地址 |
| paperUrl | String | 相关论文地址 |
| selectUrl | String | 遇见数据集链接 |
| arxivUrl | String | 关联 arXiv 论文链接 |
| dataModality | String | 数据模态（中文枚举原值） |
| datasetSize | Number | 数据规模（GB） |
| datasetNum | Integer | 数据量（条数） |
| datasetCreateDatetime | String | 业务创建时间（yyyy-MM-dd HH:mm:ss） |
| datasetUpdateDatetime | String | 业务更新时间 |
| datasetCoverUrl | String | 封面图裸文件名 |
| labels | Array<String> | 主题标签数组 |
| firstLevelName | String | 所属一级分类（中文） |
| secondLevelName | String | 所属二级分类（中文） |
| version | String | 版本号 |
| license | String | 使用许可证 |
| taskType | String | 任务类型（中文枚举原值） |
| viewCount | Long | 阅读数（本接口查询不自增） |
| usageSteps | String | 使用步骤 |
| codeExample | String | 代码示例 |
| usageNotes | String | 使用须知 |
| downloadRegisterSign | Integer | 注册下载开关：0=关闭 1=开启 |
| downloadPublicSign | Integer | 公开下载开关：0=关闭 1=开启 |
| downloadPaidSign | Integer | 有偿下载开关：0=关闭 1=开启 |
| downloadDescRegister | String | 注册下载卡片描述（存量字段，站点不展示） |
| downloadDescPublic | String | 公开下载卡片描述（存量字段，站点不展示） |
| downloadDescPaid | String | 有偿下载卡片描述（存量字段，站点不展示） |
| usageMarkdown | String | 使用说明（markdown 长文本） |
| downloadNote | String | 下载区底部提示（存量字段，站点不展示） |
| lastupTxStamp | String | 记录最后修改时间（系统维护） |

**样例说明**

请求：

```bash
curl 'https://www.qianfanghub.com/medical-api/medicalDataset/queryDatasetById?recordId=20697' \
  -H 'X-Maintenance-Token: <维护令牌>'
```

响应：

```json
{
  "yesenc": false,
  "code": "E0",
  "data": {
    "recordId": 20697,
    "slug": "bp-monitor-reading-medical-device-images-血压计读数-医疗设备图像",
    "datasetNameCn": "血压计读数 | 医疗设备图像",
    "datasetNameEn": "BP Monitor Reading | Medical Device Images",
    "datasetShortDesc": "医疗设备图像数据集，涵盖血压计读数识别、设备分类、目标检测与屏幕OCR。",
    "dataModality": "图像",
    "labels": ["医疗设备", "图像识别"],
    "firstLevelName": "心血管系统疾病",
    "secondLevelName": "其他",
    "viewCount": 2,
    "datasetCreateDatetime": "2022-06-29 00:00:00",
    "lastupTxStamp": "2026-09-03 11:34:06"
  },
  "message": "执行操作成功"
}
```

### 记录ID更新

- 提交方式：POST
- 接口地址：`https://www.qianfanghub.com/medical-api/medicalDataset/updateDatasetById`
- 表单类型：application/x-www-form-urlencoded（data=JSON 字符串）
- 说明：按记录 ID 部分更新数据集业务字段（只更新本次提交的字段，未传字段保持原值；显式传空串=主动清空该列）。用于数据维护人员的 UP 更新操作。请求头须携带维护令牌 X-Maintenance-Token（固定值，由站点方单独提供）；缺失或不匹配返回 E1「鉴权失败：令牌无效」。更新动作后端留审计日志（记录变更字段旧值→新值）。

**提交参数**

| 名称 | 类型 | 长度 | 必填 | 说明 |
|---|---|---|---|---|
| （请求头）X-Maintenance-Token | String | — | 是 | 维护令牌请求头（固定值，由站点方单独提供）；缺失或不匹配返回 E1「鉴权失败：令牌无效」 |
| recordId | Long | — | 是 | 要更新的数据集记录 ID |
| datasetNameCn | String | 1024 | 否 | 数据集中文名称 |
| datasetNameEn | String | 1024 | 否 | 数据集英文名称 |
| datasetDescriptionCn | String | 不限 | 否 | 详细描述（中文，text 列无长度限制） |
| datasetDescriptionEn | String | 不限 | 否 | 详细描述（英文，text 列无长度限制） |
| datasetShortDesc | String | 1024 | 否 | 数据集简介（短描述） |
| datasetProvider | String | 1024 | 否 | 数据集提供机构 |
| datasetSiteName | String | 1024 | 否 | 数据集来源站点名称 |
| datasetUrl | String | 不限 | 否 | 数据集原始链接（text 列无长度限制） |
| selectUrl | String | 1024 | 否 | 遇见数据集链接 |
| arxivUrl | String | 1024 | 否 | 关联的 arXiv 论文链接 |
| dataModality | String | 256 | 否 | 数据模态枚举：图像/文本/表格/视频/时序/多模态 |
| datasetSize | Number | — | 否 | 数据规模（GB，数值，如 12.5） |
| datasetNum | Integer | — | 否 | 数据量（整数，条数） |
| version | String | 256 | 否 | 版本号 |
| license | String | 256 | 否 | 使用许可证 |
| taskType | String | 256 | 否 | 适用任务类型枚举：分类/图像分割/关键点标注/回归 |
| labels | Array<String> | 3200 | 否 | 主题标签数组，如 ["医疗设备","图像识别"]；传空数组=清空标签 |
| usageMarkdown | String | 不限 | 否 | 使用说明（markdown 长文本，text 列不限长） |
| usageSteps | String | 不限 | 否 | 使用步骤（text 列不限长） |
| usageNotes | String | 不限 | 否 | 使用须知（text 列不限长） |
| codeExample | String | 不限 | 否 | 代码示例（text 列不限长） |
| datasetCoverUrl | String | 1024 | 否 | 封面图裸文件名（如 9ce8d0c4….png；图片上传走既有临时文件体系） |
| downloadRegisterSign | Integer | — | 否 | 注册下载开关：0=关闭 1=开启 |
| downloadPublicSign | Integer | — | 否 | 公开下载开关：0=关闭 1=开启 |
| downloadPaidSign | Integer | — | 否 | 有偿下载开关：0=关闭 1=开启 |
| downloadUrl | String | 1024 | 否 | 数据集下载地址 |
| paperUrl | String | 1024 | 否 | 相关论文地址 |
| datasetCreateDatetime | String | — | 否 | 数据集业务创建时间，格式 'yyyy-MM-dd HH:mm:ss'（格式非法将被忽略并列于 ignored） |
| datasetUpdateDatetime | String | — | 否 | 数据集业务更新时间，格式 'yyyy-MM-dd HH:mm:ss'（格式非法将被忽略并列于 ignored） |

**响应参数**

| 名称 | 类型 | 说明 |
|---|---|---|
| updated | Integer | 实际更新成功的字段数（0=未执行 SQL） |
| recordId | Long | 被更新的记录 ID |
| fields | Array<String> | 本次更新的字段名列表 |
| ignored | Array<String> | 被忽略的白名单外字段名列表（后端同时记 warn 日志） |

**样例说明**

请求：

```bash
curl -X POST 'https://www.qianfanghub.com/medical-api/medicalDataset/updateDatasetById' \
  -H 'X-Maintenance-Token: <维护令牌>' \
  --data-urlencode 'data={"recordId":20697,"datasetShortDesc":"新的短描述","labels":["医疗设备","图像识别"]}'
```

响应：

```json
{
  "yesenc": false,
  "code": "E0",
  "data": {
    "recordId": 20697,
    "updated": 2,
    "fields": ["datasetShortDesc", "labels"],
    "ignored": []
  },
  "message": "执行操作成功"
}
```

### 文件上传（维护）

- 提交方式：POST
- 接口地址：`https://www.qianfanghub.com/medical-api/sysTempFile/uploadFilePub2`
- 表单类型：multipart/form-data（file=文件二进制字段）
- 说明：维护用文件上传：multipart 表单提交单个文件（字段名 file），落盘临时文件目录并返回存储文件名（sysFileName 可直接用于「记录ID更新」的 datasetCoverUrl 等文件名字段）。行为与站点原有公开上传 /sys/sysTempFile/uploadFilePub 一致，仅本接口增加维护令牌校验（原接口保持开放不动）。请求头须携带维护令牌 X-Maintenance-Token（固定值，由站点方单独提供）；缺失或不匹配返回 E1「鉴权失败：令牌无效」。

**提交参数**

| 名称 | 类型 | 长度 | 必填 | 说明 |
|---|---|---|---|---|
| （请求头）X-Maintenance-Token | String | — | 是 | 维护令牌请求头（固定值，由站点方单独提供）；缺失或不匹配返回 E1「鉴权失败：令牌无效」 |
| file | File | — | 是 | 上传的文件（multipart 字段名 file）；扩展名限 png/jpg/jpeg/gif/pdf/doc/docx/xls/xlsx/zip/rar/mp3/mp4/flv |

**响应参数**

| 名称 | 类型 | 说明 |
|---|---|---|
| fileName | String | 原始文件名 |
| sysFileName | String | 落盘存储文件名（用于 datasetCoverUrl 等字段值） |
| recordId | Long | 临时文件表记录 ID |

**样例说明**

请求：

```bash
curl -X POST 'https://www.qianfanghub.com/medical-api/sysTempFile/uploadFilePub2' \
  -H 'X-Maintenance-Token: <维护令牌>' \
  -F 'file=@./cover.png'
```

响应：

```json
{
  "yesenc": false,
  "code": "E0",
  "data": {
    "fileName": "cover.png",
    "sysFileName": "a1b2c3d4e5f6....png",
    "recordId": 123456
  },
  "message": "执行操作成功"
}
```