From cb2bbc7d463920461e8b7ab367979f1aa897af11 Mon Sep 17 00:00:00 2001
From: API Changelog Bot <changelog@hulalv.com>
Date: Sat, 18 Jul 2026 18:02:42 +0800
Subject: [PATCH] =?UTF-8?q?docs(house):=20=E4=BA=A4=E6=8E=A5=E5=BE=85?=
 =?UTF-8?q?=E6=9C=80=E7=BB=88=E7=A1=AE=E8=AE=A4=E6=B4=BE=E7=94=9F=E5=BE=85?=
 =?UTF-8?q?=E5=8A=9E?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 ...¾…办新增待最终确认派生项-修改接å�£-管ç�†å�Žå�°.md | 213 ++++++++++++++++++
 1 file changed, 213 insertions(+)
 create mode 100644 changelogs-v2/2026-07/61_5053_房务待办新增待最终确认派生项-修改接�-管���.md

diff --git a/changelogs-v2/2026-07/61_5053_房务待办新增待最终确认派生项-修改接�-管���.md b/changelogs-v2/2026-07/61_5053_房务待办新增待最终确认派生项-修改接�-管���.md
new file mode 100644
index 0000000..d35e7d3
--- /dev/null
+++ 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 �按字符串�传。