4.1 KiB
4.1 KiB
房务工作台首页接活的「房务待办 + 即将入住」（替换 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（房务管理员登录态自动走房务分支，无新增端点、无需改网关）。
出参变更（房务管理员分支）
{
"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/...），前端可复用同一套类型标签渲染。
前端对接（圈中区域）
- 房务待办：在工作台首页圈中区域（顶部统计区）渲染
todoSummary——可用total作总待办徽章，或按 8 个分类计数铺卡片/红点（点进可跳房务待办列表对应 Tab）。 - 待安排住宿卡：
pendingArrangeRoom现为活数据（=todoSummary.PENDING_ARRANGE），直接用即可。 - 即将入住订单卡：
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 不变。