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 +``` + +只看“待最终确认”时： + +```http +GET /v3/admin/order/todos?scope=mine&status=OPEN&todoType=PENDING_FINALIZE&page=1&pageSize=20 +Authorization: Bearer +``` + +查询参数名是 `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 +``` + +`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 + +``` + +所有 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 均按字符串透传。