wx/hl-api-changelog
1
0
派生 0
代码 工单 合并请求 工作流 软件包 项目 发布 百科 活动

docs(v3-order): 按代码事实修订 §1/§2 changelog（fix issue #1 + 补充 5 项）

浏览代码 
回复 hl-api-changelog#1 前端反馈的 5 处契约不明 / 冲突，并同步补足 4 处文档与代码不一致：

§1 订单核心模块（15 处修改）：
- §3.1/§3.2/§3.3/§3.14 示例值：orderStatus/flowStatus 全部从中文标签改为英文枚举值
  （后端 OrderInfo.orderStatus/flowStatus 直接透传 DB 列的英文枚举字符串）
- §3.3 OrderMainVO 字段表：
  * customerName/customerPhone (admin 明文) → customerName + customerPhoneMasked（admin 也脱敏）
  * exceptionBadges/progressStepper 标注「运行时暂返 null，OrderInfoConverter 派生逻辑待 Issue 接通」
  * 新增 6 个 Tab 状态徽标字段（contractStatus/insuranceStatus/refundStatus/hasRefund/hasServiceStandard/hasFinanceDetail）
  * subStatus 枚举补 NOT_APPLICABLE + 列示 ASSIGN_PARALLEL 子项结构
  * 主聚合示例 transportPlanIds 改用真实雪花 ID（19 位）String
- §3.11 取消预览业务边界：粗状态集改英文枚举 + 说明 v3 已删「已确认」
- §3.14 transition：eventCode 入参表内联 9 个值，便于前端跳读
- §6.2 orderStatus：全表替换为 10 个英文枚举（PENDING_PAY/PENDING_COMPLETE/CUSTOMIZING/PENDING_DEPARTURE/PENDING_BALANCE/TRAVELLING/REVIEWING/SETTLED/REFUNDING/CANCELLED）
- §6.3 flowStatus：全表替换为 13 个英文枚举（AWAITING_DEPOSIT/.../CANCELLED_BEFORE_PAY）
- §6.4 consultantSource：补 SHARED + ROUND_ROBIN，说明 user-service 透传规则
- §6.17 加后端 enum 路径备注

§2 traveler 模块（9 处修改）：
- §3.1 出行人列表：每条 17 字段 → 16 字段（off-by-one 笔误）
- §3.1/§3.3 curl 示例：路径 /travelers → /traveler/list 和 /traveler/add（对齐字段表与代码 @PostMapping）
- §3.1 transportPlanIds：补全局 Long→String 序列化规则脚注 + 示例值改真实雪花 ID
- §3.4 错误码段位让位：581119 → 581106（已签合同禁删），581120 → 581107（最后成人禁删）
  （DB 段位 581119/581120 已分别被 TRAVELER_ID_CARD_DUPLICATE / TRANSPORT_PLAN_NOT_FOUND 占用）
- §3.9 smart-parse 错误码段位让位：581120/581121/581122/581123 → 581131/581132/100501/581134
  （581122 限流走 HL 全局 CommonErrorCode.RATE_LIMITED）
- §12 注意事项同步删人错误码

