hl-api-changelog/changelogs-v2/2026-09/06_7178_团期调整满团名额同步产品域库存-修改接口-管理后台.md

schema, ticket, title, consumer, author, change_type, backend_status, gateway_status, frontend_status, frontend_owner, frontend_ref, target_release, verified_at, status_note, updated_at, base

schema	ticket	title	consumer	author	change_type	backend_status	gateway_status	frontend_status	frontend_owner	frontend_ref	target_release	verified_at	status_note	updated_at	base
hl-changelog/v2	7178	团期调整满团名额同步产品域库存	admin	jw(GIT)	修改接口	deployed	verified	verified	mmg	84c0cd5b		2026-09-06	修复「调了不生效」：调名额此前只写订单域，而库存权威在产品域。后端已部署 TEST 并实测：加减名额驱动产品域满团即停/放开继续招募、低于已报名拒绝且零写入、物料准备起阶段门。请求体形状已变更（净增量），前端待接。	2026-09-06	dev-v3

团期调整满团名额：同步产品域库存 + 阶段门 + 净增量入参

影响范围：管理后台「团期详情 → 整团总览 → 调整满团名额」弹窗。 当前状态：后端已部署 TEST 并实测；前端待接入（请求体形状已变更）。

⚠️ 关键变化

1. 修复「调了不生效」。此前调名额只写订单域，而下单侧的剩余名额由产品域算出， 于是加名额放不出空位、减名额停不了售，但看板数字会变。现在调整会真正驱动售卖状态。
2. 请求体不兼容变更：由 {maxParticipants, maxRooms} 两个绝对值， 改为 {capacityDelta, reason} —— 净增量、只调户数。
3. 新增阶段门：仅「招募中」与「资源准备中」可调，物料准备中及之后返回 589538。
4. 新增权限校验 group-batch:manage（此前该接口无任何权限校验）。
5. 响应由空改为返回结果对象，直接给出弹窗三格所需数据。

一、背景

调整满团名额是给运营临时增减本期可报名户数用的。此前的实现只更新了团期侧的展示值， 没有同步到真正决定「还能不能报名」的那一侧，导致这个功能实际上不起作用—— 页面上数字变了，但客户仍按老上限被卡住。本次修复把调整落到库存权威侧， 并按新库存重算班期是否已满额。

二、变更接口清单

#	接口	方法	路径	变更类型	说明
1	调整团期满团名额	PUT	/v3/admin/order/group-batch/{groupBatchId}/capacity	修改接口	入参改为净增量并只调户数；新增阶段门与权限校验；同步产品域库存；响应改为结果对象

三、接口详情

1. 调整团期满团名额 PUT /v3/admin/order/group-batch/{groupBatchId}/capacity

VO: AdjustCapacityReqVO

使用场景

管理员在「团期详情 → 整团总览」底部操作条点「调整满团名额」， 弹窗用 −/＋ 步进器改满团户数，点「保存名额」时把净变化量提交给本接口。

典型用法：某期已满员但还有客户想报，加 2 个名额把空位放出来继续招募； 或临近出团减名额提前收口。已成团的团期加名额后仍保持成团，不会退回招募中。

入参

字段	位置	类型	必填	约束	说明
groupBatchId	path	Long	是	正整数	团期 ID
capacityDelta	body	Integer	是	不能为 0	满团名额净增量（户），可正可负。新满团户数 = 当前满团户数 + 该值
reason	body	String	否	最长 256 字	调整原因，填了写进团期操作记录。不强制必填

出参

字段	类型	说明
batchId	String	团期 ID
beforeMaxRooms	Integer	调整前满团户数
maxRooms	Integer	调整后满团户数，0 表示不限
capacityDelta	Integer	本次净增量
enrolledRooms	Integer	已报名户数（户 = 订单 = 房）
remainRooms	Integer	调整后余量 = max(0, maxRooms − enrolledRooms)；满团户数为 0（不限）时为 null

请求示例

{
  "capacityDelta": 3,
  "reason": "客户加订，放三个空位继续招募"
}

响应示例

{
  "code": 200,
  "message": "成功",
  "data": {
    "batchId": "2096510069465088002",
    "beforeMaxRooms": 2,
    "maxRooms": 5,
    "capacityDelta": 3,
    "enrolledRooms": 1,
    "remainRooms": 4
  },
  "traceId": null,
  "success": true
}

空数据 / 降级响应

调整后满团户数为 0 时表示不限名额，此时 remainRooms 返回 null， 前端不显示余量。这是正常语义而非异常。

本接口没有空列表形态；任何失败都以错误码返回，且失败一律零写入—— 产品侧与团期侧都不会留下半改状态。

错误响应

{
  "code": 589538,
  "message": "物料准备开始后不可再调整满团名额（仅招募中、资源准备中可调）",
  "data": null,
  "traceId": null,
  "success": false
}

业务边界

• 仅「招募中」与「资源准备中」可调；物料准备中及之后返回 589538。
• 调整后不得低于已报名户数，否则返回 589509；新值也不得为负。
• 新值为 0 表示不限名额，此时不受已报名数约束。
• capacityDelta 为 0 返回 589539（等于没调）。
• 需要 group-batch:manage 权限，无权限返回 589507。
• 调整不改团期状态：已成团的仍保持成团，不会退回招募中。
• 产品侧同步失败时整笔失败并返回 589540，团期侧零写入。

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

