docs(changelog): #6140 房务操作日志补「订单异常」留痕 + CLOSE 类型徽标中文化

2026-08-22 09:40:01 +08:00
@@ -0,0 +1,55 @@
+---
+schema: "hl-changelog/v2"
+ticket: "6140"
+title: "房务操作日志补「订单异常」留痕 + CLOSE 类型徽标中文化"
+consumer: "admin"
+author: "wx"
+change_type: "修改接口"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "pending"
+frontend_owner: "mmg"
+frontend_ref: ""
+target_release: ""
+verified_at: "2026-08-22"
+status_note: "房务工作台订单详情「操作日志」Tab：①订单进异常态（行程中终止/取消）现在有留痕，含发生时间；存量异常单靠读侧合成兜底，前端无需改代码；②CLOSE 类型徽标中文化（异常关闭）。前端只需确认列表正常展示新 opType。"
+updated_at: "2026-08-22"
+base: "dev-v3"
+generated: "2026-08-22T09:40:00+08:00"
+---
+
+# 房务操作日志补「订单异常」留痕 + CLOSE 类型徽标中文化（#6140）
+
+## 背景
+
+房务工作台订单详情抽屉「操作日志」Tab 三个问题（2026-08-21 wx 截图实证，TEST 订单 26-9250）：
+
+1. 订单「什么时候异常的」没有日志——只有「异常处置标记完成」，找不到进入异常态的那条；
+2. CLOSE 类型徽标显示英文原文（根因：#4307 加了 `HouseOpType.CLOSE` 常量但漏放 `HouseOpTypeLabel` 中文映射，读侧回退原值）；
+3. 系统（事件驱动）操作不落 `house_operation_log`。
+
+## 变更接口
+
+| 接口 | 变更 |
+| --- | --- |
+| `GET /v3/admin/house/orders/{orderId}/operation-log`（操作日志列表） | **新增 opType 枚举值 `EXCEPTION`（订单异常）**；`opTypeLabel` 新增映射：`CLOSE→异常关闭`、`EXCEPTION→订单异常` |
+
+无新端点、无字段结构变更；前端按 `opTypeLabel` 渲染的列表无需改代码即可看到新条目。
+
+## 新条目说明
+
+- **写侧落表**（本功能上线后的新终止/取消单）：行程中终止或订单取消使订单进房务异常态（已配房分支）时，同事务写一条 `opType=EXCEPTION` 日志：`operatorName=系统`，`summary` 形如「系统 订单异常·行程中终止 · 原因:xxx · 释放未用 N 行」，`time`=终止/取消事件处理时间；按 `orderId+EXCEPTION` 查重，事件重投不产生重复条目。
+- **读侧合成兜底**（存量异常单）：已终止但无写侧 EXCEPTION 行的订单（如 26-9250），查询时从终止退款数据合成一条「订单异常」项（`time`=终止处理时间，`id=null`），与写侧按订单去重不双计。
+- **summary 聚合**：合成项按各自 opType 计数（REQUIREMENT_SUBMIT 口径不变，EXCEPTION 至多 +1）。
+
+口径说明：写侧「释放未用 N 行」记实际释放的未确认候选行数；读侧合成取终止退款明细勾选的未用房晚数——勾选行含 CONFIRMED 被跳过时两值不同，属预期。
+
+## 前端动作
+
+无强制改动。建议确认：操作日志列表/筛选器对新增 `EXCEPTION` 类型正常展示（徽标文案直接用后端 `opTypeLabel`，勿前端硬编码映射）。
+
+## 验证证据
+
+- 单测：`HouseOpTypeLabelTest`（反射防漏）、`HouseTodoServiceTest` +3、`HouseHotelViewServiceTest` +3 全绿；`HouseModuleBoundaryArchTest` 通过。
+- 房务写路径 × 日志落痕全覆盖审计清单已随工单 #6140 评论归档（SYS_RECLAIM/询房写口功能未上线已注明；SWAP_HOTEL/SWAP_FAILED 缺口另立工单跟踪）。
+- TEST 网关实测：见工单验收评论。