wx/hl-api-changelog

派生 0

文件

T

Mimingguang e884bc0fb3

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

详情

chore(changelog): #8355 前端回写 verified(mmg,7ddbb7d9,v2.1)

2026-09-26 10:21:04 +08:00

47 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	8355	团期六节点流程前端对接总览：十张单前端改动一张表；补录三处未推 changelog 的行为变化——预支核单前均可发起且去掉四项配齐门（#8270）、流团只能在确认前发起与批复且审批中心 canApprove 确认后恒 false（#8308）、合同保险出具 / 重开 / 催签授团期管理员（#8309）	admin	jw(GIT)	修改接口	deployed	verified	verified	mmg	7ddbb7d940399e2b7fc6f73e10183032b8fa9ed7	v2.1	2026-09-26	团期流程改为六节点（招募 → 配置 → 确认 → 出行 → 核单 → 结算，SRS §0.27 / §0.27.7）后，后端 #8267～#8271、#8308、#8309、#8339～#8341 已合入 dev-v3 并部署 TEST。本条是给前端的总览：第〇节一张表列出十张单各自要改的前端位置及对应 changelog；另补录三处当时按「契约四项未改」豁免、但会改变前端行为的单。① #8270（PR #8272）POST /v3/admin/order/group-batch/{groupBatchId}/advance 删除四项配齐门（589542 不再抛出），起点前移到配置节点；随后 #8322 再前移到招募中，当前代码口径为 RECRUITING～TRIP_FINISHED 可提、核单中 / 已结算 / 已流团 589541「当前团期状态不可发起预支（进入核单后关闭）」，该接口前端已随 24_8322 交付。② #8308（PR #8313、#8315）发起流团 POST .../{groupBatchId}/disband 与同意流团 POST .../disband/{approvalId}/approve 只在 RECRUITING / RESOURCE_PREPARING 放行，确认及之后返 589544，文案由「团期已出行，不可发起或批复流团」改为「团期已确认，不可发起或批复流团」；审批中心列表 GET .../approvals/page 与流团详情 GET .../disband/{approvalId} 的流团行 canApprove 在团期确认后恒 false；确认前提交、确认时仍待审批的申请停在 PENDING，只能驳回。③ #8309（PR #8312）contracts/issue、reissue、remind-sign 的权限码 group-batch:contract:issue 新授团期管理员 GROUP_BATCH_MANAGER（user-service Flyway V20260924_8309，权限缓存 10 分钟）；团期确认后户确认行程自动出具合同保险（#8339 起由团期确认逐户驱动）。三处路径、入参、出参结构均不变。前端需：流团按钮确认后隐藏、审批中心同意按钮按 canApprove；团期管理员显示合同保险出具 / 重开 / 催签按钮；其余见第〇节。前端已交付（7ddbb7d9）：#8308 发起流团白名单收窄为招募/配置两态+DisbandBanner disbandAllowed 门控驳回重发入口；#8270 已随 24_8322 交付；审批中心同意按钮实证已按 canApprove（#8253）；#8309 合同保险三动作前端本为可见即可点零角色门，纯后端授权；spec 18 例全绿。	2026-09-24	dev-v3

团期六节点流程前端对接总览 + 预支 / 流团 / 合同保险出具权限补录（管理后台）

服务: hl-order-service-v3（端口 8086/8186）；hl-user-service（权限种子，仅 #8309） PR: #8272（#8270）、#8313 / #8315（#8308）、#8312（#8309） Issue: #8355（本条）；补录 #8270、#8308、#8309；总览覆盖 #8267～#8271、#8308、#8309、#8339～#8341 日期: 2026-09-24 影响范围: 管理后台团期详情（工具条、步骤条、财务 / 合同保险 / 配置各页签）、团期看板、团期审批中心、订单详情（团期单）、房务抢单池

⚠️ 关键变化

前端改动一次看全：第〇节按工单列出十张单各自要改的前端位置和对应 changelog，已推的五份（24_8268 / 24_8269 / 24_8271 / 24_8339 / 24_8341）与 24_8322 不重复展开，只给指引。
流团只能在「确认」之前发起（#8308）：团期进入确认（MATERIAL_PREPARING）及之后，发起流团、同意流团一律返 589544，文案改为「团期已确认，不可发起或批复流团」。团期详情的「流团」按钮在确认后应隐藏。
审批中心流团行 canApprove 在团期确认后恒 false（#8308）：列表与流团详情两处同口径，前端按 canApprove 显示「同意」即可，不要自己拼条件。确认前提交、确认时还没批的流团申请会停在待审批，只能驳回。
团期管理员可以出具 / 重开 / 催签合同保险（#8309）：group-batch:contract:issue 新授 GROUP_BATCH_MANAGER。登录信息不下发权限码，前端若按角色控制这三个按钮，需要把团期管理员加进去。
预支不再要求四项配齐（#8270）：589542 不再返回；当前允许状态为招募中～出行完毕（#8322 在 #8270 基础上再放开招募中）。该入口前端已随 24_8322 交付，此处只补 #8270 的说明。

〇、前端改动总清单（十张单）

依据 SRS §0.27 / §0.27.7（docs/group/团期模块一期实施拆分详细设计-v1.0.html，dev-v3）与各单验收评论。「前端状态」取对应 changelog 的 frontend_status。

