4.8 KiB
4.8 KiB
房务配房并发/事务加固——新增 3 个拒绝码（808119 取消/异常态、808113 需求作废态、808123 候选已更新）
变更类型：🔒 并发/事务加固（房务管家·配房写口）+ 新增错误码 端类型：管理后台（房务管家） 日期：2026-06-27 ｜ 工单：#4506 ｜ PR：#4507(批1) + #4514(批2) + #4523(韧性审计补) ｜ 服务：hl-order-service-v3（双实例已部署测试服 + happy path 回归 + 新码端到端实测通过）
背景
外部审计核实出房务配房链路一批并发/事务一致性真问题（库存泄漏、状态陈旧覆盖、回池困死、孤儿配房行等），已分两批修复并部署验证。绝大多数是后端内部硬化（库存扣减补偿、house_status CAS、统一写锁、事务内重检），前端无契约变更；仅以下两点前端需知悉。
一、新增 3 个拒绝错误码（前端按已有错误码机制展示 msg 即可）
808119 ASSIGNMENT_NOT_WRITABLE_IN_EXCEPTION——订单取消/异常处置态不可配房
- 触发：对一个 house_status=EXCEPTION（订单已取消、或在“异常”桶处置中）的需求调用「提交配房」
POST .../assignments或「单日确认」POST .../assignments/days/{day}/confirm。 - 返回：
code 808119，msg「订单已取消或异常处置中, 该需求不可新增或确认配房, 请在异常桶处理」。 - 前端：异常桶里的需求，应隐藏/禁用「提交配房」「单日确认」入口，仅保留删配房（释放）、释放回池、转单、标记完成等异常处置操作；若误触发，按 msg 提示。
808113 REQUIREMENT_INACTIVE_FOR_ASSIGN——需求已作废（定制师重调过）不可配房
- 触发：定制师改期/改行程天数会生成新版本需求并把旧版本需求作废（is_active=0）。若前端仍持旧需求 id 调用「提交配房」
POST .../assignments，后端在落库前重检发现已作废 → 拒绝。 - 返回：
code 808113，msg「需求已作废, 不可提交配房, 请由定制师重新调整需求」。 - 前端：收到 808113 说明手里的需求 id 已过期，应刷新订单/房务详情拿最新版本需求再操作（不要在旧需求上重试）。
808123 KEEP_NOT_IN_DAY_CANDIDATE——单日确认保留的配房行不属于该天候选（配房已更新）
- 触发：「单日确认」
POST .../assignments/days/{day}/confirm传的keepAssignmentIds中有 id 不属于该天「询房中」候选集。最常见原因：配房被重新提交后该天候选行的assignmentId已轮换，前端仍用了缓存的旧 id；或误传了别天的 id。 - 返回：
code 808123，msg「保留的配房行不属于该天询房中候选(可能配房已更新), 请刷新后重试」。 - 前端：收到 808123 应刷新订单/房务详情拿该天最新的
inquiringAssignments[].assignmentId再确认，不要用缓存的旧 id。keepAssignmentIds应始终取自当前详情返回的候选 id；省略/空表示「保留该天全部候选」（行为不变）。 - 重要：此前后端对全不命中的 keepAssignmentIds 会「静默把该天全部候选软删且零确认」（业务中断）；现改为 fail-fast 拒绝、不删任何候选，前端刷新重试即可恢复。
另：转单后用过期持有人身份写配房会返既有
808110（非本人抢单），语义不变。
二、行为提示：confirmDay 锁粒度收紧（一般无感）
「单日确认」POST .../assignments/days/{day}/confirm 的并发锁由 per-（需求,天） 收紧为 per-需求：同一需求的多天确认操作改为串行排队（此前可并行）。
- 房务对一个订单本就逐天顺序操作，正常无感。
- 仅当前端对同一需求的多个天几乎同时并发触发确认时，会短暂排队（30s 锁超时内依次完成），不会失败。
- 提交配房/释放/转单/单日确认现统一互斥（同一需求同一时刻只允许一个写操作），杜绝了并发写导致的状态错乱。
三、纯后端内部硬化（前端无需改动，仅列出供知悉）
- 配房单日确认扣减：候选行扣减即绑定审计 log（消除并发删除时库存不释放的泄漏窗口）；多候选部分扣减失败时自动反向释放已扣；resource 记账失败自动补偿避免库存白扣 + 幂等键可重试。
- house_status 写改 CAS（防订单取消等并发把已迁移态硬覆盖回正常态，避免已取消需求在房务视图“复活”）。
后端已完成并测试服实测通过（部署 + 双实例 health + 配房主线/释放回池 happy path 回归 + 808119/808113 端到端实测 + DB 核对）。前端仅需对 808119/808113 两个新拒绝码做对应提示与刷新。