From 6ce29f18727e1130c5e91d0d6b3bb9e4fb29f4a2 Mon Sep 17 00:00:00 2001 From: API Changelog Bot Date: Sun, 20 Sep 2026 23:26:24 +0800 Subject: [PATCH] =?UTF-8?q?docs(changelog):=20#7980=20=E8=A1=A5=E4=B8=89?= =?UTF-8?q?=E4=BB=BD=20@Lock4j=20=E5=90=8C=E5=90=8D=E9=94=81=20changelog?= =?UTF-8?q?=EF=BC=88=E6=88=BF=E5=8A=A17=E5=8F=A3/=E5=87=BA=E8=A1=8C?= =?UTF-8?q?=E4=BA=BA+=E5=8F=91=E7=A5=A88=E5=8F=A3/=E4=BA=A7=E5=93=81?= =?UTF-8?q?=E5=BA=93=E5=AD=982=E5=8F=A3=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 三份同属一个机制：@Lock4j 未写 name 时 lock4j 把方法名拼进锁键，keys 逐字相同的 多个方法各持一把锁、互不阻塞。本批给各组补同一个显式 name，互斥才真正生效。 对前端唯一可见的变化是这些端点新增一个可能返回的 100503（HTTP 200 + body code）。 路径、方法、请求/响应字段全部零变化。 - 配房工作台 7 个写口（PR #8069）：全 admin，无 mp/C 端。 - 出行人删改 + 发票申请 8 个写口（PR #8049）：三组全部触达小程序 C 端， 逐端点沿 hl-mp-service 的 Feign 与公网 Controller 查证了调用链。 - 产品库存扣减/恢复 2 个 internal 口（PR #8047）：当前零调用方，修复是预防性的。 三份 backend_status 均为 deployed 且附真实部署读数：product-v2 滚到 ba8aab3ab （部署前 4cbccc26b，落后 93 个提交）、order-v3 滚到 ba8aab3ab（部署前 c35251b07）， merge-base --is-ancestor 逐个验过。其中 AC-5 的 b9738a20f 在部署前确实不在运行版本内， 是真正的「从不生效到生效」。 🔴 三份的「八、测试环境已验证」都明写了没有做功能调用取证及其原因（写口调用会真实 改动配房行/出行人行/库存，测试服数据多会话共用且撤不回来），并写明 100503 一次都 没触发过——是「没测」不是「测过不会触发」。互斥由落库级并发 IT 与按效果枚举的契约 用例覆盖，这是 name 契约类改动的恰当取证层级。 Co-Authored-By: Claude Opus 5 (1M context) --- ...写口补同名锁新增100503冲突码-修改接口-管理后台.md | 291 ++++++ ...口补同名锁新增100503冲突码触达C端-修改接口-管理后台.md | 880 ++++++++++++++++++ ...需求级互斥新增100503可重试冲突码-修改接口-管理后台.md | 762 +++++++++++++++ 3 files changed, 1933 insertions(+) create mode 100644 changelogs-v2/2026-09/20_7980_产品库存扣减恢复两写口补同名锁新增100503冲突码-修改接口-管理后台.md create mode 100644 changelogs-v2/2026-09/20_7980_出行人删改与发票申请三组写口补同名锁新增100503冲突码触达C端-修改接口-管理后台.md create mode 100644 changelogs-v2/2026-09/20_7980_配房工作台七个写口补齐需求级互斥新增100503可重试冲突码-修改接口-管理后台.md diff --git a/changelogs-v2/2026-09/20_7980_产品库存扣减恢复两写口补同名锁新增100503冲突码-修改接口-管理后台.md b/changelogs-v2/2026-09/20_7980_产品库存扣减恢复两写口补同名锁新增100503冲突码-修改接口-管理后台.md new file mode 100644 index 00000000..b8fe992d --- /dev/null +++ b/changelogs-v2/2026-09/20_7980_产品库存扣减恢复两写口补同名锁新增100503冲突码-修改接口-管理后台.md @@ -0,0 +1,291 @@ +--- +schema: "hl-changelog/v2" +ticket: "7980" +title: "产品价格日历库存扣减/恢复两写口补同一把 @Lock4j name，新增可重试冲突码 100503，并订正 Swagger notes 里『乐观锁』的错误说法（接口路径/字段零增删）" +consumer: "internal" +author: "wx(GIT)" +change_type: "修改接口" +backend_status: "deployed" +gateway_status: "not_required" +frontend_status: "not_required" +frontend_owner: "" +frontend_ref: "" +target_release: "" +verified_at: "" +status_note: "PR #8047 已 squash 合并 dev-v3（合并提交 f72a7548c）。2026-09-20 23:20 已部署测试服 hl-product-service-v2：滚动更新两实例（8183 先起、7 秒 UP，再滚 8083、7 秒 UP），部署前 COMMIT=4cbccc26b（停在 2026-09-19，落后 93 个提交且这些提交触及本服务），部署后 COMMIT=ba8aab3ab；git merge-base --is-ancestor f72a7548c ba8aab3ab 返回 ANCESTOR_YES，确认本次改动已在运行版本内。同轮顺带把 #8011 的用例修复（4c2ec76a2）一并带上。📌 订正草稿里的一处理由错误：本仓是 monorepo、所有合并都进 dev-v3，f72a7548c 当然落在 dev-v3 祖先链内；此前用 order-v3 的部署点 5d14bc524 做 --is-ancestor 得到 NO，原因只是「那时还没滚到」，不是「属于另一条分支的独立提交」——错误理由若留着，会让人去找一条并不存在的分支线。部署前已核对 4cbccc26b..origin/dev-v3 的 hl-common 改动为纯新增（VehicleCategoryNameDTO +16 行、一个测试 +51 行），无破坏性契约变更，故单滚 product-v2 不需要连消费方一起滚。🔴 **未做任何功能调用取证，这是有意为之**：两个端点是 /internal/product/** 且当前零调用方，既不经网关、也没有任何 Feign 声明指向它们；直接打端口调用会真实扣减/恢复库存，副作用落在共享测试服上由其他会话承担，且 restore 不保证是 deduct 的精确逆操作。互斥本身由单测 ProductStockLockNameGuardTest（按效果反查两处 name 非空且相等）覆盖，这是 name 契约类改动的恰当取证层级。100503 在本服务上未做任何触发尝试，不要读成「测过不会触发」。gateway_status=not_required：两个端点路径/方法零变化，且 /internal/** 按 HL 架构约定不暴露至公网。frontend_status=not_required：全仓 grep 确认无任何 @FeignClient 声明指向 deduct-stock/restore-stock，order-v3 的 ProductFeignClient javadoc 亦明写这些接口「待后续 Issue 按需添加」，不存在任何前端或其他服务的触达路径，故本次互斥修复目前是预防性的。consumer 字段填 internal：这两个端点不属于 admin/mp 任何一端的直接接口。" +updated_at: "2026-09-20" +base: "dev-v3" +--- + +# product-v2: 产品价格日历库存扣减/恢复两写口补同一把 @Lock4j name，新增可重试冲突码 100503 + +> **存放目录**: +> - 一期(v2,无 `order-v3` 标签的工单)→ `changelogs/{YYYY-MM}/` +> - 二期(v3,`order-v3` 标签的工单)→ `changelogs-v2/{YYYY-MM}/` +> +> **服务**: hl-product-service-v2 +> **PR**: #8047 +> **Issue**: #7980（AC-8） +> **日期**: 2026-09-20 +> **影响范围**: `/internal/product/{productId}/deduct-stock`、`/internal/product/{productId}/restore-stock` 两个跨服务 internal 端点（**当前零跨服务调用方**，见业务边界） + +--- + +## ⚠️ 关键变化（非必须,本版与上版行为不同 / 纠错 / 撤销时必写） + +- `ProductPriceCalendarService.deductStock` 与 `restoreStock` 的 `@Lock4j` 的 `keys` **逐字相同**，但**两处都没写 `name`**——lock4j 缺省 `name` 时把「包名+类名+方法名」拼进 Redis 键，两处因此**各持一把锁**，可以并发互相踩踏。而 Mapper 层的实现是 `select → 改 sold → updateById` 的读改写（本身不原子），正确性完全押在这把此前不生效的锁上。 +- 本次给两处补上同一个显式 `name = "product:stock"`，互斥才真正生效。**没有新增接口、没有增删字段**，唯一契约变化是新增一个可能返回的失败码 **`100503`**，**HTTP 状态码仍是 200**。 +- 🔴 **本次同时订正了 `InternalProductController:121` Swagger notes 里的错误说法**：改前写的是「乐观锁扣减价格日历库存」，但 `product_price_calendar` 表**无 `version` 列**、`ProductPriceCalendarDO` **无 `@Version`**，「乐观锁」这个说法是假的——真实机制是本次修复的这把分布式锁。前端/调用方若据旧 notes 认为这里有乐观锁重试语义，应以本文档为准撤销该认知。 +- 🔴 **这把锁的覆盖边界（避免误读成"sold 并发已全面安全"）**：同一行 `sold` 还有第三个写口 `ProductPriceCalendarMapper#batchUpsert`（管理端批量设价，经 `ProductPricingService`/`ProductSnapshotService` 调用），同样是 select→改 sold→updateById 的读改写，且**不取本锁**，表上无 `version`/CAS，唯一键 `uk_product_date_tier` 只约束行身份不约束 `sold`。所以「管理端批量设价 ∥ 扣库存/恢复库存」的丢更新依旧存在——那是另一个问题，本次这把锁挡不住，本 PR 未处理，不在本文档改动范围内。 +- 🔴 **两个端点当前零跨服务调用方**：全仓 grep `*Feign*.java` 对 `deduct-stock`/`restore-stock` 零命中，没有任何其他微服务的 Feign 客户端声明指向这两个路径。补锁不是因为"现在正在出问题"，而是补齐一条本该存在但一直缺失的互斥闸口——回归面可实证为零（不影响任何现存调用方），闸口本身仍要补齐，不能以"零调用方"为由不修。 + +--- + +## 一、背景（选填） + +工单 #7980 AC-8 原文写的是"零调用方"，实测更准确的说法是「**零跨服务调用方**」——`InternalProductController:127/137` → `InternalProductService:590/600` → `deductStock`/`restoreStock` 这条链路在 `origin/dev-v3` 上本身是通的（Controller→Service→Mapper 三层代码完整、可编译、可被同服务内其他代码或未来的 Feign 客户端调用），只是当前没有任何其他微服务声明了指向这两个路径的 `@FeignClient` 方法。 + +--- + +## 二、变更接口清单 + +| # | 接口 | 方法 | 路径 | 变更类型 | 说明 | +|---|------|------|------|----------|------| +| 1 | 扣减库存（内部） | POST | `/internal/product/{productId}/deduct-stock` | 新增可能返回的错误码 | 抢锁超时返 100503（原接口/字段不变） | +| 2 | 恢复库存（内部） | POST | `/internal/product/{productId}/restore-stock` | 新增可能返回的错误码 | 与 §1 共用同一把 `product:stock` 锁 | + +--- + +## 三、接口详情 + +### 1. 扣减库存（内部） `POST /internal/product/{productId}/deduct-stock` + +**VO**: `无 ReqVO（Query 参数直绑，无请求体） → Void` + +#### 使用场景 + +供其他微服务（如 order 系）通过 Feign 跨服务扣减产品价格日历库存（**当前无实际调用方**，见「⚠️ 关键变化」）。底层是 `select → 改 sold → updateById` 的读改写，靠 `@Lock4j(name=product:stock)` 分布式锁串行化；本表无 `version` 列、非乐观锁（Swagger notes 已随本次改动订正）；本端点不做幂等，幂等由调用方保证。本次改动不涉及入参/出参，只新增一条「被 §2 恢复库存占用同一把锁」的失败分支。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| productId | Path | Long | ✅ | - | 产品 ID | +| date | Query | String | ✅ | yyyy-MM-dd | 日期 | +| count | Query | int | ✅ | `@Min(1)` | 扣减数量，至少为 1 | + +#### 出参 `Result` + +| 字段 | 类型 | 说明 | +|------|------|------| +| data | null | 无返回数据，成功恒为 `null` | + +#### 请求示例 + +```http +POST /internal/product/1234567890123456789/deduct-stock?date=2026-10-01&count=2 +``` + +（跨服务 Feign 调用，无请求体，参数走 Query。） + +#### 响应示例 + +```json +{ "code": 200, "message": "成功", "data": null, "success": true } +``` + +#### 空数据 / 降级响应 + +本接口无「空数据」/降级概念（成功恒返回 `data: null`；库存不足时不是"空数据"而是显式失败，见错误响应）。 + +#### 错误响应 + +```json +{ "code": 100503, "message": "资源被占用,请稍后重试", "data": null, "success": false } +``` + +| code | 触发条件 | +|------|----------| +| 400 | 参数校验失败（`count < 1`） | +| 480201 | 该日期库存不足或未开放（`sold + count` 超过 `dailyStock`，或该产品该日期无价格日历记录），请重新选择出发日期 | +| **100503（本次新增）** | 抢锁等待超过 3 秒（与 §2 恢复库存共用同一把 `product:stock` 锁），**可重试** | + +#### 业务边界 + +- 无 `@Idempotent`——本端点不做幂等，幂等由调用方（order）保证，本次改动未涉及此设计。 +- 抢锁失败（100503）时该次请求未进入方法体，零写入——`sold` 列不会被部分更新。 +- 库存判定只按 `tier_seq=1`（默认档位）查询（`selectByProductIdAndDate` 硬编码），多档位产品的其余档位库存不受本端点影响——这是既有实现的既有边界，非本次改动引入，本 PR 未处理。 +- 该锁**只覆盖本方法与 §2 恢复库存**，不覆盖 `batchUpsert`（管理端批量设价），见「⚠️ 关键变化」。 +- 老数据兼容：无字段变化。 + +--- + +### 2. 恢复库存（内部） `POST /internal/product/{productId}/restore-stock` + +**VO**: `无 ReqVO（Query 参数直绑，无请求体） → Void` + +#### 使用场景 + +供其他微服务在订单取消/过期时通过 Feign 跨服务恢复产品价格日历库存（**当前无实际调用方**，见「⚠️ 关键变化」）。底层同样是 `select → 改 sold → updateById` 的读改写，`sold` 不减到负数（`Math.max(sold-count, 0)`）。本次改动不涉及入参/出参，只新增一条「被 §1 扣减库存占用同一把锁」的失败分支。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| productId | Path | Long | ✅ | - | 产品 ID | +| date | Query | String | ✅ | yyyy-MM-dd | 日期 | +| count | Query | int | ✅ | `@Min(1)` | 恢复数量，至少为 1 | + +#### 出参 `Result` + +| 字段 | 类型 | 说明 | +|------|------|------| +| data | null | 无返回数据，成功恒为 `null` | + +#### 请求示例 + +```http +POST /internal/product/1234567890123456789/restore-stock?date=2026-10-01&count=2 +``` + +#### 响应示例 + +```json +{ "code": 200, "message": "成功", "data": null, "success": true } +``` + +#### 空数据 / 降级响应 + +该产品该日期无价格日历记录时静默跳过（不抛异常，`ProductPriceCalendarMapper#restoreStock` 内部 `record == null` 时直接 return，无任何写入）。恢复数量超过已扣数量时 `sold` 按 0 兜底，不会变负数，同样不报错。 + +#### 错误响应 + +```json +{ "code": 100503, "message": "资源被占用,请稍后重试", "data": null, "success": false } +``` + +| code | 触发条件 | +|------|----------| +| 400 | 参数校验失败（`count < 1`） | +| **100503（本次新增）** | 抢锁等待超过 3 秒（与 §1 扣减库存共用同一把 `product:stock` 锁），**可重试** | + +#### 业务边界 + +- 无 `@Idempotent`，同 §1。 +- 抢锁失败（100503）时零写入。 +- 本方法本身不会因"库存记录不存在"或"恢复超过已扣数量"抛错，均静默处理（这是既有行为，非本次改动引入）。 +- 老数据兼容：无字段变化。 + +--- + +## 四、契约约束与正确调用方式（接口类必写） + +> 本节只写**后端接受/拒绝 payload 的规则**,不写 UI 渲染建议。 + +### 并发冲突（100503）的正确处理方式 + +两个端点本次开始**真正互斥**（同一 `productId+date` 维度）：同一时刻只有一个能执行，其余排队等待，等待超过 3 秒（`acquireTimeout`，本组 `@Lock4j` 未显式设置，取 lock4j-core 注解默认值 3000ms）直接返回失败。 + +| 场景 | 响应 | +|------|------| +| ✅ 单个请求，无并发 | 200 + 正常业务结果 | +| ✅ 同 `productId+date` 两个请求先后到达，第二个在 3 秒内轮到锁 | 两个都 200（第二个排队等待） | +| ❌ 同 `productId+date` 两个请求并发，第二个等待超过 3 秒未抢到锁 | `{ "code": 100503, "message": "资源被占用,请稍后重试", "success": false }`，**HTTP 状态码仍是 200** | +| ✅ 不同 `productId` 或不同 `date` 并发 | 互不影响，各自独立加锁（锁键含 `productId` 与 `date`） | + +**调用方（若未来接入）必须做的事**：判断响应体 `code === 100503`（不是判 HTTP 状态码），命中时按业务语义重试或提示上游；**不要**当作系统异常。 + +### Swagger notes 订正说明（供以此为契约的调用方核对） + +`InternalProductController:121` 扣减库存端点的 Swagger notes 已从「乐观锁扣减价格日历库存」改为「实现是 select→改 sold→updateById 的读改写，靠 @Lock4j(name=product:stock) 分布式锁串行化，本表无 version 列、非乐观锁」。任何据旧 notes 编写的调用方文档/注释若沿用了"乐观锁"这一表述，应据本次改动订正。 + +--- + +## 五、数据库行为（涉及写操作时必写） + +本次不改变任何一次**成功**写操作实际写入的行数或内容——两个端点各自原有的写入逻辑（`sold` 列增减）逐字节不变。变化的只是"谁能在同一时刻对同一 `productId+date` 执行写入"： + +| 维度 | 改动前 | 改动后 | +|------|--------|--------| +| 两个端点是否互斥（同 productId+date） | 否（各自持独立锁，可并发） | 是（同一把锁，串行执行） | +| 抢锁失败时是否有部分写入 | N/A（此前不会因锁而失败） | 否，零写入（`@Lock4j` 方法级环绕拦截，拿不到锁直接抛异常，不产生任何 SQL） | +| `batchUpsert`（管理端批量设价）与本组两端点的并发关系 | 不受本锁保护，仍可能丢更新 | 不变——本次改动未处理，见「⚠️ 关键变化」 | + +--- + +## 六、边界行为 + +- 参数校验失败（`count<1`）→ 400 +- 库存不足或未开放（仅 `deduct-stock`）→ 480201 +- **抢锁超时（本次新增）→ 100503，HTTP 200，可重试，零写入** +- `restore-stock` 对不存在的价格日历记录/超额恢复 → 静默跳过或按 0 兜底，不报错，与本次改动无关 +- 老数据兼容：本次不涉及字段增删，存量数据无需迁移 + +--- + +## 六.5、枚举 / 数据字典（接口出现枚举时必写） + +本组两个接口均为纯数值/日期参数，无枚举字段，本节不适用。 + +## 六.6、修改前后对比（修改/删除类接口必写，新增跳过） + +### 字段级对比 + +| 字段 | 改前 | 改后 | +|------|------|------| +| （无）| 两个接口的请求参数、响应结构逐字节不变 | 同左 | + +### 行为级对比 + +| 行为 | 改前 | 改后 | +|------|------|------| +| 两个端点同 productId+date 并发时 | 各自持独立锁，可同时执行（读改写非原子，可能丢更新） | 同一把锁，串行执行，互斥真正生效 | +| 抢锁失败的响应 | 不存在这条路径 | 路径真实存在（返回 100503，HTTP 200，业务失败，可重试）；本次改动未部署测试服，无实测触发频率数据 | +| `InternalProductController:121` Swagger notes | 「乐观锁扣减价格日历库存」（与表结构不符的错误描述） | 订正为读改写 + 分布式锁串行化的真实机制描述 | +| 请求/响应字段、既有业务错误码（480201） | 不变 | 不变 | + +## 六.7、影响评估（修改/删除类必写） + +- **是否破坏向后兼容**: 否——不改字段、不改既有错误码语义；新增的 100503 失败路径由于**当前零跨服务调用方**，对现存系统零影响面。 +- **前端是否必须同步上线**: 不适用——两个端点没有任何前端或其他服务的直接调用方，本次改动不需要任何下游同步。若未来有服务接入 Feign 调用这两个端点，调用方需按「四、契约约束」处理 100503。 +- **前端 workaround 清理点**: 无。 + +## 七、不影响范围（显式声明, 帮前端/QA 缩小排查面） + +- **仅影响**: `/internal/product/{productId}/deduct-stock`、`/internal/product/{productId}/restore-stock` 两个端点在**未来有并发调用方时**的失败分支；当前因零调用方，实际影响面为零 +- **零影响**: + - `ProductPriceCalendarMapper#batchUpsert`（管理端批量设价，经 `ProductPricingService`/`ProductSnapshotService` 调用）——不取本锁，行为未变，仍可能与本组两端点产生 `sold` 丢更新（既有问题，本次未处理） + - 价格日历的其余读接口（按产品/月份/日期范围查询等） + - `InternalProductController` 其余端点（产品详情、简单报价、班期信息/报价、报名入团等） + - 两个端点的请求参数、响应结构 + - 既有业务错误码 480201 的触发条件与文案 + - hl-gateway 路由配置——`/internal/**` 本就不对公网暴露，本次未新增任何路由 + +--- + +## 八、测试环境已验证 + +**部署读数（2026-09-20 23:20）**：hl-product-service-v2 滚动更新两实例，部署前 `4cbccc26b`（停在 2026-09-19，落后 93 个提交）→ 部署后 `ba8aab3ab`，8183 与 8083 各 7 秒内起监听，`deploy-backend.sh` 报 `rolling deploy complete`。`git merge-base --is-ancestor f72a7548c ba8aab3ab` 返回 **ANCESTOR_YES**，本次改动确在运行版本内。 + +🔴 **本节到此为止，没有功能调用读数，这是有意为之而不是遗漏**：两个端点是 `/internal/product/**`、当前**零调用方**，既不经网关也无任何 Feign 声明指向；直接打端口调用会**真实扣减/恢复库存**，副作用落在共享测试服上由其他会话承担，且 `restore-stock` 不保证是 `deduct-stock` 的精确逆操作（不可靠地撤回）。互斥本身由单测 `ProductStockLockNameGuardTest` 覆盖（按效果反查两处 `name` 非空且相等），这是 `name` 契约类改动的恰当取证层级。 + +⚠️ **`100503` 在本服务上一次都没有触发过**——不是「测过、不会触发」，是**没测**。 + +--- + +## 十、相关文档 + +- 关联 Issue: [wx/HL#7980](https://git.1814.love:8443/wx/HL/issues/7980)（AC-8） +- 关联 PR: [wx/HL#8047](https://git.1814.love:8443/wx/HL/pulls/8047) + +## 关联 / 联系人 + +### 链接 + +- **Issue**: [#7980](https://git.1814.love:8443/wx/HL/issues/7980) +- **PR**: [#8047](https://git.1814.love:8443/wx/HL/pulls/8047) +- **Merge commit**: [f72a7548c](https://git.1814.love:8443/wx/HL/commit/f72a7548c)（合并后回填，backend_status 待部署后翻转） + +### 联系人 + +- **后端负责人**: @wx diff --git a/changelogs-v2/2026-09/20_7980_出行人删改与发票申请三组写口补同名锁新增100503冲突码触达C端-修改接口-管理后台.md b/changelogs-v2/2026-09/20_7980_出行人删改与发票申请三组写口补同名锁新增100503冲突码触达C端-修改接口-管理后台.md new file mode 100644 index 00000000..57ebdbae --- /dev/null +++ b/changelogs-v2/2026-09/20_7980_出行人删改与发票申请三组写口补同名锁新增100503冲突码触达C端-修改接口-管理后台.md @@ -0,0 +1,880 @@ +--- +schema: "hl-changelog/v2" +ticket: "7980" +title: "出行人删除/批量编辑与发票申请三组写口补同一把 @Lock4j name，新增可重试冲突码 100503（会传导至小程序 C 端）" +consumer: "multiple" +author: "wx(GIT)" +change_type: "修改接口" +backend_status: "deployed" +gateway_status: "not_required" +frontend_status: "pending" +frontend_owner: "mmg" +frontend_ref: "" +target_release: "" +verified_at: "" +status_note: "PR #8049 已 squash 合并 dev-v3（合并提交 43c53c4c9）。2026-09-20 23:24 已部署测试服 hl-order-service-v3：滚动更新两实例，部署前 COMMIT=c35251b07、部署后 COMMIT=ba8aab3ab，8186 与 8086 各 12 秒内起监听。`git merge-base --is-ancestor 43c53c4c9 ba8aab3ab` 返回 ANCESTOR_YES。gateway_status=not_required：端点路径/方法零变化，本次与网关路由无关，不是漏验证。🔴 本次未在测试服做功能调用取证，这是有意为之而不是遗漏：本组端点是删除出行人与批量改出行人，调用它们会真实删改订单下的出行人行；测试服订单数据被多个会话共用，删除撤不回来，副作用会落在一个不知情的人头上。互斥本身由落库级并发 IT `Lock4jSharedNameConcurrencyIT` 覆盖（3 条用例，含专为自调用入口 `deleteByInternal` 单写的一条），不变量是「订单至少留 1 位成人」；另有 `Lock4jSharedNameContractTest` 按 SpEL 反查全类、钉死三组的成员集合，能抓住日后新加的第 N 个方法。⚠️ `100503` 在测试服上一次都没有触发过——不是「测过、不会触发」，是没测；临界区短不等于永不超时，更长事务/更大载荷/生产数据量下仍可能出现。" +updated_at: "2026-09-20" +base: "dev-v3" +--- + +# order-v3: 出行人删除/批量编辑与发票申请三组写口补同一把 @Lock4j name，新增可重试冲突码 100503（会传导至小程序 C 端） + +> **存放目录**: +> - 一期(v2,无 `order-v3` 标签的工单)→ `changelogs/{YYYY-MM}/` +> - 二期(v3,`order-v3` 标签的工单)→ `changelogs-v2/{YYYY-MM}/` +> +> **服务**: hl-order-service-v3（另涉 hl-mp-service 四个透传/BFF 入口） +> **PR**: #8049 +> **Issue**: #7980（AC-7 第一/三/四组） +> **日期**: 2026-09-20 +> **影响范围**: 管理后台「订单出行人」删除/批量编辑、「订单调整」提交（出行人 tab）、「发票管理」申请开票 + 小程序 C 端「出行人补全/删除」「申请发票」 + +--- + +## ⚠️ 关键变化（非必须,本版与上版行为不同 / 纠错 / 撤销时必写） + +- 三组写口的 `@Lock4j` 都写了**逐字相同**的 `keys`，却都**没写 `name`**——lock4j 2.2.7 缺省 `name` 时用「类全限定名 + 方法名」当默认值拼进 Redis 键，于是每组内的多个方法**各持一把互不相干的锁**，可以并发互相踩踏： + 1. **`traveler:delete:order`**（3 处）：`TravelerService.deleteTraveler`（admin）/ `mpDeleteTraveler`（mp）/ `deleteByInternal`（internal Feign，且它经 `this.deleteTraveler(...)` 自调用，不走 Spring 代理，之前**一次都没触发过**锁）。「最后 1 位成人禁删」是内存计数的 check-then-act，`order_traveler` 无 `@Version`、无行锁复读，没有第二道锁兜底——两个并发删除请求各读到「还有 2 个成人」的旧快照就会把成人删到 0。 + 2. **`traveler:batch-edit`**（3 处）：`TravelerService.batchEditTravelers`（admin 直接批量编辑）/ `batchEditTravelersForAdjustment`（订单调整提交里的出行人 tab）/ `mpBatchEditTravelers`（mp）。「基于内存合并的最终生效集合先校验后写库」同样是 check-then-act，没有第二道锁兜底。 + 3. **`order-invoice:apply`**（2 处）：`InvoiceAdminService.adminApplyInvoice`（admin）/ `InvoiceMpService.mpApplyInvoice`（mp）。两者前置条件相同（同一个 `validateApplyEligibility`，含「一单一票」existsActive 检查），`order_invoice` 无 `UNIQUE`、`OrderInvoice` 无 `@Version`，补 `name` 之前 admin 申请 ∥ mp 申请可各读到 existsActive 旧快照并各插一条申请单。 +- 本次给三组各自补上**同一个**显式 `name`（分别为 `"traveler:delete:order"` / `"traveler:batch-edit"` / `"order-invoice:apply"`），组内互斥才真正生效。**接口路径、请求/响应字段、既有业务错误码全部零增删**，唯一契约变化是新增一个可能返回的失败码 **`100503`**，**HTTP 状态码仍是 200**。 +- 🔴 **新增的失败路径会到达小程序 C 端**：出行人补全/删除、申请发票均是 mp 端用户自助操作，命中锁冲突时前端会等待最多约 3 秒后收到 `code=100503`（"资源被占用,请稍后重试"）。**传输层仍是 HTTP 200**，失败信息在响应体的 `code` 字段里——前端如果只看 HTTP 状态码会把这次失败误判为成功。 +- 🔴 **本 PR 只做 AC-7 里判定为「要修」的三组**。同一份判定还覆盖了另外三组，均**不修**（不在本文档「二、变更接口清单」范围内，行为未变，仅供背景参考）： + - `order-ins:` 组（保险 `purchaseCore`）：判定为「有意不加 name」——`purchaseCore` 本身没有按单去重逻辑，补锁对「同单不重复出单」零贡献；真正的缺口在工单未列出的 `autoPurchase`/`autoPurchaseByScheme`（连 `@Lock4j` 都没有），本轮只订正了两处描述这把锁效果的假注释，完整修复另起工单，本文档不涉及。 + - `material:tag:name:`（resource 服务）：有 `uk_tag_name` 唯一索引兜底，判定不修。 + - `fleet:msg-tpl:default:`（fleet 服务）：有 InnoDB 行锁兜底，判定不修。 + +--- + +## 一、背景 + +工单 #7980 第四节原文对以下几处描述与代码不符，本 PR 已订正（不影响本次「要不要补锁」的结论，只是让文档准确）：① 第 5 组「同名标签双插（无唯一索引）」——`material_tag` 实际**有** `UNIQUE KEY uk_tag_name`；② 第 3 组两处行号已漂移（AC-4 改动注释所致），实际为 `TravelerService.java:126`/`:150`（现已改为本次改动后的真实行号）；③ 第 3 组组大小实际是 **3** 个方法（`deleteTraveler`/`mpDeleteTraveler`/`deleteByInternal`）不是 2 个，其中 `deleteByInternal` 因自调用问题此前**从未触发过**锁，是最危险的一处。 + +--- + +## 二、变更接口清单 + +| # | 接口 | 方法 | 路径 | 变更类型 | 说明 | +|---|------|------|------|----------|------| +| 1 | 出行人软删（admin） | POST | `/v3/admin/order/{id}/traveler/{travelerId}/delete` | 新增可能返回的错误码 | 与 §2/§3 共用 `traveler:delete:order` 锁 | +| 2 | 客户删除出行人（mp internal） | POST | `/v3/internal/mp/order/{id}/traveler/{travelerId}/delete` | 新增可能返回的错误码 | 经 hl-mp-service 到达小程序 C 端 | +| 3 | 跨服务删除出行人（internal Feign） | DELETE | `/v3/internal/order/orders/{orderId}/travelers/{travelerId}` | 新增可能返回的错误码 | 当前零跨服务调用方，见业务边界 | +| 4 | 批量 upsert 出行人（admin） | POST | `/v3/admin/order/{id}/traveler/batch-edit` | 新增可能返回的错误码 | 与 §5/§6 共用 `traveler:batch-edit` 锁 | +| 5 | 调整订单统一提交（含出行人 tab） | POST | `/v3/admin/order/{id}/adjustment/submit` | 新增可能返回的错误码（条件触发） | 仅当请求体含出行人增删改时才会命中本组锁 | +| 6 | 客户出行人补全（mp internal） | POST | `/v3/internal/mp/order/{id}/traveler/batch-edit` | 新增可能返回的错误码 | 经 hl-mp-service 到达小程序 C 端 | +| 7 | 定制师代客申请发票（admin） | POST | `/v3/admin/order/{orderId}/invoice/apply` | 新增可能返回的错误码 | 与 §8 共用 `order-invoice:apply` 锁 | +| 8 | 用户申请开票（mp internal） | POST | `/v3/internal/mp/order/{orderId}/invoice/apply` | 新增可能返回的错误码 | 经 hl-mp-service 到达小程序 C 端 | + +--- + +## 三、接口详情 + +### 1. 出行人软删（admin） `POST /v3/admin/order/{id}/traveler/{travelerId}/delete` + +**VO**: `无 ReqVO（纯路径参数，无请求体） → Boolean` + +#### 使用场景 + +管理后台订单详情页，定制师/客服删除某个出行人（已签电子合同禁删；订单最后 1 位成人禁删）。本次改动不涉及入参/出参，只新增一条「被本组另外 2 个写口占用同一把锁」的失败分支。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| id | Path | Long | ✅ | - | 订单 ID | +| travelerId | Path | Long | ✅ | - | 出行人 ID | + +#### 出参 `Result` + +| 字段 | 类型 | 说明 | +|------|------|------| +| data | Boolean | 恒为 `true`（失败走异常，不会返回 `false`） | + +#### 请求示例 + +```http +POST /v3/admin/order/1234567890123456789/traveler/70123456789012/delete +Authorization: Bearer {token} +``` + +#### 响应示例 + +```json +{ "code": 200, "message": "成功", "data": true, "success": true } +``` + +#### 空数据 / 降级响应 + +本接口无「空数据」/降级概念（成功恒返回 `true`，失败一律抛业务异常）。 + +#### 错误响应 + +```json +{ "code": 100503, "message": "资源被占用,请稍后重试", "data": null, "success": false } +``` + +| code | 触发条件 | +|------|----------| +| 401 | 未登录（网关拦截） | +| 581102 | 订单不存在 | +| 581110 | 出行人 ID 不属于该订单 | +| 581106 | 已签电子合同，禁止删除出行人 | +| 581107 | 出行人是订单最后 1 位成人，禁止删除 | +| 100502 | 3 秒幂等窗口内重复提交（键=id+travelerId） | +| **100503（本次新增）** | 抢锁等待超过 3 秒（与 §2 mp 删除、§3 internal Feign 删除共用同一把 `traveler:delete:order` 锁），**可重试** | + +#### 业务边界 + +- 幂等：`@Idempotent`（`keyPrefix=traveler:delete`）3 秒窗口，键含订单 ID + 出行人 ID。 +- 抢锁失败（100503）时该次请求未进入方法体，零写入——「最后 1 位成人」的计数不会被并发破坏。 +- 软删：级联软删桥接表 `order_transport_plan_traveler`，并写 `order_status_log` 流水（`TRAVELER_DELETE`）。 +- 已签约阶段删人会触发"作废旧合同/保单 + 重新签约/投保"事件（按订单状态白名单过滤），不受本次改动影响。 + +--- + +### 2. 客户删除出行人（mp internal） `POST /v3/internal/mp/order/{id}/traveler/{travelerId}/delete` + +**VO**: `无 ReqVO（纯路径参数，无请求体） → Void` + +#### 使用场景 + +小程序 C 端用户在「我的订单」自助删除出行人，仅订单确认前（PENDING_PAY/CUSTOMIZING）放行，且只能删自己名下订单的出行人。**本端点是 order-v3 的 internal 路径，C 端不直接访问它**，而是经 hl-mp-service 的公网入口 `DELETE /mp/order/{orderId}/traveler/{travelerId}`（`MpOrderTravelerController`）透传调用。本次改动不涉及入参/出参，只新增一条抢锁超时的失败分支。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| id | Path | Long | ✅ | - | 订单 ID | +| travelerId | Path | Long | ✅ | - | 出行人 ID | + +（`userId` 从 JWT 解析，前端不传，由网关透传 `X-User-Id`。） + +#### 出参 `Result` + +| 字段 | 类型 | 说明 | +|------|------|------| +| data | null | 无返回数据 | + +#### 请求示例 + +```http +DELETE /mp/order/1234567890123456789/traveler/70123456789012 +Authorization: Bearer {token} +``` + +（以上为小程序 C 端实际调用的公网地址；order-v3 侧 internal 路径见本节标题。） + +#### 响应示例 + +```json +{ "code": 200, "message": "成功", "data": null, "success": true } +``` + +#### 空数据 / 降级响应 + +本接口无「空数据」/降级概念。 + +#### 错误响应 + +```json +{ "code": 100503, "message": "资源被占用,请稍后重试", "data": null, "success": false } +``` + +| code | 触发条件 | +|------|----------| +| 581122 | 订单不属于当前用户（越权） | +| 581145 | 订单已确认，出行人信息不可再经小程序修改（须走 admin） | +| 581102/581110/581106/581107 | 同 §1（复用 `deleteTraveler` 全部业务规则） | +| 100502 | 3 秒幂等窗口内重复提交 | +| **100503（本次新增）** | 抢锁等待超过 3 秒（与 §1 admin 删除、§3 internal Feign 删除共用同一把 `traveler:delete:order` 锁），**可重试** | + +#### 业务边界 + +- 幂等：`@Idempotent` 3 秒窗口（键=订单 ID）。 +- 越权校验：`order.userId == 当前登录 userId`，不满足统一返 581122，不额外区分"不存在"与"无权限"。 +- 状态门禁：仅 `PENDING_PAY`/`CUSTOMIZING` 放行，订单确认后（`PENDING_DEPARTURE` 起）及已完成/已取消一律禁止，防止客户改动触发合同作废重签/退保重投保。 +- 抢锁失败（100503）时零写入，业务规则全部委托 `deleteTraveler`，见 §1。 + +--- + +### 3. 跨服务删除出行人（internal Feign） `DELETE /v3/internal/order/orders/{orderId}/travelers/{travelerId}` + +**VO**: `无 ReqVO（纯路径参数，无请求体） → Boolean` + +#### 使用场景 + +供其他微服务通过 Feign 跨服务删除出行人（无 JWT 鉴权，依赖网络隔离，Gateway 不暴露 `/internal/**` 至公网）。🔴 全仓 grep 确认**当前零跨服务调用方**——没有任何 `@FeignClient` 接口声明指向本路径，是本组三处里唯一没有现存调用方的一处。本次改动不涉及入参/出参，只是把此前**完全裸奔**（因自调用问题一次都没触发过锁）的这条链路纳入本组互斥。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| orderId | Path | Long | ✅ | - | 订单 ID | +| travelerId | Path | Long | ✅ | - | 出行人 ID | + +#### 出参 `Result` + +| 字段 | 类型 | 说明 | +|------|------|------| +| data | Boolean | 恒为 `true`（委托 `deleteTraveler`，失败走异常） | + +#### 请求示例 + +```http +DELETE /v3/internal/order/orders/1234567890123456789/travelers/70123456789012 +``` + +（跨服务 Feign 调用，无鉴权头。） + +#### 响应示例 + +```json +{ "code": 200, "message": "成功", "data": true, "success": true } +``` + +#### 空数据 / 降级响应 + +本接口无「空数据」/降级概念，也无当前真实流量。 + +#### 错误响应 + +```json +{ "code": 100503, "message": "资源被占用,请稍后重试", "data": null, "success": false } +``` + +| code | 触发条件 | +|------|----------| +| 581102/581110/581106/581107 | 同 §1（委托 `deleteTraveler`，`adminId` 传 `null`） | +| **100503（本次新增）** | 抢锁等待超过 3 秒（与 §1 admin 删除、§2 mp 删除共用同一把 `traveler:delete:order` 锁），**可重试** | + +#### 业务边界 + +- 无 `@Idempotent`（internal Feign 端点通常由调用方自行保证幂等）。 +- 🔴 **本次改动前，本端点的调用链（`deleteByInternal` → `this.deleteTraveler(...)`）是自调用，不经 Spring 代理，`deleteTraveler` 上的 `@Lock4j` 在这条链路上此前一次都不会触发**——`deleteByInternal` 方法本身现已补上独立的 `@Lock4j(name="traveler:delete:order")`，才真正纳入互斥；这不是"补 name"本身的效果，而是本次一并修的一个更深的问题（自调用丢锁）。 +- 当前零调用方，不代表本条不需要修：与 A/B/C 三份 changelog 里 C 份（库存扣减）同类判定——回归面可实证为零，但闸口本身要补齐。 +- 抢锁失败（100503）时零写入。 + +--- + +### 4. 批量 upsert 出行人（admin） `POST /v3/admin/order/{id}/traveler/batch-edit` + +**VO**: `TravelerBatchEditReqVO → TravelerBatchEditRespVO` + +#### 使用场景 + +管理后台订单详情页，定制师/客服批量新增/更新出行人（id=null 新增，id 非 null 更新，整体事务，≤30 行）。本次改动不涉及入参/出参字段，只新增一条「被本组另外 2 个写口占用同一把锁」的失败分支。 + +#### 入参 + +路径参数 + Body： + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| id | Path | Long | ✅ | - | 订单 ID | +| travelers | Body | List\ | ✅ | `@NotEmpty`，≤30 | 待修改出行人数组 | +| travelers[].id | Body | Long | - | null=新增/非 null=更新 | 更新时必须属于该 orderId | +| travelers[].name | Body | String | - | - | 姓名 | +| travelers[].gender | Body | String | - | 1=男/2=女/0=未知 | 性别 | +| travelers[].birthday | Body | LocalDate | ✅ | - | 出生日期，后端按年龄自动派生出行人类型 | +| travelers[].idType | Body | String | - | 字典 id_card_type | 证件类型 | +| travelers[].idNo | Body | String | - | 格式按证件类型校验 | 证件号（明文传，DB 加密） | +| travelers[].nationality | Body | String | - | 不可空字符串 | 国籍（12301 必报字段） | +| travelers[].race | Body | String | - | 不可空字符串 | 民族（12301 必报字段） | +| travelers[].phone | Body | String | - | 11 位数字 | 出行人手机（明文传，DB 加密） | +| travelers[].email | Body | String | - | 宽松格式 | 电子邮箱 | +| travelers[].emergencyContact | Body | String | - | - | 紧急联系人姓名 | +| travelers[].emergencyPhone | Body | String | - | - | 紧急联系人电话 | +| travelers[].roomGroupNo | Body | Integer | - | 不超家庭数上限 | 同住分组号 | + +#### 出参 `Result` + +| 字段 | 类型 | 说明 | +|------|------|------| +| createdCount | Integer | 本次新增的出行人数（id=null 行） | +| updatedCount | Integer | 本次更新的出行人数（id 非 null 行） | +| completedCount | Integer | 本次操作后变为 COMPLETED 的行数 | +| pendingCount | Integer | 仍为 PENDING 的行数 | +| allCompleted | Boolean | 该订单所有出行人是否已完善 | + +#### 请求示例 + +```json +{ + "travelers": [ + { + "id": null, + "name": "张三", + "gender": "1", + "birthday": "1985-08-12", + "idType": "ID_CARD", + "idNo": "220103198508121234", + "nationality": "中国", + "race": "汉族", + "phone": "13812342046" + } + ] +} +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "data": { "createdCount": 1, "updatedCount": 0, "completedCount": 1, "pendingCount": 0, "allCompleted": true }, + "success": true +} +``` + +#### 空数据 / 降级响应 + +本接口无「空数据」概念（`travelers` 要求非空），无降级路径。 + +#### 错误响应 + +```json +{ "code": 100503, "message": "资源被占用,请稍后重试", "data": null, "success": false } +``` + +| code | 触发条件 | +|------|----------| +| 401 | 未登录（网关拦截） | +| 581105 | 批量大小超限（>30） | +| 581102 | 订单不存在 | +| 581119 | 出行人证件号重复（同批） | +| 581101 | 12301 必报字段缺失（国籍/民族为空字符串） | +| 581112/581113/581114 | 证件号/手机号格式非法、出生日期晚于今天 | +| 581103/581104 | 性别编码不合法、同住分组号超出上限 | +| 581118 | 新增项缺少必填信息（姓名/证件类型/证件号至少一项） | +| 581110 | 更新项不属于该订单 | +| 581111 | 已签电子合同后禁止修改证件号 | +| 581136 | 成人手机号硬门禁（至少一名成人须填手机号） | +| 100502 | 3 秒幂等窗口内重复提交（键=订单 ID） | +| **100503（本次新增）** | 抢锁等待超过 3 秒（与 §5 订单调整提交、§6 mp 出行人补全共用同一把 `traveler:batch-edit` 锁），**可重试** | + +#### 业务边界 + +- 幂等：`@Idempotent` 3 秒窗口（键=订单 ID）。 +- 抢锁失败（100503）时零写入——所有校验（配额、去重、必填矩阵）都在事务内完成，锁竞争失败不会产生任何部分写入。 +- 校验顺序：批量大小 → 订单存在 → 身份证去重 → 姓名硬拦截 → 12301 字段 → 格式类字段 → 新增/更新分支各自的必填与归属校验 → 成人手机号硬门禁（基于内存合并的最终生效集合），任一失败整事务回滚。 +- 老数据兼容：无字段变化。 + +--- + +### 5. 调整订单统一提交（含出行人 tab） `POST /v3/admin/order/{id}/adjustment/submit` + +**VO**: `AdjustmentSubmitReqVO → AdjustmentSubmitRespVO` + +#### 使用场景 + +⚠️ 本接口是订单调整弹窗的统一提交入口，覆盖人数/行程/住宿/用车等多个子领域，**本节只描述与本次改动相关的「出行人 tab」部分**，其余子领域（改期/行程编辑/房需求/车需求）字段与行为均**不在本次改动范围内、未变化**，完整入参见既有产品/接口文档。当请求体 `updates.people.travelers`（或兼容旧契约的 `updates.travelers`）含新增/更新/删除任一项时，后端内部会调用与 §4 admin 批量编辑**同名**的锁（`traveler:batch-edit`），本次改动前该调用完全不受这把锁保护——补 `name` 之后，本接口在处理出行人变更时会真的把 §4/§6 挡在门外。 + +#### 入参（仅出行人相关部分，其余字段见既有文档） + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| id | Path | Long | ✅ | - | 订单 ID | +| updates.people.travelers.add | Body | List\ | - | - | 新增出行人列表 | +| updates.people.travelers.update | Body | List\ | - | 含 id 字段 | 更新出行人列表 | +| updates.people.travelers.remove | Body | List\ | - | - | 删除出行人 id 列表 | +| updates.people.travelers.add[].name | Body | String | - | - | 姓名 | +| updates.people.travelers.add[].idType | Body | String | - | - | 证件类型 | +| updates.people.travelers.add[].idNo | Body | String | - | - | 证件号（脱敏回显，编辑回传按未修改处理规则见 §4 同款字段） | +| updates.people.travelers.add[].birthday | Body | LocalDate | 条件必填 | 新增必填 | 出生日期，用于派生出行人类型 | +| updates.people.travelers.add[].travelerType | Body | String | - | ADULT/CHILD | 出行人类型 | +| updates.people.travelers.add[].remark | Body | String | - | - | 备注 | +| updates（其余字段：schedule/itinerary/hotelRequirement/vehicleRequirement/transferRequirement） | Body | - | - | 见既有文档 | 与本次改动无关，未变化 | + +#### 出参 `Result` + +| 字段 | 类型 | 说明 | +|------|------|------| +| success | Boolean | 提交是否成功（极简响应，失败统一走全局异常处理器返回 `Result{code,message}`） | + +#### 请求示例（仅出行人 tab 片段） + +```json +{ + "updates": { + "people": { + "travelers": { + "add": [ + { "name": "李四", "idType": "ID_CARD", "idNo": "110101198801011234", "birthday": "1988-01-01" } + ], + "remove": [70123456789013] + } + } + } +} +``` + +#### 响应示例 + +```json +{ "code": 200, "message": "成功", "data": { "success": true }, "success": true } +``` + +#### 空数据 / 降级响应 + +`updates` 各子域均可为 null（按需填），但不能全 null（否则 `AdjustmentErrorCode.ADJUST_NO_EFFECTIVE_CHANGE`）。不含出行人变更时本次改动完全不生效，走原有逻辑。 + +#### 错误响应 + +```json +{ "code": 100503, "message": "资源被占用,请稍后重试", "data": null, "success": false } +``` + +| code | 触发条件 | +|------|----------| +| 401 | 未登录（网关拦截） | +| （出行人相关）581101/581103/581104/581110-581114/581118/581119/581136 | 同 §4 校验矩阵，按调整后目标人数校验（区别于 §4 按数据库当前声明人数校验） | +| **100503（本次新增，仅当本次提交含出行人变更时可能触发）** | 抢锁等待超过 3 秒（与 §4 admin 批量编辑、§6 mp 出行人补全共用同一把 `traveler:batch-edit` 锁），**可重试** | +| （其余子领域错误码） | 与本次改动无关，未变化，不在本文档范围 | + +#### 业务边界 + +- 无 `@Idempotent`（本端点覆盖多子领域，幂等策略由前端弹窗层面控制，不在本次改动范围）。 +- **配额校验口径与 §4 不同**：本入口按"本次调整的最终人数"校验（`targetDeclaration`），并在校验时排除同一事务中待删除的旧出行人；§4 普通编辑入口按数据库中的当前声明人数校验。 +- 抢锁失败（100503）**只影响本次请求整体**——本接口是单一事务原子应用所有子领域改动，出行人锁竞争失败会导致整个 `adjustment/submit` 请求失败回滚，不会出现"其他子域改完、出行人没改完"的部分成功。 +- 老数据兼容：无字段变化。 + +--- + +### 6. 客户出行人补全（mp internal） `POST /v3/internal/mp/order/{id}/traveler/batch-edit` + +**VO**: `TravelerBatchEditReqVO → TravelerBatchEditRespVO` + +#### 使用场景 + +小程序 C 端用户自助补全/修改出行人信息，仅订单确认前（`PENDING_PAY`/`CUSTOMIZING`）放行，且只能改自己名下订单。**本端点是 order-v3 的 internal 路径**，C 端经 hl-mp-service 的三个公网入口间接调用：`POST /mp/order/{orderId}/traveler`（新增单个出行人）、`PUT /mp/order/{orderId}/traveler/{travelerId}`（修改单个出行人）、`POST /mp/v3/order/{id}/traveler/batch-edit`（批量补全）。本次改动不涉及入参/出参字段，只新增一条抢锁超时的失败分支。 + +#### 入参 + +同 §4（`TravelerBatchEditReqVO`，字段表见上节，不重复列出）。`userId` 从 JWT 解析，前端不传。 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| id | Path | Long | ✅ | - | 订单 ID | +| travelers | Body | List\ | ✅ | `@NotEmpty`，≤30 | 字段结构同 §4 | + +#### 出参 `Result` + +字段结构同 §4： + +| 字段 | 类型 | 说明 | +|------|------|------| +| createdCount | Integer | 本次新增的出行人数（id=null 行） | +| updatedCount | Integer | 本次更新的出行人数（id 非 null 行） | +| completedCount | Integer | 本次操作后变为 COMPLETED 的行数 | +| pendingCount | Integer | 仍为 PENDING 的行数 | +| allCompleted | Boolean | 该订单所有出行人是否已完善 | + +#### 请求示例 + +```json +{ + "travelers": [ + { "id": null, "name": "王五", "idType": "ID_CARD", "idNo": "310101199001011234", "birthday": "1990-01-01" } + ] +} +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "data": { "createdCount": 1, "updatedCount": 0, "completedCount": 1, "pendingCount": 0, "allCompleted": true }, + "success": true +} +``` + +#### 空数据 / 降级响应 + +本接口无「空数据」概念（`travelers` 要求非空），无降级路径。 + +#### 错误响应 + +```json +{ "code": 100503, "message": "资源被占用,请稍后重试", "data": null, "success": false } +``` + +| code | 触发条件 | +|------|----------| +| 581122 | 订单不属于当前用户（越权） | +| 581145 | 订单已确认，出行人信息不可再经小程序修改 | +| 581101/581105/581110-581114/581118/581119/581136 | 同 §4 校验矩阵 | +| 100502 | 3 秒幂等窗口内重复提交 | +| **100503（本次新增）** | 抢锁等待超过 3 秒（与 §4 admin 批量编辑、§5 订单调整提交共用同一把 `traveler:batch-edit` 锁），**可重试** | + +#### 业务边界 + +- 幂等：`@Idempotent` 3 秒窗口（键=订单 ID）。 +- 越权与状态门禁同 §2。 +- 🔴 **本 PR 尤其重要的一处**：`mpBatchEditTravelers` 的方法体最终委托 `this.batchEditTravelers(...)`（自调用），此前该调用同样有绕过代理丢锁的历史问题，本次连同 §4/§5 一并补齐同一 `name`，三个入口现在才真正互斥——补锁前，客户在小程序自助编辑与定制师在 admin 后台同时编辑同一订单的出行人可能互不阻塞（内存计算的配额各按各的旧快照算，静默丢更新）。 +- 抢锁失败（100503）时零写入。 +- 老数据兼容：无字段变化。 + +--- + +### 7. 定制师代客申请发票（admin） `POST /v3/admin/order/{orderId}/invoice/apply` + +**VO**: `AdminInvoiceApplyReqVO → AdminInvoiceApplyRespVO` + +#### 使用场景 + +管理后台「发票管理」，定制师代客户申请开票（订单状态须 ∈ {CUSTOMIZING, PENDING_DEPARTURE, TRAVELLING, COMPLETED}，或已取消且净实收>0；一单一票）。本次改动不涉及入参/出参字段，只新增一条「被 §8 mp 申请占用同一把锁」的失败分支。 + +#### 入参 + +路径参数 + Body： + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| orderId | Path | Long | ✅ | - | 订单 ID | +| invoiceType | Body | String | ✅ | `@NotBlank`，VAT_NORMAL/VAT_SPECIAL | 发票类型 | +| titleType | Body | String | ✅ | `@NotBlank`，COMPANY/PERSONAL | 抬头类型，专票只能开给单位 | +| titleName | Body | String | ✅ | `@NotBlank`，≤200 字符 | 抬头名称 | +| taxNo | Body | String | 条件必填 | ≤64 字符 | 税号（titleType=COMPANY 或 invoiceType=VAT_SPECIAL 必填） | +| bankName | Body | String | 条件必填 | ≤128 字符 | 开户行（invoiceType=VAT_SPECIAL 必填） | +| bankAccount | Body | String | 条件必填 | ≤64 字符 | 开户账号（同上） | +| registAddress | Body | String | 条件必填 | ≤500 字符 | 注册地址（同上） | +| registPhone | Body | String | 条件必填 | ≤32 字符 | 注册电话（同上） | +| email | Body | String | ✅ | `@Email`，≤128 字符 | 收件邮箱 | +| remark | Body | String | - | ≤500 字符 | 备注/货物或应税劳务名称 | + +#### 出参 `Result` + +| 字段 | 类型 | 说明 | +|------|------|------| +| id | String（雪花，序列化为字符串） | 发票 ID | +| orderId | String | 订单 ID | +| status | String | 发票状态（REQUESTED=待开票） | +| amount | BigDecimal | 开票金额（申请阶段为 null，开票时才计算写入） | +| requestedAt | LocalDateTime | 申请时间 | +| requestedBy | String | 申请人（定制师真实姓名） | + +#### 请求示例 + +```json +{ + "invoiceType": "VAT_NORMAL", + "titleType": "COMPANY", + "titleName": "上海呼籁旅行科技有限公司", + "taxNo": "91310115MA1K48XXXX", + "email": "finance@hulalv.com" +} +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "data": { + "id": "2100889866400104450", + "orderId": "1234567890123456789", + "status": "REQUESTED", + "amount": null, + "requestedAt": "2026-09-20T14:30:25", + "requestedBy": "李定制" + }, + "success": true +} +``` + +#### 空数据 / 降级响应 + +本接口无「空数据」概念（成功恒返回完整响应），无降级路径。 + +#### 错误响应 + +```json +{ "code": 100503, "message": "资源被占用,请稍后重试", "data": null, "success": false } +``` + +| code | 触发条件 | +|------|----------| +| 401 | 未登录（网关拦截） | +| 581511 | 该订单已存在有效发票（一单一票） | +| 581524 | 订单当前状态不可申请开票 | +| 581513 | 发票类型非法 | +| 581523 | 增值税专用发票只能开给单位 | +| 581514 | 公司抬头或专票必须填写税号 | +| 581515 | 增值税专用发票须填写银行及注册信息 | +| 581516 | 收件邮箱不能为空 | +| 100502 | 5 秒幂等窗口内重复提交（键=订单+发票类型+抬头名称，抬头或类型不同即不拦） | +| **100503（本次新增）** | 抢锁等待超过 3 秒（与 §8 mp 申请共用同一把 `order-invoice:apply` 锁），**可重试** | + +#### 业务边界 + +- 幂等：`@Idempotent` 5 秒窗口，键含订单+发票类型+抬头名称——**抬头或类型不同即不拦**，替代不了这把锁（两个不同抬头的并发申请仍会分别通过幂等但撞上一单一票）。 +- 抢锁失败（100503）时该次请求零写入，`existsActive` 检查与 INSERT 之间不会被并发穿透。 +- 开票金额本次申请不写，由后续「完成开票」（另一 PR #8043 的 `issueInvoice`）自动计算写入，与本次改动无关。 +- 老数据兼容：无字段变化。 + +--- + +### 8. 用户申请开票（mp internal） `POST /v3/internal/mp/order/{orderId}/invoice/apply` + +**VO**: `MpInvoiceApplyReqVO → MpInvoiceApplyRespVO` + +#### 使用场景 + +小程序 C 端用户自助申请开票（仅本人订单，状态门槛与一单一票规则与 §7 相同）。**本端点是 order-v3 的 internal 路径**，C 端经 hl-mp-service 的公网入口 `POST /mp/v3/order/{orderId}/invoice/apply`（`MpV3CollabInvoiceApplyController`）透传调用。本次改动不涉及入参/出参字段，只新增一条「被 §7 admin 申请占用同一把锁」的失败分支。 + +#### 入参 + +路径参数 + Body： + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| orderId | Path | Long | ✅ | - | 订单 ID | +| invoiceType | Body | String | ✅ | `@NotBlank`，VAT_NORMAL/VAT_SPECIAL | 发票类型 | +| titleType | Body | String | ✅ | `@NotBlank`，COMPANY/PERSONAL | 抬头类型 | +| titleName | Body | String | ✅ | `@NotBlank`，≤200 字符 | 抬头名称 | +| taxNo | Body | String | 条件必填 | ≤64 字符 | 税号 | +| bankName | Body | String | 条件必填 | ≤128 字符 | 开户行 | +| bankAccount | Body | String | 条件必填 | ≤64 字符 | 开户账号 | +| registAddress | Body | String | 条件必填 | ≤500 字符 | 注册地址 | +| registPhone | Body | String | 条件必填 | ≤32 字符 | 注册电话 | +| email | Body | String | ✅ | `@Email`，≤128 字符 | 收件邮箱 | +| applyReason | Body | String | - | ≤500 字符 | 申请说明 | + +（`userId` 从 JWT 解析，前端不传。） + +#### 出参 `Result` + +| 字段 | 类型 | 说明 | +|------|------|------| +| id | Long | 发票主键 | +| orderId | Long | 订单 ID | +| status | String | 状态：实际写入值为 `REQUESTED`（与 hl-mp-service 侧 VO 注释所写"固定 APPLIED"不一致，以 order-v3 源码 `InvoiceMpService.mpApplyInvoice` 实际赋值为准） | +| amount | BigDecimal | 申请金额（申请阶段为 null） | +| applyAt | LocalDateTime | 申请时间 | +| triggerPushLogIds | List\ | 触发的通知推送日志 ID 列表（当前恒为空数组） | + +#### 请求示例 + +```json +{ + "invoiceType": "VAT_NORMAL", + "titleType": "PERSONAL", + "titleName": "张三", + "email": "zhangsan@example.com" +} +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "data": { + "id": 2100889866400104460, + "orderId": 1234567890123456789, + "status": "REQUESTED", + "amount": null, + "applyAt": "2026-09-20T14:35:10", + "triggerPushLogIds": [] + }, + "success": true +} +``` + +#### 空数据 / 降级响应 + +本接口无「空数据」概念，无降级路径。 + +#### 错误响应 + +```json +{ "code": 100503, "message": "资源被占用,请稍后重试", "data": null, "success": false } +``` + +| code | 触发条件 | +|------|----------| +| 581470 | 订单不存在或不属于当前用户 | +| 581511/581524/581513/581523/581514/581515/581516 | 同 §7 校验矩阵（复用 `InvoiceAdminService.validateApplyEligibility` / `validateInvoiceFields`） | +| 100502 | 5 秒幂等窗口内重复提交 | +| **100503（本次新增）** | 抢锁等待超过 3 秒（与 §7 admin 申请共用同一把 `order-invoice:apply` 锁），**可重试** | + +#### 业务边界 + +- 幂等：`@Idempotent` 5 秒窗口，口径同 §7。 +- 抢锁失败（100503）时零写入。 +- `requestedBy` 落库为用户 ID 字符串（区别于 admin 端落真实姓名），字段本身不在本次改动范围。 +- 老数据兼容：无字段变化。 + +--- + +## 四、契约约束与正确调用方式（接口类必写） + +> 本节只写**后端接受/拒绝 payload 的规则**，不写 UI 渲染建议。 + +### 正确 / 错误的客户端处理方式 + +本次不涉及请求体字段的互斥/联动规则变化，契约约束集中在"如何处理新失败码"： + +| 场景 | 处理方式 | +|------|----------| +| ✅ 收到 `code=100503` | 提示"另一个操作正在进行，请稍后重试"，**允许用户重试**，不当系统错误上报、不静默吞掉 | +| ✅ 判断成功/失败 | 一律读响应体 `code`（`===200` 才算成功），不能只看 HTTP 状态码 | +| ❌ 只看 HTTP 状态码 | `100503` 场景下 HTTP 仍是 200，只看状态码会把失败误判为成功，界面会"假装成功"但后端实际零写入 | +| ❌ 把 `100503` 当致命错误弹全屏报错 | 应视为可重试的低频并发退避，不要引导用户联系客服或上报崩溃监控 | + +### 三组锁各自的互斥范围（不要混淆） + +| 锁 name | 互斥范围 | 不在范围内 | +|---------|----------|------------| +| `traveler:delete:order` | §1 admin 删除 / §2 mp 删除 / §3 internal Feign 删除，三者对**同一 orderId** | 出行人的新增/编辑（属于 `traveler:batch-edit` 组） | +| `traveler:batch-edit` | §4 admin 批量编辑 / §5 订单调整提交（仅含出行人变更时）/ §6 mp 出行人补全，三者对**同一 orderId** | 出行人的删除（属于 `traveler:delete:order` 组）；§5 的非出行人子域（改期/行程/住宿/用车）与本锁无关 | +| `order-invoice:apply` | §7 admin 申请 / §8 mp 申请，两者对**同一 orderId** | 「完成开票」`issueInvoice`、「重新上传」`reuploadInvoice`、「申请重开」`reissueInvoice`（那三者共用**另一把**锁 `order-invoice:issue`，已在 PR #8043 / changelog `20_7980_发票签发重传重开三写口补同一把锁新增100503冲突码触达C端-修改接口-管理后台.md` 中处理，与本文档不是同一组） | + +### 幂等与并发冲突的区别 + +- 请求体**逐字节相同**且在幂等窗口内重复提交 → 幂等拦截，返回 `100502`（请勿重复提交），这是**另一个已存在的错误码**，本次不变。 +- 请求体**不同**或已过幂等窗口，但撞上组内另一写口正在执行的同订单请求 → 本次新增的 `100503`。 + +--- + +## 五、数据库行为（涉及写操作时必写） + +本次不改变任何一次**成功**写操作实际写入的行数或内容——8 个端点各自原有的写入逻辑（软删/桥接表级联/批量 upsert/发票 INSERT）逐字节不变。变化的只是"谁能在同一时刻对同一 orderId 执行本组写入"： + +| 组 | 改动前 | 改动后 | +|----|--------|--------| +| `traveler:delete:order` | admin/mp/internal 各持一把锁（internal 因自调用问题实际从未持锁），可并发互相踩踏「最后 1 位成人」内存计数 | 三者共享同一把锁，串行执行 | +| `traveler:batch-edit` | admin/adjustment/mp 各持一把锁，可并发各读旧快照后各自写库 | 三者共享同一把锁，串行执行 | +| `order-invoice:apply` | admin/mp 各持一把锁，可并发各读 `existsActive` 旧快照后各插一条申请 | 两者共享同一把锁，串行执行，一单一票才真正生效 | +| 抢锁失败时是否有部分写入 | N/A（此前不会因锁而失败） | 否，零写入（`@Lock4j` 方法级环绕拦截，拿不到锁直接抛异常） | + +--- + +## 六、边界行为 + +- 未登录 → 401（网关拦截） +- 订单不存在/不属于当前用户 → 581102/581110/581122/581470（各端点适用情况见上） +- 出行人删除相关业务闸口（已签合同/最后成人）→ 581106/581107，不受本次改动影响 +- 出行人批量编辑校验矩阵（12301/格式/配额）→ 581101/581103/581104/581112-581114/581118/581119/581136，不受本次改动影响 +- mp 端状态门禁（订单确认后禁止自助改动）→ 581145，不受本次改动影响 +- 发票一单一票/状态门槛 → 581511/581524，不受本次改动影响 +- **抢锁超时（本次新增）→ 100503，HTTP 200，可重试，零写入** +- 幂等窗口内重复提交（请求体相同）→ 100502，与本次改动无关，行为不变 +- 老数据兼容：本次不涉及字段增删，存量数据无需迁移 + +--- + +## 六.5、枚举 / 数据字典（接口出现枚举时必写） + +### 出行人性别（gender，出现于 §4/§6） + +**所属字段**: `travelers[].gender` | **类型**: `String` + +| 值 | 中文 | 说明 | +|----|------|------| +| `1` | 男 | - | +| `2` | 女 | - | +| `0` | 未知 | - | + +### 发票类型（invoiceType，出现于 §7/§8） + +**所属字段**: `invoiceType` | **类型**: `String` + +| 值 | 中文 | 说明 | +|----|------|------| +| `VAT_NORMAL` | 增值税普通发票 | 默认场景 | +| `VAT_SPECIAL` | 增值税专用发票 | 要求 `titleType=COMPANY`，且税号/银行/注册信息 5 字段全必填 | + +### 发票抬头类型（titleType，出现于 §7/§8） + +**所属字段**: `titleType` | **类型**: `String` + +| 值 | 中文 | 说明 | +|----|------|------| +| `COMPANY` | 单位 | 抬头为公司名，`taxNo` 必填 | +| `PERSONAL` | 个人 | 抬头为个人姓名，`taxNo` 非必填 | + +### 发票状态（status，出现于 §7/§8 出参） + +**所属字段**: `AdminInvoiceApplyRespVO.status` / `MpInvoiceApplyRespVO.status` | **类型**: `String` + +| 值 | 中文 | 说明 | +|----|------|------| +| `REQUESTED` | 待开票 | 申请成功后的初始状态（admin/mp 两端申请落库值一致，均为 `REQUESTED`） | + +## 六.6、修改前后对比（修改/删除类接口必写，新增跳过） + +### 字段级对比 + +| 字段 | 改前 | 改后 | +|------|------|------| +| （无）| 8 个接口的请求字段、响应字段逐字节不变 | 同左 | + +### 行为级对比 + +| 行为 | 改前 | 改后 | +|------|------|------| +| `traveler:delete:order` 组三入口并发 | 各持一把锁（internal 一支因自调用问题实际从未持锁），可并发破坏「最后 1 位成人」计数 | 三者共用同一把锁，串行执行 | +| `traveler:batch-edit` 组三入口并发 | 各持一把锁，可并发各按旧快照写库 | 三者共用同一把锁，串行执行 | +| `order-invoice:apply` 组两入口并发 | 各持一把锁，一单一票检查可被并发穿透 | 两者共用同一把锁，串行执行 | +| 抢锁失败的响应 | 不存在这条路径 | 路径真实存在（返回 100503，HTTP 200，业务失败，可重试）；本次改动未部署测试服，无实测触发频率数据 | +| 请求/响应字段、既有业务错误码 | 不变 | 不变 | + +## 六.7、影响评估（修改/删除类必写） + +- **是否破坏向后兼容**: 否——不改字段、不改既有错误码语义；但**新增了一条此前不存在的失败路径**（100503），且该路径会传导至小程序 C 端。 +- **前端是否必须同步上线**: 建议同步——尤其是小程序 C 端出行人补全/删除、发票申请三个入口，命中该分支时若前端无兜底会把失败误判为成功（HTTP 200）。**触发频率本文档未做任何测试服实测**，不可援引本工单其他 changelog（fleet 价格日历 #8035、发票签发 #8043）测试服实测出的"频率极低"结论——那是各自独立测量的结果，本组三把锁粒度均为单订单，与被测的价格日历/发票签发粒度不同，机制相同不代表频率相同。 +- **前端 workaround 清理点**: 无（本次是新增失败路径，不是清理旧 workaround）。 + +## 七、不影响范围（显式声明, 帮前端/QA 缩小排查面） + +- **仅影响**: 上述 8 个端点，抢锁失败时的响应体 +- **零影响**: + - 出行人列表查询（`GET /v3/admin/order/{id}/traveler/list`）、出行人校验（`GET .../traveler/validate`） + - 单个出行人新增（`POST /v3/admin/order/{id}/traveler/add`，走另一把独立锁 `order:traveler:add:{id}`，本次未涉及） + - 大交通批次相关接口 + - 发票的「完成开票」「重新上传」「申请重开」三个写口（属于另一把锁 `order-invoice:issue`，已在 #8043 处理，非本文档范围） + - 发票详情/列表/下载/企业信息自动回填等只读接口 + - `order-ins:`（保险）/ `material:tag:name:`（resource）/ `fleet:msg-tpl:default:`（fleet）三组，本轮判定不修，行为未变 + - 8 个端点的请求字段、响应字段结构 + - 既有业务错误码的触发条件与文案 + - 幂等拦截（100502）的行为 + - 单个请求在**无并发**时的行为（延迟、返回值、写入内容全部不变） + - hl-gateway 路由配置——8 个端点路径/方法零变化 + +--- + +## 八、测试环境已验证 + +**部署读数（2026-09-20 23:24）**：hl-order-service-v3 滚动更新两实例，部署前 `c35251b07` → 部署后 `ba8aab3ab`，8186 与 8086 各 12 秒内起监听，`deploy-backend.sh` 报 `rolling deploy complete`。`git merge-base --is-ancestor 43c53c4c9 ba8aab3ab` 返回 **ANCESTOR_YES**。 + +🔴 本次**未在测试服做功能调用取证，这是有意为之而不是遗漏**：本组端点是删除出行人与批量改出行人，调用它们会**真实删改订单下的出行人行**；测试服订单数据被多个会话共用，删除**撤不回来**，副作用会落在一个不知情的人头上。 + +互斥本身由**落库级并发 IT** `Lock4jSharedNameConcurrencyIT` 覆盖（3 条用例，含专为自调用入口 `deleteByInternal` 单写的一条），不变量是「订单至少留 1 位成人」；另有 `Lock4jSharedNameContractTest` 按 SpEL 反查全类、钉死三组的成员集合，**能抓住日后新加的第 N 个方法**。 + +⚠️ **`100503` 在测试服上一次都没有触发过**——不是「测过、不会触发」，是**没测**。 + +--- + +## 十、相关文档 + +- 关联 Issue: [wx/HL#7980](https://git.1814.love:8443/wx/HL/issues/7980)（AC-7） +- 关联 PR: [wx/HL#8049](https://git.1814.love:8443/wx/HL/pulls/8049) +- 相关（另一组锁，非本文档范围）: `changelogs-v2/2026-09/20_7980_发票签发重传重开三写口补同一把锁新增100503冲突码触达C端-修改接口-管理后台.md`（PR #8043，`order-invoice:issue` 锁） + +## 关联 / 联系人 + +### 链接 + +- **Issue**: [#7980](https://git.1814.love:8443/wx/HL/issues/7980) +- **PR**: [#8049](https://git.1814.love:8443/wx/HL/pulls/8049) +- **Merge commit**: [43c53c4c9](https://git.1814.love:8443/wx/HL/commit/43c53c4c9)（合并后回填，backend_status 待部署后翻转） + +### 联系人 + +- **后端负责人**: @wx diff --git a/changelogs-v2/2026-09/20_7980_配房工作台七个写口补齐需求级互斥新增100503可重试冲突码-修改接口-管理后台.md b/changelogs-v2/2026-09/20_7980_配房工作台七个写口补齐需求级互斥新增100503可重试冲突码-修改接口-管理后台.md new file mode 100644 index 00000000..9601dc52 --- /dev/null +++ b/changelogs-v2/2026-09/20_7980_配房工作台七个写口补齐需求级互斥新增100503可重试冲突码-修改接口-管理后台.md @@ -0,0 +1,762 @@ +--- +schema: "hl-changelog/v2" +ticket: "7980" +title: "配房工作台七个写口（提交/单日确认/位置调整/清空全部/清空当天/转单/释放）补同一把 @Lock4j name，新增可重试冲突码 100503（接口路径/字段零增删）" +consumer: "admin" +author: "wx(GIT)" +change_type: "修改接口" +backend_status: "deployed" +gateway_status: "not_required" +frontend_status: "pending" +frontend_owner: "mmg" +frontend_ref: "" +target_release: "" +verified_at: "" +status_note: "PR #8069 已 squash 合并 dev-v3（合并提交 b9738a20f）。2026-09-20 23:24 已部署测试服 hl-order-service-v3：滚动更新两实例，部署前 COMMIT=c35251b07、部署后 COMMIT=ba8aab3ab，8186 与 8086 各 12 秒内起监听。`git merge-base --is-ancestor b9738a20f ba8aab3ab` 返回 ANCESTOR_YES。🔴 并且部署前 `b9738a20f` 确实不在 `c35251b07` 内（同一判据返回 NO），即本次部署是真正的「从不生效到生效」，不是重跑一遍确认。gateway_status=not_required：端点路径/方法零变化，本次与网关路由无关，不是漏验证。🔴 本次未在测试服做功能调用取证，这是有意为之而不是遗漏：这 7 个端点全是写口（`submit` / `confirmDay` / `updatePlacement` / `clearAssignments` / `clearAssignmentsByDay` / `transfer` / `release`），调用它们会真实改动配房行与库存记账，而测试服的房务数据被多个会话共用，`clear` 与 `release` 造成的后果撤不回来——副作用会落在一个不知情的人头上。互斥本身由落库级并发 IT `HouseRequirementWriteLockConcurrencyIT` 覆盖：绿轮 `house_hotel_assignment(active)=[]`、`house_dual_deduction_log(持有中)=[]`，submit 挂起 1109ms、锁键只有一把；变异轮（拆掉 7 处 `name`）留下 1 行孤儿 + 库存未释放，submit 只挂 213ms、两个键且其中一个带方法名。这比任何测试服抓包都更直接。⚠️ `100503` 在测试服上一次都没有触发过——不是「测过、不会触发」，是没测；临界区短不等于永不超时，更长事务/更大载荷/生产数据量下仍可能出现。" +updated_at: "2026-09-20" +base: "dev-v3" +--- + +# order-v3: 配房工作台七个写口补同一把 @Lock4j name，新增可重试冲突码 100503 + +> **存放目录**: +> - 一期(v2,无 `order-v3` 标签的工单)→ `changelogs/{YYYY-MM}/` +> - 二期(v3,`order-v3` 标签的工单)→ `changelogs-v2/{YYYY-MM}/` +> +> **服务**: hl-order-service-v3 +> **PR**: #8069 +> **Issue**: #7980（AC-5） +> **日期**: 2026-09-20 +> **影响范围**: 管理后台「房务配房工作台」§2.2 提交配房、单日确认、§2.3b 位置调整、§2.4b/§2.4c 清空配房、§1.3 转单、§1.4 释放共 7 个写操作，在**并发命中同一需求**时的失败分支 + +--- + +## ⚠️ 关键变化（非必须,本版与上版行为不同 / 纠错 / 撤销时必写） + +- 这 7 个写口分散在 `HouseAssignmentAdminController`（5 个）与 `HouseGrabAdminController`（2 个）两个类上，`@Lock4j` 的 `keys` 逐字相同（`'house:req:write:' + #requirementId`），代码注释里一直写着「统一需求级写锁 house:req:write:reqId」，但**补 `name` 之前这句话是假的**：lock4j 2.2.7 缺省 `name` 时用「类全限定名 + 方法名」当默认值拼进 Redis 键，7 个方法名不同 ⇒ 拿到的是 **7 把互不相干的锁**，可以互相踩踏（比如 `submit` 还没插完候选，`clearAssignments` 就把它软删了）。 +- 本次给 7 处补上同一个显式 `name = HouseRequirementLockConstants.REQUIREMENT_WRITE_LOCK_NAME`（值 `"house:req:write"`），互斥才真正生效。**没有新增接口、没有增删字段**，唯一契约变化是新增一个可能返回的失败码 **`100503`**，**HTTP 状态码仍是 200**。 +- 🔴 **本 PR 覆盖边界（避免误读成「房务写已全部串行」）**：同一张 `house_hotel_assignment` 表上仍有三类写口**不在这把锁内**，本次未处理：① `HouseAssignmentAdminController` 的 `update`（`PUT /v3/admin/order/assignments/{id}`）与 `delete`（`DELETE /v3/admin/order/assignments/{id}`）完全无锁；② `HouseGroupBatchAssignmentService`（团期整团重配）走另一个键空间；③ 订单域直写路径。这三类不在本文档「二、变更接口清单」内，行为未变。 +- 🔴 **本组已确认无 mp / C 端**：7 个 Service 方法各只有一个调用方（对应各自的 admin Controller 方法），路径全部落在 `/v3/admin/order/...`，新增的 `100503` 只会到达 hl-ui 房务工作台，不经过小程序。 + +--- + +## 一、背景（选填） + +`HouseHotelAssignmentDO` **确有** `@Version` 字段（`:116`），项目也**确实注册了** `OptimisticLockerInnerInterceptor`（`SlowSqlConfiguration:40`），但对这 7 个写口的并发场景乐观锁**不生效**，原因有三层：① `submit`/`clear*` 走的是 `insert`/`deleteById`，两者都绕过 `@Version`（乐观锁只拦 `updateById`）；② `confirmDay` 的最小补丁 SQL 不携带版本字段；③ `submit` 内部的 `updateById` 调用**从不检查返回值**，版本冲突会静默退化成空操作。三层叠加下唯一能兜住这组写口互斥的就是这把分布式锁，而它在补 `name` 之前并不生效。 + +变异证明（管理者第一手复跑）：拆掉 7 处 `name` 后，集成测试 `submitParallelClearAssignments_leavesNoOrphanRowNorHeldInventory` 转红——`submit` 还没插完候选，`clearAssignments` 已把该需求下的旧配房行软删，两者没有被同一把锁挡住。落库读数对照： + +| 维度 | 变异轮（缺 name，坏形态） | 复绿轮（补齐 name） | +|------|------|------| +| `house_hotel_assignment(active)` 孤儿行 | 1 行孤儿 | `[]`（无孤儿） | +| `house_dual_deduction_log(持有中)` | 库存未释放 | `[]`（已释放） | +| `submit` 实际挂起耗时 | 213ms | 1109ms（真正排队等锁） | +| 在途可见锁键数 | 2 把（其中一把带方法名） | 1 把 | + +--- + +## 二、变更接口清单 + +| # | 接口 | 方法 | 路径 | 变更类型 | 说明 | +|---|------|------|------|----------|------| +| 1 | 提交配房方案 | POST | `/v3/admin/order/hotel-requirements/{requirementId}/assignments` | 新增可能返回的错误码 | 抢锁超时返 100503（原接口/字段不变） | +| 2 | 单日确认配房 | POST | `/v3/admin/order/hotel-requirements/{requirementId}/assignments/days/{dayNumber}/confirm` | 新增可能返回的错误码 | 与 §1 共用同一把需求级锁 | +| 3 | 调整单条配房位置与资源 | PUT | `/v3/admin/order/hotel-requirements/{requirementId}/assignments/{id}/placement` | 新增可能返回的错误码 | 与 §1 共用同一把需求级锁 | +| 4 | 清空当前需求全部配房 | DELETE | `/v3/admin/order/hotel-requirements/{requirementId}/assignments` | 新增可能返回的错误码 | 与 §1 共用同一把需求级锁 | +| 5 | 清空当前需求某一天配房 | DELETE | `/v3/admin/order/hotel-requirements/{requirementId}/assignments/days/{dayNumber}` | 新增可能返回的错误码 | 与 §1 共用同一把需求级锁 | +| 6 | 转单 / 超管强制指派 | POST | `/v3/admin/order/hotel-requirements/{requirementId}/transfer` | 新增可能返回的错误码 | 与 §1 共用同一把需求级锁 | +| 7 | 释放回抢单池 | POST | `/v3/admin/order/hotel-requirements/{requirementId}/release` | 新增可能返回的错误码 | 与 §1 共用同一把需求级锁 | + +--- + +## 三、接口详情 + +### 1. 提交配房方案 `POST /v3/admin/order/hotel-requirements/{requirementId}/assignments` + +**VO**: `AssignmentSubmitReqVO → AssignmentSubmitRespVO` + +#### 使用场景 + +房务在配房工作台对某个已抢到手的住宿需求批量提交候选方案（一次可提交多晚 × 多家庭，每项对应一晚一组房间）。本次改动不涉及本接口的入参/出参字段，只新增一条「被本组另外 6 个写口占用同一把需求级锁」的失败分支。 + +#### 入参 + +路径参数 `requirementId`（住宿需求 ID）+ Body： + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| requirementId | Path | Long | ✅ | - | 需求 ID（逻辑 FK → order_hotel_requirement.id） | +| items | Body | List\ | ✅ | `@NotEmpty` | 配房项列表（批量），每项一晚一组房间 | +| items[].dayNumber | Body | Integer | ✅ | ≥1 | 第几天（1=Day1） | +| items[].hotelId | Body | Long | ✅ | - | 酒店 ID | +| items[].roomTypeId | Body | Long | ✅ | - | 房型 ID，须归属该 hotelId（否则 808112） | +| items[].roomCategory | Body | String | ✅ | `@NotBlank` | 房型字典 code | +| items[].roomCount | Body | Integer | ✅ | ≥1 | 间数 | +| items[].protoPrice | Body | BigDecimal | - | ≥0 | 协议价快照，不传按当日资源协议价兜底 | +| items[].settlementPrice | Body | BigDecimal | - | ≥0 | 结算价快照，不传按当日资源结算价兜底，再兜底协议价 | +| items[].settleType | Body | String | - | `cash\|sign\|company` | 支付方式快照，不传取酒店资源配置 | +| items[].deductInventory | Body | Boolean | ✅ | - | 是否扣减资源酒店房型库存 | +| items[].syncProtocolPrice | Body | Boolean | - | 默认 false | 是否把协议价同步写回 resource 价格日历 | +| items[].syncSettlementPrice | Body | Boolean | - | 默认 false | 是否把结算价同步写回 resource 价格日历 | +| items[].syncSettleType | Body | Boolean | - | 默认 false | 是否把支付方式同步写回酒店资源 | +| items[].remark | Body | String | - | - | 备注 | +| items[].replaceReason | Body | String | - | ≤256 字符 | 替换原因（仅该天旧行被本项替换时落库） | + +#### 出参 `Result` + +| 字段 | 类型 | 说明 | +|------|------|------| +| successCount | Integer | 成功条数 | +| failCount | Integer | 失败条数 | +| items | List\ | 每条配房结果 | +| items[].dayNumber | Integer | 第几天 | +| items[].assignmentId | String（雪花，序列化为字符串） | 配房 ID | +| items[].arrange | String | 配房状态：pending / waiting / confirmed / problem | +| items[].deductInventory | Boolean | 本次配房是否扣减了资源库存 | + +#### 请求示例 + +```json +{ + "items": [ + { + "dayNumber": 1, + "hotelId": 200001, + "roomTypeId": 300001, + "roomCategory": "STANDARD", + "roomCount": 2, + "protoPrice": 320.00, + "settlementPrice": 300.00, + "settleType": "cash", + "deductInventory": true, + "syncProtocolPrice": false, + "syncSettlementPrice": false, + "syncSettleType": false, + "remark": "已电话确认" + } + ] +} +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "data": { + "successCount": 1, + "failCount": 0, + "items": [ + { "dayNumber": 1, "assignmentId": "70200", "arrange": "waiting", "deductInventory": true } + ] + }, + "success": true +} +``` + +#### 空数据 / 降级响应 + +本接口无「空数据」概念（成功恒返回统计 + 明细数组，items 不会为空数组，因为入参 items 本身要求非空）。无降级路径。 + +#### 错误响应 + +```json +{ "code": 100503, "message": "资源被占用,请稍后重试", "data": null, "success": false } +``` + +| code | 触发条件 | +|------|----------| +| 400 | 参数校验失败（items 为空等） | +| 401 | 未登录（网关拦截） | +| 808090/808091 | 未登录或非房务角色 / 房务组长只读监督，无权提交配房 | +| 808100 | 需求不存在 | +| 808113 | 需求已作废（is_active=0），不可提交配房 | +| 808110 | 需求不属于当前用户（被他人抢到） | +| 808116 | 需求未被任何人抢单，须先抢单再配房 | +| 808119 | 订单已取消或异常处置中，不可新增配房 | +| 808102 | 任一 item 的 dayNumber 超出该需求应配晚数 | +| 808111 | items 为空（禁止保存空方案清空已有配置） | +| 808112 | 房型不属于所选酒店 | +| 808117 | 同一次提交内同天同酒店同房型重复 | +| 808124 | 是否扣减资源库存（deductInventory）必选 | +| 589552/589553 | 团期子订单：团期尚未成团 / 班期尚未建团（未成团不得占用资源） | +| 100502 | 3 秒幂等窗口内重复提交（键=requirementId） | +| **100503（本次新增）** | 抢锁等待超过 3 秒（本组另外 6 个写口之一正持有 `house:req:write` 锁），**可重试** | + +#### 业务边界 + +- 幂等：`@Idempotent` 3 秒窗口（键=requirementId），窗口内重复提交直接拒绝，不会走到锁竞争这一步。 +- 抢锁失败（100503）时该次请求**未进入方法体，零写入**——`@HouseWriteGuarded` 拦截器先于 `@Lock4j`/`@Idempotent` 执行角色门（先拦非房务角色），角色门通过后 `@Lock4j` 拿不到锁直接抛异常，业务代码一行不会执行，不产生任何 SQL。 +- `deductInventory=true` 的项在提交阶段即占用库存（防超卖），但计入「已配房」仍以 `CONFIRMED` 为准（`INQUIRING` 不计入 finalize 闸口判定）。 +- 房型归属越权校验在任何插入/扣减之前执行：`roomTypeId` 不属于所传 `hotelId` 时整个 submit 拒绝，不部分写入。 +- 老数据兼容：本次不涉及字段增删，存量配房记录无需迁移。 + +--- + +### 2. 单日确认配房 `POST /v3/admin/order/hotel-requirements/{requirementId}/assignments/days/{dayNumber}/confirm` + +**VO**: `AssignmentDayConfirmReqVO（请求体可选，可为 null） → Void` + +#### 使用场景 + +房务对某一天点「确认」：从该天询房中（INQUIRING）候选行里挑选要保留的（可多家），被挑中的翻 `CONFIRMED` 并此刻扣减库存，落选的软删并按需还原库存。本次改动不涉及入参/出参字段，只新增一条抢锁超时的失败分支。 + +#### 入参 + +路径参数 + 可选 Body： + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| requirementId | Path | Long | ✅ | - | 需求 ID | +| dayNumber | Path | Integer | ✅ | ≥1 | 第几天（从 1 开始） | +| keepAssignmentIds | Body | List\（JSON 传字符串数组） | - | 省略/空=该天全部候选都保留确认 | 该天要保留并确认的配房行 ID 列表（可多家） | + +#### 出参 `Result` + +| 字段 | 类型 | 说明 | +|------|------|------| +| data | null | 无返回数据，`Result.data` 恒为 `null` | + +#### 请求示例 + +```json +{ "keepAssignmentIds": ["1234567890"] } +``` + +（`keepAssignmentIds` 省略或不传 body 时按「该天全部候选都保留」处理。） + +#### 响应示例 + +```json +{ "code": 200, "message": "成功", "data": null, "success": true } +``` + +#### 空数据 / 降级响应 + +本接口无「空数据」概念（成功恒返回 `data: null`），无降级路径。 + +#### 错误响应 + +```json +{ "code": 100503, "message": "资源被占用,请稍后重试", "data": null, "success": false } +``` + +| code | 触发条件 | +|------|----------| +| 401 | 未登录（网关拦截） | +| 808090/808091 | 未登录或非房务角色 / 房务组长只读监督，无权确认 | +| 808100 | 需求不存在 | +| 808113 | 需求已作废 | +| 808110 | 需求不属于当前用户 | +| 808116 | 需求未被任何人抢单 | +| 808119 | 订单已取消或异常处置中 | +| 808102 | dayNumber 超出该需求应配晚数 | +| 808118 | 该天无询房中（INQUIRING）候选可确认 | +| 808123 | `keepAssignmentIds` 中存在不属于该天候选集的 ID（可能配房已更新，需刷新后重试） | +| 589552/589553 | 团期子订单未成团 / 班期未建团 | +| 100502 | 3 秒幂等窗口内重复确认（键=requirementId+dayNumber） | +| **100503（本次新增）** | 抢锁等待超过 3 秒（与本组另外 6 个写口共用同一把 `house:req:write` 锁），**可重试** | + +#### 业务边界 + +- 幂等：`@Idempotent` 3 秒窗口（键=requirementId+dayNumber）。 +- 抢锁失败（100503）时零写入，逻辑同 §1；候选行状态不会被部分翻转。 +- 单日确认不再重复扣库存——扣减动作已在 submit 阶段发生，本接口只做状态翻转（保留→CONFIRMED）与落选软删/还原。 +- 老数据兼容：无字段变化。 + +--- + +### 3. 调整单条配房位置与资源 `PUT /v3/admin/order/hotel-requirements/{requirementId}/assignments/{id}/placement` + +**VO**: `AssignmentPlacementUpdateReqVO → Void` + +#### 使用场景 + +房务对已存在的单条配房行原子调整目标晚次、酒店、房型和房间数（前端只传目标 dayNumber，入住日期由后端按当前订单行程推导）。涉及扣库存时先预占目标库存，本地事务提交后再释放原库存。本次改动不涉及入参/出参字段，只新增一条抢锁超时的失败分支。 + +#### 入参 + +路径参数 + Body： + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| requirementId | Path | Long | ✅ | - | 当前生效住宿需求 ID | +| id | Path | Long | ✅ | - | house_hotel_assignment 主键 | +| dayNumber | Body | Integer | ✅ | ≥1 | 目标晚次（1=第1晚） | +| hotelId | Body | Long | ✅ | - | 目标酒店 ID | +| roomTypeId | Body | Long | ✅ | - | 目标房型 ID，须归属该 hotelId | +| roomCategory | Body | String | ✅ | `@NotBlank` | 目标房型字典 code | +| roomCount | Body | Integer | ✅ | ≥1 | 目标房间数 | +| protoPrice | Body | BigDecimal | - | ≥0 | 协议价快照，不传按目标房型和目标入住日读取资源价格日历 | +| settlementPrice | Body | BigDecimal | - | ≥0 | 结算价快照，不传同上兜底 | +| settleType | Body | String | - | `cash\|sign\|company` | 支付方式快照 | +| deductInventory | Body | Boolean | ✅ | - | 是否扣减资源库存 | +| syncProtocolPrice | Body | Boolean | - | 默认 false | 是否同步协议价到目标房型目标日期价格日历 | +| syncSettlementPrice | Body | Boolean | - | 默认 false | 是否同步结算价 | +| syncSettleType | Body | Boolean | - | 默认 false | 是否同步支付方式到目标酒店资源 | +| remark | Body | String | - | - | 备注，不传保留原备注 | + +#### 出参 `Result` + +| 字段 | 类型 | 说明 | +|------|------|------| +| data | null | 无返回数据 | + +#### 请求示例 + +```json +{ + "dayNumber": 2, + "hotelId": 200001, + "roomTypeId": 300001, + "roomCategory": "STANDARD", + "roomCount": 2, + "protoPrice": 320.00, + "settlementPrice": 280.00, + "settleType": "cash", + "deductInventory": true, + "syncProtocolPrice": false, + "syncSettlementPrice": false, + "syncSettleType": false, + "remark": "改期后重新询房" +} +``` + +#### 响应示例 + +```json +{ "code": 200, "message": "成功", "data": null, "success": true } +``` + +#### 空数据 / 降级响应 + +本接口无「空数据」概念，无降级路径。 + +#### 错误响应 + +```json +{ "code": 100503, "message": "资源被占用,请稍后重试", "data": null, "success": false } +``` + +| code | 触发条件 | +|------|----------| +| 401 | 未登录（网关拦截） | +| 808090/808091 | 角色门 | +| 808124 | deductInventory 未传 | +| 808120 | 配房行不存在，或 requirementId 与该行实际归属需求不一致 | +| 808100/808113 | 需求不存在 / 已作废 | +| 808110/808116 | 需求不属于当前用户 / 未被抢单 | +| 808119 | 订单已取消或异常处置中 | +| 808102 | 目标 dayNumber 超出应配晚数 | +| 808112 | 目标房型不属于目标酒店 | +| 808126 | 涉及库存迁移但原配房缺少可释放的持有日志（禁止继续迁移造成双扣） | +| 589552/589553 | 团期子订单未成团 / 班期未建团 | +| **100503（本次新增）** | 抢锁等待超过 3 秒（与本组另外 6 个写口共用同一把 `house:req:write` 锁），**可重试** | + +#### 业务边界 + +- 本接口无 `@Idempotent`，仅靠 `@Lock4j` 串行化 + 库存迁移前置校验去重。 +- 事务外编排：目标库存先预占并标 PENDING，本地事务内原子更新配房与扣减日志；任一阶段失败精确释放新预占，原配房与原库存保持不变。抢锁失败（100503）属于最早期失败，同样零写入。 +- 改期前旧日期的只读配房行不可经本接口调整（会抛只读相关错误码，非本次新增范围）。 +- 老数据兼容：无字段变化。 + +--- + +### 4. 清空当前需求全部配房 `DELETE /v3/admin/order/hotel-requirements/{requirementId}/assignments` + +**VO**: `无 ReqVO（纯路径参数，无请求体） → AssignmentClearRespVO` + +#### 使用场景 + +房务在已配房后先清空当前需求下全部 active 配房行（软删 + 按需释放库存），用于驳回需求或重新配房。不释放抢单人、不回抢单池。本次改动不涉及出参字段，只新增一条抢锁超时的失败分支。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| requirementId | Path | Long | ✅ | - | 需求 ID | + +#### 出参 `Result` + +| 字段 | 类型 | 说明 | +|------|------|------| +| clearedCount | Integer | 本次清空的 active 配房行数 | + +#### 请求示例 + +```http +DELETE /v3/admin/order/hotel-requirements/1234567890123456789/assignments +Authorization: Bearer {token} +``` + +#### 响应示例 + +```json +{ "code": 200, "message": "成功", "data": { "clearedCount": 2 }, "success": true } +``` + +#### 空数据 / 降级响应 + +该需求下没有任何 active 配房行时同样返回 200 成功，`clearedCount=0`，不报错。无降级路径。 + +#### 错误响应 + +```json +{ "code": 100503, "message": "资源被占用,请稍后重试", "data": null, "success": false } +``` + +| code | 触发条件 | +|------|----------| +| 401 | 未登录（网关拦截） | +| 808090/808091 | 角色门 | +| 808100/808113 | 需求不存在 / 已作废 | +| 808110/808116 | 需求不属于当前用户 / 未被抢单 | +| 589552/589553 | 团期子订单未成团 / 班期未建团 | +| **100503（本次新增）** | 抢锁等待超过 3 秒（与本组另外 6 个写口共用同一把 `house:req:write` 锁），**可重试** | + +#### 业务边界 + +- 无 `@Idempotent`，仅靠 `@Lock4j` 串行化。 +- 抢锁失败（100503）时零写入，`clearedCount` 不会出现"清了一半"的中间态。 +- 只清空当前生效需求下 active 配房行，不影响历史已作废需求下的行。 +- 老数据兼容：无字段变化。 + +--- + +### 5. 清空当前需求某一天配房 `DELETE /v3/admin/order/hotel-requirements/{requirementId}/assignments/days/{dayNumber}` + +**VO**: `无 ReqVO（纯路径参数，无请求体） → AssignmentClearRespVO` + +#### 使用场景 + +房务在每个行程日行内点「清空」，只清空该天配房，不影响其他天、不释放抢单人、不回抢单池。本次改动不涉及出参字段，只新增一条抢锁超时的失败分支。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| requirementId | Path | Long | ✅ | - | 需求 ID | +| dayNumber | Path | Integer | ✅ | ≥1 | 第几天 | + +#### 出参 `Result` + +| 字段 | 类型 | 说明 | +|------|------|------| +| clearedCount | Integer | 本次清空的 active 配房行数 | + +#### 请求示例 + +```http +DELETE /v3/admin/order/hotel-requirements/1234567890123456789/assignments/days/2 +Authorization: Bearer {token} +``` + +#### 响应示例 + +```json +{ "code": 200, "message": "成功", "data": { "clearedCount": 1 }, "success": true } +``` + +#### 空数据 / 降级响应 + +该天没有 active 配房行时同样返回 200 成功，`clearedCount=0`。无降级路径。 + +#### 错误响应 + +```json +{ "code": 100503, "message": "资源被占用,请稍后重试", "data": null, "success": false } +``` + +| code | 触发条件 | +|------|----------| +| 401 | 未登录（网关拦截） | +| 808090/808091 | 角色门 | +| 808102 | dayNumber < 1 | +| 808100/808113 | 需求不存在 / 已作废 | +| 808110/808116 | 需求不属于当前用户 / 未被抢单 | +| 589552/589553 | 团期子订单未成团 / 班期未建团 | +| **100503（本次新增）** | 抢锁等待超过 3 秒（与本组另外 6 个写口共用同一把 `house:req:write` 锁），**可重试** | + +#### 业务边界 + +- 无 `@Idempotent`，仅靠 `@Lock4j` 串行化。 +- 抢锁失败零写入，逻辑同 §4；仅影响本 dayNumber 行，不波及其他天。 +- 老数据兼容：无字段变化。 + +--- + +### 6. 转单 / 超管强制指派 `POST /v3/admin/order/hotel-requirements/{requirementId}/transfer` + +**VO**: `HouseTransferReqVO → Void` + +#### 使用场景 + +普通房务把手上的需求转给另一位房务，或超管强制指派。后端按 JWT 身份分流：普通房务必须是当前 claimer，`reason` 可选；超管不要求是当前 claimer，`reason` 须 ≥10 字。**只能转「已经被某个房务抢到」的需求**（`status=PROCESSING`），未认领的需求恒返 808001；团期子订单永远到不了 `PROCESSING`（逐户抢单对团单无条件拒），归属改由整团认领端点建立，本接口对团单不适用。本次改动不涉及入参/出参字段，只新增一条抢锁超时的失败分支。 + +#### 入参 + +路径参数 + Body： + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| requirementId | Path | Long | ✅ | - | 需求 ID | +| toUserId | Body | Long（JSON 传字符串） | ✅ | `@NotNull` | 接收人房务 ID | +| reason | Body | String | - | ≤200 字符；超管指派须 ≥10 字（Service 层校验） | 转单/指派原因 | +| skipUpperLimit | Body | Boolean | - | 默认 false，历史字段（单量上限已下线） | 仅审计留痕用，不影响结果 | + +#### 出参 `Result` + +| 字段 | 类型 | 说明 | +|------|------|------| +| data | null | 无返回数据 | + +#### 请求示例 + +```json +{ "toUserId": "1003", "reason": "我今天临时请假，转给小图接手" } +``` + +#### 响应示例 + +```json +{ "code": 200, "message": "成功", "data": null, "success": true } +``` + +#### 空数据 / 降级响应 + +本接口无「空数据」概念，无降级路径。 + +#### 错误响应 + +```json +{ "code": 100503, "message": "资源被占用,请稍后重试", "data": null, "success": false } +``` + +| code | 触发条件 | +|------|----------| +| 401 | 未登录（网关拦截） | +| 808090/808091 | 角色门 | +| 808001 | 需求未认领（status≠PROCESSING），普通转单/超管指派均不适用 | +| 808002 | 需求已不存在（已取消/已配完） | +| 808010 | 普通房务调用且非当前 claimer | +| 808011 | 接收人不存在或已离职 | +| 808012 | 转单/指派原因不能为空（普通转单在需要时） | +| 808013 | 一单转单次数达上限（3 次，仅普通房务触发） | +| 808014 | 接收人就是当前归属人 | +| 808016 | 超管指派原因长度不足 10 字 | +| **100503（本次新增）** | 抢锁等待超过 3 秒（与本组另外 6 个写口共用同一把 `house:req:write` 锁），**可重试** | + +#### 业务边界 + +- 无 `@Idempotent`，仅靠 `@Lock4j` 串行化，与 submit/confirmDay/release 互斥（防转单改 claimer 与配房写口并发，授权过期仍写）。 +- 抢锁失败零写入，claimer 不会被部分改写。 +- 底层 CAS 前置是 `status='PROCESSING'`，该状态只由抢单端点写入；团期子订单永远到不了这个状态，需改用团级整团认领入口。 +- 老数据兼容：无字段变化。 + +--- + +### 7. 释放回抢单池 `POST /v3/admin/order/hotel-requirements/{requirementId}/release` + +**VO**: `HouseReleaseReqVO（请求体可选） → Void` + +#### 使用场景 + +房务把手上的需求释放回抢单池（例如客人改行程暂时无法配房）。已有 `CONFIRMED` 配房时禁止释放（须先删除配房）。本次改动不涉及入参/出参字段，只新增一条抢锁超时的失败分支。 + +#### 入参 + +路径参数 + 可选 Body： + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| requirementId | Path | Long | ✅ | - | 需求 ID | +| reason | Body | String | - | ≤200 字符 | 释放原因，前端「确认释放」弹窗可能整个不传 body | + +#### 出参 `Result` + +| 字段 | 类型 | 说明 | +|------|------|------| +| data | null | 无返回数据 | + +#### 请求示例 + +```json +{ "reason": "客人改行程,暂时无法配房" } +``` + +（`reason` 及整个请求体均可省略。） + +#### 响应示例 + +```json +{ "code": 200, "message": "成功", "data": null, "success": true } +``` + +#### 空数据 / 降级响应 + +本接口无「空数据」概念，无降级路径。 + +#### 错误响应 + +```json +{ "code": 100503, "message": "资源被占用,请稍后重试", "data": null, "success": false } +``` + +| code | 触发条件 | +|------|----------| +| 401 | 未登录（网关拦截） | +| 808090/808091 | 角色门 | +| 808020 | 需求不属于当前用户 | +| 808021 | 已有 CONFIRMED 配房，无法释放（须先删除配房） | +| **100503（本次新增）** | 抢锁等待超过 3 秒（与本组另外 6 个写口共用同一把 `house:req:write` 锁），**可重试** | + +#### 业务边界 + +- 无 `@Idempotent`，仅靠 `@Lock4j` 串行化，与 confirmDay/submit/transfer 互斥（根治 release 的 countConfirmed 检查与 confirmDay 插 CONFIRMED 行的竞态）。 +- 抢锁失败零写入，claimer 字段不会被部分清空。 +- 释放后写 `op_type=RELEASE` 留痕（不受本次改动影响）。 +- 老数据兼容：无字段变化。 + +--- + +## 四、契约约束与正确调用方式（接口类必写） + +> 本节只写**后端接受/拒绝 payload 的规则**,不写 UI 渲染建议。 + +### 并发冲突（100503）的正确处理方式 + +7 个写口本次开始**真正共用同一把需求级锁**：同一 `requirementId` 上任一时刻只有一个能执行，其余排队等待，等待超过 3 秒（`acquireTimeout`，本组 `@Lock4j` 均未显式设置，取 lock4j-core 注解默认值 3000ms）直接返回失败，不会无限排队。 + +| 场景 | 响应 | +|------|------| +| ✅ 单个请求，无并发 | 200 + 正常业务结果 | +| ✅ 同需求两个请求先后到达，第二个在 3 秒内轮到锁 | 两个都 200（第二个排队等待，非立即失败） | +| ❌ 同需求两个请求并发，第二个等待超过 3 秒未抢到锁 | `{ "code": 100503, "message": "资源被占用,请稍后重试", "success": false }`，**HTTP 状态码仍是 200** | +| ✅ 不同 requirementId 并发 | 互不影响，各自独立加锁 | + +**前端必须做的事**：判断响应体 `code === 100503`（不是判 HTTP 状态码），命中时提示"另一个配房操作正在进行，请稍后重试"并允许用户重新提交；**不要**当作系统异常、**不要**静默吞掉不提示。 + +### 角色门与锁/幂等的执行顺序 + +`@HouseWriteGuarded` 拦截器（`HandlerInterceptor.preHandle`）执行在所有 Controller 方法级 AOP（`@Idempotent`/`@Lock4j`）**之前**——非房务角色（如组长）会先被 808090/808091 拒绝，不会消耗幂等令牌或进入锁排队；只有通过角色门的合法请求才会走到本次新增的 100503 分支。 + +--- + +## 五、数据库行为（涉及写操作时必写） + +本次不改变任何一次**成功**写操作实际写入的行数或内容——7 个端点各自原有的写入逻辑（insert 候选行 / 状态翻转 / 软删 / 库存记账）逐字节不变。变化的只是"谁能在同一时刻对同一需求执行写入"： + +| 维度 | 改动前 | 改动后 | +|------|--------|--------| +| 7 个写口是否互斥（同 requirementId） | 否（各自持独立锁，可并发） | 是（同一把锁，串行执行） | +| 抢锁失败时是否有部分写入 | N/A（此前不会因锁而失败） | 否，零写入（`@Lock4j` 方法级环绕拦截，拿不到锁直接抛异常，业务方法体不会被调用，不产生任何 SQL） | +| `submit ∥ clearAssignments` 并发结果（变异证明实测） | 可能留 1 行孤儿配房 + 库存持有日志不释放 | 干净排队，无孤儿行、无未释放库存 | + +--- + +## 六、边界行为 + +- 未登录 → 401（网关拦截） +- 非房务角色 / 房务组长只读监督 → 808090/808091（`@HouseWriteGuarded` 拦截器先于锁/幂等执行） +- 需求不存在/已作废/未认领/不属于当前用户 → 808100/808113/808116/808110（各端点适用情况见上） +- 团期子订单未成团 → 589552/589553（未成团不得占用资源） +- **抢锁超时（本次新增）→ 100503，HTTP 200，可重试，零写入** +- 幂等窗口内重复提交（submit/confirmDay，请求相同）→ 100502，与本次改动无关，行为不变 +- 老数据兼容：本次不涉及字段增删，存量数据无需迁移 + +--- + +## 六.5、枚举 / 数据字典（接口出现枚举时必写） + +以下枚举在本组接口中均**未变化**，仅为方便前端自包含联调随本次改动一并列出。 + +### settleType（支付方式，出现于 §1/§3） + +**所属字段**: `items[].settleType` / `settleType` | **类型**: `String`（正则约束 `cash|sign|company`） + +| 值 | 中文 | 说明 | +|----|------|------| +| `cash` | 现付 | 结算方式，不传取酒店资源配置 | +| `sign` | 签单 | 结算方式 | +| `company` | 公司结 | 结算方式 | + +### arrange（配房状态，出现于 §1 出参 `items[].arrange`） + +**所属字段**: `AssignmentSubmitRespVO.Item.arrange` | **类型**: `String` + +| 值 | 中文 | 说明 | +|----|------|------| +| `pending` | 待处理 | 配房行初始态 | +| `waiting` | 询房中 | 对应库内 `confirm_status=INQUIRING` | +| `confirmed` | 已确认 | 对应库内 `confirm_status=CONFIRMED` | +| `problem` | 异常 | 配房异常 | + +## 六.6、修改前后对比（修改/删除类接口必写，新增跳过） + +### 字段级对比 + +| 字段 | 改前 | 改后 | +|------|------|------| +| （无）| 7 个接口的请求字段、响应字段逐字节不变 | 同左 | + +### 行为级对比 + +| 行为 | 改前 | 改后 | +|------|------|------| +| 7 个写口同需求并发时 | 各自持独立锁，可同时执行（注释宣称"统一需求级写锁"，实际不成立） | 同一把锁，串行执行，互斥真正生效 | +| `submit ∥ clearAssignments`（变异证明实测） | 可留 1 行孤儿配房 + 库存持有日志不释放 | 干净排队，无孤儿行 | +| 抢锁失败的响应 | 不存在这条路径 | 路径真实存在（返回 100503，HTTP 200，业务失败，可重试）；本次改动未部署测试服，无实测触发频率数据 | +| 接口文档"7 个写口全互斥"这句话 | 写在代码注释里但**不成立** | 写在代码注释里且**成立** | +| 请求/响应字段、既有业务错误码 | 不变 | 不变 | + +## 六.7、影响评估（修改/删除类必写） + +- **是否破坏向后兼容**: 否——不改字段、不改既有错误码语义；但**新增了一条此前不存在的失败路径**（100503），前端若没有处理未知业务码的兜底逻辑，可能会把这次失败展示成不友好的提示（而不是"请重试"）。 +- **前端是否必须同步上线**: 建议同步（识别 `code=100503` 并提示可重试），但**触发频率本文档未做任何测试服实测**，无法给出"高频/低频"的判断依据，不可援引本工单另外两份（fleet 价格日历、发票签发）测试服实测的"频率极低"结论——那两份是各自独立测量的结果，机制相同不代表频率相同（本组是需求级锁，锁粒度 = 单个住宿需求，与价格日历/发票的锁粒度不同）。 +- **前端 workaround 清理点**: 无（本次是新增失败路径，不是清理旧 workaround）。 + +## 七、不影响范围（显式声明, 帮前端/QA 缩小排查面） + +- **仅影响**: 房务配房工作台上述 7 个写操作，抢锁失败时的响应体 +- **零影响**: + - `update`（`PUT /v3/admin/order/assignments/{id}`）/ `delete`（`DELETE /v3/admin/order/assignments/{id}`）——本次未处理，仍无锁 + - §2.1 候选源查询（`GET .../candidates`）、§2.5 房间分配查询/写入、§1.1/§1.2/§1.5 抢单池列表/抢单/我的接单 + - §2.7 最终确认、回执上传/查询 + - 团期整团重配（`HouseGroupBatchAssignmentService`，走另一个键空间） + - 7 个写口的请求字段、响应字段结构 + - 既有业务错误码（808xxx / 589552 / 589553）的触发条件与文案 + - 幂等拦截（100502）的行为 + - 单个请求在**无并发**时的行为（延迟、返回值、写入内容全部不变） + - hl-gateway 路由配置——7 个端点路径/方法零变化 + +--- + +## 八、测试环境已验证 + +**部署读数（2026-09-20 23:24）**：hl-order-service-v3 滚动更新两实例，部署前 `c35251b07` → 部署后 `ba8aab3ab`，8186 与 8086 各 12 秒内起监听，`deploy-backend.sh` 报 `rolling deploy complete`。`git merge-base --is-ancestor b9738a20f ba8aab3ab` 返回 **ANCESTOR_YES**。🔴 **并且部署前 `b9738a20f` 确实不在 `c35251b07` 内**（同一判据返回 NO），即本次部署是真正的「从不生效到生效」，不是重跑一遍确认。 + +🔴 本次**未在测试服做功能调用取证，这是有意为之而不是遗漏**：这 7 个端点全是写口（`submit` / `confirmDay` / `updatePlacement` / `clearAssignments` / `clearAssignmentsByDay` / `transfer` / `release`），调用它们会**真实改动配房行与库存记账**，而测试服的房务数据被多个会话共用，`clear` 与 `release` 造成的后果**撤不回来**——副作用会落在一个不知情的人头上。 + +互斥本身由**落库级并发 IT** `HouseRequirementWriteLockConcurrencyIT` 覆盖：绿轮 `house_hotel_assignment(active)=[]`、`house_dual_deduction_log(持有中)=[]`，submit 挂起 1109ms、锁键只有一把；**变异轮**（拆掉 7 处 `name`）留下 1 行孤儿 + 库存未释放，submit 只挂 213ms、**两个键且其中一个带方法名**。这比任何测试服抓包都更直接。 + +⚠️ **`100503` 在测试服上一次都没有触发过**——不是「测过、不会触发」，是**没测**。 + +--- + +## 十、相关文档 + +- 关联 Issue: [wx/HL#7980](https://git.1814.love:8443/wx/HL/issues/7980)（AC-5） +- 关联 PR: [wx/HL#8069](https://git.1814.love:8443/wx/HL/pulls/8069) + +## 关联 / 联系人 + +### 链接 + +- **Issue**: [#7980](https://git.1814.love:8443/wx/HL/issues/7980) +- **PR**: [#8069](https://git.1814.love:8443/wx/HL/pulls/8069) +- **Merge commit**: [b9738a20f](https://git.1814.love:8443/wx/HL/commit/b9738a20f)（合并后回填，backend_status 待部署后翻转） + +### 联系人 + +- **后端负责人**: @wx