工单	后端变化（一句话）	前端要改什么	changelog	前端状态
#8267	自动成团改为满团（户数或人数任一达满团容量，待支付算名额）；不再按最低成团门槛自动成团	无代码改动。成团时机变了：达到最低门槛不会再自动进入配置节点，需人工点「成团」或等满团；页面上的门槛只作参考	无（定时任务判据变化，按豁免口径未推）	—
#8268	新增人工「确认」端点（配置 → 确认），门不满足 589556 逐项回执；确认物资只在配置节点可调；`recheck-material-gate` 下线	团期详情新增「确认」按钮（仅 `RESOURCE_PREPARING`）并展示 589556 逐项未满足项；「确认物资」挪到配置节点；移除物资门复判入口	24_8268（bfc1a32）	verified（hl-admin@72b5e17c）
#8269	确认后导摄 / 物资 / 订房计划 / 分房 / 需求确认与打回 / 正式用车需求 / 抢单池等写口一律拒绝	确认后隐藏或置灰上述配置写操作，按新文案提示（589598 / 808600 / 809111 等）；房务抢单池 `batchStatus` 筛选只保留「资源准备中」（其它值 400）	24_8269（bfc1a32）	pending
#8270	预支删除四项配齐门（589542 不再返回），配置节点起可提；#8322 再放开到招募中，进入核单后关闭	「发起预支」按钮不再按四项配齐置灰，按团期状态判断：招募中～出行完毕可用，核单中 / 已结算 / 已流团置灰	本条（接口 1）；另见 24_8322	已随 24_8322 交付（verified）
#8271	看板改七桶、统计条 13 键；分页 / 详情 / 看板行新增 `stage` / `stageName` / `tripSubStatus` / `tripSubStatusName`；核团 / 验团用语改核单 / 结算	看板页签与统计条切七桶（`total` 只等于七桶之和，不要对 `buckets` 整体求和）；详情步骤条按 `stage` / `tripSubStatus` 展示；文案「核团 / 验团」改「核单 / 结算」	24_8271（bfc1a32）	pending
#8308	发起流团、同意流团只在招募 / 配置；确认后 589544；审批中心与流团详情的流团行 `canApprove` 确认后恒 false	团期详情「流团」按钮在确认后（`stage` 不是 `RECRUIT` / `CONFIGURE`）隐藏；审批中心「同意」按钮只看 `canApprove`；589544 透传后端文案	本条（接口 2～5）	pending
#8309	`group-batch:contract:issue` 授团期管理员；团期确认后户确认行程自动出具合同保险	「合同保险」页签的出具 / 作废重开 / 催签按钮对 `GROUP_BATCH_MANAGER` 显示；确认后无需人工出具（自动出）	本条（接口 6～8）	pending
#8339	团期确认连带逐户确认行程；589556 改为「；」分段逐户回执；团期单在团期确认前单户确认返 581065；时间线新事件 `BATCH_SUB_ORDER_CONFIRM_FAILED`	团期单订单详情在团期确认前隐藏或置灰「确认行程」并处理 581065；589556 按「；」分段逐户展示；时间线显示新事件（`eventTypeName` 后端已给）	24_8339（846822a）	pending
#8340	团期单子订单出发 / 返团随团期（1007 不再推团期单，1041 / 1042 同步推子订单）	无代码改动。团期单子订单的「出行中」「已完成」时点改为跟随团期；团期没出发，子订单也不出发	无（定时任务行为变化，按豁免口径未推）	—
#8341	团期进入核单 / 结算 / 反结算同步子订单；团期结算有逐户核单未提交的户返 589568 并列订单 ID	团期结算处理 589568 新原因（提示先去对应订单提交逐户核单）；团期结算后不再引导逐户点「结算确认」，子订单核单 / 结算状态随团期	24_8341（846822a）	pending

按页面归并（同一页面的改动集中在这里，便于排期）：

页面	改动	来源
团期看板	页签与统计条七桶；阶段名改核单 / 结算	#8271
团期详情 · 步骤条	六节点 + 出行子状态，读 `stage` / `tripSubStatus`	#8271
团期详情 · 工具条	「确认」按钮（配置节点）；「流团」按钮只在招募 / 配置显示	#8268、#8308
团期详情 · 配置类页签（人员 / 物资 / 订房 / 分房 / 需求 / 用车）	确认后写操作隐藏或置灰；确认物资挪到配置节点	#8268、#8269
团期详情 · 财务	预支入口招募中～出行完毕可用	#8270、#8322
团期详情 · 合同保险	确认前不可出具；团期管理员可见出具 / 重开 / 催签	#8268、#8309、#8339
团期详情 · 结算	589568 未提交户提示	#8341
团期详情 · 时间线	新事件 `BATCH_SUB_ORDER_CONFIRM_FAILED`	#8339
团期审批中心	流团行「同意」按 `canApprove`	#8308
订单详情（团期单）	团期确认前隐藏「确认行程」，处理 581065	#8339
房务抢单池	`batchStatus` 筛选只留资源准备中	#8269

一、背景

jw 2026-09-23 定案团期六节点（SRS §0.27），2026-09-24 补充子订单跟随团期（§0.27.7）与流团收窄（§0.27.4 #2）。十张后端单均已合入 dev-v3、部署 TEST 并验收关单，其中五张推了 changelog；#8270、#8308、#8309 当时按「接口名 / 入参 / 出参 / 返回结构均未改」豁免未推，但三者都改变了前端按钮的可用条件或可见角色，本条补录。#8267、#8340 是定时任务行为变化，无前端代码改动，只在第〇节说明时机变化。

节点	持久态 `batchStatus`	派生 `stage`（#8271）	可流团	可预支	可出具合同保险
招募	`RECRUITING`	`RECRUIT`	✅	✅	❌
配置	`RESOURCE_PREPARING`	`CONFIGURE`	✅	✅	❌
确认	`MATERIAL_PREPARING`	`CONFIRM`	❌ 589544	✅	✅
出行	`PENDING_DEPARTURE` / `TRAVELLING` / `TRIP_FINISHED`	`TRIP`	❌ 589544	✅	✅
核单	`REVIEWING`	`REVIEW`	❌ 589544	❌ 589541	✅
结算	`SETTLED`	`SETTLE`	❌ 589544	❌ 589541	✅
已流团	`CANCELLED`	`DISBANDED`	❌ 589544	❌ 589541	❌ 589548

二、变更接口清单

