xj-platform/health-emergency/API文档-急救宣教资源管理v3.md

急救宣教资源管理 API 文档 v3

基础信息
网关地址: http://{gateway-host}:{port}（前端加 /health-emergency 前缀）
服务直连: http://{host}:7011（调试用，不加前缀）
认证方式: 请求头 X-Access-Token: {token}
Content-Type: application/json; charset=utf-8
统一响应格式: {"success": bool, "message": "...", "code": 200, "result": {...}, "timestamp": ...}
日期格式: yyyy-MM-dd HH:mm:ss（东八区）

---

V3 变更说明（相比 V2）

#	变更项	说明
1	审批与上架分离	审核通过（approve）后不再自动发布，需单独调用 publish 上架；publish 要求 auditStatus=11（已通过），否则报错；新增状态"已通过"
2	分类扁平化	分类仅一级（无子分类），标签绑定到分类下，listRoot 返回全部分类，listChildren 返回分类下的标签
3	分类标签联动	新增 GET /category/listWithTags 返回分类+嵌套标签，前端一次请求即可实现分类/标签联动选择
4	标签绑定分类	标签新增/编辑时 parentId（所属分类）必填；标签列表 listAll 支持 parentId 筛选
5	批量发布行为变更	batchPublish 仅对 auditStatus=11 的资源生效，跳过未审核通过的
6	导出状态映射修正	auditStatus=11 但未上架的资源导出显示"已通过"而非"已发布"

---

目录

1. 通用枚举说明
2. 状态流转
3. 分类管理
4. 标签管理
5. 资源管理
6. 审核管理
7. 推送管理
8. 收藏管理
9. 版本管理
10. 响应数据结构

---

通用枚举说明

内容类型 contentType

值	说明
IMAGE_TEXT	图文
VIDEO	视频
AUDIO	音频
PDF	PDF

复合状态查询 combinedStatus（资源列表筛选用）

前端一个下拉框统一筛选，后端根据值域自动分发：

下拉选项	传值	分发逻辑
草稿	0	查 status
已发布	1	查 status
已下架	2	查 status
待审核	10	查 auditStatus
已通过	11	查 auditStatus
已驳回	12	查 auditStatus

规则：combinedStatus ≤ 9 分发到 status，combinedStatus ≥ 10 分发到 auditStatus。
combinedStatus 与 status / auditStatus 参数互斥——同时传时 combinedStatus 优先。

发布状态 status

值	说明
0	草稿
1	已发布
2	已下架

审核状态 auditStatus

值	说明
null	无审核动作（新建/编辑后）
10	待审核
11	已通过
12	已驳回

综合状态展示对照表（V3 新增）

前端列表的状态列按此表展示：

auditStatus	status	前端显示
null	0	草稿
10	0	待审核
11	0	已通过（V3 新增）
11	1	已发布
11	2	已下架
12	0	已驳回

分类/标签类型 type

值	说明
1	分类（扁平，仅一级）
2	标签（绑定到分类）

通用状态（分类/标签）

值	说明
1	正常
2	冻结

用户行为类型

值	说明
1	阅读
2	收藏

---

状态流转

新建 ──→ 草稿 (status=0, auditStatus=null)
  │
  └── 提交审核 ──→ 待审核 (status=0, auditStatus=10)
                    │
                    ├── 审核通过 ──→ 已通过 (status=0, auditStatus=11)  ← V3 变更
                    │                  │
                    │                  ├── 上架 ──→ 已发布 (status=1, auditStatus=11)
                    │                  │            │
                    │                  │            ├── 下架 ──→ 已下架 (status=2, auditStatus=11)
                    │                  │            │            │
                    │                  │            │            └── 上架 ──→ 已发布 (status=1, auditStatus=11)
                    │                  │            │
                    │                  │            └── 编辑 ──→ 草稿 (status=0, auditStatus=null)
                    │                  │
                    │                  └── 编辑 ──→ 草稿 (status=0, auditStatus=null)
                    │
                    └── 审核驳回 ──→ 已驳回 (status=0, auditStatus=12)
                                        │
                                        └── 编辑 ──→ 草稿 (status=0, auditStatus=null)

