---
schema: "hl-changelog/v2"
ticket: "7284"
title: "团期下单校验改判实时库存：满员班期退单后能重新下单，满员时错误码由 581028 改为 581031/581034"
consumer: "multiple"
author: "jw(GIT)"
change_type: "修改接口"
backend_status: "deployed"
gateway_status: "verified"
frontend_status: "not_required"
frontend_owner: "mmg"
frontend_ref: ""
target_release: ""
verified_at: "2026-09-08"
status_note: "前端不改:接口出入参零变化;满员错误码 581028→581031/581034 由拦截器透后端 message(本系统无中央错误码字典,581027 新触发源同此);前端未消费 581028 业务码(仅 disband.js 注释)。实时库存改判纯后端。"
updated_at: "2026-09-08"
base: "dev-v3"
---

# 团期: 下单校验改判实时库存 + 产品域库存聚合 fail-closed

> **服务**: hl-order-service-v3、hl-product-service-v2、hl-order-service-v2（**必须按序部署**: product-v2 → order-v3 → order-v2）
> **PR**: #7330
> **Issue**: #7284
> **日期**: 2026-09-08
> **影响范围**: GROUP 产品下单（管理后台代客下单 + 小程序下单 + order-v2 admin 创单）

---

## ⚠️ 关键变化

**出入参结构一个字段都没改。** 前端不改不报错，但有两件事必须知道：

1. **「满员班期退单后卖不出去」这个 bug 消失了**——班期一旦被推成「已满额」，
   即使客户退单腾出真实空位，下单仍会被 **581028** 拒；现在改判实时库存，有余位就能下。
   小程序日历上那个「点进去能选、下单却报错」的分裂也随之消失。
2. **真正满员时的错误码变了**：由 **581028**「团期状态不允许报名」改为
   **581031**「团期剩余房间不足」或 **581034**「团期剩余名额不足」。
   前端若对 581028 有特殊文案，需知悉该码现在只在「班期已取消 / 已结束 / 状态未知」时出现。

改前实测（AC-1，在部署本次改动**之前**于测试服复现）：`maxRooms=2` 的班期下满 2 单后
`batch_status=FULL`，退掉 1 单后同一次 `getBatchInfo` 响应里 `remainingRooms=1`（余量已自愈）
而 `batchStatus` 仍是 `FULL`（死缓存不自愈），再下单返回 `code=581028`。

---

## 一、背景

GROUP 下单校验读的是产品域**持久列** `group_tour_batch.batch_status`，只放行「报名中 / 即将满额」。
而这个持久列翻回「报名中」的唯一入口是产品服务的 `unenroll`，**order-v3 的普通取消链路
（超时自动取消 / 退款 / admin 取消 / C 端取消）一个都不调它**；唯一能翻回去的 `enroll`
又只在**创单成功后**才调——形成死结。

同时这是一个「展示与下单两套真相」的问题：小程序价格日历的可选性由**实时库存**算，
所以退单后那一天在日历上是可选的，客户点进去下单才被 581028 拒。

第二件事：产品域 `GET /internal/product/batch/{batchId}/info` 的库存聚合原本在失败时
**静默降级为「无活跃订单」**，返回偏大的剩余名额。本次去掉了下单闸对持久状态的依赖后，
这两个余量数就是创单路径上**唯一**的超卖闸，故同单把它改成 fail-closed。

---

## 二、变更接口清单

| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
|---|------|------|------|----------|------|
| 1 | 管理后台代客下单 | POST | `/v3/admin/order` | 行为变化 | 满员判定改用实时库存；出入参与响应结构**不变**，错误码触发集合收窄 |
| 2 | 小程序下单 | POST | `/v3/internal/mp/order/create` | 行为变化 | 同上 |

---

## 三、接口详情

### 1. 管理后台代客下单 `POST /v3/admin/order`

**VO**: `OrderCreateRespVO`

#### 使用场景

管理后台定制师代客下单。调用方 hl-ui 订单创建页。GROUP 产品必须带 `productBatchId`。

