diff --git a/changelogs-v2/2026-06/51_4618_房务工作台首页接活的房务待办与即将入住_前端对接-管理后台.md b/changelogs-v2/2026-06/51_4618_房务工作台首页接活的房务待办与即将入住_前端对接-管理后台.md new file mode 100644 index 0000000..58ac6a6 --- /dev/null +++ b/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,现为活的对象列表 + { + "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 不变。