From 80088ae7d11b1a6f1ef4dc6660096d58e5e0ab80 Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Sat, 20 Jun 2026 15:05:48 +0800 Subject: [PATCH] =?UTF-8?q?docs(v2):=20=E6=88=BF=E5=8A=A1=E5=89=8D?= =?UTF-8?q?=E7=AB=AF=E5=AF=B9=E6=8E=A54=E9=97=AE=E7=AD=94=E5=A4=8D(?= =?UTF-8?q?=E8=BD=AC=E5=8D=95=E5=AD=97=E6=AE=B5+productType=E8=AE=A1?= =?UTF-8?q?=E6=95=B0+=E5=BE=85=E7=A1=AE=E8=AE=A4=E5=BC=82=E5=B8=B8?= =?UTF-8?q?=E7=A9=BA=E6=80=81+=E6=88=91=E7=9A=84=E6=8E=A5=E5=8D=95?= =?UTF-8?q?=E8=A1=A5=E9=87=91=E9=A2=9D=20PR#4123)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...productType计数+待确认异常空态+我的接单补金额-管理后台.md | 127 ++++++++++++++++++ 1 file changed, 127 insertions(+) create mode 100644 changelogs-v2/2026-06/20_房务前端对接问题答复4项-转单字段+productType计数+待确认异常空态+我的接单补金额-管理后台.md diff --git a/changelogs-v2/2026-06/20_房务前端对接问题答复4项-转单字段+productType计数+待确认异常空态+我的接单补金额-管理后台.md b/changelogs-v2/2026-06/20_房务前端对接问题答复4项-转单字段+productType计数+待确认异常空态+我的接单补金额-管理后台.md new file mode 100644 index 0000000..0f4e234 --- /dev/null +++ b/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 " -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）。