docs(changelog-v2): order-v3 review 跟进 (PR #2833-2836 + hotfix #2840)
review 检出 P0/P1 共 4 张工单(#2821-2824)修复落地测试服: - HOUSE 配房工作台 §2.1-§2.5 + 询房 §3.3/§3.6 共 7 个接口路径迁移 - HOUSE-SWAP 越权校验 + 状态机 from 推导 + DRIVER 通知补发 + 4 个错误码同步文档 - 出行人 internal Feign transportPlanIds 真实化 + 错误码段位修正 - 大交通 TransportPlanVO Long 字段返字符串(防 JS 精度)+ batchReplace 加幂等 - order_todo 加唯一索引(hotfix V20260521_004 generated column UNIX_TIMESTAMP → COALESCE) - 通知中心 internal VO 后缀 + dispatch 单一真相源(前端不调,内部规范) 前端必看:7 个路径变更 + Long 字段类型变化 + 出行人错误码段位 5 处。
这个提交包含在：
API Changelog Bot
父节点
5371ba071b
当前提交
ed10a93879
@ -0,0 +1,186 @@
|
||||
# order-v3 review 跟进:配房工作台 / 询房 URL 重排 + HOUSE swap 多项修复 + 出行人/大交通杂项
|
||||
|
||||
> **存放目录**: 二期(v3 `order-v3` 标签)→ `changelogs-v2/2026-05/`
|
||||
> **服务**: hl-order-service-v3 (8086) + hl-user-service (8081)
|
||||
> **PR**: #2833 / #2834 / #2835 / #2836 / #2840(hotfix)
|
||||
> **Issue**: #2821 / #2822 / #2823 / #2824
|
||||
> **日期**: 2026-05-21
|
||||
> **影响范围**: 管理端 HOUSE 配房工作台 + HOUSE 询房 + HOUSE 换酒店 + 出行人/大交通若干字段
|
||||
|
||||
---
|
||||
|
||||
## ⚠️ 关键变化(前端必看)
|
||||
|
||||
### 🔴 路径变更(配房工作台 + 询房,5+2=7 个接口)
|
||||
|
||||
前端按 `API-SPEC-HOUSE-V1.1.html` 文档对接,**之前 4 个 PR (#2738-2754) 落地的代码路径与文档严重不一致,会全部 404**;本批 PR #2833 已**对齐文档**。前端按文档实现的请直接对接新路径;之前对接到旧路径的,请按下表改 URL:
|
||||
|
||||
| 接口 | 旧路径(已废弃) | 新路径(以此为准) |
|
||||
|------|----------------|-------------------|
|
||||
| §2.1 配房候选源 | `GET /v3/admin/house/assignments/candidates?requirementId=X` | **`GET /v3/admin/order/hotel-requirements/{rid}/candidates`** (rid 走 PathVariable) |
|
||||
| §2.2 提交配房 | `POST /v3/admin/house/assignments`(rid 在 body) | **`POST /v3/admin/order/hotel-requirements/{rid}/assignments`**(rid 走 PathVariable;body 不再传 requirementId) |
|
||||
| §2.3 修改配房 | `PUT /v3/admin/house/assignments/{id}` | **`PUT /v3/admin/order/assignments/{id}`** |
|
||||
| §2.4 删除配房 | `DELETE /v3/admin/house/assignments/{id}` | **`DELETE /v3/admin/order/assignments/{id}`** |
|
||||
| §2.5 房间分配 | `POST /v3/admin/house/assignments/{id}/rooms`(POST 写入) | **`GET /v3/admin/order/orders/{orderId}/rooms`**(HTTP 方法 + 路径 + 入参形态全改 — GET 查询语义,按家庭分组返结果) |
|
||||
| §3.3 询房历史 | `GET /v3/admin/order/inquiry/by-order` | **`GET /v3/admin/order/inquiry?orderId=X`** |
|
||||
| §3.6 加急 | `POST /v3/admin/order/inquiry/{id}/urgent` | **`POST /v3/admin/order/inquiry/{id}/escalate`** |
|
||||
|
||||
§2.5 GET 新 VO `OrderRoomsRespVO`:
|
||||
|
||||
```json
|
||||
{
|
||||
"orderId": "string",
|
||||
"families": [
|
||||
{
|
||||
"familyNo": "F1",
|
||||
"travelers": [{ "travelerId": "string", "name": "张三", "phoneMasked": "138****5612" }],
|
||||
"days": [{ "dayNumber": 1, "rooms": [{ "hotelName": "...", "roomTypeName": "..." }] }]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 一、背景
|
||||
|
||||
dev-v3 近 3 天(2026-05-18~21)合并 30+ PR / 786 文件 / +74,352 行(出行人 + 大交通 + HOUSE H01-H10 + FIX A-H + 通知中心 internal),全模块工作流 review 检出 10 P0 + 36 P1。本批 4 张 P0/P1 工单(#2821-2824)+ 1 张 hotfix(#2840 Flyway 修)对应 4 张 PR + 1 张 hotfix 全部测试服部署 + Flyway 落库 + admin token round-trip 验证通过。
|
||||
|
||||
---
|
||||
|
||||
## 二、变更接口清单
|
||||
|
||||
| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
|
||||
|---|------|------|------|----------|------|
|
||||
| 1 | 配房候选源 | GET | `/v3/admin/order/hotel-requirements/{rid}/candidates` | **路径迁移** | 旧 `/v3/admin/house/assignments/candidates` 废弃 |
|
||||
| 2 | 提交配房 | POST | `/v3/admin/order/hotel-requirements/{rid}/assignments` | **路径迁移** | rid 改 PathVariable,body 删 requirementId |
|
||||
| 3 | 修改配房 | PUT | `/v3/admin/order/assignments/{id}` | **路径迁移** | |
|
||||
| 4 | 删除配房 | DELETE | `/v3/admin/order/assignments/{id}` | **路径迁移** | |
|
||||
| 5 | 房间分配 | **GET**(原 POST) | `/v3/admin/order/orders/{orderId}/rooms` | **方法+路径全改+新 VO** | 改为查询语义,按家庭分组聚合 |
|
||||
| 6 | 询房历史 | GET | `/v3/admin/order/inquiry?orderId=X` | **路径迁移** | `/by-order` 后缀去掉 |
|
||||
| 7 | 询房加急 | POST | `/v3/admin/order/inquiry/{id}/escalate` | **路径迁移** | `/urgent` 改 `/escalate` |
|
||||
| 8 | 换酒店提交 | POST | `/v3/admin/order/swap-hotel/commit` | **权限校验补全** | 越权返 `808402`(详 §三-1) |
|
||||
| 9 | 大交通 VO 字段类型 | - | `TransportPlanVO.id / orderId / travelers[].id` | **响应字段类型 Long → String** | 防 JS 精度丢失 |
|
||||
| 10 | 出行人 internal Feign | GET | `/v3/internal/traveler/list-by-order/{orderId}` | **返回字段补值** | `transportPlanIds` 不再永空,合同/保险拿到真大交通批次 |
|
||||
| 11 | 出行人错误码 | - | 多接口 | **错误码段位修正** | 见 §三-3 |
|
||||
| 12 | 大交通 batchReplace | POST | `/v3/admin/order/{id}/transport-plan/batch-replace` | **加幂等 + 分布式锁** | 防重复提交触发全量替换 |
|
||||
|
||||
---
|
||||
|
||||
## 三、接口详情
|
||||
|
||||
### 1. 换酒店模块 (PR #2834)
|
||||
|
||||
#### 权限校验补齐(原 TODO)
|
||||
|
||||
之前 `POST /v3/admin/order/swap-hotel/commit` 没校验"当前用户是订单 assignee" — 任何房务 token 都能改别人的订单。**已修复,跨用户越权返 `808402`**。
|
||||
|
||||
```http
|
||||
HTTP/1.1 200 OK
|
||||
{ "code": 808402, "message": "当前用户必须为订单 assignee 才能操作", "success": false }
|
||||
```
|
||||
|
||||
#### 状态机审计正确性
|
||||
|
||||
之前 `swap` 业务的状态机 fire 写死 `from=CLAIMING`,审计日志失真。现根据 `house_todo` 表 OPEN `SWAP_HOTEL`/`REFUND` 待办推导真实 from(`EXCEPTION` 或 `CLAIMING`)。**前端 UI 不直接感知,但订单操作日志看 from 字段会更准确**。
|
||||
|
||||
#### DRIVER 通知补发(原漏发,业务 BUG)
|
||||
|
||||
API-SPEC-HOUSE §5.3 列了 4 个 receiver_type(`OLD_HOTEL / NEW_HOTEL / DRIVER / ORDER_CUSTOMER`),之前代码只发 3 个,**司机收不到换酒店通知**。本 PR 补 DRIVER。
|
||||
|
||||
⚠️ DRIVER 实际企微推送需 FLEET `vehicle_plan` 反查 Feign(留尾,后续工单接通),当前发送链路 = 事件落库 + dispatcher noop 占位(不抛错不阻塞)。
|
||||
|
||||
#### 新增错误码(API-SPEC-HOUSE §5.3 / §11.6 已同步)
|
||||
|
||||
| 错误码 | 说明 |
|
||||
|--------|------|
|
||||
| `808404` | 旧酒店 ID 与新酒店 ID 相同 |
|
||||
| `808405` | 仅 PROCESSING / EXCEPTION 状态可换酒店 |
|
||||
| `808406` | 换酒店写库失败,请重试 |
|
||||
| `808407` | 新酒店库存不足 |
|
||||
|
||||
---
|
||||
|
||||
### 2. 大交通 — Long 字段类型变化 (PR #2836)
|
||||
|
||||
`TransportPlanVO` 中以下三个字段以前响应是 JSON Number(可能精度丢失),现统一返字符串:
|
||||
|
||||
| VO 字段 | 旧类型 | 新类型 | 示例 |
|
||||
|---------|--------|--------|------|
|
||||
| `TransportPlanVO.id` | number | **string** | `"80012345"` |
|
||||
| `TransportPlanVO.orderId` | number | **string** | `"30099887"` |
|
||||
| `TransportPlanVO.travelers[].id` | number | **string** | `"40055001"` |
|
||||
|
||||
**前端检查**:`Number(id)` / `parseInt(id)` 这类用法需改;直接 `id` 字符串传回后端 / 当 key 用没影响。
|
||||
|
||||
---
|
||||
|
||||
### 3. 出行人错误码段位修正 (PR #2836)
|
||||
|
||||
`docs/order-v3/api/API-SPEC-V5.54.html` 错误码表 5 处更新(以代码为准):
|
||||
|
||||
| 章节 | 旧码 | 新码 |
|
||||
|------|------|------|
|
||||
| §2.1 列表 | `581100` | `581102` |
|
||||
| §2.2 批量编辑 9 行错误码表 | 581100-581124 | **581101-581105 / 581110-581114 / 581111 / 581119** |
|
||||
| §2.3 单个新增 | `581100` → `581102`;补 581115/581116/581118 |
|
||||
| §2.4 删除 | `581119→581106 / 581120→581107 / 581100→581102` |
|
||||
| §2.8 智能解析 | `581120-581123` | `581131-581134` |
|
||||
| §2.9 校验 | `581124` | `581102` |
|
||||
|
||||
前端如做了 i18n 映射,请按新码更新 — 否则会命中默认文案。
|
||||
|
||||
---
|
||||
|
||||
### 4. 出行人 internal Feign `transportPlanIds` 真实化 (PR #2836)
|
||||
|
||||
`GET /v3/internal/traveler/list-by-order/{orderId}` 之前 `transportPlanIds` 字段硬编码空数组,合同/保险服务跨服务调用永远拿不到出行人绑定的大交通批次 ID。本 PR 修复,字段返真实值。**前端不直接调 internal,影响合同/保险出参的"出行人.transportPlanIds"字段**。
|
||||
|
||||
---
|
||||
|
||||
### 5. 大交通 batchReplace 并发保护 (PR #2836)
|
||||
|
||||
`POST /v3/admin/order/{id}/transport-plan/batch-replace` 全量替换接口加 `@Idempotent`(3s)+ `@Lock4j`(30s)— 短时间重复提交会拒绝,前端无需改但可减少重复提交风险。
|
||||
|
||||
---
|
||||
|
||||
### 6. 通知中心 internal 套件规范(后端内部) (PR #2835)
|
||||
|
||||
`/internal/notification/dispatch` / `/publish` 加幂等 + dispatch 返回类型从 void 改 `DispatchResult { success, channelsTriggered, errorMessage }`。**前端不调 internal,无影响**。
|
||||
|
||||
---
|
||||
|
||||
### 7. order_todo 唯一索引 (PR #2836 / hotfix #2840)
|
||||
|
||||
DB 加 `(order_id, todo_type, sequence, deleted_marker)` 唯一索引,防并发触发重复紧急待办。前端无感。
|
||||
|
||||
> hotfix #2840:V20260521_004 generated column 用 `UNIX_TIMESTAMP` 触发 MySQL 8 `ERROR 3763 disallowed function`,已改 `COALESCE(deleted_at, '1970-01-01')`(deterministic)。
|
||||
|
||||
---
|
||||
|
||||
## 四、测试服验证状态
|
||||
|
||||
| 服务 | 部署 commit | uptime | Flyway | admin round-trip |
|
||||
|------|------------|--------|--------|------------------|
|
||||
| hl-user-service | dev-v3 含 #2834/#2835 | 已重启 | V20260521_007 success=1 17:49 | ✅ |
|
||||
| hl-order-service-v3 | dev-v3 含 #2833/#2836/#2840 | 18:12 重启 | V20260521_004 success=1 18:12 | ✅ §3.3 / §3.6 / §2.5 / §2.1 全 200/合理 400 |
|
||||
|
||||
唯一索引 `uk_todo_order_type_seq_active` 已在 `hl_order_service_v3.order_todo` 表生效。
|
||||
|
||||
---
|
||||
|
||||
## 五、留尾(后续 v3 工单)
|
||||
|
||||
- **HOUSE-SWAP DRIVER 通知** wework 真值切换 → 需 FLEET `vehicle_plan` 反查 Feign 工单
|
||||
- **HOUSE-FIX-A 候选源数据真实化**(`loadProductPool`)→ 需 H04 完整接通 `ProductV2FeignClient`
|
||||
- **`HouseInventoryCheckedEvent` 消费方**(`H09` MQ 桥接 PR)
|
||||
- **TravelerErrorCode 段位整体迁移代码常量**(大版本可决议)
|
||||
- **`operationLogMapper` 收敛** 到 `HotelOperationLogService`(待该 Service 出现)
|
||||
|
||||
---
|
||||
|
||||
## 六、关联
|
||||
|
||||
- 工单: #2821 / #2822 / #2823 / #2824(全部 closed)
|
||||
- PR: #2833 / #2834 / #2835 / #2836 / #2840(全部 merged into dev-v3)
|
||||
- Review 来源: Claude /@cr 7 个 agent 并发对照 `docs/order-v3/` SRS+API+DB+Detail
|
||||
正在加载...
x
在新工单中引用
屏蔽一个用户