diff --git a/changelogs-v2/2026-07/19_房务待处理询房超时标签未渲染-前端待处理-管理后台.md b/changelogs-v2/2026-07/19_房务待处理询房超时标签未渲染-前端待处理-管理后台.md new file mode 100644 index 0000000..2357fed --- /dev/null +++ b/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[]` | 前端需消费的待办原因标签数组 |