文档(order/admin): 房务6态全返回-订单详情进度条6步(#4255)+我的订单筛选6tab(#4261) 已上线可对接

changelogs-v2/2026-06/23_4255_4261_房务6态全返回-订单详情进度条6步+我的订单筛选6tab-管理后台.md

@@ -0,0 +1,67 @@
+# 房务 6 态全返回：订单详情进度条 6 步 + 我的订单筛选 6 tab（已上线测试服·可对接）
+
+> 变更类型：✅ 修改接口（响应结构，已部署测试服 + API 验证）
+> 端类型：管理后台（房务管家 `housekeeper`：订单详情 + 我的订单列表）
+> 日期：2026-06-23 ｜ 工单：#4255 / #4261 ｜ PR：#4257 / #4263 ｜ 服务：hl-order-service-v3
+> 背景：wx 要求房务侧进度/筛选**完全按房务 6 态（HouseStateEnum）后端返回**，前端只渲染、不写死。
+
+房务侧 6 态：`PENDING_CLAIM`待配房 / `CLAIMING`配房中 / `IN_INQUIRY`询房中 / `PENDING_FINALIZE`待最终确认 / `CONFIRMED`已确认 / `EXCEPTION`异常。
+
+---
+
+## 1. 订单详情进度条：4 步 → 6 步（#4255）
+
+`GET /admin/house/orders/{orderId}` 的 `data.progress.steps` **从 4 个变 6 个**（每态一个节点，按态序）：
+
+| step | label | 对应态 |
+|---|---|---|
+| 1 | 待配房 | PENDING_CLAIM |
+| 2 | 配房中 | CLAIMING |
+| 3 | **询房中** | IN_INQUIRY |
+| 4 | 待最终确认 | PENDING_FINALIZE |
+| 5 | 已确认 | CONFIRMED |
+| 6 | **异常** | EXCEPTION |
+
+- `progress.currentStep`：当前态对应的 step（**1-6**）。
+- 每个 step：`{step, label, desc, completed, completedAt}`。`completed`：前 4 节点=已越过该步；已确认=`state==CONFIRMED` 才完成；异常=`state==EXCEPTION`。
+- `progress.houseStatus` + `houseStatusLabel`（6 态枚举名 + 中文）仍透传，前端可据 `houseStatus==EXCEPTION` 对异常节点做特殊视觉（红/告警）。
+- 前端：进度条**遍历 steps 渲染 6 个节点**（别写死 4 个）。
+- 实测：`progress.steps` 返 6 个（待配房…异常）✓。
+
+## 2. 我的订单筛选 tab：5 → 6（#4261）
+
+`GET /v3/admin/order/grab-pool/my-claims/hotel` 的 `data.stats` **拆出「询房中」**。原 `inProgress` 把 配房中+询房中 合并，现新增独立计数：
+
+| stats 字段 | tab | 对应态 |
+|---|---|---|
+| (total) | 全部 | — |
+| **`claiming`** | 配房中 | CLAIMING |
+| **`inInquiry`** | 询房中 | IN_INQUIRY |
+| `pendingConfirm` | 待确认 | PENDING_FINALIZE |
+| `confirmed` | 已确认 | CONFIRMED |
+| `exception` | 异常 | EXCEPTION |
+
+- `inProgress`（=claiming+inInquiry）**保留**做向后兼容；**新前端用 `claiming` / `inInquiry` 分别显示「配房中」「询房中」两个 tab 的数字徽章**。
+- 列表筛选 `status` 参新增取值：`claiming`（只看配房中）/ `inInquiry`（只看询房中）；原 `inProgress/pendingConfirm/confirmed/exception` 不变。
+- 实测：stats 返 `{inProgress, claiming, inInquiry, pendingConfirm, confirmed, exception}` 六字段 ✓。
+
+## 3. curl 实测（2026-06-23 测试服，过网关 9443）
+```bash
+# 进度条 6 步
+curl '.../admin/house/orders/2068234602970828802' -H 'Authorization: Bearer <token>'
+#   → data.progress.steps 6 个(待配房/配房中/询房中/待最终确认/已确认/异常), currentStep 1-6
+
+# 我的订单 stats 6 字段
+curl '.../v3/admin/order/grab-pool/my-claims/hotel?page=1&pageSize=20' -H 'Authorization: Bearer <token>'
+#   → data.stats = {inProgress, claiming, inInquiry, pendingConfirm, confirmed, exception}
+```
+
+## 4. 前端处理建议
+- **进度条**：遍历 `progress.steps` 渲染 6 节点；当前态高亮 `currentStep`；异常态据 `houseStatus==EXCEPTION` 特殊样式。
+- **我的订单 tab**：渲染 6 个（全部 + 配房中`claiming` + 询房中`inInquiry` + 待确认`pendingConfirm` + 已确认`confirmed` + 异常`exception`）；点 tab 时列表带 `status=claiming/inInquiry/...` 筛选。
+- 不要写死 4 步 / 5 tab。
+
+## 5. 兼容 / 回滚
+- 进度条：steps 加 2 项 + currentStep 上限到 6（旧前端若按数组渲染自动变 6；按固定 4 渲染需改）。
+- tab：stats 加 claiming/inInquiry，inProgress 保留兼容。
+- 无 DB 迁移。回滚 = revert PR #4257 / #4263 重新部署 hl-order-service-v3。