wx/hl-api-changelog

派生 0

文件

T

Mimingguang a107bc9f18

changelog-filename-gate / validate (push) Failing after 2s

详情

chore(changelog): 回写 #7135/#7142/#7143/#7158/前端缺陷条前端交付状态

2026-09-06 16:33:44 +08:00

16 KiB

原始文件 Blame 文件历史

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	7158	团期手动成团门槛与提前成团留痕	admin	jw(GIT)	修改接口	deployed	verified	verified	mmg	2952ab90		2026-09-06	后端已部署 TEST 并实测：成团带理由成功、重复成团 589537、不传 body 兼容路径均通过。前端待接：成团弹窗三格读 minToForm、产品排期表单加最低成团户数输入框。	2026-09-06	dev-v3

团期手动成团：成团门槛 min_to_form 与提前成团留痕

影响范围：管理后台「团期详情 → 整团总览 → 成团」弹窗，以及产品「Step4 班期」维护表单。当前状态：后端已部署 TEST 并实测；前端待接入。

⚠️ 关键变化

成团接口新增可选请求体。POST .../group 原来无请求体，现在可传 formedNote（提前成团理由）。 不传 body 时行为与之前完全一致，前端不改也不会坏。
成团新增权限校验 group-batch:manage。此前该接口无任何权限校验。
重复成团改为语义化错误码 589537，此前返回笼统的 589501「团期状态不允许当前操作」。
新增成团门槛字段 minToForm（最低成团户数，户 = 订单 = 房）。团期详情与产品班期两侧都新增该字段，供成团弹窗三格渲染。

一、背景

招募中的团期需管理员手动点「成团」才进入成团状态，进入后才能开始需求审核 / 配置资源。成团弹窗顶部要显示三格「已售 5/9 户 · 成团标准满 6 户 · 距标准差 1 户」，但此前成团标准没有任何数据源：团期侧的 minGroupPeople 是「人数」口径且全局无写入方恒为 null，产品侧只有按人数的最低成团人数。本次新增按户数的 minToForm 补齐这条链路。

门槛只提示不拦截：未达标也可提前成团，这是业务要求。系统在任何情况下都不自动成团。

二、变更接口清单

#	接口	方法	路径	变更类型	说明
1	团期手动成团	POST	`/v3/admin/order/group-batch/{groupBatchId}/group`	修改接口	新增可选请求体 formedNote；新增权限校验；重复成团改 589537
2	团期详情	GET	`/v3/admin/order/group-batch/{groupBatchId}`	修改接口	出参新增 minToForm（成团门槛户数）
3	产品班期修改	PUT	`/admin/product/item/{id}/schedule`	修改接口	入参新增 minToForm（最低成团户数）
4	产品班期列表	GET	`/admin/product/item/{id}/schedule/list`	修改接口	出参新增 minToForm

三、接口详情

1. 团期手动成团 `POST /v3/admin/order/group-batch/{groupBatchId}/group`

VO: GroupBatchFormReqVO

使用场景

管理员在「团期详情 → 整团总览」底部操作条点「成团」，弹窗确认后调用。仅招募中（RECRUITING）的团期可成团；成团后团期进入资源准备中，才能开始需求审核与配置资源。已售户数未达成团门槛时也可以成团（提前成团），此时建议在弹窗里填写理由。

入参

字段	位置	类型	必填	约束	说明
groupBatchId	path	Long	是	正整数	团期 ID
formedNote	body	String	否	最长 256 字	提前成团理由。整个 body 可以不传；不传等同于不带理由，行为与本次改动前一致

出参

字段	类型	说明
code	Integer	200 表示成团成功
message	String	提示文案
data	Object	固定为 null，本接口无返回体
success	Boolean	true 表示成功

请求示例

{
  "formedNote": "客户催促，线下已谈妥另外 1 户"
}

响应示例

{
  "code": 200,
  "message": "成功",
  "data": null,
  "traceId": null,
  "success": true
}

空数据 / 降级响应

本接口成功时 data 恒为 null，不存在空数据形态。成团流水文案里的「已售 N/M 户」依赖实时聚合，聚合失败时降级为不带户数的文案， 不影响成团本身成功，前端无需为此做特殊处理。

