feat(emergency): 新增移动端宣教详情接口，整理移动端API文档

- 新增 FirstAidResourceApiController，提供 GET /api/emergency/firstAid/resource/queryById - RequestPrefix 新增 FIRST_AID_RESOURCE 路径常量 - API文档-应急群聊拉人.md 合并入新文档 API文档-移动端接口.md（含群聊拉人 + 宣教资源） - API文档-急救宣教资源管理v3.md 保持管理后台接口
2026-07-06 15:45:55 +08:00
parent 9a022aa9cc
commit 4cb3411eca
5 changed files with 1068 additions and 292 deletions
@@ -0,0 +1,275 @@
+# 急救模块移动端 API 文档
+
+> **基础信息**  
+> 网关地址: `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`（东八区）
+
+---
+
+## 目录
+
+1. [应急群聊拉人](#1-应急群聊拉人-apiemergency)
+2. [宣教资源](#2-宣教资源-apiemergencyfirstaidresource)
+
+---
+
+## 1. 应急群聊拉人 `api/emergency`
+
+> 网关完整路径: `/health-emergency/api/emergency`
+
+### 1.1 搜索专家（专业人员） `GET /order/searchExpert`
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|:---:|------|
+| realname | String | 否 | 姓名，模糊搜索 |
+| centerId | String | 否 | 应急中心ID |
+| excludeSessionId | String | 否 | 群组ID，用于排除已在群中的人 |
+| pageNo | Integer | 否 | 页码，默认1 |
+| pageSize | Integer | 否 | 每页条数，默认10 |
+
+```json
+// 响应 result
+{
+  "records": [
+    {
+      "userId": "xxx", "realname": "张医生", "avatar": "https://...",
+      "type": "6", "centerId": "xxx",
+      "post": "主任医师", "school": "北京大学", "edu": "博士",
+      "goodAt": "心血管内科", "deptName": "急诊科"
+    }
+  ],
+  "total": 50, "size": 10, "current": 1
+}
+```
+
+| 字段 | 说明 |
+|------|------|
+| userId | 用户ID，邀请时传入 memberList |
+| realname | 姓名 |
+| avatar | 头像 |
+| type | 类型，"6"=专业人员 |
+| centerId | 应急中心ID |
+| post | 职称 |
+| school | 毕业院校 |
+| edu | 学历 |
+| goodAt | 擅长领域 |
+| deptName | 科室 |
+
+### 1.2 搜索员工 `GET /order/searchEmployee`
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|:---:|------|
+| realname | String | 否 | 姓名，模糊搜索 |
+| orgCode | String | 否 | 部门编码 |
+| workNo | String | 否 | 工号 |
+| phone | String | 否 | 手机号 |
+| excludeSessionId | String | 否 | 群组ID，用于排除已在群中的人 |
+| pageNo | Integer | 否 | 页码，默认1 |
+| pageSize | Integer | 否 | 每页条数，默认10 |
+
+```json
+// 响应 result
+{
+  "records": [
+    {
+      "userId": "xxx", "realname": "张三", "avatar": "https://...",
+      "orgCode": "650000001001", "orgName": "新疆油田公司",
+      "deptName": "安全环保部", "phone": "13800000000", "workNo": "A00123"
+    }
+  ],
+  "total": 200, "size": 10, "current": 1
+}
+```
+
+| 字段 | 说明 |
+|------|------|
+| userId | 用户ID，邀请时传入 memberList |
+| realname | 姓名 |
+| avatar | 头像 |
+| orgCode | 部门编码 |
+| orgName | 单位名称（二级单位） |
+| deptName | 部门名称 |
+| phone | 手机号 |
+| workNo | 工号 |
+
+### 1.3 创建群聊 `GET /createGroupMag`
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|:---:|------|
+| name | String | 是 | 群聊名称 |
+| longitude | String | 是 | 经度 |
+| latitude | String | 是 | 纬度 |
+| type | String | 否 | 类型 |
+
+> 返回 `groupId`（群组ID），作为后续拉人接口的入参。
+
+### 1.4 邀请进群 `POST /addGroupUser`
+
+拉专家或员工加入应急群聊。
+
+```json
+// Request Body
+{
+  "groupId": "1907659384834752513",
+  "memberList": ["userId1", "userId2"],
+  "memberType": 1
+}
+```
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|:---:|------|
+| groupId | String | 是 | 群组ID（即 `createGroupMag` 返回的 `groupId`） |
+| memberList | List\<String\> | 是 | 要邀请的用户ID列表，最多100个 |
+| memberType | Integer | 否 | `0`=专家/专业人员, `1`=员工，**默认0** |
+
+```json
+// 响应
+{"success": true, "message": "", "result": true}
+```
+
+> 已在群中的人员会自动跳过，不会报错。所有选中的人都在群中时返回失败。
+
+### 1.5 移除群成员 `POST /removeGroupUser`
+
+```json
+// Request Body
+{ "groupId": "1907659384834752513", "memberList": ["userId1"] }
+```
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|:---:|------|
+| groupId | String | 是 | 群组ID |
+| memberList | List\<String\> | 是 | 要移除的用户ID列表 |
+
+```json
+// 响应
+{"success": true, "message": "", "result": true}
+```
+
+> 只能移除后续拉入的协助人员，不能移除发起人和初始操作/专业人员。
+
+### 1.6 群成员列表 `GET /order/getGroupMemberList`
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|:---:|------|
+| sessionId | String | 是 | 群组ID |
+
+```json
+// 响应 result
+[
+  { "orderId": "...", "userId": "发起人id", "userName": "李四", "avatar": "https://...", "isGroupMember": 1, "memberType": -1 },
+  { "orderId": "...", "userId": "操作人员id", "userName": "王五", "avatar": "https://...", "isGroupMember": 1, "memberType": 0 },
+  { "orderId": "...", "userId": "专业人员id", "userName": "张医生", "avatar": "https://...", "isGroupMember": 1, "memberType": 1 },
+  { "orderId": "...", "userId": "员工id", "userName": "张三", "avatar": "https://...", "isGroupMember": 1, "memberType": 2 },
+  { "orderId": "...", "userId": "其他专业人id", "userName": "赵医生", "avatar": "https://...", "isGroupMember": 0, "memberType": 1 }
+]
+```
+
+| 字段 | 说明 |
+|------|------|
+| orderId | 应急单ID |
+| userId | 用户ID |
+| userName | 姓名 |
+| avatar | 头像 |
+| isGroupMember | `1`=在群中, `0`=可邀请 |
+| memberType | `-1`=发起人, `0`=操作人员, `1`=专业人员, `2`=员工 |
+
+### 1.7 memberType 字典
+
+| 值 | 含义 | 场景 |
+|:---:|------|------|
+| -1 | 发起人 | 创建应急的人 |
+| 0 | 操作人员 | 应急中心调度员 |
+| 1 | 专业人员 | 专家/医生 |
+| 2 | 员工 | 普通员工（被拉入群） |
+
+### 典型调用流程
+
+```
+1. 创建群聊
+   GET /health-emergency/api/emergency/createGroupMag?name=xxx&longitude=xxx&latitude=xxx
+
+2. 查看当前成员
+   GET /health-emergency/api/emergency/order/getGroupMemberList?sessionId={groupId}
+   → 展示群成员列表（按 memberType 区分标签展示）
+   → isGroupMember=0 的显示为"可邀请"
+
+3. 搜索要拉的人
+   GET /health-emergency/api/emergency/order/searchExpert?realname=张&excludeSessionId={groupId}
+   GET /health-emergency/api/emergency/order/searchEmployee?realname=李&excludeSessionId={groupId}
+   → 展示搜索结果，用户勾选
+
+4. 确认邀请
+   POST /health-emergency/api/emergency/addGroupUser
+   {"groupId": "{groupId}", "memberList": ["id1","id2"], "memberType": 0}
+
+5. 移除成员
+   POST /health-emergency/api/emergency/removeGroupUser
+   {"groupId": "{groupId}", "memberList": ["id1"]}
+
+6. 刷新成员列表
+   GET /health-emergency/api/emergency/order/getGroupMemberList?sessionId={groupId}
+```
+
+---
+
+## 2. 宣教资源 `api/emergency/firstAid/resource`
+
+> 网关完整路径: `/health-emergency/api/emergency/firstAid/resource`
+
+### 2.1 根据宣教ID查询详情 `GET /resource/queryById`
+
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|:---:|------|
+| id | String | 是 | 宣教资源ID |
+
+```json
+// 响应 result
+{
+  "id": "...",
+  "title": "心肺复苏指南",
+  "summary": "摘要简介",
+  "contentType": "IMAGE_TEXT",
+  "categoryId": "cat1",
+  "categoryName": "心肺复苏",
+  "applicableScenario": "适用场景",
+  "tags": "tag1,tag2",
+  "tagNameList": ["成人", "初级"],
+  "content": "<h1>富文本HTML正文</h1>",
+  "coverImage": "https://example.com/cover.jpg",
+  "fileUrl": "[\"https://example.com/file1.pdf\"]",
+  "viewCount": 100,
+  "favoriteCount": 20,
+  "isFavorited": false,
+  "effectiveTime": "2026-07-01 00:00:00",
+  "expiryTime": "2026-12-31 23:59:59",
+  "createTime": "2026-07-01 10:00:00",
+  "updateTime": "2026-07-05 14:30:00"
+}
+```
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| id | String | 资源ID |
+| title | String | 标题 |
+| summary | String | 摘要/简介 |
+| contentType | String | 内容类型：`IMAGE_TEXT`/`VIDEO`/`AUDIO`/`PDF` |
+| categoryId | String | 分类ID |
+| categoryName | String | 分类名称 |
+| applicableScenario | String | 适用场景 |
+| tags | String | 标签ID（逗号分隔） |
+| tagNameList | List\<String\> | 标签名称列表 |
+| content | String | 富文本正文HTML |
+| coverImage | String | 封面图URL |
+| fileUrl | String | 附件URL列表（JSON数组字符串） |
+| viewCount | Integer | 浏览次数 |
+| favoriteCount | Integer | 收藏次数 |
+| isFavorited | Boolean | 当前用户是否已收藏 |
+| effectiveTime | Date | 生效时间 |
+| expiryTime | Date | 失效时间 |
+| createTime | Date | 创建时间 |
+| updateTime | Date | 更新时间 |