关联：
- Issue: https://git.1814.love:8443/wx/hl-api-changelog/issues/1
- 验证代码 commit: HL@dev-v3 47d24228
- 验证报告: HL/.claude/tmp-changelog/issue1-analysis.md（仅本地）
这个提交包含在：
yaosutu
2026-05-19 10:28:11 +08:00
父节点 fa843a7ba8
当前提交 89a1938cb9
共修改 2 个文件，包含 91 行新增和 69 行删除
下载 Patch 文件 下载 Diff 文件 展开所有文件 折叠所有文件
changelogs-v2/2026-05/18_§2_traveler模块-新增接口-管理后台.md
+19 -17
查看文件
@@ -69,7 +69,7 @@
`id` (path, Long) — 订单 ID
#### 出参（`Result<List<TravelerVO>>`，每条 17 字段）
#### 出参（`Result<List<TravelerVO>>`，每条 16 字段）
| 字段 | 类型 | 说明 |
|------|------|------|
@@ -90,6 +90,8 @@
| `profileStatus` | String | 枚举见 §6.4（PENDING / COMPLETED） |
| `transportPlanIds` | List\<Long\> | 关联的大交通批次 ID 列表 |
> ⚠️ **transportPlanIds 序列化规则**：后端字段类型 `List<Long>`，但 HL 全局 Jackson `NumberSerializer` 会自动把超过 JS 安全整数（2^53-1）的 Long 转 String 输出。大交通批次 ID 是雪花 ID（19 位），**实际响应中一定是 String 数组**；下面示例值 `80012345`（8 位短整数）仅为可读性目的，**生产值类似 `"80012345678901234"`**。前端按 String 数组接收。
#### 错误码
| code | 含义 |
@@ -102,7 +104,7 @@
**典型 - 请求**：
```http
GET /v3/admin/order/60123456789012/travelers
GET /v3/admin/order/60123456789012/traveler/list
Authorization: Bearer {admin_jwt}
```
@@ -128,7 +130,7 @@ Authorization: Bearer {admin_jwt}
"emergencyPhone": "13900008888",
"roomGroupNo": 1,
"profileStatus": "COMPLETED",
"transportPlanIds": [80012345, 80012346]
"transportPlanIds": ["80012345678901234", "80012345678901235"]
},
{
"id": "70123456789013",
@@ -317,7 +319,7 @@ Content-Type: application/json
**典型 - 请求**：
```http
POST /v3/admin/order/60123456789012/travelers
POST /v3/admin/order/60123456789012/traveler/add
Authorization: Bearer {admin_jwt}
Content-Type: application/json
@@ -392,15 +394,15 @@ Content-Type: application/json
|------|------|
| `581020` | 订单不存在 |
| `581110` | 出行人不属于该订单 |
| `581119` | 已签电子合同，禁止删除出行人 |
| `581120` | 出行人是订单最后 1 位成人，禁止删除 |
| `581106` | 已签电子合同，禁止删除出行人（DB 段位让位：581119 已被 `TRAVELER_ID_CARD_DUPLICATE` 占用，文档原 581119 让位至此） |
| `581107` | 出行人是订单最后 1 位成人，禁止删除（DB 段位让位：581120 已被 `TRANSPORT_PLAN_NOT_FOUND` 占用，文档原 581120 让位至此） |
#### 业务边界
- ✅ **软删**：UPDATE `order_traveler.deleted=1`，不真删
- ✅ **级联解除桥接**：UPDATE `order_transport_plan_traveler.deleted=1`
- ❌ **已签合同禁删**：合同强约束 → `581119`
- ❌ **最后成人禁删**：保留至少 1 位成人 → `581120`
- ❌ **已签合同禁删**：合同强约束 → `581106`
- ❌ **最后成人禁删**：保留至少 1 位成人 → `581107`
#### 示例
@@ -417,10 +419,10 @@ Authorization: Bearer {admin_jwt}
{ "code": 200, "data": true, "msg": "success" }
```
**异常（已签合同 581119） - 响应**：
**异常（已签合同 581106） - 响应**：
```json
{ "code": 581119, "data": null, "msg": "订单已签电子合同，禁止删除出行人" }
{ "code": 581106, "data": null, "msg": "订单已签电子合同，禁止删除出行人" }
```
---
@@ -774,10 +776,10 @@ Authorization: Bearer {admin_jwt}
| code | 含义 |
|------|------|
| `581120` | 原文超长（> 20000 字符） |
| `581121` | 原文为空或全行无法解析 |
| `581122` | 限流触发（10 次/分钟） |
| `581123` | 订单状态不允许批量导入（已结算 / 已取消） |
| `581131` | 原文超长（> 20000 字符）（DB 段位让位：原文档 581120 已被 `TRANSPORT_PLAN_NOT_FOUND` 占用） |
| `581132` | 原文为空或全行无法解析（DB 段位让位：原文档 581121 改至此） |
| `100501` | 限流触发（10 次/分钟）—— 走 HL 全局 `CommonErrorCode.RATE_LIMITED`，不在 traveler 段位 |
| `581134` | 订单状态不允许批量导入（已结算 / 已取消）（DB 段位让位：原文档 581123 改至此） |
#### 业务边界 + 审计安全
@@ -822,10 +824,10 @@ Content-Type: application/json
}
```
**异常（限流 581122） - 响应**：
**异常（限流 100501） - 响应**：
```json
{ "code": 581122, "data": null, "msg": "智能导入解析过于频繁,请稍后再试" }
{ "code": 100501, "data": null, "msg": "请求过于频繁，请稍后再试" }
```
---
@@ -1018,7 +1020,7 @@ Authorization: Bearer {admin_jwt}
- **§2.8 smart-parse 待 wx 新建（Issue [#2526](https://git.1814.love:8443/wx/HL/issues/2526)）**：前端可先按本文字段对接 UI，wx 实现完接口立即可调；接口字段已确定不会变
- **敏感字段明文返回**：§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`
- **删人合同强约束**：§3.4 已签电子合同后禁止删人 → `581106`
- **`/v3/admin/**` 公司隔离**：所有 admin 接口均带跨公司隔离校验，跨公司访问返 `581021`，前端无需自行过滤
---