docs(changelog-v2): 房务管家完备性 — 日历4状态+抢单productType+待办生产者全齐(含取消→退订) (#3179/#3188 PR3180/3200/3202)

changelogs-v2/2026-05/28_HOUSE完备性_日历4状态+抢单productType+待办生产者全齐_PR3180-3200-3202.md

@@ -0,0 +1,64 @@
+# 二期 v3 房务管家：日历 4 状态点 + 抢单池 productType + 待办生产者全齐（含取消→退订）
+
+> **服务**: hl-order-service-v3
+> **PR**: #3180、#3200、#3202(hotfix)
+> **Issue**: #3179、#3188
+> **日期**: 2026-05-28
+> **影响**: 🟡 房务管家「日历视图 / 抢单池 / 待办 Tab」数据更完整；接口路径与字段结构**不变**，仅字段从恒空/恒 0 变为真实值、待办 Tab 新增几类会真正产生的待办
+
+---
+
+## 总览（前端 mmg 必读）
+
+继上一批房务接口真实化后，本批补齐房务管家剩余的完备性缺口。**接口路径、字段结构均不变**，前端可据此把对应 UI 由"空态/恒 0"切到真实渲染。
+
+---
+
+## 1. 日历视图 4 状态点真实化（§2.6）— PR #3180
+
+`GET /admin/house/calendar?month=YYYY-MM&scope=mine|all`
+
+此前每天 / 汇总只有"进行中(inProgress)"有真实计数，"待配房(pending) / 询房中(inquiry) / 异常(exception)"恒为 0。现已全部按真实状态聚合：
+
+- **待配房 pending**：未被房务抢单的需求（按订单出发日落格）
+- **询房中 inquiry**：有 PENDING 询房的订单
+- **异常 exception**：有 OPEN 异常类待办（换酒店 / 退订 / 询房超时等）的订单
+- **进行中 inProgress**：已配房且不在以上桶
+
+`summary.{inProgress,pending,inquiry,exception}` 与每天 `statusDots[]`（含 label/count/color）均返真实值。优先级：异常 > 询房中 > 待配房 > 进行中。
+
+## 2. 抢单池 productType 接通（§1.1）— PR #3180
+
+`GET /v3/admin/order/grab-pool/hotel-requirements`
+
+- 列表项 `productType`（CORE/GROUP/CUSTOM）、`productNo` 此前恒 null，现经产品服务真实返回（如 `productType=CORE`、`productNo=C260520001`）。
+- `productType` 作为**查询筛选项现已生效**（按产品类型过滤抢单池）。
+- 上游产品服务查不到 / 降级时该字段如实 null，不报错。
+
+## 3. 待办 Tab 生产者全齐（§4.1 / §3.4）— PR #3180 + #3200
+
+`GET /v3/admin/order/todos` —— 此前部分待办类型只有"消费/RESOLVE"没有"生产者"，对应 Tab 永远空。现补齐，7 类待办均会真正产生：
+
+| 待办类型 | 何时产生（新增/原有） |
+|---|---|
+| `SWAP_HOTEL` 换酒店 | **新增**：酒店回填**拒单**时自动产（#3180）；换酒店完成后自动 RESOLVE |
+| `INVENTORY_CHECK_OVERDUE` 核房超期 | **新增**：每日巡检 Job 扫到酒店快照过期自动产（#3180）；核房后自动 RESOLVE |
+| `REFUND` 退订 | **新增**：订单**确认后取消**（房务已配房锁酒店）时自动产，归属原接单房务（#3200）；详见下 |
+| `INQUIRY_TIMEOUT` 询房超时 / `INQUIRY_ESCALATED` 询房加急 / `RETURN_TO_HK` 退回房务 | 原有，不变 |
+
+> 注：`UNDELIVERED` 为历史遗留类型（其"询房 4h 无回复"语义已由 `INQUIRY_TIMEOUT` 承接），不再单独产生。
+
+## 4. 订单取消 → 退订待办 + 待办清理（§1.3 / §4）— PR #3200（hotfix #3202）
+
+订单取消后房务侧的联动此前未生效（监听链路缺陷），现已接通：
+
+- 订单取消时，该订单房务侧"配房前置工作"类 OPEN 待办（换酒店/询房超时/核房超期等）**自动 RESOLVE**（取消后这些已无意义）。
+- 若取消时**房务已配房锁酒店**，自动产一条 `REFUND` 待办，归属原接单房务（无归属则广播），提示其处理酒店退订/释放。`reason` 取订单取消原因。
+- 业务规则确认：小蒙马(GROUP)库存在**下单时**扣减、其他产品无库存 —— 配房环节不涉及库存扣减/恢复。
+
+---
+
+## 验证
+以上全部已合并 dev-v3 + 测试服双实例部署，并经真机验证：日历 4 状态点真实计数、抢单池 productType 真实返回、酒店拒单产换酒店待办、订单取消产退订待办（取消订单 → SWAP_HOTEL 待办 RESOLVED + REFUND 待办 OPEN 归属原房务）。无接口路径/字段结构变更。
+
+如需任一接口完整响应样例或字段疑问，回我即可。