复制 ──→ 草稿 (status=0, auditStatus=null)，标题+" - 副本"
回滚 ──→ 草稿 (status=0, auditStatus=null)

V3 关键变更：审核通过后资源进入"已通过"状态，需运营人员点击"上架"才变为"已发布"。编辑/回滚后需重新提交审核。

---

1. 分类管理 emergency/firstAid/category

分类为扁平结构（仅一级），标签通过 parentId 绑定到分类下。

1.1 分页列表 GET /category/list

参数	类型	必填	默认值	说明
pageNo	Integer	否	1	页码
pageSize	Integer	否	10	每页条数
name	String	否	-	名称模糊搜索
status	Integer	否	-	状态（1=正常/2=冻结）

// 响应 result
{
  "records": [
    {
      "id": "...",
      "name": "心肺复苏",
      "type": 1,
      "parentId": null,
      "description": "...",
      "sortNo": 0,
      "status": 1,
      "resourceCount": 5,
      "createTime": "2026-06-22 10:00:00"
    }
  ],
  "total": 6, "size": 10, "current": 1, "pages": 1
}

1.2 全部列表（树形） GET /category/listAll

无参数。返回全部分类及其下标签的嵌套树，tags 为标签数组，resourceCount 为使用量。

[
  {
    "id": "cat1", "name": "心肺复苏", "resourceCount": 5,
    "tags": [
      { "id": "tag1", "name": "成人", "resourceCount": 3 },
      { "id": "tag2", "name": "儿童", "resourceCount": 2 }
    ]
  },
  {
    "id": "cat2", "name": "创伤急救", "resourceCount": 3,
    "tags": [...]
  }
]

1.3 分类列表 GET /category/listRoot

无参数，返回全部分类（type=1）扁平列表（含 resourceCount）。

1.4 标签列表（按分类） GET /category/listChildren

参数	类型	必填	说明
parentId	String	是	分类ID

返回指定分类下的标签（type=2），含 resourceCount。

1.5 分类及标签嵌套列表 GET /category/listWithTags 🆕 V3 新增

与 listAll 返回结构相同，无参数，返回全部分类及其下标签的嵌套结构。

1.6 详情 GET /category/queryById

参数	类型	必填	说明
id	String	是	分类ID

1.7 新增 POST /category/add

{
  "name": "分类名称",
  "description": "描述（可选）",
  "sortNo": 1,
  "status": 1
}

分类不再需要 parentId（扁平化，仅一级）。

1.8 编辑 POST /category/edit

{
  "id": "分类ID",
  "name": "新名称",
  "description": "新描述",
  "sortNo": 2,
  "status": 1
}

1.9 删除 POST /category/delete

{"id": "分类ID"}

级联校验：分类下存在标签或资源时拒绝删除。

1.10 批量删除 POST /category/deleteBatch

["id1", "id2"]

1.11 导出Excel GET /category/exportXls

参数与分页列表一致。返回 Excel 文件流。

1.12 导入Excel POST /category/importExcel

文件上传，格式与导出一致。

---

2. 标签管理 emergency/firstAid/tag

标签与分类共用 QH_EME_FIRST_AID_RESOURCE_CATEGORY 表，type=2 区分。标签通过 parentId 绑定到分类。

2.1 分页列表 GET /tag/list

参数	类型	必填	默认值	说明
pageNo	Integer	否	1	页码
pageSize	Integer	否	10	每页条数
name	String	否	-	名称模糊搜索
parentId	String	否	-	所属分类ID

2.2 全部列表 GET /tag/listAll

参数	类型	必填	默认值	说明
parentId	String	否	-	所属分类ID（传则只返回该分类下的标签，不传返回全部）

返回标签列表（含 resourceCount 引用数量）。

