docs(v2): 房务前端对接4问答复(转单字段+productType计数+待确认异常空态+我的接单补金额 PR#4123)

changelogs-v2/2026-06/20_房务前端对接问题答复4项-转单字段+productType计数+待确认异常空态+我的接单补金额-管理后台.md

@@ -0,0 +1,127 @@
+# 【答复·管理后台】房务前端对接 4 个问题逐项答复（转单字段 / productType 计数 / 待确认·异常空态 / 我的接单补金额）
+
+> 类型：接口契约确认 + 1 处字段补充（PR #4123）
+> 端：管理后台（hl-ui）
+> 服务：hl-order-service-v3
+> 日期：2026-06-20
+> 关联：前端对接反馈（口头），无工单（前端反馈走 changelog）
+
+---
+
+## ⚠️ 关键说明
+
+前端对接房务时反馈 4 个问题，逐项核查代码 + 测试服 DB 地面真相后答复如下。**结论：1 个真问题已修（item 4 我的接单卡片补金额，PR #4123），另 3 个是契约确认 / 设计取舍 / 空态，均无需前端改动方向，照下方说明对接即可。**
+
+| # | 前端反馈 | 核查结论 | 处置 |
+|---|---------|---------|------|
+| 1 | 转单 body 字段名两份契约都没列 | `{toUserId, reason}` 前端猜的**完全正确**，另有可选 `skipUpperLimit` | 契约已确认，无需改 |
+| 2 | productType 筛选时「N 单待抢」徽标计数虚高 | 设计取舍（productType 跨服务字段不能下推 SQL）：徽标 total = **池总数**，productType 是当页视图过滤 | 徽标语义说明，无需改 |
+| 3 | 我的接单「待确认/异常」两 tab stats 恒 0 | **不是「都映射 PROCESSING」**——映射 100% 正确、状态流转已接通；恒 0 是**当前测试库这两态 0 行**（空态） | 不要隐藏 tab，渲染空态即可 |
+| 4 | 列表卡片未渲染金额 | 抢单池卡片本就有 `totalAmount`；**我的接单卡片原缺**，已补齐对齐 | **PR #4123 已修** |
+
+---
+
+## 1. 转单接口字段名（item 1）—— 契约确认，前端猜对了
+
+**端点**：`POST /v3/admin/order/hotel-requirements/{requirementId}/transfer`
+**请求体 VO**：`HouseTransferReqVO`
+
+| JSON Key | 类型 | 必填 | 说明 |
+|----------|------|------|------|
+| `toUserId` | Long（字符串传） | ✅ 必填 | 接收人房务 ID（= `admin_user.admin_id`） |
+| `reason` | String | ✅ 必填 | 转单/指派原因（普通房务 ≥1 字，超管 ≥10 字；长度 1~200） |
+| `skipUpperLimit` | Boolean | 否（默认 false） | 跳过 30 单上限（**仅超管有效**，普通房务传 true 也忽略） |
+
+> 前端猜的 `{toUserId, reason}` **一字不差正确**，补一个可选 `skipUpperLimit` 即可。`toUserId` 是接收房务的 `admin_id`（即「我的接单」「抢单池」卡片里 `consultantId` 同源的 admin 主键体系）。
+
+**示例**
+
+```bash
+curl -X POST "https://api.test.1814.love:9443/v3/admin/order/hotel-requirements/70123/transfer" \
+  -H "Authorization: Bearer <token>" -H "Content-Type: application/json" \
+  -d '{"toUserId": 1003, "reason": "我今天临时请假，转给小图接手"}'
+```
+
+失败（如接收人不存在 / 超 30 单上限）走业务错误码 toast，不崩页面。上线转单前可在 Knife4j 自测一次确认。
+
+---
+
+## 2. productType 筛选时「N 单待抢」徽标计数（item 2）—— 设计取舍，徽标 = 池总数
+
+**现象属实**：抢单池列表按 productType 筛选时，返回的 `total` 是池总数（不随 productType 收窄），故 `total >> 当前 list 长度`。
+
+**根因（非 bug，是架构约束）**：
+- `productType` 是 **product 域字段**，`order_main` 表里没有这列，需跨服务 Feign（`ProductFeignClient`）按 productId 现查补上。
+- 抢单池为小数据集（5~8 人小团队的待抢需求，单页装得下），故设计为：SQL 出准 total + list → 当页 Feign enrich 补 productType → **当页内存按 productType 精筛**。
+- 受 CODE_RULES §9「事务内禁同步 Feign」约束，productType 无法下推到 Mapper 的 SQL WHERE，total 只能是 DB 端未含 productType 的池总数。
+
+**前端对接建议**：
+- 「N 单待抢」徽标语义 = **抢单池待抢总数**（productType 是当页视图过滤，不改变池里有多少单待抢）。
+- 按前端自己的建议，**筛选 productType 时弱化/隐藏该徽标**，或标注为「池内共 N 单」，避免与筛选后列表长度产生「数字对不上」的观感即可。
+- 当前测试库抢单池为 0 行（24 条需求全部已确认），该现象暂不会触发。
+
+> 备注：若后续产品要求 productType 筛选下徽标精确计数，需做「拉全池 enrich 后过滤再分页」的小改（小数据集可行），届时另立。当前不改。
+
+---
+
+## 3. 我的接单「待确认 / 异常」两 tab stats 恒 0（item 3）—— 空态，不是 bug，请勿隐藏 tab
+
+**前端假设「这俩 tab 都映射到 PROCESSING」—— 经核查不成立。** 映射完全正确、各自独立：
+
+| 前端 tab | 后端 status key | 房务 6 态（house_status） |
+|---------|----------------|------------------------|
+| 进行中 | `inProgress` | CLAIMING / IN_INQUIRY |
+| **待确认** | `pendingConfirm` | **PENDING_FINALIZE** |
+| 已确认 | `confirmed` | CONFIRMED |
+| **异常** | `exception` | **EXCEPTION** |
+
+- stats 按**细分** house_status 分别统计（非按粗状态归并），代码逻辑正确。
+- 状态机流转**已接通**：`CLAIMING → PENDING_FINALIZE`（配房全部确认 ASSIGNMENT_CONFIRM_FULL）、`PENDING_FINALIZE → CONFIRMED`、`IN_INQUIRY → EXCEPTION`（拒单/超时无回复）。
+
+**恒 0 的真因 = 测试库当前这两态 0 行**（地面真相）：
+
+```
+house_status 全量分布（order_hotel_requirement）：CONFIRMED = 24（仅此一态）
+PENDING_FINALIZE / EXCEPTION：全表 0 行
+```
+
+当前测试数据里 24 条需求全部停在 CONFIRMED，没有任何单子走到「待最终确认」或「异常」，所以这两个 tab 计数为 0 是**如实反映数据的空态**，不是计数错误。
+
+**前端对接建议**：**不要禁用/隐藏这两个 tab**——它们是真实状态，等订单走到配房全确认（→待确认）/ 拒单超时（→异常）时会自动出数。前端把 0 渲染成空态/灰显即可。要现场验证，可造一条单子走完配房确认流程看「待确认」出数。
+
+---
+
+## 4. 列表卡片金额渲染（item 4）—— 我的接单卡片已补 `totalAmount`（PR #4123）
+
+**核查发现两张卡片不对称**：
+- **抢单池**列表项 `HouseGrabPageItemRespVO` —— **本就有** `totalAmount`（String「6840.00」，对应 mock 的 ¥6,840），前端直接渲染即可，后端无需改。
+- **我的接单**列表项 `HouseMyOrderItemRespVO` —— **原缺任何金额字段**，已补齐（镜像抢单池同口径，JOIN `order_main.order_amount`）。
+
+**变更（PR #4123，已合并部署测试服）**：我的接单列表项新增字段
+
+| 字段 | 类型 | 序列化 | 说明 |
+|------|------|--------|------|
+| `totalAmount` | BigDecimal | **String（防精度）** | 订单总额（元），取 `order_main.order_amount`，与抢单池卡片同口径 |
+
+```jsonc
+// GET /v3/admin/order/grab-pool/my-claims/hotel  → data.list[]
+{
+  "id": "70123",
+  "orderNo": "26-0501",
+  "guestName": "张先生一家",
+  "totalAmount": "6840.00",   // ★ 新增，String
+  "houseStatus": "已确认",
+  "consultantId": "1002"
+  // ...其余字段不变
+}
+```
+
+> 非破坏性加字段，前端按需渲染（是否在卡片展示金额按原型定；后端两张卡片现已都提供）。金额统一 String 传输防精度，前端展示加 ¥ 前缀即可。
+
+---
+
+## 验证
+
+- `HouseGrabServiceImplTest` 40 + `*ArchTest`（MapperBoundary 22 + RedLine 9 + LocalCacheVetting 1 = 32）全绿。
+- 部署测试服 order-v3 双实例（8086/8186）成功；带新 JOIN 列的 my-claims 查询在生产库实跑返 200。
+- item 4 字段来源核对：我的接单关联 24 单 `order_amount` 全非空（3105.00 ~ 22000.00）。