API Changelog Bot cb2bbc7d46 docs(house): 交接待最终确认派生待办

2026-07-18 18:02:42 +08:00

8.9 KiB

原始文件 Blame 文件历史

【前端对接·管理后台】房务待办新增“待最终确认”派生项

Issue: wx/HL#5053

PR: wx/HL#5059

合并提交: 989318c3925b

服务: hl-order-service-v3 / hl-user-service

日期: 2026-07-18

影响范围: 房务“待处理”列表、待办类型筛选、订单详情跳转、房务工作台待办统计

一、对接结论

房务“待处理”页的唯一主数据源仍是 GET /v3/admin/order/todos，不要改用任何 my-claims 接单列表接口。my-claims 不返回完整的待办类型聚合，不能替代待办接口。
待办接口新增可选类型 PENDING_FINALIZE，中文标签为“待最终确认”。它是查询时派生的虚拟待办，不落 house_todo，因此 derived=true、标签级 todoId=null。
当前房务持有的 active 住宿需求处于 status=PROCESSING、houseStatus=PENDING_FINALIZE 时，接口返回该派生项；最终确认后需求进入 DONE/CONFIRMED，该项从列表、筛选结果和统计中自然消失。
list[].todoTypes[] 是一订单多标签的权威数据。点击 PENDING_FINALIZE 标签时必须使用该标签自己的 requirementId，不能依赖聚合行顶层 requirementId。
派生项不可调用待办 RESOLVE。用户应打开 OrderDetailModal 完成“最终确认”，成功后刷新待办列表与工作台仪表盘。
房务工作台 GET /admin/profile/dashboard 的 todoSummary 同步新增大写键 PENDING_FINALIZE。
本次没有修改 hl-ui；下文列出的现有前端筛选和标签级参数问题需由前端处理。

二、待办接口变化

2.1 请求

GET /v3/admin/order/todos?scope=mine&status=OPEN&page=1&pageSize=20
Authorization: Bearer <room-manager-token>

只看“待最终确认”时：

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 响应示例

{
  "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 生命周期

当前房务 + active requirement
status=PROCESSING + houseStatus=PENDING_FINALIZE
  → /todos 出现 PENDING_FINALIZE 派生标签
  → 用户从该标签进入订单详情并执行最终确认
  → status=DONE + houseStatus=CONFIRMED
  → /todos、todoType facet、stats 和 dashboard 中该项均消失/归零

该链路不创建 house_todo 记录，也不改变既有持久化待办的 RESOLVE 语义。

三、房务工作台统计变化

房务角色调用：

GET /admin/profile/dashboard?period=today
Authorization: Bearer <room-manager-token>

data.todoSummary 新增：

{
  "total": 4,
  "PENDING_FINALIZE": 1
}

键名固定为大写 PENDING_FINALIZE，与待办接口 stats、todoTypes[].typeCode 共用同一常量。
最终确认后该值归零；前端刷新列表时应同时刷新工作台数据或使对应查询缓存失效。

四、前端必须处理的现有问题

4.1 筛选器混用了“房务状态”和“待办类型”

当前 src/views/housekeeper/todos/index.vue:220-227 把以下值放在同一个 STATUS_OPTIONS 中：

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 标签。建议保留标签字段并按点击项分发：

const pendingFinalizeTag = row.todoTypes.find(
  (item) => item.typeCode === 'PENDING_FINALIZE'
)

openOrderDetail({
  orderId: row.orderId,
  requirementId: pendingFinalizeTag?.requirementId,
  claimScope: 'mine',
})

实际组件仍应复用现有 OrderDetailModal，传入：

<OrderDetailModal
  :order-id="orderId"
  :requirement-id="requirementId"
  claim-scope="mine"
/>

所有 ID 均按字符串处理，禁止转为 JavaScript Number。

4.3 完成动作

PENDING_FINALIZE 的处理入口是订单详情内“最终确认”，不是待办 RESOLVE：

从点击标签取得 orderId + todoTypes[].requirementId。
以 claimScope=mine 打开 OrderDetailModal。
用户执行一次“最终确认”。
成功后刷新 /v3/admin/order/todos 和 /admin/profile/dashboard。
列表行、筛选计数和工作台徽章应同步消失/归零。

五、已完成的后端与测试环境验证

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 均按字符串透传。

8.9 KiB 原始文件 Blame 文件历史 Unescape Escape