docs(house): 交接待最终确认派生待办

2026-07-18 18:02:42 +08:00 · 2026-07-18 18:02:42 +08:00 · cb2bbc7d46
--- a/changelogs-v2/2026-07/61_5053_房务待办新增待最终确认派生项-修改接口-管理后台.md
+++ b/changelogs-v2/2026-07/61_5053_房务待办新增待最终确认派生项-修改接口-管理后台.md
@ -0,0 +1,213 @@
+# 【前端对接·管理后台】房务待办新增“待最终确认”派生项
+
+> Issue: [wx/HL#5053](https://git.1814.love:8443/wx/HL/issues/5053)
+>
+> PR: [wx/HL#5059](https://git.1814.love:8443/wx/HL/pulls/5059)
+>
+> 合并提交: `989318c3925b`
+>
+> 服务: `hl-order-service-v3` / `hl-user-service`
+>
+> 日期: 2026-07-18
+>
+> 影响范围: 房务“待处理”列表、待办类型筛选、订单详情跳转、房务工作台待办统计
+
+## 一、对接结论
+
+1. 房务“待处理”页的唯一主数据源仍是 `GET /v3/admin/order/todos`，不要改用任何 `my-claims` 接单列表接口。`my-claims` 不返回完整的待办类型聚合，不能替代待办接口。
+2. 待办接口新增可选类型 `PENDING_FINALIZE`，中文标签为“待最终确认”。它是查询时派生的虚拟待办，不落 `house_todo`，因此 `derived=true`、标签级 `todoId=null`。
+3. 当前房务持有的 active 住宿需求处于 `status=PROCESSING`、`houseStatus=PENDING_FINALIZE` 时，接口返回该派生项；最终确认后需求进入 `DONE/CONFIRMED`，该项从列表、筛选结果和统计中自然消失。
+4. `list[].todoTypes[]` 是一订单多标签的权威数据。点击 `PENDING_FINALIZE` 标签时必须使用该标签自己的 `requirementId`，不能依赖聚合行顶层 `requirementId`。
+5. 派生项不可调用待办 `RESOLVE`。用户应打开 `OrderDetailModal` 完成“最终确认”，成功后刷新待办列表与工作台仪表盘。
+6. 房务工作台 `GET /admin/profile/dashboard` 的 `todoSummary` 同步新增大写键 `PENDING_FINALIZE`。
+7. 本次没有修改 `hl-ui`；下文列出的现有前端筛选和标签级参数问题需由前端处理。
+
+## 二、待办接口变化
+
+### 2.1 请求
+
+```http
+GET /v3/admin/order/todos?scope=mine&status=OPEN&page=1&pageSize=20
+Authorization: Bearer <room-manager-token>
+```
+
+只看“待最终确认”时：
+
+```http
+GET /v3/admin/order/todos?scope=mine&status=OPEN&todoType=PENDING_FINALIZE&page=1&pageSize=20
+Authorization: Bearer <room-manager-token>
+```
+
+查询参数名是 `todoType`，不是 `type`。`todoType` 支持逗号分隔多选。
+
+### 2.2 响应示例
+
+```json
+{
+  "code": 200,
+  "data": {
+    "list": [
+      {
+        "id": null,
+        "orderId": "2000000000000000001",
+        "orderNo": "HL202607180001",
+        "todoType": "PENDING_FINALIZE",
+        "todoTypeLabel": "待最终确认",
+        "title": "待最终确认",
+        "urgency": "normal",
+        "status": "OPEN",
+        "derived": true,
+        "requirementId": "2000000000000000101",
+        "orderTodoCount": 1,
+        "todoTypes": [
+          {
+            "typeCode": "PENDING_FINALIZE",
+            "typeLabel": "待最终确认",
+            "urgency": "normal",
+            "count": 1,
+            "derived": true,
+            "todoId": null,
+            "requirementId": "2000000000000000101",
+            "unreadCount": null
+          }
+        ]
+      }
+    ],
+    "total": 1,
+    "stats": {
+      "PENDING_FINALIZE": 1
+    }
+  }
+}
+```
+
+字段规则：
+
+| 字段 | 前端规则 |
+|---|---|
+| `list[].todoTypes[]` | 一订单多待办类型的权威标签数组，必须完整渲染。 |
+| `todoTypes[].typeCode` | 新增可选值 `PENDING_FINALIZE`。 |
+| `todoTypes[].typeLabel` | 直接展示后端中文“待最终确认”。 |
+| `todoTypes[].derived` | `true` 表示虚拟待办，由源业务状态自然消失。 |
+| `todoTypes[].todoId` | `PENDING_FINALIZE` 固定为 `null`，禁止调用 `RESOLVE`。 |
+| `todoTypes[].requirementId` | 打开该标签对应房务详情时使用；雪花 ID 按字符串透传。 |
+| `list[].requirementId` | 只兼容聚合行主标签；一行多标签时不能替代标签级字段。 |
+| `stats.PENDING_FINALIZE` | 当前 scope 内“待最终确认”需求数；无数据也返回 `0`。 |
+
+`stats` 是当前 scope 的完整分类计数，不因本次 `todoType` facet 收窄；因此筛选结果 `total` 可以是 `1`，同时其他统计槽仍保留其真实值。
+
+### 2.3 生命周期
+
+```text
+当前房务 + active requirement
+status=PROCESSING + houseStatus=PENDING_FINALIZE
+  → /todos 出现 PENDING_FINALIZE 派生标签
+  → 用户从该标签进入订单详情并执行最终确认
+  → status=DONE + houseStatus=CONFIRMED
+  → /todos、todoType facet、stats 和 dashboard 中该项均消失/归零
+```
+
+该链路不创建 `house_todo` 记录，也不改变既有持久化待办的 RESOLVE 语义。
+
+## 三、房务工作台统计变化
+
+房务角色调用：
+
+```http
+GET /admin/profile/dashboard?period=today
+Authorization: Bearer <room-manager-token>
+```
+
+`data.todoSummary` 新增：
+
+```json
+{
+  "total": 4,
+  "PENDING_FINALIZE": 1
+}
+```
+
+- 键名固定为大写 `PENDING_FINALIZE`，与待办接口 `stats`、`todoTypes[].typeCode` 共用同一常量。
+- 最终确认后该值归零；前端刷新列表时应同时刷新工作台数据或使对应查询缓存失效。
+
+## 四、前端必须处理的现有问题
+
+### 4.1 筛选器混用了“房务状态”和“待办类型”
+
+当前 `src/views/housekeeper/todos/index.vue:220-227` 把以下值放在同一个 `STATUS_OPTIONS` 中：
+
+```text
+HOTEL_REPLY_TIMEOUT / PENDING_ARRANGE /
+CLAIMING / IN_INQUIRY / PENDING_FINALIZE / EXCEPTION
+```
+
+但同文件 `:370` 固定请求 `status=OPEN`，`:374` 又把所有非“全部”选项都作为 `todoType`，最终由 `:386` 请求待办接口。
+
+- `HOTEL_REPLY_TIMEOUT`、`PENDING_ARRANGE`、`PENDING_FINALIZE` 是合法 `HouseTodoType`。
+- `CLAIMING`、`EXCEPTION` 是房务业务状态，不是待办类型，作为 `todoType` 请求会得到空结果。
+- `IN_INQUIRY` 已不再是顶层房务状态，也不是待办类型。
+
+前端应删除这三个无效 `todoType` 选项；如产品确实需要按房务状态筛选，应另行使用声明支持该参数的数据源，不能继续混传给 `/todos.todoType`。
+
+同时，`src/api/housekeeper/todos.js:53` 的注释仍写 `params.type`，实际页面和后端均使用 `params.todoType`；请同步修正文档注释，API 调用本身仍是 `:66-67` 的 `/v3/admin/order/todos`。
+
+### 4.2 标签级 `requirementId` 在映射时丢失
+
+当前 `src/views/housekeeper/todos/index.vue:290-313` 把 `todoTypes[]` 映射成 `reasonTags` 时只保留了 `typeCode/label/derived`，未保留标签自己的 `requirementId`；`:267` 和 `:453` 只使用聚合行顶层 `requirementId`。
+
+一订单多标签时，顶层字段属于“主标签”，不保证就是用户点击的 `PENDING_FINALIZE` 标签。建议保留标签字段并按点击项分发：
+
+```js
+const pendingFinalizeTag = row.todoTypes.find(
+  (item) => item.typeCode === 'PENDING_FINALIZE'
+)
+
+openOrderDetail({
+  orderId: row.orderId,
+  requirementId: pendingFinalizeTag?.requirementId,
+  claimScope: 'mine',
+})
+```
+
+实际组件仍应复用现有 `OrderDetailModal`，传入：
+
+```vue
+<OrderDetailModal
+  :order-id="orderId"
+  :requirement-id="requirementId"
+  claim-scope="mine"
+/>
+```
+
+所有 ID 均按字符串处理，禁止转为 JavaScript `Number`。
+
+### 4.3 完成动作
+
+`PENDING_FINALIZE` 的处理入口是订单详情内“最终确认”，不是待办 `RESOLVE`：
+
+1. 从点击标签取得 `orderId + todoTypes[].requirementId`。
+2. 以 `claimScope=mine` 打开 `OrderDetailModal`。
+3. 用户执行一次“最终确认”。
+4. 成功后刷新 `/v3/admin/order/todos` 和 `/admin/profile/dashboard`。
+5. 列表行、筛选计数和工作台徽章应同步消失/归零。
+
+## 五、已完成的后端与测试环境验证
+
+- PR #5059 已合并到 `dev-v3`，合并提交为 `989318c3925b`。
+- `hl-order-service-v3` TEST 部署任务 `fd8522fe` 成功，`8086/8186` 双实例健康。
+- `hl-user-service` TEST 部署任务 `372a9f3e` 成功，`8081/8181` 双实例健康。
+- 网关 API 实测：进入待最终确认前 `PENDING_FINALIZE=0`；测试需求进入 `PROCESSING/PENDING_FINALIZE` 后，列表、facet、`stats` 和 dashboard 均为 `1`；最终确认后均恢复为 `0`。
+- TEST DB 对账：派生项出现时没有新增 `house_todo(PENDING_FINALIZE)`；最终确认后需求为 `DONE/CONFIRMED`，两晚配房仍为 `CONFIRMED`，房务归属和配房数据均保留。
+- 真实调试 Chrome 已验证“待最终确认”标签可见、筛选只剩目标订单、最终确认后列表空态；浏览器验收仅作为前端对接参考，不改变上述接口契约。
+
+## 六、前端验收清单
+
+- [ ] “待处理”页仅以 `GET /v3/admin/order/todos` 为主数据源。
+- [ ] `STATUS_OPTIONS` 不再把 `CLAIMING/IN_INQUIRY/EXCEPTION` 作为 `todoType` 发送。
+- [ ] 使用 `todoType=PENDING_FINALIZE` 可筛出“待最终确认”订单。
+- [ ] 完整渲染 `list[].todoTypes[]`，显示后端 `typeLabel`。
+- [ ] 映射和点击事件保留 `todoTypes[].requirementId`。
+- [ ] 以 `orderId + 标签级 requirementId + claimScope=mine` 打开 `OrderDetailModal`。
+- [ ] 派生标签不调用待办 `RESOLVE`。
+- [ ] 最终确认成功后刷新待办列表和 dashboard，标签与计数同步消失。
+- [ ] 所有雪花 ID 均按字符串透传。