#	接口	方法	路径	变更类型	说明
1	发起团期预支（GB-ADM-042）	POST	`/v3/admin/order/group-batch/{groupBatchId}/advance`	修改（前置门放宽 + 错误码停用 + 文案）	#8270：删除四项配齐门，589542 不再返回，配置节点起可提；当前口径（含 #8322）招募中～出行完毕
2	发起流团申请（GB-ADM-060）	POST	`/v3/admin/order/group-batch/{groupBatchId}/disband`	修改（前置门收窄 + 文案）	#8308：只在招募 / 配置可发起，确认后 589544，文案改
3	同意流团（GB-ADM-062）	POST	`/v3/admin/order/group-batch/disband/{approvalId}/approve`	修改（前置门收窄 + 文案）	#8308：团期已确认时拒绝执行 589544，申请仍待审批
4	团期审批中心列表（GB-ADM-061）	GET	`/v3/admin/order/group-batch/approvals/page`	修改（出参取值）	#8308：流团行 `canApprove` 在团期确认后恒 false
5	流团申请详情（GB-ADM-061）	GET	`/v3/admin/order/group-batch/disband/{approvalId}`	修改（出参取值）	#8308：`canApprove` 同接口 4
6	手动开合同 / 保险（GB-ADM-031）	POST	`/v3/admin/order/group-batch/{groupBatchId}/contracts/issue`	修改（授权角色）	#8309：团期管理员可调
7	作废重开合同 / 保险（GB-ADM-031）	POST	`/v3/admin/order/group-batch/{groupBatchId}/contracts/reissue`	修改（授权角色）	#8309：同上
8	批量催签合同	POST	`/v3/admin/order/group-batch/{groupBatchId}/contracts/remind-sign`	修改（授权角色）	#8309：同上

路径、HTTP 方法、入参、成功出参结构均不变；网关无改动（均在既有 /v3/admin/order/group-batch 前缀下）；无新增错误码；#8309 新增一条 user-service 权限种子，无 order-v3 schema 变更。

三、接口详情

1. 发起团期预支 `POST /v3/admin/order/group-batch/{groupBatchId}/advance`

VO: CreateGroupBatchAdvanceReqVO → OrderAdvanceRespVO

使用场景

团期详情「财务」页签点「发起预支」。#8270 起不再要求房 / 车 / 导游领队 / 摄影四项配齐，配置节点即可提；#8322 又把起点前移到招募中。下面按当前 dev-v3 代码（#8270 + #8322 合成态）描述，领款人限定主报账人（589557）的细节见 24_8322。

入参

字段	位置	类型	必填	约束	说明
groupBatchId	Path	Long	✅	订单侧团期主键	不存在 589500（不变）
payeeStaffId	Body	Long	✅	须为本团主报账人	取领款人候选接口返回的 `id`（#8322）
advanceType	Body	String	✅	字典 `advance_type`	借款类型（不变）
amount	Body	BigDecimal	✅	≥ 0.01 且 ≤ 团期统一池可用余额	超额 585004（不变）
purpose	Body	String	否	≤ 255 字	用途说明（不变）
voucherUrl	Body	String	否	≤ 512 字符	凭证 URL（不变）

出参

字段	类型	说明
id	Long(String)	预支单 ID（不变）
orderId	Long	团期级预支恒 null（不变）
payeeStaffId / payeeName / payeeRole	String	领款人快照（不变）
advanceType / amount / purpose / voucherUrl	-	同入参（不变）
status / statusText	String	创建后恒 `SUBMITTED` / 「待审批」（不变）
createdByName / createTime / submittedAt	String	发起人与时间（不变）

请求示例

POST /v3/admin/order/group-batch/2102696181195001858/advance HTTP/1.1
Host: api.test.1814.love:9443
Authorization: Bearer <admin token>
Content-Type: application/json

{
  "payeeStaffId": 1002,
  "advanceType": "TICKET",
  "amount": 100,
  "purpose": "门票备用金"
}

响应示例

{
  "code": 200,
  "message": "成功",
  "data": {
    "id": "2102968264214872066",
    "orderId": null,
    "payeeStaffId": "1002",
    "payeeName": "李雪梅",
    "payeeRole": "GUIDE",
    "advanceType": "TICKET",
    "amount": 100,
    "purpose": "门票备用金",
    "voucherUrl": null,
    "status": "SUBMITTED",
    "statusText": "待审批",
    "createdByName": "admin",
    "createTime": "2026-09-24 11:48:00",
    "submittedAt": "2026-09-24 11:48:00"
  },
  "success": true
}

空数据 / 降级响应

写接口，无空数据形态；任何校验失败零写入。时间线 BATCH_ADVANCE 写入失败只降级告警，不影响预支单创建（不变）。

{ "code": 200, "message": "成功", "data": { "id": "2102968264214872066", "status": "SUBMITTED" }, "success": true }

错误响应

团期处于核单中 / 已结算 / 已流团（文案为当前代码值，见六.6 沿革）：

{
  "code": 589541,
  "message": "当前团期状态不可发起预支（进入核单后关闭）",
  "success": false,
  "data": null
}

code	触发	说明
589541	`batchStatus` 不在招募中～出行完毕	文案两次变化，见六.6
589542	—	#8270 起不再返回（四项配齐门已删除，码位保留不复用）
585007 / 589557	领款人不在本团 / 不是主报账人	见 24_8322
585004	超团期统一池可用余额	不变
589507	角色无 `group-batch:finance:advance`	不变（团期管理员仍未授此码）

业务边界

允许状态：RECRUITING、RESOURCE_PREPARING、MATERIAL_PREPARING、PENDING_DEPARTURE、TRAVELLING、TRIP_FINISHED；REVIEWING / SETTLED / CANCELLED 拒 589541。
#8270 本身只加了 RESOURCE_PREPARING 并删四项门；RECRUITING 由 #8322 放开。
只看团期状态、不看四项 ready 位；超支仍由团期统一池上限兜住。
校验顺序：589500 → 589541 → 585007 → 589557 → 借款类型 → 585004。

2. 发起流团申请 `POST /v3/admin/order/group-batch/{groupBatchId}/disband`

VO: DisbandSubmitReqVO → DisbandApprovalRespVO

使用场景

团期详情工具条「流团」按钮，提交流团审批申请（批准后才真正流团）。#8308 起只在招募、配置两个节点可发起；团期人工确认之后（确认 / 出行 / 核单 / 结算）一律拒绝，确认后单户退出走退单审批。

入参

字段	位置	类型	必填	约束	说明
groupBatchId	Path	Long	✅	团期主键	不变
reason	Body	String	✅	非空，≤ 512 字	流团理由（不变）

出参

字段	类型	说明
approvalId	Long	审批单 ID（不变）
groupBatchId / batchNo / batchName / batchLabel	-	团期信息（不变）
approvalStatus / approvalStatusName	String	新建恒 `PENDING` / 「待审批」（不变）
affectedOrderCount / participantCount / estimatedRefundAmount	-	提交时快照（不变）
applicantId / applicantName / ccUserNames / createTime	-	不变
canApprove	Boolean	当前用户能否批；口径见接口 5（本次新增阶段条件）