2.3 详情 GET /tag/queryById

参数	类型	必填	说明
id	String	是	标签ID

2.4 新增 POST /tag/add

{
  "name": "标签名称",
  "parentId": "所属分类ID（必填）",
  "description": "描述（可选）",
  "sortNo": 1,
  "status": 1
}

2.5 编辑 POST /tag/edit

{
  "id": "标签ID",
  "name": "新名称",
  "parentId": "所属分类ID",
  "description": "新描述",
  "sortNo": 2,
  "status": 1
}

2.6 删除 POST /tag/delete

{"id": "标签ID"}

级联校验：标签已被资源引用时拒绝删除。

2.7 批量删除 POST /tag/deleteBatch

["id1", "id2"]

2.8 导出Excel GET /tag/exportXls

参数与分页列表一致。返回 Excel 文件流。

2.9 导入Excel POST /tag/importExcel

文件上传，格式与导出一致。

---

3. 资源管理 emergency/firstAid/resource

3.1 分页列表 GET /resource/list

参数	类型	必填	默认值	说明
pageNo	Integer	否	1	页码
pageSize	Integer	否	10	每页条数
title	String	否	-	标题模糊搜索
categoryId	String	否	-	分类ID精确匹配
contentType	String	否	-	内容类型：IMAGE_TEXT/VIDEO/AUDIO/PDF
combinedStatus	Integer	否	-	复合状态筛选（≤9查status，≥10查auditStatus）
status	Integer	否	-	发布状态（审核页独立筛选用）
auditStatus	Integer	否	-	审核状态（审核页独立筛选用）
tags	String	否	-	标签ID，逗号分隔

互斥规则：combinedStatus 与 status/auditStatus 互斥，同时传时 combinedStatus 优先。

3.2 详情 GET /resource/queryById

参数	类型	必填	说明
id	String	是	资源ID

响应额外填充：categoryName、tagNameList、isFavorited。

3.3 新增 POST /resource/add

{
  "title": "资源标题（必填）",
  "summary": "摘要简介",
  "contentType": "IMAGE_TEXT",
  "categoryId": "分类ID",
  "applicableScenario": "适用场景描述",
  "tags": "标签ID1,标签ID2",
  "content": "<h1>富文本HTML正文</h1>",
  "coverImage": "https://example.com/cover.jpg",
  "fileUrl": "[\"https://example.com/file1.pdf\"]",
  "effectiveTime": "2026-07-01 00:00:00",
  "expiryTime": "2026-12-31 23:59:59"
}

新建后 status=0（草稿）、auditStatus=null。

3.4 编辑 POST /resource/edit

{
  "id": "资源ID",
  "title": "新标题",
  "contentType": "IMAGE_TEXT",
  "categoryId": "分类ID",
  "tags": "标签ID1,标签ID2",
  "content": "<p>新内容</p>",
  "...": "其他字段同上"
}

编辑后自动退回草稿 + 清除审核状态（status=0, auditStatus=null），并保存编辑前后各一条版本快照（"编辑前版本"和"编辑更新"）。

3.5 删除 POST /resource/delete

{"id": "资源ID"}

逻辑删除（delFlag=1）。

3.6 批量删除 POST /resource/deleteBatch

["id1", "id2"]

3.7 提交审核 POST /resource/submitForReview

{"id": "资源ID"}

auditStatus 变为 10（待审核）。

3.8 下架 POST /resource/takeDown

{"id": "资源ID"}

status 变为 2（已下架）。

3.9 上架 POST /resource/publish ⚠️ V3 变更

{"id": "资源ID"}

V3 行为变更：仅 auditStatus=11（已通过）的资源可上架，否则返回错误 "该资源尚未通过审核，无法上架"。上架后 status=1，审核字段不变。下架操作无前置校验，任意状态均可下架。

3.10 批量下架 POST /resource/batchTakeDown

["id1", "id2"]

