From 74dc7f0ede2fd98f7d27fdf70d4a627198143588 Mon Sep 17 00:00:00 2001
From: API Changelog Bot <changelog@hulalv.com>
Date: Tue, 8 Sep 2026 22:30:06 +0800
Subject: [PATCH] =?UTF-8?q?docs(changelog):=20=E5=8F=91=E5=B8=83=20#7339?=
 =?UTF-8?q?=20=E5=BA=93=E5=AD=98=E5=B9=82=E7=AD=89=E5=A5=91=E7=BA=A6?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 ...ˆ¿æ€�库存幂等与补å�¿è½®æ¬¡-修改接å�£-管ç�†å�Žå�°.md | 321 ++++++++++++++++++
 1 file changed, 321 insertions(+)
 create mode 100644 changelogs-v2/2026-09/08_7339_房�库存幂等与补�轮次-修改接�-管���.md

diff --git a/changelogs-v2/2026-09/08_7339_房�库存幂等与补�轮次-修改接�-管���.md b/changelogs-v2/2026-09/08_7339_房�库存幂等与补�轮次-修改接�-管���.md
new file mode 100644
index 00000000..3318e87f
--- /dev/null
+++ b/changelogs-v2/2026-09/08_7339_房�库存幂等与补�轮次-修改接�-管���.md
@@ -0,0 +1,321 @@
+---
+schema: "hl-changelog/v2"
+ticket: "7339"
+title: "房�库存�作改为请求体幂等契约并引入补�轮次"
+consumer: "internal"
+author: "wx(GIT)"
+change_type: "修改接�"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "not_required"
+frontend_owner: ""
+frontend_ref: ""
+target_release: ""
+verified_at: ""
+status_note: "resource 与 order-v3 已在测试环境按 merge commit 439e53d1e �对�布；内部 Feign�跨实例幂等�补�轮次� Job 已验�"
+updated_at: "2026-09-08"
+base: "dev-v3"
+---
+
+# 房务库存：房�库存幂等与补�轮次
+
+> **�务**: hl-resource-service�hl-order-service-v3
+> **PR**: #7356
+> **Issue**: #7339
+> **日期**: 2026-09-08
+> **影�范围**: order-v3 到 resource 的内部房�扣�/释放 Feign 契约与补�生命周期
+
+---
+
+## ⚠� 关键�化
+
+库存扣�和释放的 `date`�`qty`�`opId` 从 Query �数改为 JSON 请求体，属于�兼容的内部 Feign �更；`hl-resource-service` 与 `hl-order-service-v3` 必须�批�布，�止新旧版本混跑。补��作 ID 必须带轮次；普通�夜释放严格为 `release-{logId}-{rollbackRound}`。
+
+---
+
+## 一�背景
+
+原接�缺少�久化幂等账本，�一业务动作在超时�试�跨实例�放或补��试时�能��改�库存。现在�务端冻结首次请求指纹和首次结果，订�侧用 `rollbackRound` 区分�一�有关系的�新扣�轮次，并�留既有跨夜循环语义。
+
+---
+
+## 二��更接�清�
+
+| # | 接� | 方法 | 路径 | �更类型 | 说明 |
+|---|------|------|------|----------|------|
+| 1 | 扣�房型库存 | POST | `/internal/resource/hotels/{hotelId}/room-types/{roomTypeId}/deduct` | Query 改 JSON Body | 增加�久化幂等�请求指纹与首次结果�放 |
+| 2 | 释放房型库存 | POST | `/internal/resource/hotels/{hotelId}/room-types/{roomTypeId}/release` | Query 改 JSON Body | 按实际已用�下界 CAS 释放，��负数 |
+
+---
+
+## 三�接�详情
+
+### 1. 扣�房型库存 `POST /internal/resource/hotels/{hotelId}/room-types/{roomTypeId}/deduct`
+
+**VO**: `RoomInventoryOpReqDTO -> Result<HouseInventoryOpRespDTO>`
+
+#### 使用场景
+
+order-v3 在�房库存�有时通过内部 Feign 调用。调用方必须为�个生命周期轮次生�稳定且唯一的 `opId`；�一 `opId` 的�试必须��路径�日期�数�和�作类型完全一致。
+
+#### 入�
+
+| 字段 | �置 | 类型 | 必填 | 约� | 说明 |
+|------|------|------|------|------|------|
+| hotelId | Path | Long | ✅ | �空 | 酒店 ID |
+| roomTypeId | Path | Long | ✅ | �空 | 房型 ID |
+| date | Body | LocalDate | ✅ | YYYY-MM-DD | 入�日期 |
+| qty | Body | Integer | ✅ | >= 1 | 扣�数� |
+| opId | Body | String | ✅ | �空，最长 256 | �夜为 `deduct-{idempotencyKey}-{rollbackRound}`；仅多夜追加 `-d{nightIndex}` |
+
+#### 出� `Result<HouseInventoryOpRespDTO>`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| changed | Integer | 首次�作实际改�数� |
+| remain | Integer | 首次�作�的�用库存 |
+| duplicated | Boolean | 是�为已�交首次结果的�放 |
+
+#### 请求示例
+
+```json
+{
+  "date": "2026-09-09",
+  "qty": 2,
+  "opId": "deduct-asgn-123-d1-rt456-h789-0"
+}
+```
+
+#### �应示例
+
+```json
+{
+  "code": 200,
+  "message": "�功",
+  "data": { "changed": 2, "remain": 8, "duplicated": false },
+  "success": true
+}
+```
+
+#### 空数� / �级�应
+
+`hotel.stock.enabled=false` 时�改�库存，但�冻结该 `opId` 的首次�功快照；开关����放�会补执行。
+
+```json
+{ "code": 200, "data": { "changed": 0, "remain": 10, "duplicated": false }, "success": true }
+```
+
+#### 错误�应
+
+```json
+{
+  "code": 310403,
+  "message": "房型库存�足或日历记录缺失",
+  "success": false,
+  "data": null
+}
+```
+
+#### 业务边界
+
+- 仅�许内部鉴�调用，�通过管�端网关暴露。
+- 首次账本写入�库存�化和结果快照属于�一事务。
+- �� `opId` 返回首次 `changed/remain` 且 `duplicated=true`，�会读�当�库存伪造新快照。
+- �一 `opId` 改� `hotelId`�`roomTypeId`�`date`�`qty` 或�作类型会拒�。
+- 库存�足的 `310403` 结果�久化；补充库存��放旧 `opId` �拒�。
+
+### 2. 释放房型库存 `POST /internal/resource/hotels/{hotelId}/room-types/{roomTypeId}/release`
+
+**VO**: `RoomInventoryOpReqDTO -> Result<HouseInventoryOpRespDTO>`
+
+#### 使用场景
+
+order-v3 删除�房��消订���酒店回滚或补� Job 释放房�。普通�夜必须使用 `release-{logId}-{rollbackRound}`；日期�缀�用于�留的多夜循环。
+
+#### 入�
+
+| 字段 | �置 | 类型 | 必填 | 约� | 说明 |
+|------|------|------|------|------|------|
+| hotelId | Path | Long | ✅ | �空 | 酒店 ID |
+| roomTypeId | Path | Long | ✅ | �空 | 房型 ID |
+| date | Body | LocalDate | ✅ | YYYY-MM-DD | 释放日期 |
+| qty | Body | Integer | ✅ | >= 1 | 请求释放上� |
+| opId | Body | String | ✅ | �空，最长 256 | �夜严格为 `release-{logId}-{rollbackRound}`；仅多夜追加 `-d{stayDate}` |
+
+#### 出� `Result<HouseInventoryOpRespDTO>`
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| changed | Integer | 实际释放数�，等于 `min(qty, stockUsed)` |
+| remain | Integer | �作�的�用库存 |
+| duplicated | Boolean | 是�为已�交首次结果的�放 |
+
+#### 请求示例
+
+```json
+{
+  "date": "2026-09-09",
+  "qty": 999,
+  "opId": "release-2097325826075738113-1"
+}
+```
+
+#### �应示例
+
+```json
+{
+  "code": 200,
+  "message": "�功",
+  "data": { "changed": 1, "remain": 10, "duplicated": false },
+  "success": true
+}
+```
+
+#### 空数� / �级�应
+
+当�已用�为 0 时，接��功返回 `changed=0`；�会把已用�更新为负数。
+
+```json
+{ "code": 200, "data": { "changed": 0, "remain": 10, "duplicated": false }, "success": true }
+```
+
+#### 错误�应
+
+```json
+{
+  "code": 310404,
+  "message": "酒店ID/房型ID/日期��为空",
+  "success": false,
+  "data": null
+}
+```
+
+#### 业务边界
+
+- 仅�许内部鉴�调用，�通过管�端网关暴露。
+- 释放先读�当�已用�，计算实际释放�，�用类型安全的期望值与下界 CAS 更新；0 行时�读并有界�试。
+- �一释放 `opId` �放���回补；��释放 `opId` 并�也�� `stockUsed >= 0`。
+- `rollbackRound` �始为 0；仅当�一扣�日志从 `DONE` �新进入�有状�时原�自增一次。
+- `nights > 1` 继续按既有多夜循环处�，�拆分原扣�日志，也�拒�多夜请求。
+
+---
+
+## 四�契约约�与正确调用方�
+
+### ✅ 正确 / � 错误 payload 对照
+
+| 场景 | payload |
+|------|---------|
+| ✅ 首次扣� | `{ "date": "2026-09-09", "qty": 2, "opId": "deduct-asgn-123-d1-rt456-h789-0" }` |
+| ✅ ��作�试 | 请求体与路径全部�� |
+| ✅ �夜释放 | `{ "date": "2026-09-09", "qty": 2, "opId": "release-456-0" }` |
+| � 沿用旧 Query �数 | `?date=2026-09-09&qty=2&opId=...`，新版本��接� |
+| � �用 opId 改数� | � `opId` 将 `qty` 从 2 改为 3，会拒� |
+
+### 切�状�时的必�动作
+
+`hl-resource-service` 与 `hl-order-service-v3` 必须�批�旧�� commit �新；�止任一�务先����形� Query/Body 混版。回退必须两�务一起从 R0 回到 R-1，必�时�一起回 R-2；新增�移����兼容，�回滚 DDL。
+
+---
+
+## 五�数�库行为
+
+| 调用行为 | 外部�观察结果 |
+|----------|----------------|
+| 首次�功扣�/释放 | �作身份�完整请求指纹和首次结果原��交 |
+| 相� opId 完整�放 | ��改�库存，返回首次快照并标记 duplicated |
+| 相� opId ��指纹 | 拒�，�覆盖首次身份或结果 |
+| 库存�足扣� | 返回并�久化 310403，�续�放�拒� |
+| DONE 日志�新扣� | `rollbackRound` 原� +1，新轮次使用新的扣�/释放 opId |
+
+---
+
+## 六�边界行为
+
+- 未�带有效内部令牌 → 403。
+- 扣�库存�足或日历缺失 → 310403，且旧 `opId` 永久关闭。
+- 日期�数��路径或�作类型与原 `opId` 指纹�一致 → 310404 拒�。
+- 释放数�大于当�已用� → �释放实际已用�。
+- 并���和并���释放键 → 最终库存一致，`stockUsed` ��于 0。
+- 补� Job �认 `updateTime` 已超过宽�期的精确 `PENDING` 快照；新鲜更新�会被旧扫�结果误处�。
+
+## 六.6�修改��对比
+
+### 字段级对比
+
+| 字段 | 改� | 改� |
+|------|------|------|
+| date | Query `@RequestParam` | JSON Body `RoomInventoryOpReqDTO.date` |
+| qty | Query `@RequestParam` | JSON Body `RoomInventoryOpReqDTO.qty`，>= 1 |
+| opId | Query `@RequestParam` | JSON Body `RoomInventoryOpReqDTO.opId`，最长 256，完整指纹冻结 |
+| duplicated | �稳定�放语义 | 明确表示命中首次已�交快照 |
+| rollbackRound | 无 | 从 0 开始，DONE �活时自增一次 |
+
+### 行为级对比
+
+| 行为 | 改� | 改� |
+|------|------|------|
+| ��请求 | �能��改�库存 | 唯一账本�放首次结果 |
+| 库存�足�旧请求�试 | 补库存��能延迟执行 | 310403 �久拒�，旧 opId ��执行 |
+| 超�释放 | 缺少轮次隔离和下界�护 | 按实际已用�释放，类型安全 CAS 有界�试 |
+| �一日志�新�有 | �作身份�能与旧释放碰撞 | rollbackRound 区分�生命周期 |
+
+## 六.7�影�评估
+
+- **是�破���兼容**: 是，内部 Feign 从 Query 改为 JSON Body。
+- **�端是�必须�步上线**: �；无 frontend API �化。
+- **�端 workaround 清�点**: 无。
+- **�务�布约�**: resource 与 order-v3 必须�批�布/�批回退，�能混版。
+
+## 七��影�范围
+
+- **仅影�**: order-v3 调 resource 的内部房�扣��释放�补�生命周期。
+- **零影�**:
+  - 管���和�程� HTTP 入�/出�。
+  - 既有酒店�房型和价格日历读�接�。
+  - 多夜�房循环；�拆日志��拒� `nights > 1`。
+  - 其他 order-v3 订��计价与支付�程。
+
+---
+
+## 八�测试环境已验�
+
+```text
+两�务�批部署 dev-v3@439e53d1e，��务 2 个新实例，旧 PID 无��，四个�康探针� HTTP 200 ✓
+网关 GET /admin/hotel/items → HTTP 200 / code 200 ✓
+网关 GET /v3/admin/house/staff → HTTP 200 / code 200 ✓
+跨实例��扣�返回首次快照，date/qty/opType 三类指纹冲��拒� ✓
+普通�夜轮次 opId：deduct-...-0/1 与 release-{logId}-0/1 精确命中 ✓
+释放 qty=999�并��� release opId � stockUsed=0 且全库 stockUsed<0 为 0 ✓
+库存�足 310403 在补库存�用旧 opId �放�拒� ✓
+补� Job 跳过新鲜 PENDING；�实例并�触���轮 release ledger �好 1 �并收敛 DONE ✓
+测试夹具�账本和订�日志全部清�；Job 1025/1026 已�� ACTIVE ✓
+```
+
+---
+
+## ��相关历� PR
+
+| PR | Issue | 说明 | 是��有效 |
+|----|-------|------|------------|
+| #7356 | #7339 | 内部库存�久化幂等�释放 CAS 与补�轮次 | ✅ 最新 |
+
+---
+
+## ��相关文档
+
+- 关� Issue: [wx/HL#7339](https://git.1814.love:8443/wx/HL/issues/7339)
+- 关� PR: [wx/HL#7356](https://git.1814.love:8443/wx/HL/pulls/7356)
+- 部署回退: R0 `439e53d1e`；R-1 `4a39b7fbb`；R-2 `f36a5b4e`
+
+## 关� / �系人
+
+### 链接
+
+- **Issue**: [#7339](https://git.1814.love:8443/wx/HL/issues/7339)
+- **PR**: [#7356](https://git.1814.love:8443/wx/HL/pulls/7356)
+- **Merge commit**: [439e53d1e273d58e68988c5db39db3e21d4733f2](https://git.1814.love:8443/wx/HL/commit/439e53d1e273d58e68988c5db39db3e21d4733f2)
+
+### �系人
+
+- **�端负责人**: @wx