请求示例

{
  "reason": "临近出团仍未达最低成团数（6 户）"
}

响应示例

{
  "code": 200,
  "message": "成功",
  "data": {
    "approvalId": "2102949786913333999",
    "groupBatchId": "2102946606599028738",
    "batchNo": "GT-26-0004",
    "batchName": "小蒙马夏季亲子营",
    "batchLabel": "1",
    "approvalStatus": "PENDING",
    "approvalStatusName": "待审批",
    "reason": "临近出团仍未达最低成团数（6 户）",
    "affectedOrderCount": 1,
    "participantCount": 2,
    "estimatedRefundAmount": 0.00,
    "actualRefundAmount": null,
    "applicantName": "团期管理员",
    "ccUserNames": [],
    "canApprove": false
  },
  "success": true
}

空数据 / 降级响应

团期下无活跃子订单时照常建单，affectedOrderCount=0、estimatedRefundAmount=0、ccUserNames 为空数组（不变）：

{ "code": 200, "message": "成功", "data": { "approvalStatus": "PENDING", "affectedOrderCount": 0, "estimatedRefundAmount": 0, "ccUserNames": [] }, "success": true }

错误响应

团期已确认（MATERIAL_PREPARING 及之后，含已结算 / 已流团）：

{
  "code": 589544,
  "message": "团期已确认，不可发起或批复流团",
  "success": false,
  "data": null
}

code	触发	说明
589544	团期不在 `RECRUITING` / `RESOURCE_PREPARING`	口径收窄 + 文案改（原「团期已出行，…」）
589543	已有一条待审批流团申请	不变
589554	团期下有出行中的子订单	不变
589507	无 `group-batch:manage`	不变

业务边界

判定顺序：589507 → 589500 → 589544 → 589543 → 589554。
改前 MATERIAL_PREPARING / PENDING_DEPARTURE 可发起，改后拒 589544。
只建申请单、写团期时间线 BATCH_DISBAND_SUBMIT，不动团期、子订单、名额和钱（不变）。

3. 同意流团 `POST /v3/admin/order/group-batch/disband/{approvalId}/approve`

VO: ApproveDisbandReqVO → DisbandApprovalRespVO

使用场景

审批中心 / 流团详情的「同意」。批准后才执行流团（团期置已流团、逐户退款、释放配车）。#8308 起执行前再按团期当前状态判一次：配置节点提交、批复前团期已被人工确认的申请，同意时拒绝执行。

入参

字段	位置	类型	必填	约束	说明
approvalId	Path	Long	✅	流团审批单 ID	不存在 589545（不变）
remark	Body	String	否	≤ 512 字	批复备注；请求体可省略（不变）

出参

字段	类型	说明
approvalStatus / approvalStatusName	String	成功后 `APPROVED` / 「已通过」（不变）
actualRefundAmount	BigDecimal	已发起退款金额（不变）
approvedById / approvedByName / approvedAt / approveRemark	-	批复信息（不变）
canApprove	Boolean	已处理恒 false（不变）
其余字段	-	同接口 2（不变）

请求示例

{
  "remark": "确认无法成团，同意流团"
}

响应示例

{
  "code": 200,
  "message": "成功",
  "data": {
    "approvalId": "2102949786913333999",
    "groupBatchId": "2102946606599028738",
    "approvalStatus": "APPROVED",
    "approvalStatusName": "已通过",
    "actualRefundAmount": 0.00,
    "approvedByName": "admin",
    "approveRemark": "确认无法成团，同意流团",
    "canApprove": false
  },
  "success": true
}

空数据 / 降级响应

请求体可整体不传（不变）；退款单由提交后的异步监听建出，actualRefundAmount 先落暂定值、提交后回读定稿（不变）。

{}

错误响应

团期在申请提交后被人工确认（或已进入出行 / 核单）：

{
  "code": 589544,
  "message": "团期已确认，不可发起或批复流团",
  "success": false,
  "data": null
}

code	触发	说明
589544	团期当前不在招募 / 配置，且不是终态	口径收窄 + 文案改；整笔回滚，申请仍 `PENDING`、团期状态不变
589501	团期已结算 / 已流团	不变
589547	非管理员（ADMIN / SUPER_ADMIN）批复	不变
589546	申请已处理	不变
589554	有出行中子订单	不变

业务边界

阶段判定走 CAS 白名单（与发起共用同一集合），确认后到达的批复 CAS 落空即拒，不会半执行。
被 589544 拒的申请不会自动关闭：审批中心 canApprove=false 不再显示「同意」，需人工「驳回」（驳回接口不看团期阶段，不变）。
团期流团的前端入口也应随团期确认隐藏（见接口 2）。

4. 团期审批中心列表 `GET /v3/admin/order/group-batch/approvals/page`

VO: GroupBatchApprovalListReqVO → PageResult<GroupBatchApprovalItemRespVO>

使用场景

团期审批中心统一列表（流团 + 退单户）。「同意」按钮以 canApprove 为准。#8308 起流团行多一个条件：团期仍在招募 / 配置。退单户行口径不变。

入参

字段	位置	类型	必填	约束	说明
bizType	Query	String	否	`DISBAND` / `WITHDRAW`	不传两类都要（不变）
approvalStatus	Query	String	否	`PENDING` / `APPROVED` / `REJECTED`	不变
groupBatchId	Query	Long	否	-	不变
batchName	Query	String	否	-	团期名称 / 期号搜索（不变）
pageNum	Query	Integer	否	≥ 1	默认 1（不变）
pageSize	Query	Integer	否	1～100	默认 20（不变）

出参

字段	类型	说明
records[].canApprove	Boolean	取值口径变化：流团行 = 管理员角色且 `PENDING` 且团期存在且团期 `batchStatus ∈ {RECRUITING, RESOURCE_PREPARING}`；团期确认后恒 false
records[].bizType / approvalStatus / groupBatchId / batchName 等	-	不变
total / pageNum / pageSize	-	不变

请求示例

GET /v3/admin/order/group-batch/approvals/page?bizType=DISBAND&approvalStatus=PENDING&pageNum=1&pageSize=20 HTTP/1.1
Host: api.test.1814.love:9443
Authorization: Bearer <admin token>