3.11 批量上架 POST /resource/batchPublish ⚠️ V3 变更

["id1", "id2"]

V3 行为变更：仅对 auditStatus=11 的资源设置 status=1，跳过未通过审核的。

3.12 记录阅读 POST /resource/incrementView

{"id": "资源ID"}

同一用户重复阅读不累计，返回 "已阅读过"。

3.13 复制资源 POST /resource/copy

{"id": "源资源ID"}

标题追加 " - 副本"，status=0, auditStatus=null，浏览/收藏归零。

3.14 导出Excel GET /resource/exportXls

参数	类型	必填	说明
selections	String	否	勾选的ID列表（逗号分隔），不传则导出全部
title	String	否	标题筛选
categoryId	String	否	分类筛选
contentType	String	否	类型筛选
status	Integer	否	状态筛选

导出字段：标题、摘要、分类、类型、标签、状态、阅读/收藏、创建时间。

3.15 导入Excel POST /resource/importExcel

文件上传，格式与导出一致。

---

4. 审核管理 emergency/firstAid/audit

4.1 待审核列表 GET /audit/pending

参数	类型	必填	默认值	说明
pageNo	Integer	否	1	页码
pageSize	Integer	否	10	每页条数
title	String	否	-	标题搜索
categoryId	String	否	-	分类筛选
contentType	String	否	-	内容类型筛选

4.2 已通过列表 GET /audit/passed

参数同上。

4.3 已驳回列表 GET /audit/rejected

参数同上。

4.4 审核通过 POST /audit/approve ⚠️ V3 变更

{"id": "资源ID"}

V3 行为变更：仅设置 auditStatus=11（已通过）、审核人、审核时间，并清除 auditRejectReason，不再同时设置 status=1。审核后资源进入"已通过"状态，需单独调用上架接口发布。

4.5 审核驳回 POST /audit/reject

{"id": "资源ID", "reason": "驳回原因"}

参数	类型	必填	说明
id	String	是	资源ID
reason	String	是	驳回原因

auditStatus 变为 12，记录驳回原因和审核信息。

4.6 审核记录列表 GET /audit/records

参数	类型	必填	默认值	说明
pageNo	Integer	否	1	页码
pageSize	Integer	否	10	每页条数
resourceTitle	String	否	-	资源标题搜索
auditStatus	Integer	否	-	审核状态：11=通过/12=驳回
startDate	String	否	-	开始日期（yyyy-MM-dd）
endDate	String	否	-	结束日期（yyyy-MM-dd）

从审核记录表查询，按审核时间倒序。

---

5. 推送管理 emergency/firstAid/push

应急调度员在「正在应急」页面右侧面板搜索宣教资源，推送给求助者。

5.1 可推送资源列表 GET /push/resourceList

参数	类型	必填	默认值	说明
orderId	String	否	-	工单ID（用于标记推送状态）
keyword	String	否	-	关键词搜索（标题/内容）
categoryId	String	否	-	分类筛选
contentType	String	否	-	内容类型筛选
pageNo	Integer	否	1	页码
pageSize	Integer	否	20	每页条数

仅展示 status=1 && auditStatus=11 且未失效的资源。传 orderId 时，列表项的 pushed 字段标记该工单下是否已推送。

5.2 推送单条 POST /push/send

{
  "resourceId": "资源ID",
  "orderId": "工单ID"
}

校验资源状态为 status=1 && auditStatus=11，否则返回 "仅已发布且审核通过的资源可推送"。同一工单+同一资源不允许重复推送，重复返回 "该资源已推送，请勿重复操作"。

5.3 一键推送（批量） POST /push/batchSend

{
  "orderId": "工单ID（必填）",
  "resourceIds": ["id1", "id2"],
  "filterParams": {
    "keyword": "搜索关键词",
    "categoryId": "分类ID",
    "contentType": "IMAGE_TEXT"
  }
}

resourceIds 与 filterParams 二选一：