#### 入参

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|------|------|------|------|------|------|
| productId | Body | Long | ✅ | — | 产品 ID；**入参一个都没变** |
| productBatchId | Body | Long | GROUP 必填 | — | 产品侧班期 ID；为空抛 581026 |
| tierSeq | Body | Integer | ✅ | — | 档位序号 |
| departureDate | Body | LocalDate | ✅ | `yyyy-MM-dd` | 出发日期 |
| adultCount / childCount / youngChildCount | Body | Integer | ✅ / ❌ / ❌ | ≥0 | 参与名额校验的三项（babyCount 不参与） |
| roomCount | Body | Integer | ❌ | ≥0 | 房间（户）数，参与房间库存校验 |
| customerName / customerPhone | Body | String | ✅ | — | 客户姓名 / 手机号 |

#### 出参 `Result<OrderCreateRespVO>`

| 字段 | 类型 | 说明 |
|------|------|------|
| id | Long | 订单 ID；**响应结构完全不变** |
| orderNo | String | 订单号 |
| orderStatus | String | PENDING_PAY 等 |
| 其余全部字段 | — | **完全不变** |

#### 请求示例

```http
POST /v3/admin/order HTTP/1.1
Authorization: Bearer <admin-token>
Content-Type: application/json

{
  "productId": 2056947670512971778,
  "productBatchId": 2097208296820678658,
  "tierSeq": 1,
  "departureDate": "2026-11-07",
  "adultCount": 2,
  "childCount": 0,
  "roomCount": 1,
  "customerName": "张三",
  "customerPhone": "13800002043"
}
```

#### 响应示例

```json
{
  "code": 200,
  "message": "成功",
  "success": true,
  "data": {
    "id": "2097211100872290306",
    "orderNo": "HL20260908143105038",
    "orderStatus": "PENDING_PAY",
    "orderStatusName": "待支付"
  }
}
```

上面这一单下在了一个 `batch_status=FULL`、`remainingRooms=1` 的班期上——**改前它会被 581028 拒**。

#### 空数据 / 降级响应

**产品域库存聚合失败时本接口 fail-closed 拒单**，返回 581027，不再放行。
改前是静默按「无活跃订单」降级、返回偏大的剩余名额从而放行，属超卖风险。
展示链路（小程序团期列表 / 详情、管理后台班期列表 / 价格日历）**保持原有降级不变**，
聚合失败时照常 200 返回，不会整片报错。

```json
{
  "code": 581027,
  "message": "团期信息获取失败",
  "success": false,
  "data": null
}
```

#### 错误响应

```json
{
  "code": 581031,
  "message": "团期剩余房间不足",
  "success": false,
  "data": null
}
```

**错误码集合无新增**，但**触发条件变了**：

| 码 | 含义 | 变化 |
|----|------|------|
| 581028 | 团期状态不允许报名 | **触发集收窄**：只在班期「取消中 / 已取消 / 已结束 / 状态未知」时出现。满员不再走这个码 |
| 581031 | 团期剩余房间不足 | **新增触发场景**：真正满员（房间维度）由它承担 |
| 581034 | 团期剩余名额不足 | **新增触发场景**：真正满员（人数维度）由它承担 |
| 581027 | 团期信息获取失败 | **新增触发源**：产品域库存聚合失败（fail-closed） |

#### 业务边界

- **未知状态一律拒单**：班期状态为空或不在字典内时按 581028 拒。产品侧将来新增状态值而订单侧
  镜像未同步时，应当暴露成拒单而不是静默放行——跨服务枚举漂移不该由客户承担。
- **满员仍然拒得住**：改的只是「用哪个数判满」，不是「不判满」。实测真满员时返 581031。
- **产品域仍会继续写「已满额」持久值**，只是不再有人拿它做下单闸门；管理后台班期列表上
  该状态照常显示，前端无需改动。
- **并发超卖窗口客观存在**：本次不做 TCC 强一致，创单入口仍无按班期的分布式锁，
  预查是 TOCTOU 不可靠防护——这是既有限制，本次未改变。

### 2. 小程序下单 `POST /v3/internal/mp/order/create`

