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

> 模块：管理后台 · 房控台 · 工作台首页 `/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` |
