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

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