响应示例

{
  "code": 200,
  "message": "成功",
  "data": {
    "records": [
      {
        "approvalId": "2102949786913334001",
        "bizType": "DISBAND",
        "bizTypeName": "流团",
        "groupBatchId": "2102949786913333250",
        "batchName": "小蒙马夏季亲子营",
        "approvalStatus": "PENDING",
        "approvalStatusName": "待审批",
        "orderId": null,
        "affectedOrderCount": 1,
        "canApprove": false
      }
    ],
    "total": 1,
    "pageNum": 1,
    "pageSize": 20
  },
  "success": true
}

空数据 / 降级响应

无匹配时空页（不变）：

{ "code": 200, "message": "成功", "data": { "records": [], "total": 0, "pageNum": 1, "pageSize": 20 }, "success": true }

错误响应

{
  "code": 589507,
  "message": "无操作权限（当前角色未授予团期权限，或该团期不在您名下）",
  "success": false,
  "data": null
}

业务边界

canApprove=false 的待审批流团行仍会出现在列表里（状态仍是待审批），前端只隐藏「同意」，保留「驳回」。
退单户行（WITHDRAW）的 canApprove 口径不变。
非管理员角色（如 FINANCE）恒 false（不变）。

5. 流团申请详情 `GET /v3/admin/order/group-batch/disband/{approvalId}`

VO: DisbandApprovalRespVO

使用场景

审批中心点开流团申请的详情抽屉；「同意」按钮以 canApprove 为准，与列表同口径。

入参

字段	位置	类型	必填	约束	说明
approvalId	Path	Long	✅	流团审批单 ID	不存在 589545（不变）

出参

字段	类型	说明
canApprove	Boolean	取值口径变化：`PENDING` 且团期 `batchStatus ∈ {RECRUITING, RESOURCE_PREPARING}` 且管理员角色；团期确认后恒 false
其余字段	-	同接口 2（不变）

请求示例

GET /v3/admin/order/group-batch/disband/2102949786913334001 HTTP/1.1
Host: api.test.1814.love:9443
Authorization: Bearer <admin token>

响应示例

{
  "code": 200,
  "message": "成功",
  "data": {
    "approvalId": "2102949786913334001",
    "groupBatchId": "2102949786913333250",
    "approvalStatus": "PENDING",
    "approvalStatusName": "待审批",
    "reason": "临近出团仍未达最低成团数",
    "affectedOrderCount": 1,
    "estimatedRefundAmount": 0.00,
    "approvedByName": null,
    "canApprove": false
  },
  "success": true
}

空数据 / 降级响应

团期已软删时 batchNo / batchName 为 null、canApprove=false（不变）：

{ "code": 200, "message": "成功", "data": { "approvalStatus": "PENDING", "batchNo": null, "canApprove": false }, "success": true }

错误响应

{
  "code": 589545,
  "message": "流团申请不存在",
  "success": false,
  "data": null
}

业务边界

与接口 4 同一判据（共用可流团状态集），两处不会不一致。
与接口 3 的拒绝条件一致：canApprove=false 时点「同意」必得 589544。

6. 手动开合同 / 保险 `POST /v3/admin/order/group-batch/{groupBatchId}/contracts/issue`

VO: GroupBatchContractIssueReqVO → GroupBatchIssueResultVO

使用场景

「合同保险」页签逐户手动开合同 / 保险。#8309 起团期管理员也能用（此前只有 ADMIN / SUPER_ADMIN）。团期确认后户确认行程会自动出具，本接口是出具失败时的人工补出通路。出具门口径见 24_8268 / 24_8339，本次不变。

入参

字段	位置	类型	必填	约束	说明
groupBatchId	Path	Long	✅	团期主键	不变
orderIds	Body	List<Long>	否	须属本团	为空 = 本期全部活跃户（不变）
target	Body	String	✅	`CONTRACT` / `INSURANCE` / `BOTH`	不变

出参

字段	类型	说明
totalCount / successCount / failCount / skipCount	Integer	不变
results[].orderId / target / outcome / message	-	`outcome` ∈ `SUCCESS` / `SKIPPED` / `FAILED`（不变）

请求示例

{
  "orderIds": ["2102947020270653443"],
  "target": "CONTRACT"
}

响应示例

团期管理员调用，该户已自动出具（TEST 实测形态）：

{
  "code": 200,
  "message": "成功",
  "data": {
    "totalCount": 1,
    "successCount": 0,
    "failCount": 0,
    "skipCount": 1,
    "results": [
      { "orderId": "2102947020270653443", "target": "CONTRACT", "outcome": "SKIPPED", "message": "该户合同已出具，自动跳过" }
    ]
  },
  "success": true
}

空数据 / 降级响应

本期无活跃户时 totalCount=0、results 为空数组（不变）：

{ "code": 200, "message": "成功", "data": { "totalCount": 0, "successCount": 0, "failCount": 0, "skipCount": 0, "results": [] }, "success": true }

错误响应

角色未授 group-batch:contract:issue（ROOM_MANAGER / VEHICLE_MANAGER / CUSTOMIZER / FINANCE 等）：

{
  "code": 589507,
  "message": "无操作权限（当前角色未授予团期权限，或该团期不在您名下）",
  "success": false,
  "data": null
}

code	触发	说明
589507	角色未授码	团期管理员不再返回；其余角色不变
589548	团期未确认	不变（24_8268 / 24_8339）
589549	`target` 非法	不变
589512	`orderIds` 含非本团订单	不变

业务边界

授权：ADMIN、SUPER_ADMIN、GROUP_BATCH_MANAGER（本次新增）；其余角色 589507。
权限码缓存 10 分钟：部署后最长 10 分钟内团期管理员仍可能 589507，之后自动生效（TEST 已过缓存验证）。
判权顺序：589507 → 589500 → 589548 → 目标解析。

7. 作废重开合同 / 保险 `POST /v3/admin/order/group-batch/{groupBatchId}/contracts/reissue`

VO: GroupBatchContractIssueReqVO → GroupBatchIssueResultVO

使用场景

「开错」态的补救通路：先作废该户现有单据再重开。授权与接口 6 相同，团期管理员可用。

