diff --git a/changelogs-v2/2026-07/08_4710_房务首页待办卡片化-即将入住过滤-修改接口-管理后台.md b/changelogs-v2/2026-07/08_4710_房务首页待办卡片化-即将入住过滤-修改接口-管理后台.md new file mode 100644 index 0000000..f17b83c --- /dev/null +++ b/changelogs-v2/2026-07/08_4710_房务首页待办卡片化-即将入住过滤-修改接口-管理后台.md @@ -0,0 +1,66 @@ +# 房务工作台首页增强——待办卡片化 + 即将入住只显已配房完成 + +> 模块:管理后台 · 房控台 · 工作台首页 `/dashboard`(ROOM_MANAGER 角色) +> 类型:**后端修改(已合并 dev-v3 + 部署测试服 + API 实测)** + 前端接入 +> 日期:2026-07-01 · 关联 PR #4710 / 工单 #4677 +> 背景:「房务待办」区只显示计数徽章看不到订单、「即将入住」把配房中的单也列进去语义不对——两处体验问题一次修。 + +## 【前端 · 房控台】需改动 + +### 1. 首页新增 `todoCards`(替换计数徽章) + +`GET /admin/profile/dashboard?period=today`(ROOM_MANAGER)→ `data.todoCards` 新增字段: + +```json +"todoCards": [ + { + "orderId": "2071526390884171777", + "orderNo": "HL20260629172912905", + "guestName": "张伟", + "personsDesc": "2大", + "departDate": "2026-07-06", + "todoType": "HOTEL_REPLY_TIMEOUT", + "todoTypeLabel": "酒店超时未回复", + "description": "第1晚 海拉尔嘉世豪酒店 已发询房超过 12 小时仍未确认, 请跟进酒店或换酒店", + "urgency": "danger" + } +] +``` + +- **来源**:与待办列表「我的」Tab 同口径同排序,取前 5 条订单聚合行精简投影。 +- **字段说明**: + - `orderId`/`orderNo`/`guestName`/`personsDesc`/`departDate`:订单展示字段(与即将入住单项同套字段)。 + - `todoType`/`todoTypeLabel`:该订单**主标签**(紧急度最高那条)的类型码和中文标签(与待办列表同套字典)。 + - `description`:待办说明文字(优先取 reason,缺失回退 title)。首发版每个 `orderId` 只有一行(一卡)。 + - `urgency`:紧急度(danger/warn/normal)。 +- **前端改法**:首页「房务待办」区按 `todoCards` 渲染订单卡片列表(替换当前只展示 `todoSummary` 中各分类计数的徽章)。卡片点击可跳该订单详情/待办列表。**`todoSummary` 计数字段名/结构不变**,如需徽章仍可用。 +- **⚠️ 空列表**:如果当前登录房务没有待办单(该房务无归属订单),`todoCards` 返 `[]`,前端应隐藏卡片区或显示「暂无待办订单」空态。 + +### 2. 「即将入住」列表行为变化(后端过滤,前端无需改) + +`data.upcomingTrips` 字段名/结构**完全不变**,但后端现在**只返回已配房完成**的订单进入即将入住: +- **放行**:`houseStatus = CONFIRMED`(已完成)或 `PENDING_FINALIZE`(待最终确认,房已配定只差回传)。 +- **排除**:`CLAIMING`(配房中)/ `PENDING_CLAIM`(待配房)/ `EXCEPTION`(异常)不再出现。 + +> 前端渲染逻辑无需改——即将入住列表原来就逐条取 `upcomingTrips[i].houseStatusLabel` 显示状态,「配房中」的卡本来就不适合放在「即将入住」——这些单现在归待办卡片区。 + +### 3. 小结 + +| 改动 | 前端动作 | +|------|---------| +| `todoCards` 新增字段 | **需接入**:首页待办区改读 `todoCards` 渲染卡片列表 | +| `upcomingTrips` 过滤收窄 | **无需改**:后端已过滤,前端列表行为自动对齐 | +| `todoSummary`/`upcomingTrips` 结构 | **无变化**:字段名/类型/嵌套全不变 | + +## 已验证(测试服 API 实测) + +- `GET /admin/profile/dashboard`(ROOM_MANAGER,admin token)→ `data.todoCards` 存在且含正确字段(1 张 PENDING_ARRANGE 卡片,orderId/orderNo/guestName/personsDesc/departDate/todoType/todoTypeLabel/description/urgency 全部有效)。 +- `description` 回退逻辑:派生项 PENDING_ARRANGE 无 `reason`,正确回退到 `title`(「新抢需求待配房 · HL20260629172912905 · 出发 2026-07-06」)。 +- `upcomingTrips`:admin 只有 CLAIMING 态需求,即将入住列表为空(过滤生效)。 +- 响应结构无回归:`totalHotels`/`totalRoomTypes`/`pendingArrangeRoom`/`todoSummary` 各字段完整。 + +## 涉及接口 + +| 方法 | 路径 | 说明 | +|------|------|------| +| GET | `/admin/profile/dashboard` | 房务首页(ROOM_MANAGER)新增 `todoCards` |