changelog: #4677 房务首页待办卡片化+即将入住过滤 (PR #4710)

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` |