入参

字段	位置	类型	必填	约束	说明
groupBatchId	Path	Long	✅	团期主键	不变
orderIds	Body	List<Long>	否	须属本团	不变
target	Body	String	✅	`CONTRACT` / `INSURANCE` / `BOTH`	不变
reason	Body	String	否	-	作废原因（不变）

出参

字段	类型	说明
totalCount / successCount / failCount / skipCount	Integer	不变
results[]	List	逐户结果（不变）

请求示例

{
  "orderIds": ["2102947020270653443"],
  "target": "CONTRACT",
  "reason": "方案选错"
}

响应示例

{
  "code": 200,
  "message": "成功",
  "data": {
    "totalCount": 1,
    "successCount": 1,
    "failCount": 0,
    "skipCount": 0,
    "results": [
      { "orderId": "2102947020270653443", "target": "CONTRACT", "outcome": "SUCCESS", "message": null }
    ]
  },
  "success": true
}

空数据 / 降级响应

作废失败的户记 FAILED、不进重开，不影响其他户（不变）：

{ "code": 200, "message": "成功", "data": { "totalCount": 1, "successCount": 0, "failCount": 1, "skipCount": 0, "results": [] }, "success": true }

错误响应

{
  "code": 589507,
  "message": "无操作权限（当前角色未授予团期权限，或该团期不在您名下）",
  "success": false,
  "data": null
}

业务边界

与接口 6 同一权限码、同一出具门；团期管理员改前 589507，改后放行。
重开后旧合同 VOIDED、新合同 GENERATED（TEST 实测）。

8. 批量催签合同 `POST /v3/admin/order/group-batch/{groupBatchId}/contracts/remind-sign`

VO: GroupBatchContractRemindReqVO → GroupBatchIssueResultVO

使用场景

「合同保险」页签「批量催签」，只对合同已出未签的户发短信。授权与接口 6 相同，团期管理员可用。

入参

字段	位置	类型	必填	约束	说明
groupBatchId	Path	Long	✅	团期主键	不变
orderIds	Body	List<Long>	否	须属本团	为空 = 本期全部已出未签户；请求体可省略（不变）

出参

字段	类型	说明
totalCount / successCount / failCount / skipCount	Integer	不变
results[].target	String	恒 `CONTRACT`（不变）
results[].outcome / message	String	未出具或已签的户 `SKIPPED`（不变）

请求示例

{
  "orderIds": ["2102947020270653443"]
}

响应示例

{
  "code": 200,
  "message": "成功",
  "data": {
    "totalCount": 1,
    "successCount": 1,
    "failCount": 0,
    "skipCount": 0,
    "results": [
      { "orderId": "2102947020270653443", "target": "CONTRACT", "outcome": "SUCCESS", "message": null }
    ]
  },
  "success": true
}

空数据 / 降级响应

没有已出未签的户时全部 SKIPPED，不发短信、不写时间线（不变）：

{ "code": 200, "message": "成功", "data": { "totalCount": 1, "successCount": 0, "failCount": 0, "skipCount": 1, "results": [ { "target": "CONTRACT", "outcome": "SKIPPED", "message": "该户合同未出具或已签署，无需催签" } ] }, "success": true }

错误响应

{
  "code": 589507,
  "message": "无操作权限（当前角色未授予团期权限，或该团期不在您名下）",
  "success": false,
  "data": null
}

业务边界

本接口不受出具门约束（合同能催签说明已出具，不变）。
团期管理员改前 589507，改后放行；其余角色不变。

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

✅ 正确 / ❌ 错误调用对照

场景	调用
✅ 流团按钮可见性	团期 `stage ∈ {RECRUIT, CONFIGURE}` 才显示「流团」
❌ 确认后仍显示流团按钮	点了必 589544
✅ 审批中心「同意」	直接读 `canApprove`；false 时只给「驳回」
❌ 前端自己按 `approvalStatus=PENDING` 显示「同意」	团期确认后点了必 589544
✅ 预支按钮	`batchStatus` 在核单之前（招募中～出行完毕）可用
❌ 按四项配齐置灰预支	四项门已删除，会误挡
✅ 合同保险出具 / 重开 / 催签按钮	对 ADMIN / SUPER_ADMIN / GROUP_BATCH_MANAGER 显示；是否可点再看面板 `issuable`（重开 / 出具）
❌ 只对 ADMIN 显示	团期管理员无入口，只能找管理员代点

按钮显隐速查（按 `stage`）

按钮	RECRUIT	CONFIGURE	CONFIRM	TRIP	REVIEW	SETTLE	DISBANDED
流团	✅	✅	❌	❌	❌	❌	❌
发起预支	✅	✅	✅	✅	❌	❌	❌
确认（#8268）	❌	✅	❌	❌	❌	❌	❌
合同保险出具 / 重开	❌	❌	✅	✅	✅	✅	❌
配置类写操作（#8269）	✅	✅	❌	❌	❌	❌	❌

精确判定以 batchStatus 为准（stage 由其派生）；配置类写操作各接口的细分口径（如订房计划仅配置节点）见 24_8269。

错误码处理

589544：透传后端文案即可；新文案「团期已确认，不可发起或批复流团」。按旧文案「团期已出行」做过字符串匹配的要改。
589541：透传；文案两次变化，勿做字符串匹配。
589542：不再返回，针对它的分支可删除。

五、数据库行为

前端动作	外部可观察的写入
发起预支成功	`order_advance` 一行（`scope=GROUP_BATCH`）+ 时间线 `BATCH_ADVANCE`（不变）；被 589541 拒零写入
发起流团成功	`group_batch_approval` 一行 `PENDING` + 时间线 `BATCH_DISBAND_SUBMIT`（不变）；被 589544 拒零写入
同意流团被 589544 拒	整笔回滚：审批单仍 `PENDING`、团期状态不变、子订单不取消
审批中心 / 详情读	只读
团期管理员出具 / 重开 / 催签	与管理员调用相同的合同 / 保险 / 短信写入（不变）

Schema / 数据变更：order-v3 零 schema 变更。hl-user-service 新增 Flyway V20260924_8309__grant_group_batch_manager_contract_issue.sql：向 admin_role_permission 按 role_key='GROUP_BATCH_MANAGER' 与 permission_code='group-batch:contract:issue' 子查询 INSERT IGNORE 一行（幂等，角色或权限码不存在时零行）。TEST 已于 2026-09-24 10:16:17 执行。