• 传 resourceIds：仅推送指定ID
• 传 filterParams：按条件查询后全量推送

部分失败不影响其他条，响应返回成功计数 {"count": 3}。

---

6. 收藏管理 emergency/firstAid/favorite

6.1 切换收藏 POST /favorite/toggle

{"id": "资源ID"}

已收藏则取消，未收藏则收藏。返回 {"favorited": true/false}。

6.2 查询收藏状态 GET /favorite/isFavorited

参数	类型	必填	说明
resourceId	String	是	资源ID

返回 {"favorited": true/false}。

6.3 我的收藏列表 GET /favorite/myList

参数	类型	必填	默认值	说明
pageNo	Integer	否	1	页码
pageSize	Integer	否	10	每页条数

---

7. 版本管理 emergency/firstAid/version

7.1 版本历史列表 GET /version/list

参数	类型	必填	说明
resourceId	String	是	资源ID

按版本号倒序，每条含：id, resourceId, versionNo, title, content, changeDescription, isCurrent, createBy, createTime。

7.2 回滚 POST /version/rollback

{"id": "版本记录ID"}

将目标版本的内容覆盖到资源，重置 status=0, auditStatus=null，并保存一条新的版本记录（标记为"回滚到版本N"）。

7.3 版本差异对比 GET /version/diff

参数	类型	必填	说明
versionId1	String	是	版本1的ID
versionId2	String	是	版本2的ID（须同一资源）

返回两个版本的完整信息用于前端差异对比。

---

响应数据结构

通用列表分页

{
  "success": true,
  "message": "",
  "code": 200,
  "result": {
    "records": [ ... ],
    "total": 100,
    "size": 10,
    "current": 1,
    "pages": 10
  },
  "timestamp": 1782196719184
}

通用操作响应

{
  "success": true,
  "message": "已上架",
  "code": 200,
  "result": "已上架",
  "timestamp": 1782196719184
}

资源列表项关键字段

字段	类型	说明
id	String	资源ID
title	String	标题
summary	String	摘要
contentType	String	内容类型
categoryId	String	分类ID
categoryName	String	分类名称（非持久）
tags	String	标签ID（逗号分隔）
tagNameList	List<String>	标签名称数组（非持久）
content	String	富文本正文
coverImage	String	封面图URL
fileUrl	String	附件JSON数组字符串
status	Integer	发布状态（0=草稿/1=已发布/2=已下架）
auditStatus	Integer	审核状态（null/10=待审核/11=已通过/12=已驳回）
auditRejectReason	String	驳回原因
auditBy	String	审核人
auditById	String	审核人ID
auditTime	Date	审核时间
viewCount	Integer	浏览次数
favoriteCount	Integer	收藏次数
isFavorited	Boolean	当前用户是否已收藏（非持久）
pushed	Boolean	当前工单下是否已推送（非持久，仅推送列表）
effectiveTime	Date	生效时间
expiryTime	Date	失效时间
createTime	Date	创建时间
updateTime	Date	更新时间

分类/标签项关键字段

字段	类型	说明
id	String	ID
name	String	名称
type	Integer	类型（1=分类/2=标签）
parentId	String	所属分类ID（标签有值，分类为null）
parentName	String	所属分类名称（非持久）
description	String	描述
sortNo	Integer	排序号
status	Integer	状态（1=正常/2=冻结）
resourceCount	Integer	关联资源数量（非持久，listAll/listWithTags 返回）
tags	List<FirstAidResourceCategory>	标签列表（非持久，listAll/listWithTags 返回）
createTime	Date	创建时间

审核记录项关键字段

字段	类型	说明
id	String	记录ID
resourceId	String	资源ID
resourceTitle	String	资源标题（非持久，查询时填充）
auditStatus	Integer	审核状态（11=通过/12=驳回）
auditRejectReason	String	驳回原因
auditBy	String	审核人
auditById	String	审核人ID
auditTime	Date	审核时间
createTime	Date	记录创建时间