错误响应

{
  "code": 589537,
  "message": "团期已成团，不可重复成团",
  "data": null,
  "traceId": null,
  "success": false
}

业务边界

仅 RECRUITING 状态可成团；已成团（含之后各状态）返回 589537，已流团返回 589501。
重复成团零副作用：不写状态、不写流水、不触发任何下游动作。
未达成团门槛不拦截，照常成团，仅在成团流水里标注未达标与理由。
需要 group-batch:manage 权限，无权限返回 589507。
系统在任何情况下都不自动成团；达标只代表「允许成团」。

2. 团期详情 `GET /v3/admin/order/group-batch/{groupBatchId}`

VO: GroupBatchDetailRespVO

使用场景

打开团期详情页时调用。本次新增的 minToForm 与既有 enrolledRooms / maxRooms 一起，足以渲染成团弹窗顶部三格，前端不需要再调其他接口。

入参

字段	位置	类型	必填	约束	说明
groupBatchId	path	Long	是	正整数	团期 ID

出参

字段	类型	说明
minToForm	Integer	本次新增。最低成团户数，户 = 订单 = 房。null 或 0 表示未设门槛
enrolledRooms	Integer	已售户数（成团弹窗第一格分子）
maxRooms	Integer	满团户数（第一格分母），0 表示不限
remainRooms	Integer	剩余户数，不限时为 null
minGroupPeople	Integer	历史字段，最低成团人数，全局无写入方恒为 null。成团门槛请改用 minToForm
batchStatus	String	团期状态码

请求示例

GET /v3/admin/order/group-batch/2096412454643802114
Authorization: Bearer <token>

响应示例

{
  "code": 200,
  "message": "成功",
  "data": {
    "groupBatchId": "2096412454643802114",
    "batchStatus": "RECRUITING",
    "enrolledRooms": 1,
    "maxRooms": 8,
    "remainRooms": 7,
    "minToForm": 6,
    "minGroupPeople": null
  },
  "success": true
}

空数据 / 降级响应

minToForm 为 null 或 0 表示该团期未设成团门槛。此时前端只显示第一格「已售 X/Y 户」，不显示「成团标准」与「距标准差」两格。本次上线前建出的存量团期一律是这种情况，不做数据回填。

错误响应

{
  "code": 589500,
  "message": "团期不存在",
  "data": null,
  "success": false
}

业务边界

三格渲染口径：已售 enrolledRooms/maxRooms 户；成团标准满 minToForm 户；距标准差 max(0, minToForm - enrolledRooms) 户。
minToForm 是建团时从产品班期快照下来的，之后改产品班期不会回改已建出的团期。
minGroupPeople 与 minToForm 是两个不同口径的字段，并存且互不换算，不要混用。

3. 产品班期修改 `PUT /admin/product/item/{id}/schedule`

VO: ScheduleSaveReqVO

使用场景

产品维护 Step4「班期」表单保存时调用。本次新增 minToForm，即该班期的最低成团户数，与既有 maxRooms（满团户数）成对维护。

入参

字段	位置	类型	必填	约束	说明
id	path	Long	是	正整数	产品 ID
batchId	body	Long	是	修改时必传	班期 ID
minToForm	body	Integer	否	非负整数	本次新增。最低成团户数，空或 0 表示不限
maxRooms	body	Integer	否	非负整数	满团户数，0 表示不限

出参

字段	类型	说明
data	Long	班期 ID
success	Boolean	是否成功

请求示例

{
  "batchId": 2052935476557328386,
  "departureDate": "2026-10-01",
  "adultPrice": 2925.00,
  "childPrice": 2425.00,
  "singleRoomDiff": 500.00,
  "maxRooms": 8,
  "minToForm": 6
}

响应示例

{
  "code": 200,
  "message": "成功",
  "data": 2052935476557328386,
  "success": true
}

空数据 / 降级响应

minToForm 不传时服务端兜底为 0（不限），与 maxRooms / maxParticipants 的兜底口径一致。存量班期在本次 DDL 后取默认值 0，不做回填。

错误响应

{
  "code": 403,
  "message": "无操作权限",
  "data": null,
  "success": false
}