六、边界行为

未登录 → 401（网关拦截）；团期不存在 → 589500。
确认前提交、确认时仍待审批的流团申请停在 PENDING：canApprove=false，只能驳回；后端不自动关闭（产品待定，见六.7）。
流团驳回（POST .../disband/{approvalId}/reject）不看团期阶段，确认后仍可驳回，用于清理上述申请。
流团批复判的是批复那一刻的团期状态，不是提交时的。
已流团 / 已结算团期发起流团返 589544，同意流团返 589501（不变的区分）。
团期管理员授权有 10 分钟权限缓存。
预支领款人为主报账人、候选接口只返回主报账人，见 24_8322。

六.5、枚举 / 数据字典

错误码（本条涉及，均为既有码）

码	当前文案	本条变化
589541	当前团期状态不可发起预支（进入核单后关闭）	触发区间收窄为核单中 / 已结算 / 已流团；文案改
589542	房 / 车 / 导 / 摄四项配齐后才能预支	不再抛出，码位保留
589544	团期已确认，不可发起或批复流团	触发区间扩大到确认及之后；文案改
589507	无操作权限（当前角色未授予团期权限，或该团期不在您名下）	团期管理员调合同保险三接口不再触发

角色 × 合同保险写权限（`group-batch:contract:issue`）

角色	改前	改后
SUPER_ADMIN / ADMIN	✅	✅
GROUP_BATCH_MANAGER	❌ 589507	✅
FINANCE / CUSTOMIZER / ROOM_MANAGER / VEHICLE_MANAGER 等	❌ 589507	❌ 589507

六.6、修改前后对比

字段级对比

字段 / 码	改前	改后
预支允许状态	`MATERIAL_PREPARING`～`TRIP_FINISHED` 且四项 ready	#8270：`RESOURCE_PREPARING`～`TRIP_FINISHED`；#8322：`RECRUITING`～`TRIP_FINISHED`；不看四项
589541 文案	当前团期状态不可发起预支（须为物料准备中 / 待出发 / 出行中）	#8270：…（须在资源准备中至出行完毕之间，进入核单后关闭）→ #8322：当前团期状态不可发起预支（进入核单后关闭）
589542	四项未齐时返回	不再返回
流团发起 / 批复允许状态	`RECRUITING` / `RESOURCE_PREPARING` / `MATERIAL_PREPARING` / `PENDING_DEPARTURE`	`RECRUITING` / `RESOURCE_PREPARING`
589544 文案	团期已出行，不可发起或批复流团	团期已确认，不可发起或批复流团
流团行 `canApprove`	管理员 + `PENDING` + 团期存在	另加团期在招募 / 配置
团期管理员调 contracts/issue、reissue、remind-sign	589507	放行

行为级对比

行为	改前	改后
确认后流团	可发起、可批复（至待出发）	发起、批复均 589544
确认前提交、确认后批复	批复执行流团	拒绝执行，申请仍待审批
预支入口	四项配齐后	进入核单前
合同保险人工补出	只有管理员	团期管理员也可
团期确认后户确认行程	自动出具（逐户事件）	不变；#8339 起由团期确认逐户驱动

六.7、影响评估

是否破坏向后兼容: 部分是。确认后仍显示流团按钮 / 按 PENDING 显示「同意」的前端会让用户点出 589544；按四项配齐置灰预支的前端会误挡；按旧 589544 文案做字符串匹配的要改。结构均不变，不会解析失败。
前端是否必须同步上线: 建议同步。不改时后端仍正确拦截，只是按钮可点但报错、团期管理员缺入口。
待产品裁决: 确认前提交、确认时仍待审批的流团申请是否要在团期确认时自动驳回（当前需人工驳回，#8308 验收评论已记）。
前端 workaround 清理点: 删除 589542 分支；流团 / 同意按钮改读 stage / canApprove；合同保险按钮角色白名单加 GROUP_BATCH_MANAGER。

七、不影响范围

仅影响: 团期预支状态门、流团发起 / 批复阶段门与 canApprove、合同保险三个写接口的授权角色。
零影响:
- 流团驳回 POST /v3/admin/order/group-batch/disband/{approvalId}/reject（不看团期阶段，不变）
- 退单户审批（GB-ADM-070～074）及审批中心退单户行的 canApprove
- 团期预支领款人候选、财务总览、预支记录（候选口径见 24_8322）
- 合同保险面板 GET .../contracts 与出具门（见 24_8268 / 24_8339）
- 团期管理员的其它权限（仍不授 group-batch:finance:advance）
- 小程序端
第〇节列出的其余单的接口细节以各自 changelog 为准，本条不重复。

八、测试环境已验证

均为 TEST 环境真实网关实测，证据见各单验收评论；三单均已验收关单。

#8270（dev-v3 @ b212cb708，2026-09-23 17:47–17:49；构建身份：配置节点团期配不存在的领款人得 585007 而非 589541）

#	场景	结果
1	`RESOURCE_PREPARING` 且四项 ready 0/0/0/0	200 `SUBMITTED`，`order_advance` 落 1 行，时间线 `BATCH_ADVANCE`
2	`MATERIAL_PREPARING` / `PENDING_DEPARTURE` / `TRAVELLING` / `TRIP_FINISHED`	均 200
3	`RECRUITING` / `REVIEWING` / `SETTLED` / `CANCELLED`	均 589541、零写入（其中 `RECRUITING` 已被 #8322 放开，11:47 复测招募中 200）
4	可用 5890.00：提 5890.01 / 5890 / 再 0.01	585004 / 200 / 585004
5	ROOM_MANAGER / VEHICLE_MANAGER	589507

#8308（dev-v3 @ 3cd787713 / b2e7140e3，2026-09-24 10:22–10:36；构建身份：589544 返回新文案）