**VO**: `MpOrderDetailVO`

#### 使用场景

小程序下单，经 mp BFF 转发到 order-v3。与管理后台代客下单共用同一套 GROUP 校验逻辑。

#### 入参

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|------|------|------|------|------|------|
| productId | Body | Long | ✅ | — | 产品 ID；**入参一个都没变** |
| productBatchId | Body | Long | GROUP 必填 | — | 产品侧班期 ID |
| tierSeq | Body | Integer | ✅ | — | 档位序号 |
| departureDate | Body | LocalDate | ✅ | `yyyy-MM-dd` | 出发日期 |
| adultCount / childCount / youngChildCount | Body | Integer | ✅ / ❌ / ❌ | ≥0 | 参与名额校验的三项 |
| roomCount | Body | Integer | ❌ | ≥0 | 房间（户）数 |

#### 出参 `Result<MpOrderDetailVO>`

| 字段 | 类型 | 说明 |
|------|------|------|
| orderId | Long | 订单 ID；**响应结构完全不变** |
| orderNo | String | 订单号 |
| orderStatus | String | 订单状态 |
| 其余全部字段 | — | **完全不变** |

#### 请求示例

```http
POST /v3/internal/mp/order/create HTTP/1.1
Content-Type: application/json

{
  "productId": 2056947670512971778,
  "productBatchId": 2097208296820678658,
  "tierSeq": 1,
  "departureDate": "2026-11-07",
  "adultCount": 2,
  "roomCount": 1
}
```

#### 响应示例

```json
{
  "code": 200,
  "message": "成功",
  "success": true,
  "data": { "orderId": "2097211100872290306", "orderNo": "HL20260908143105038", "orderStatus": "PENDING_PAY" }
}
```

#### 空数据 / 降级响应

同管理后台下单：产品域库存聚合失败时返 581027 拒单；展示链路不受影响，
价格日历与班期列表在同一场景下仍正常 200 返回。

```json
{
  "code": 581027,
  "message": "团期信息获取失败",
  "success": false,
  "data": null
}
```

#### 错误响应

```json
{
  "code": 581034,
  "message": "团期剩余名额不足",
  "success": false,
  "data": null
}
```

错误码变化同管理后台下单那张表。

#### 业务边界

- **「日历可选、下单报错」这个分裂消失**：日历可选性本来就按实时库存算，现在下单闸也按实时库存判，
  两边终于是同一个真相。
- **小程序侧无需改代码**：出入参与响应结构零变化；只是原本会拿到 581028 的场景，
  现在要么下单成功，要么拿到 581031 / 581034。

---

## 四、契约约束与正确调用方式

- **不要再把 581028 当作「满员」的信号**。满员请判 581031 / 581034。
  581028 从此只表示「这个班期已取消 / 已结束 / 状态异常」，属于不可恢复的拒绝，
  提示客户换一期，而不是提示「稍后再试」。
- **581027 是可重试的**：它表示产品域暂时算不出库存，客户稍后重试通常会成功。
- 班期列表 / 价格日历的可选性判定**不要改**：它们本来就读实时库存，与下单闸现在一致。

---

## 五、数据库行为

- 本次**无表结构变更、无数据迁移**。
- 产品域班期的「已满额」持久值仍照常写入，只是不再参与下单判定。
- 订单创建、名额计数的写入行为一字未改。

---

## 六、边界行为

- **班期不属于该产品**：仍返 581055，未变。
- **已过报名截止日 / 已出发**：仍分别返 581029 / 581030，未变。
- **未选班期**：GROUP 产品未传 `productBatchId` 仍返 581026，未变。
- **零元班期 / 不限名额班期**：`maxRooms` 或 `maxParticipants` 为 0/空表示不限，
  对应的余量为 null，跳过该维度校验，行为未变。

## 六.6、修改前后对比

