docs(house): notify frontend todo timeout tags

changelogs-v2/2026-07/19_房务待处理询房超时标签未渲染-前端待处理-管理后台.md

@@ -0,0 +1,113 @@
+# 房务待处理询房超时标签未渲染
+
+> 模块：管理后台 · 房务管家 `/housekeeper/todos`
+> 类型：**前端待处理（后端无接口变更）**
+> 日期：2026-07-05
+> 说明：后端待办接口已返回询房超时标签，前端需切换正确数据源并渲染 `todoTypes`。
+
+## 问题现象
+
+测试页面：
+
+- 页面：房务管家 → 待处理
+- 订单：`HL20260703140009570`
+- 客人：`wx定制师配房测试03`
+- 现象：订单已发起询房超过 10 分钟，页面卡片仍只显示“配房中”，未显示“酒店超时未回复/询房超时”标签。
+
+## 后端当前口径
+
+后端接口已返回超时待办，不是定时任务异常。
+
+```http
+GET /v3/admin/order/todos?scope=mine&page=1&pageSize=20&status=OPEN
+```
+
+测试服复验结果：
+
+| 字段 | 值 |
+|------|----|
+| `orderNo` | `HL20260703140009570` |
+| `todoType` | `HOTEL_REPLY_TIMEOUT` |
+| `title` | `酒店超10分钟未回复 · 请跟进或换酒店` |
+| `stats.HOTEL_REPLY_TIMEOUT` | `2` |
+
+`todoTypes` 返回：
+
+| typeCode | typeLabel | count | derived |
+|----------|-----------|-------|---------|
+| `HOTEL_REPLY_TIMEOUT` | `酒店超时未回复` | `2` | `false` |
+| `PENDING_ARRANGE` | `刚抢单待配房` | `1` | `true` |
+
+## 根因
+
+当前前端待处理页仍在调用“我的接单”列表接口：
+
+```http
+GET /v3/admin/order/grab-pool/my-claims/hotel
+```
+
+该接口是接单列表口径，只返回 `todoCount=2`，不返回具体 `todoTypes`。因此页面无法知道本单有哪些待办原因，也就不能展示 `HOTEL_REPLY_TIMEOUT` 标签。
+
+## 【前端 · 管理后台】处理要求
+
+### 1. 待处理页数据源切换为待办接口
+
+房务待处理页 `/housekeeper/todos` 列表应调用：
+
+```http
+GET /v3/admin/order/todos
+```
+
+建议参数：
+
+| 场景 | 参数 |
+|------|------|
+| 我的未完成 | `scope=mine&status=OPEN&page=1&pageSize=20` |
+| 全部 | `scope=all&status=OPEN&page=1&pageSize=20` |
+| 按类型筛选 | 增加 `todoType=HOTEL_REPLY_TIMEOUT` 等枚举 |
+
+不要再使用 `my-claims/hotel` 的 `status=claiming/inInquiry/pendingConfirm/exception` 口径作为待处理页主数据源。
+
+### 2. 按 `todoTypes[]` 渲染多标签
+
+待处理页卡片需要按后端 `todoTypes[]` 渲染原因标签：
+
+- `typeLabel` 作为标签文案。
+- `count > 1` 时展示数量，例如 `酒店超时未回复 · 2`。
+- `derived=true` 的标签可保留弱化/虚线样式，但仍需展示。
+- 一单多标签时同一行并列展示，不互相覆盖。
+
+### 3. 超时说明优先展示 `reason`
+
+卡片说明文案建议优先级：
+
+```ts
+reason || title || lastAction || remark || note
+```
+
+`HOTEL_REPLY_TIMEOUT` 的 `reason` 会包含第几晚、酒店名和超时说明，优先展示可帮助房务判断要跟进哪家酒店。
+
+## 验收标准
+
+| 场景 | 期望 |
+|------|------|
+| `HL20260703140009570` 出现在待处理页 | 卡片显示 `酒店超时未回复 · 2` 标签 |
+| 同一单同时有 `PENDING_ARRANGE` | 同行展示 `刚抢单待配房` 标签 |
+| 选择“酒店超时未回复”筛选 | 请求使用 `todoType=HOTEL_REPLY_TIMEOUT`，列表仍能返回该单 |
+| 后端 `todoTypes` 有多个类型 | 前端多标签并列展示，不被订单状态“配房中”覆盖 |
+
+## 排查约定
+
+以后类似“页面没显示待办标签/状态，但怀疑后端任务异常”的问题，先复现后端接口：
+
+1. 调 `GET /v3/admin/order/todos` 看 `list/todoTypes/stats`。
+2. 如果接口已返回对应标签或统计，直接按前端数据源/字段渲染问题处理。
+3. 只有接口未返回或数据条件不成立时，再继续排查后端定时任务、派生逻辑或数据状态。
+
+## 影响范围
+
+| 页面/能力 | 说明 |
+|-----------|------|
+| `/housekeeper/todos` | 房务管家待处理列表 |
+| `GET /v3/admin/order/todos` | 复用现有接口，无新增字段 |
+| `todoTypes[]` | 前端需消费的待办原因标签数组 |