• 提交净增量，不要提交总数。前端步进器算出的总数只用于展示， 提交时给差值即可。这样两人同时调也不会互相覆盖成对方的总数。
• 不再接收人数容量。此前的 maxParticipants 字段已移除，人数容量由产品侧维护。
• 调整前先看能不能调：团期进入物料准备后按钮应置灰，避免用户点了才报错。
• 弹窗三格数据：调整前可从团期详情取「当前名额 / 已报名」； 调整成功后直接用本接口返回的 maxRooms / enrolledRooms / remainRooms 刷新， 不必再拉一次详情。
• 重试是安全的。若前端超时后重试同一请求，服务端以团期侧当前值为基数重算， 不会把同一个增量叠加两次。

五、数据库行为

• 调整会同时更新产品侧与团期侧的满团户数，并按新库存重算班期是否已满额： 售罄时停止继续接单，库存恢复时重新开放报名。
• 先写产品侧，成功后才写团期侧；产品侧写失败即整笔失败、团期侧不留任何痕迹。
• 每次成功调整写一条团期操作记录，内容形如 「满团名额：9→10（+1） · 理由：客户加订一间」，含操作人与时间；未填理由时省略后半段。
• 拒绝的三种情况（阶段不允许 / 低于已报名 / 增量为 0）均不产生任何写入。
• 历史上两侧数值已经不一致的团期，本次不做批量订正；下一次调整会自动把两侧拉齐。

六、边界行为

• 已成团的团期加名额后仍保持成团，只是把空位放出来继续招募，满团即停。
• 减名额减到正好等于已报名户数是允许的（余量为 0），再减一户即被拒绝。
• 满团户数为 0 表示不限，此时无论已报名多少都不触发下限校验。
• 团期未绑定产品班期时返回 589540（无处可写，不静默放过）。

六.6、修改前后对比

项	修改前	修改后
是否真正影响售卖	❌ 只改团期侧展示值，加名额放不出空位、减名额停不了售	✅ 同步到库存权威侧，满团即停 / 放开继续招募都生效
请求体	{maxParticipants, maxRooms} 两个绝对值，均必填	{capacityDelta, reason}，净增量、只调户数
响应	空（调完要再拉一次详情）	返回调整前后值、已报名与余量
阶段限制	无，任何状态都能调	仅招募中与资源准备中，其余 589538
权限	无任何校验	group-batch:manage
调整原因	无此入参	reason 选填，写进操作记录
操作记录	只有「最大人数：20→24，最大房间：8→9」	「满团名额：9→10（+1） · 理由：…」

六.7、影响评估

• 请求体不兼容：字段整体更换。上线前已核对管理后台前端仓库， 没有任何页面在调用本接口（原型侧本就是提交净增量，只是此前只在前端本地累加）， 因此未设兼容期。若有未知调用方，需同步改造。
• 阶段门是行为变更：此前任何状态都能调，现在物料准备后会被拒。 这是有意收紧——那之后房车已按户数配好，改名额会让资源计划失真。
• 权限是行为变更：group-batch:manage 已随上一单建好并授予管理员与超级管理员， 本次直接复用，无需额外配置。
• 资源准备中调整的已知风险：该阶段房务/车务可能已按当前户数派单订房订车， 此时加减名额不会回头改动已派资源，需人工复核资源计划。
• 新增字段与新响应均为增量，不改动任何既有字段的类型与含义。

七、不影响范围

• 下单与库存扣减的判定口径不变，仍按满团户数与人数上限；本次只是让调整真正作用到它。
• 人数容量不受影响，仍由产品侧维护。
• 团期状态机不变：调整不推进也不回退任何状态。
• 成团、取消成团、流团三个动作本次未改动。
• 小程序端不受影响，改动全部在管理后台侧。

八、测试环境已验证

TEST 环境已部署产品服务与订单服务并实测通过：

• 加名额 +1：产品侧满团户数随之变化，团期侧同步，返回三格数据。
• 减名额 −2：两侧同步。
• 减到正好等于已报名户数：班期转为已满额、停止接单。
• 再加 1 户：班期恢复报名中，空位重新放出。
• 减到低于已报名户数：拒绝且零写入（产品侧数值未变）。
• 增量为 0：拒绝。
• 物料准备中及之后调整：拒绝且零写入。
• 已成团（资源准备中）加名额：成功，班期继续招募，团期仍保持成团不回退。

十、相关文档

• 工单：HL#7178
• 合并：HL PR#7181（已合入 dev-v3）
• 关联工单：HL#7158（团期手动成团），本单复用其建立的 group-batch:manage 权限码； 弹窗顶部「满 6 户成团 · 满 9 户满团」的成团标准数据亦由该单交付

关联 / 联系人

• 后端：jw
• 前端待接：弹窗步进器改为提交净增量、接收新的响应结构刷新三格； 团期进入物料准备后按钮置灰；未达标提示与「不得低于已报名数」的前端拦截保持不变