业务边界

minToForm 只服务团期运营台的成团弹窗与成团留痕，不参与任何下单与库存判定。
库存与满团判定仍然只看 maxRooms / maxParticipants，本次不受影响。
与既有的按人数的最低成团人数字段并存、互不覆盖、互不换算。
改这里不会回改已经建出的团期，团期侧是建团时的快照。

4. 产品班期列表 `GET /admin/product/item/{id}/schedule/list`

VO: ScheduleRespVO

使用场景

产品维护 Step4「班期」列表回显，以及班期编辑弹窗打开时取当前值。

入参

字段	位置	类型	必填	约束	说明
id	path	Long	是	正整数	产品 ID

出参

字段	类型	说明
minToForm	Integer	本次新增。最低成团户数，0 表示不限
maxRooms	Integer	满团户数，0 表示不限
batchId	Long	班期 ID
departureDate	String	出发日期

请求示例

GET /admin/product/item/2044306857534636034/schedule/list
Authorization: Bearer <token>

响应示例

{
  "code": 200,
  "message": "成功",
  "data": [
    {
      "batchId": 2052935476557328386,
      "batchNo": "Q202610012052935476548939777",
      "departureDate": "2026-10-01",
      "maxRooms": 8,
      "minToForm": 0
    }
  ],
  "success": true
}

空数据 / 降级响应

产品下无班期时 data 为空数组。存量班期的 minToForm 一律回显 0，表示尚未设置成团门槛，属正常值而非异常。

错误响应

{
  "code": 404,
  "message": "产品不存在",
  "data": null,
  "success": false
}

业务边界

列表回显的 minToForm 是产品侧权威值；团期侧显示的是建团时的快照，两者可能不同，属预期。
该字段不影响列表排序与筛选。

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

成团请求体整体可选。前端可以继续用无 body 的旧调用，也可以传 {"formedNote": "..."}。建议：已售户数未达 minToForm 时在弹窗里出现理由输入框并把值传上来。
理由本期不强制必填。服务端不会因为没填理由而拒绝成团，前端可自行决定是否做前端必填。
成团弹窗三格全部来自团期详情接口，不需要额外接口。minToForm 为 null 或 0 时只显示第一格。
同一份 ScheduleSaveReqVO 也被新建班期 POST /admin/product/item/{id}/schedule 使用，该接口同样接受 minToForm，语义与修改班期完全一致；批量创建 POST /admin/product/item/{id}/schedule/batch-create 使用 ScheduleBatchCreateReqVO，同样新增了 minToForm 并逐个透传给每个新建班期。这三个入口共用一套口径，前端按同一字段接入即可。
权限：成团需要 group-batch:manage。该权限已随本次发布授予 ADMIN 与 SUPER_ADMIN。若线上还有其他角色需要点成团，需要单独补授，否则会被拦为 589507。

五、数据库行为

成团成功时推进团期状态，并写入一条成团操作流水，内容形如「手动成团 · 已售 1/8 户 · 未达标(满6户) · 理由：客户催促」，含操作人与时间。未设门槛时省略达标判定段，未填理由时省略理由段。
重复成团、无权限、团期不存在三种情况均不产生任何写入。
成团门槛在产品侧维护、在建团时快照到团期侧，之后两侧独立，不做双向同步。
存量数据不回填：本次上线前已存在的班期与团期，成团门槛一律为默认值（0 或空）。

六、边界行为

未达成团门槛照常可以成团，门槛只影响提示与流水文案。
系统在任何情况下都不自动成团，达标只代表「允许成团」。
成团后的既有下游行为不变：派生导游 / 摄影需求标志、免闸置位、尝试推进物料准备、驱动子订单进需求态并派发配房配车待办。
成团流水文案里的已售户数与团期详情同源（实时聚合），不读持久计数列，两处显示不会打架。

六.6、修改前后对比

