# 二期 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 归属原房务）。无接口路径/字段结构变更。

如需任一接口完整响应样例或字段疑问，回我即可。
