docs(changelog-v2): 房务工作台首页接活的房务待办+即将入住(#4618 前端对接)

changelogs-v2/2026-06/51_4618_房务工作台首页接活的房务待办与即将入住_前端对接-管理后台.md

@@ -0,0 +1,72 @@
+# 房务工作台首页接活的「房务待办 + 即将入住」（替换 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 不变。