#	场景	结果
1	招募中、配置节点团期：团期管理员发起 → ADMIN 同意	`PENDING` → `APPROVED`，团期 `CANCELLED`，订单取消
2	团期依次置 `MATERIAL_PREPARING` / `PENDING_DEPARTURE` / `TRAVELLING` / `TRIP_FINISHED` / `REVIEWING` / `SETTLED` 后发起	均 589544，状态不变，申请行 0→0
3	配置节点提交（`PENDING`）→ 团期管理员真实 confirm → ADMIN 同意	589544；团期仍 `MATERIAL_PREPARING`，申请仍 `PENDING`，子订单未取消
4	团期 2102949786913333250 确认前：ADMIN 看列表与详情	`canApprove=true`（FINANCE 对照 false）
5	同团真实 confirm 后：列表与详情	两处均 `canApprove=false`，申请仍 `PENDING`；点同意 589544

#8309（dev-v3 @ 3cd787713，2026-09-24 10:24–10:29；Flyway 20260924.8309 于 10:16:17 执行，判权测试在 10:27:30 过缓存后执行，未用超管）

#	场景	结果
1	团期人工确认后 A 户确认行程	1 秒内自动出具：合同 1 份（mock 自动签约 SIGNED）+ 保险 2 条 INSURED，`order_main` 同步；未确认行程的 B 户不出具
2	ROOM_MANAGER / VEHICLE_MANAGER / CUSTOMIZER × 出具 / 重开 / 催签	9 次全 589507
3	GROUP_BATCH_MANAGER 出具	过判权，`SKIPPED`（已出具）
4	GROUP_BATCH_MANAGER 作废重开合同	`SUCCESS`，旧合同 `VOIDED`、新合同 `GENERATED`
5	GROUP_BATCH_MANAGER 催签新合同	`SUCCESS`

本地：#8270 GroupBatchAdvanceServiceTest 17 例 + 错误码守卫 20 例；#8308 相关单测 373 例 + Docker IT 27 例；#8309 迁移测试与 GroupBatchIssueGateListenerChainTest 等，均 0 失败。

九、相关历史 PR

PR	Issue	说明	是否仍有效
#8272	#8270	预支配置节点起可提、删四项门	✅（起点已被 #8323 再前移到招募中）
#8323	#8322	预支招募中可提、领款人限主报账人	✅ 最新
#8313	#8308	流团收窄到确认之前，589544 文案	✅
#8315	#8308	审批中心 / 详情流团行 `canApprove` 加阶段条件	✅
#8312	#8309	`group-batch:contract:issue` 授团期管理员	✅

十、相关文档

关联 Issue: wx/HL#8355；补录 #8270、#8308、#8309
关联 PR: #8272、#8313、#8315、#8312
需求依据：SRS §0.27 / §0.27.7（docs/group/团期模块一期实施拆分详细设计-v1.0.html，dev-v3）
同批 changelog：
- changelogs-v2/2026-09/24_8268_团期人工确认端点与确认后才出合同保险-新增接口-管理后台.md
- changelogs-v2/2026-09/24_8269_团期确认后锁定配置各写口收紧到配置阶段-修改接口-管理后台.md
- changelogs-v2/2026-09/24_8271_团期看板与详情按六节点展示看板改七桶-修改接口-管理后台.md
- changelogs-v2/2026-09/24_8339_团期确认联动子订单确认行程与团期单禁单户确认581065-修改接口-管理后台.md
- changelogs-v2/2026-09/24_8341_团期核单结算反结算同步子订单与结算589568列未提交户-修改接口-管理后台.md
- changelogs-v2/2026-09/24_8322_团期预支核单前均可发起与领款人限定主报账人-修改接口-管理后台.md

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

团期六节点流程前端对接总览 + 预支 / 流团 / 合同保险出具权限补录（管理后台）

⚠️ 关键变化

〇、前端改动总清单（十张单）

一、背景

二、变更接口清单

三、接口详情

1. 发起团期预支 POST /v3/admin/order/group-batch/{groupBatchId}/advance

使用场景

入参

出参

请求示例

响应示例

空数据 / 降级响应

错误响应

业务边界

2. 发起流团申请 POST /v3/admin/order/group-batch/{groupBatchId}/disband

使用场景

入参

出参

请求示例

响应示例

空数据 / 降级响应

错误响应

业务边界

3. 同意流团 POST /v3/admin/order/group-batch/disband/{approvalId}/approve

使用场景

入参

出参

请求示例

响应示例

空数据 / 降级响应

错误响应

业务边界

4. 团期审批中心列表 GET /v3/admin/order/group-batch/approvals/page

使用场景

入参

出参

请求示例

响应示例

空数据 / 降级响应

错误响应

业务边界

5. 流团申请详情 GET /v3/admin/order/group-batch/disband/{approvalId}

使用场景

入参

出参

请求示例

响应示例

空数据 / 降级响应

错误响应

业务边界

6. 手动开合同 / 保险 POST /v3/admin/order/group-batch/{groupBatchId}/contracts/issue

使用场景

入参

出参

请求示例

响应示例

空数据 / 降级响应

错误响应

业务边界

7. 作废重开合同 / 保险 POST /v3/admin/order/group-batch/{groupBatchId}/contracts/reissue

使用场景

入参

出参

请求示例

响应示例

空数据 / 降级响应

错误响应

业务边界

8. 批量催签合同 POST /v3/admin/order/group-batch/{groupBatchId}/contracts/remind-sign

使用场景

入参

出参

请求示例

响应示例

空数据 / 降级响应

错误响应

业务边界

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

47 KiB

原始文件 Blame 文件历史

1. 发起团期预支 `POST /v3/admin/order/group-batch/{groupBatchId}/advance`

2. 发起流团申请 `POST /v3/admin/order/group-batch/{groupBatchId}/disband`

3. 同意流团 `POST /v3/admin/order/group-batch/disband/{approvalId}/approve`

4. 团期审批中心列表 `GET /v3/admin/order/group-batch/approvals/page`

5. 流团申请详情 `GET /v3/admin/order/group-batch/disband/{approvalId}`

6. 手动开合同 / 保险 `POST /v3/admin/order/group-batch/{groupBatchId}/contracts/issue`

7. 作废重开合同 / 保险 `POST /v3/admin/order/group-batch/{groupBatchId}/contracts/reissue`

8. 批量催签合同 `POST /v3/admin/order/group-batch/{groupBatchId}/contracts/remind-sign`

按钮显隐速查（按 `stage`）

角色 × 合同保险写权限（`group-batch:contract:issue`）