# 房务工作台首页接活的「房务待办 + 即将入住」（替换 v2 死源，前端对接）

> 模块：工作台首页 / 仪表盘（角色=房务管理员 ROOM_MANAGER，管理后台）
> 类型：出参新增字段 + 字段结构变更（PR #4620 已合 dev-v3 + 测试服实测）
> 关联工单：#4618
> 日期：2026-06-29

## 背景

房务反馈「工作台首页要显示房务的待办，且数据都要活的」。

排查发现：房务工作台首页 `GET /admin/profile/dashboard`（角色=房务管理员）的「待安排住宿 / 即将入住」原读 **order-v2 旧看板死源**（查 v2 `order_todo`/`order_main`，二期房务数据不在那），所以 `pendingArrangeRoom` 恒 0、`upcomingTrips` 恒空，也没有房务待办。本次切到**活的 order-v3 房务域**数据。

## 接口（不变）

`GET /admin/profile/dashboard`（房务管理员登录态自动走房务分支，无新增端点、无需改网关）。

## 出参变更（房务管理员分支）

```jsonc
{
  "totalHotels": 39,            // 不变（酒店总数，resource 活数据）
  "totalRoomTypes": 36,         // 不变（房型总数）

  "pendingArrangeRoom": 11,     // 【修正·变活】待安排住宿数。原恒 0，现 = 我的「刚抢单待配房」数（活）

  "todoSummary": {              // 【新增·对接】房务待办分类统计（scope=我的，活）
    "total": 11,                //   待办聚合订单总数（OPEN）
    "SWAP_HOTEL": 0,            //   换酒店
    "REFUND": 0,                //   退订
    "INVENTORY_CHECK_OVERDUE": 0,//  核房超期
    "RETURN_TO_HK": 0,         //   退回房务
    "REQUIREMENT_ADJUSTED": 0, //   需求变更重配
    "HOTEL_REPLY_TIMEOUT": 2,  //   酒店超时未回复
    "PENDING_ARRANGE": 11,     //   刚抢单待配房（派生项）
    "UNREAD_CHAT": 0           //   定制师消息未读（派生项）
  },

  "upcomingTrips": [            // 【结构变更·对接】即将入住，原恒空 List<Map>，现为活的对象列表
    {
      "orderId": "2071435652078993409",   // 雪花，String
      "orderNo": "HL20260629112839481",
      "guestName": "E2E客户21",            // 主联系人
      "personsDesc": "2大1小",             // 人数描述（全 0 为 null）
      "departDate": "2026-07-02",          // 出发日（近 7 天）
      "houseStatus": "CLAIMING",           // 房务状态码
      "houseStatusLabel": "配房中"          // 房务状态中文（必中文，前端直接展示）
    }
    // ...
  ]
}
```

口径（已与产品确认）：
- `todoSummary` / `pendingArrangeRoom` 按 **scope=我的**（owner=我 + 未归属广播），与房务待办列表「我的」Tab 一致。
- `upcomingTrips` = 我（claimer=我）负责、**出发日在近 7 天**的订单，按出发日升序，最多 10 条。
- `todoSummary` 的 8 个分类键与**房务待办列表 stats 共用同一套大写常量**（`SWAP_HOTEL`/`PENDING_ARRANGE`/...），前端可复用同一套类型标签渲染。

## 前端对接（圈中区域）

1. **房务待办**：在工作台首页圈中区域（顶部统计区）渲染 `todoSummary`——可用 `total` 作总待办徽章，或按 8 个分类计数铺卡片/红点（点进可跳房务待办列表对应 Tab）。
2. **待安排住宿**卡：`pendingArrangeRoom` 现为活数据（= `todoSummary.PENDING_ARRANGE`），直接用即可。
3. **即将入住订单**卡：`upcomingTrips` 现为活的对象列表，字段见上；原来若按 Map 的旧键取值需改为按新字段名取（`orderNo`/`guestName`/`personsDesc`/`departDate`/`houseStatusLabel`）。

软依赖：order-v3 临时不可达时整块降级为 0/空，不阻断首页其它面板（酒店统计照常）。

## 测试服实测（SSH 内网网关 8080）

- `pendingArrangeRoom`：0 → **11**（活的待配房）。
- `todoSummary`：新增，`{total:11, PENDING_ARRANGE:11, HOTEL_REPLY_TIMEOUT:2, 其余 0}`，与 `GET /v3/admin/order/todos?scope=mine` 地面真相一致。
- `upcomingTrips`：空 → **7 条**真实订单（出发日 2026-07-02~07-06，houseStatusLabel=「配房中」，人数/客人正确）。
- `totalHotels/totalRoomTypes`：39/36 不变。