hl-api-changelog/changelogs-v2/2026-07/08_4710_房务首页待办卡片化-即将入住过滤-修改接口-管理后台.md

房务工作台首页增强——待办卡片化 + 即将入住只显已配房完成

模块：管理后台 · 房控台 · 工作台首页 /dashboard（ROOM_MANAGER 角色） 类型：后端修改（已合并 dev-v3 + 部署测试服 + API 实测） + 前端接入 日期：2026-07-01 · 关联 PR #4710 / 工单 #4677 背景：「房务待办」区只显示计数徽章看不到订单、「即将入住」把配房中的单也列进去语义不对——两处体验问题一次修。

【前端 · 房控台】需改动

1. 首页新增 todoCards（替换计数徽章）

GET /admin/profile/dashboard?period=today（ROOM_MANAGER）→ data.todoCards 新增字段：

"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