| 场景 | 改前 | 改后 |
|------|------|------|
| 班期已满员被推成「已满额」，客户退单腾出真实空位后再下单 | **581028 拒单**，且永远解不开（取消链路不回写产品域状态） | **200 创单成功** |
| 班期真正满员（剩余房间为 0）再下单 | 581028「团期状态不允许报名」 | **581031「团期剩余房间不足」** |
| 班期真正满员（剩余名额为 0）再下单 | 581028 | **581034「团期剩余名额不足」** |
| 班期已取消 / 取消中 / 已结束 | 581028 | 581028（**不变**） |
| 班期状态为空或不在字典内 | 581028 | 581028（**不变**，fail-closed） |
| 产品域库存聚合失败时下单 | 按「无活跃订单」降级，**放行**（超卖风险） | **581027 拒单**（fail-closed） |
| 产品域库存聚合失败时看班期列表 / 价格日历 | 正常 200 | 正常 200（**不变**，展示链路保持 fail-open） |

## 六.7、影响评估

- **前端零改动**：两个下单接口的出入参与响应结构完全不变。
- **需要前端知悉的一点**：若对 581028 做过「团期状态不允许报名」的特殊文案或埋点，
  满员场景现在走 581031 / 581034，文案分支需相应调整（不调也只是提示词不够精准，不会报错）。
- **对客户的净效果**：原本会被莫名其妙拒掉的下单现在能成功；原本模糊的「团期状态不允许报名」
  换成了明确的「剩余房间/名额不足」。
- **对运营的净效果**：不再需要靠「调整满团名额」或「去产品后台编辑一次班期」来玄学解锁班期。
- **风险**：产品域库存聚合失败期间 GROUP 下单会整体拒单（581027）。这是刻意的取舍——
  宁可拒单，不可超卖。该失败本身是产品域 → 订单域的内部调用异常，正常情况下不发生。

---

## 七、不影响范围

- 非 GROUP 产品（自由行 / 定制）的下单校验**完全未触碰**。
- 订单取消、退款、转期链路未改。
- 产品域班期的展示态计算（`GroupBatchDisplayStatusResolver`）未改。
- 团期名额计数与对账 Job 未改。
- 管理后台「调整满团名额」的校验规则未改。

---

## 八、测试环境已验证

部署次序（硬约束）：**product-v2 14:27:25 DONE → order-v3 14:28:43 STEP1 → order-v2 14:30:14 DONE**，
三服务同一 commit。回滚反序（先 order-v3 后 product-v2）也已实测走通。

| 验证项 | 结果 |
|--------|------|
| 满员班期退单后再下单（改前 → 改后） | **581028 → 200 创单成功** |
| 下满即查产品域状态 | 仍「报名中」——填满班期的那一单不会把状态推成「已满额」 |
| 真满员再下单 | **581031「团期剩余房间不足」** |
| 班期「已取消」/「取消中」/「已结束」 | 均 **581028** |
| 班期状态置为字典外的值 | **581028**（fail-closed） |
| 产品域库存聚合失败时 `getBatchInfo` | **480203**（产品域内部码，订单侧翻成 581027） |
| 同场景下 order-v2 admin 创单 | **503102** 拒单（锁内库存硬守卫不再拿到虚高余量） |
| 同场景下团期转期 | **200 成功**，`warnings` 含「目标团期行程天数未取到，订单沿用原天数，请人工核对」 |
| 同场景下展示链路 | 小程序班期列表 / 产品详情、管理后台班期列表 / 价格日历**全部仍 200** |
| 单元测试 | product-v2 1606 例、order-v3 9048 例，均 0 失败 0 错误 |

---

## 十、相关文档

- Issue #7284、PR #7330
- 关联工单：#7283（流团后班期置为不可售，本单的前置）、#7293（库存聚合失败不再持久改写班期状态）
- 设计文档校正：SRS 与 HOUSE 详设中「订单取消时主 API 调 product unenroll」的描述与代码不符，
  已在本次一并标注校正（order-v3 的取消链路从不调用该端点）

---

## 关联 / 联系人

- 后端：jw
- 前端：mmg（hl-ui / 小程序）
- 前端待办：①若对 581028 有特殊文案，满员场景改判 581031 / 581034；
  ②可选补录 581027 的新触发源说明。**接口结构零变化，不改也不会报错。**