diff --git a/changelogs-v2/2026-05/18_§2_traveler模块-新增接口-管理后台.md b/changelogs-v2/2026-05/18_§2_traveler模块-新增接口-管理后台.md index 231fe78..17d765c 100644 --- a/changelogs-v2/2026-05/18_§2_traveler模块-新增接口-管理后台.md +++ b/changelogs-v2/2026-05/18_§2_traveler模块-新增接口-管理后台.md @@ -12,9 +12,10 @@ |---|---|---|---| | **§2A 出行人 admin CRUD** | §2.1 列表 / §2.2 批量编辑 / §2.3 新增 / §2.4 软删 | **4** | ✅ | | **§2B 大交通批次 admin CRUD** | §2.6.1 列表 / §2.6.2 新增 / §2.6.3 编辑 / §2.6.4 软删 | **4** | ✅ | -| **§2C internal Feign** | §2.7 跨服务查出行人（含明文+解密审计） | **1** | ✅ | -| **§2D 动词类操作** | §2.8 smart-parse（⚠️ 待新建，Issue #2526）/ §2.9 validate | **2** | §2.9 ✅，§2.8 ⏳ wx 实现中 | -| **§2 合计** | — | **11** | ✅ 本次推送（§2.8 字段先定，wx 实现后接口可立即对接） | +| **§2C 动词类操作** | §2.8 smart-parse（⚠️ 待新建，Issue #2526）/ §2.9 validate | **2** | §2.9 ✅，§2.8 ⏳ wx 实现中 | +| **§2 合计** | — | **10** | ✅ 本次推送（§2.8 字段先定，wx 实现后接口可立即对接） | + +> **不在本 changelog 范围内**：§2.7 `GET /v3/internal/order/orders/{orderId}/travelers`（internal Feign 跨服务查出行人 + 解密审计）属于**后端 changelog 范畴**（受众=其他后端服务/运维，不是前端），将单独推到 `hl-backend-changelog` 仓库。 --- @@ -26,9 +27,8 @@ - 出行人不在 §1.1 创单接口里传，创单后通过 §2 单独添加（v4.8 取消占位行模型） - admin 端明文返回 idNo / phone / emergencyPhone（仅 B 端定制师可见，JWT 鉴权保护） - 大交通通过 `order_transport_plan_traveler` 桥接表（M:N）关联出行人，支持「一家分两批到达」场景 -- §2.7 internal feign 解密返回明文，**写入审计流水** `order_decrypt_audit_log` -本次推送 §2 模块全 11 接口，对应管理后台原型 F20 / F21 / F27（详情概览 + 出行人补全 + 接送站 + 大交通登记弹窗）。 +本次推送 §2 模块管理后台 10 个接口，对应管理后台原型 F20 / F21 / F27（详情概览 + 出行人补全 + 接送站 + 大交通登记弹窗）。`§2.7 internal feign` 不在本文档范围（见 §0 说明）。 --- @@ -44,9 +44,10 @@ | 6 | 2.6.2 | 大交通批次新增 | POST | `/v3/admin/order/{id}/transport-plans` | | 7 | 2.6.3 | 大交通批次编辑 | PUT | `/v3/admin/order/{id}/transport-plans/{planId}` | | 8 | 2.6.4 | 大交通批次软删 | DELETE | `/v3/admin/order/{id}/transport-plans/{planId}` | -| 9 | 2.7 | 跨服务查出行人（Feign） | GET | `/v3/internal/order/orders/{orderId}/travelers` | -| 10 | 2.8 ⏳ | 出行人智能批量解析 | POST | `/v3/admin/order/{id}/traveler/smart-parse` | -| 11 | 2.9 | 出行人信息校验 | GET | `/v3/admin/order/{id}/traveler/validate` | +| 9 | 2.8 ⏳ | 出行人智能批量解析 | POST | `/v3/admin/order/{id}/traveler/smart-parse` | +| 10 | 2.9 | 出行人信息校验 | GET | `/v3/admin/order/{id}/traveler/validate` | + +> §2.7 internal feign 接口不在本表（属后端 changelog）。 --- @@ -746,89 +747,7 @@ Authorization: Bearer {admin_jwt} --- -### 3.9 §2.7 跨服务查出行人（internal Feign） - -**路径**：`GET /v3/internal/order/orders/{orderId}/travelers` -**使用场景**：合同域签约 / 保险域投保 / mp-service 聚合等跨服务调用 -**敏感字段**：**明文返回**（idNo / phone / emergencyPhone 解密，仅内网 Feign + 签名校验保护） -**审计**：每次调用 INSERT `order_decrypt_audit_log`（解密审计永久流水） - -#### 入参 - -| 字段 | 类型 | 必填 | 说明 | -|------|------|:----:|------| -| `orderId` | Long | ✅ | 订单 ID（path） | -| `purpose` | String | ✅ | Query 参数。枚举见 §6.9（CONTRACT_SIGN / INSURANCE_ISSUE / OTHER） | - -#### 出参（`Result>`） - -字段同 §3.1 + 多 1 个 `decryptedAt`： - -| 字段 | 类型 | 说明 | -|------|------|------| -| ... | | 同 §3.1 全部字段（含敏感明文） | -| `decryptedAt` | LocalDateTime | 本次解密时间戳，写入审计流水 | - -#### 错误码 - -| code | 含义 | -|------|------| -| `589100` | orderId 不存在 | -| `589101` | purpose 枚举非法 | - -#### 业务边界 - -- ✅ **内网 Feign 专用**：Gateway 不暴露 `/internal/**` 至公网 -- ✅ **审计流水**：每次调用都写 `order_decrypt_audit_log`，含 `orderId` / `purpose` / `decryptedAt` / 调用方服务（取自 Feign 签名头） -- ⚠️ **purpose 必填**：用于审计 / 合规追溯，前端 / 上层调用方必须正确传 - -#### 示例 - -**典型 - 请求**： - -```http -GET /v3/internal/order/orders/60123456789012/travelers?purpose=CONTRACT_SIGN -``` - -**典型 - 响应**： - -```json -{ - "code": 200, - "data": [ - { - "id": "70123456789012", - "orderId": "60123456789012", - "travelerType": "ADULT", - "name": "张三", - "gender": "MALE", - "birthday": "1985-08-12", - "idType": "ID_CARD", - "idNo": "220103198508121234", - "nationality": "中国", - "race": "汉族", - "phone": "13812342046", - "emergencyContact": "李四", - "emergencyPhone": "13988888888", - "roomGroupNo": 1, - "profileStatus": "COMPLETED", - "transportPlanIds": [80012345, 80012346], - "decryptedAt": "2026-05-18T22:30:25" - } - ], - "msg": "success" -} -``` - -**异常（purpose 非法 589101） - 响应**： - -```json -{ "code": 589101, "data": null, "msg": "purpose 枚举非法" } -``` - ---- - -### 3.10 §2.8 出行人智能批量解析 ⏳ +### 3.9 §2.8 出行人智能批量解析 ⏳ **路径**：`POST /v3/admin/order/{id}/traveler/smart-parse` **使用场景**：F27 出行人补全 / 一键导入弹窗。定制师粘贴多行文本（姓名+证件号+手机号），后端解析为结构化出行人列表，校验后批量入库 @@ -911,7 +830,7 @@ Content-Type: application/json --- -### 3.11 §2.9 出行人信息校验 +### 3.10 §2.9 出行人信息校验 **路径**：`GET /v3/admin/order/{id}/traveler/validate` **使用场景**：支付前 / 锁单前置校验（同 §1.8 confirm-checklist 的 `TRAVELER_COMPLETE` 项底层依赖） @@ -1078,19 +997,9 @@ Authorization: Bearer {admin_jwt} | `AFTERNOON` | 下午 | | `EVENING` | 晚上 | -### 6.9 purpose（Feign 调用目的） +### 6.9 missingFields（缺失字段名） -**使用字段**：§3.9 入参 `purpose`（Query） - -| 值 | 说明 | -|----|------| -| `CONTRACT_SIGN` | 合同签约 | -| `INSURANCE_ISSUE` | 保险出单 | -| `OTHER` | 其他场景（需在审计流水里另行说明） | - -### 6.10 missingFields（缺失字段名） - -**使用字段**：§3.11 出参 `incompleteList[].missingFields[]` +**使用字段**：§3.10 出参 `incompleteList[].missingFields[]` 可能值（与 §3.1 字段名一致）：`name` / `idType` / `idNo` / `phone` @@ -1100,15 +1009,14 @@ Authorization: Bearer {admin_jwt} - **是否破坏向后兼容**：否（v3 全新二期，前端 v3 项目仓库首次消费） - **前端是否必须同步上线**：是 -- **本次推送范围**：§2 模块全 11 接口（含 §2.8 smart-parse 字段先定，wx 实现后立即可对接） +- **本次推送范围**：§2 模块管理后台 10 接口（含 §2.8 smart-parse 字段先定，wx 实现后立即可对接）。§2.7 internal feign 走后端 changelog 仓库，不在本表。 --- ## 12. 注意事项 - **§2.8 smart-parse 待 wx 新建（Issue [#2526](https://git.1814.love:8443/wx/HL/issues/2526)）**：前端可先按本文字段对接 UI，wx 实现完接口立即可调；接口字段已确定不会变 -- **敏感字段明文返回**：§2.1 / §2.3 / §2.7 / §2.9 / §2.8 admin/internal 接口返回 `idNo` / `phone` / `emergencyPhone` 明文，前端拿到后**不要**写本地 log / 不要塞 URL query；§2.9 `incompleteList[].name` 已脱敏 -- **`/v3/internal/**` 不暴露公网**：§3.9 跨服务 Feign 接口只在内网调用，前端不调 +- **敏感字段明文返回**：§2.1 / §2.3 / §2.8 / §2.9 admin 接口返回 `idNo` / `phone` / `emergencyPhone` 明文，前端拿到后**不要**写本地 log / 不要塞 URL query；§2.9 `incompleteList[].name` 已脱敏 - **桥接表约束**：§3.6 / §3.7 大交通批次新增/编辑时同方向同一出行人只能在 1 个 plan（错则 `581143`） - **删人合同强约束**：§3.4 已签电子合同后禁止删人 → `581119` - **`/v3/admin/**` 公司隔离**：所有 admin 接口均带跨公司隔离校验，跨公司访问返 `581021`，前端无需自行过滤 @@ -1121,5 +1029,6 @@ Authorization: Bearer {admin_jwt} - **SRS 业务规格**: `docs/order-v3/srs/order-cloud-v3-srs-v5.50.html` §1.0i 出行人模型 / §2 大交通 - **数据库 Schema**: `docs/order-v3/database/DATABASE-SCHEMA-V5.50.html`（`order_traveler` / `order_transport_plan` / `order_transport_plan_traveler` / `order_decrypt_audit_log`） - **§1 总 changelog**（订单核心模块）: `changelogs-v2/2026-05/18_§1_订单核心模块-新增接口-管理后台.md`（详情主聚合 §1.3.1 引用本模块 §2.1 TravelerVO 字段口径） -- **关联 Issue**：[#2517](https://git.1814.love:8443/wx/HL/issues/2517) ~ [#2527](https://git.1814.love:8443/wx/HL/issues/2527) 11 个，全部 assign wx；§2.8 [#2526](https://git.1814.love:8443/wx/HL/issues/2526) 为 0→1 新建 +- **§2.7 internal feign 单独走后端 changelog**: 待推 `hl-backend-changelog/.../18_§2.7_traveler-internal-feign-新增接口.md`（受众=合同 / 保险服务） +- **关联 Issue**：[#2517](https://git.1814.love:8443/wx/HL/issues/2517) ~ [#2527](https://git.1814.love:8443/wx/HL/issues/2527) 11 个（含 §2.7 [#2525](https://git.1814.love:8443/wx/HL/issues/2525) internal feign 单独走后端 changelog），全部 assign wx；§2.8 [#2526](https://git.1814.love:8443/wx/HL/issues/2526) 为 0→1 新建 - **后端负责人**: @yaosutu / 实施 @wx