fix(§2): 删 §2.7 internal feign 接口节(前端 changelog 不收 internal)
按 CLAUDE.md changelog 受众判定:
- /v3/admin/* → 前端 changelog(本仓库 hl-api-changelog)
- /v3/internal/* → 后端 changelog(hl-backend-changelog,受众=其他后端服务/运维)
§2.7 GET /v3/internal/order/orders/{orderId}/travelers 是 internal Feign
跨服务接口(合同/保险服务调用),前端不消费,移出本文档:
- §0 模块全貌:删 §2C internal Feign 行,合计 11→10,加范围说明
- §1 接口背景:删 §2.7 解密审计行
- §2 变更清单:删第 9 行,剩 10 条
- §3.9 §2.7 internal feign 节整段删除
- §3.10 §2.8 smart-parse 重编号为 §3.9
- §3.11 §2.9 validate 重编号为 §3.10
- §6.9 purpose(Feign 调用目的)枚举删除
- §6.10 missingFields 重编号为 §6.9
- §11 推送范围:11→10 + 说明 §2.7 走后端 changelog
- §12 注意事项:删 internal 公网约束行
- §13 关联:加 §2.7 单独走后端 changelog 链接 + Issue #2525 备注
§2.7 后端 changelog 会单独推到 hl-backend-changelog 仓库。
这个提交包含在:
父节点
757a5dd60b
当前提交
2059566991
@ -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<List<TravelerInternalVO>>`)
|
||||
|
||||
字段同 §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
|
||||
|
||||
正在加载...
x
在新工单中引用
屏蔽一个用户