项	修改前	修改后
成团请求体	无请求体	可选 body，含 `formedNote`；不传时行为不变
成团权限	无任何权限校验	需要 `group-batch:manage`，无权限 589507
重复成团	589501「团期状态不允许当前操作」	589537「团期已成团，不可重复成团」
成团流水	固定文案「成团」	带已售 / 满团 / 达标情况 / 提前成团理由
团期详情成团门槛	只有恒为 null 的 `minGroupPeople`（人数口径）	新增 `minToForm`（户数口径），弹窗三格可渲染
产品班期成团门槛	只有按人数的最低成团人数	新增按户数的 `minToForm`，可在班期表单维护

六.7、影响评估

对现有前端调用零破坏：成团请求体可选，不传 body 的老调用行为与改动前完全一致，已在 TEST 实测确认。
权限是行为变更：group-batch:manage 已随发布授予 ADMIN / SUPER_ADMIN；若还有其他角色在点成团，上线后会被拦住，需要补授权限。这是本次唯一需要运维配合的点。
错误码语义变更：重复成团由 589501 变为 589537。若前端对 589501 做过特殊处理，需要同步识别 589537。
新增字段均为增量，不改动任何既有字段的类型与含义；minGroupPeople 保持原样不动。
团期成团的下游链路（子订单推进、待办派发）本次未做任何改动。

七、不影响范围

取消成团、流团两个接口本次未改动，仍然没有权限校验，将另行统一处理。
下单、库存扣减、满团判定完全不受影响，仍只看 maxRooms / maxParticipants。
小程序端不受影响，本次改动全部在管理后台侧。
成团通知（公众号 / 短信）本期不做，弹窗上的通知勾选框暂无后端对应入参，成团后仍需人工通知客户。

八、测试环境已验证

TEST 环境已部署 product-v2、user-service、order-v3 三个服务并实测通过：

团期详情返回 minToForm / maxRooms / enrolledRooms / remainRooms，minGroupPeople 保持并存。
带 formedNote 成团成功，团期由招募中进入资源准备中。
重复成团返回 589537「团期已成团，不可重复成团」。
不传请求体再次调用同样走到业务校验而非参数错误，确认请求体确实可选。
产品班期列表返回 minToForm，存量班期回显 0。

未在测试环境覆盖的三项：成团流水文案（团期流水目前无对外查询接口，由单元测试保证）、产品班期写入 minToForm（受产品模块数据权限限制未能实调）、建团快照（需在设置门槛后新建团期订单才能观察）。

十、相关文档

工单：HL#7158
合并：HL PR#7168（已合入 dev-v3）
前置工单：HL#7104（成团驱动子订单流程推进），本次改成团入口，与其下游改动互不冲突

关联 / 联系人

后端：jw
前端待接两项：成团弹窗三格读取 minToForm 并在未达标时出现提前成团理由输入框；产品 Step4 班期表单新增「最低成团户数」输入框。

16 KiB 原始文件 Blame 文件历史 Unescape Escape

团期手动成团：成团门槛 min_to_form 与提前成团留痕

⚠️ 关键变化

一、背景

二、变更接口清单

三、接口详情

1. 团期手动成团 POST /v3/admin/order/group-batch/{groupBatchId}/group

使用场景

入参

出参

请求示例

响应示例

空数据 / 降级响应

错误响应

业务边界

2. 团期详情 GET /v3/admin/order/group-batch/{groupBatchId}

使用场景

入参

出参

请求示例

响应示例

空数据 / 降级响应

错误响应

业务边界

3. 产品班期修改 PUT /admin/product/item/{id}/schedule

使用场景

入参

出参

请求示例

响应示例

空数据 / 降级响应

错误响应

业务边界

4. 产品班期列表 GET /admin/product/item/{id}/schedule/list

使用场景

入参

出参

请求示例

响应示例

空数据 / 降级响应

错误响应

业务边界

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

五、数据库行为

六、边界行为

六.6、修改前后对比

六.7、影响评估

七、不影响范围

八、测试环境已验证

十、相关文档

关联 / 联系人

16 KiB

原始文件 Blame 文件历史

1. 团期手动成团 `POST /v3/admin/order/group-batch/{groupBatchId}/group`

2. 团期详情 `GET /v3/admin/order/group-batch/{groupBatchId}`

3. 产品班期修改 `PUT /admin/product/item/{id}/schedule`

4. 产品班期列表 `GET /admin/product/item/{id}/schedule/list`