1019 行
47 KiB
Markdown
1019 行
47 KiB
Markdown
---
|
||
schema: "hl-changelog/v2"
|
||
ticket: "8355"
|
||
title: "团期六节点流程前端对接总览：十张单前端改动一张表；补录三处未推 changelog 的行为变化——预支核单前均可发起且去掉四项配齐门（#8270）、流团只能在确认前发起与批复且审批中心 canApprove 确认后恒 false（#8308）、合同保险出具 / 重开 / 催签授团期管理员（#8309）"
|
||
consumer: "admin"
|
||
author: "jw(GIT)"
|
||
change_type: "修改接口"
|
||
backend_status: "deployed"
|
||
gateway_status: "verified"
|
||
frontend_status: "verified"
|
||
frontend_owner: "mmg"
|
||
frontend_ref: "7ddbb7d940399e2b7fc6f73e10183032b8fa9ed7"
|
||
target_release: "v2.1"
|
||
verified_at: "2026-09-26"
|
||
status_note: "团期流程改为六节点（招募 → 配置 → 确认 → 出行 → 核单 → 结算，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 例全绿。"
|
||
updated_at: "2026-09-24"
|
||
base: "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
|
||
> **影响范围**: 管理后台团期详情（工具条、步骤条、财务 / 合同保险 / 配置各页签）、团期看板、团期审批中心、订单详情（团期单）、房务抢单池
|
||
|
||
---
|
||
|
||
## ⚠️ 关键变化
|
||
|
||
1. **前端改动一次看全**：第〇节按工单列出十张单各自要改的前端位置和对应 changelog，已推的五份（24_8268 / 24_8269 / 24_8271 / 24_8339 / 24_8341）与 24_8322 不重复展开，只给指引。
|
||
2. **流团只能在「确认」之前发起**（#8308）：团期进入确认（`MATERIAL_PREPARING`）及之后，发起流团、同意流团一律返 **589544**，文案改为「团期已确认，不可发起或批复流团」。团期详情的「流团」按钮在确认后应隐藏。
|
||
3. **审批中心流团行 `canApprove` 在团期确认后恒 false**（#8308）：列表与流团详情两处同口径，前端按 `canApprove` 显示「同意」即可，不要自己拼条件。确认前提交、确认时还没批的流团申请会停在待审批，只能驳回。
|
||
4. **团期管理员可以出具 / 重开 / 催签合同保险**（#8309）：`group-batch:contract:issue` 新授 `GROUP_BATCH_MANAGER`。登录信息不下发权限码，前端若按角色控制这三个按钮，需要把团期管理员加进去。
|
||
5. **预支不再要求四项配齐**（#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 | 发起人与时间（不变） |
|
||
|
||
#### 请求示例
|
||
|
||
```http
|
||
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": "门票备用金"
|
||
}
|
||
```
|
||
|
||
#### 响应示例
|
||
|
||
```json
|
||
{
|
||
"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` 写入失败只降级告警，不影响预支单创建（不变）。
|
||
|
||
```json
|
||
{ "code": 200, "message": "成功", "data": { "id": "2102968264214872066", "status": "SUBMITTED" }, "success": true }
|
||
```
|
||
|
||
#### 错误响应
|
||
|
||
团期处于核单中 / 已结算 / 已流团（文案为当前代码值，见六.6 沿革）：
|
||
|
||
```json
|
||
{
|
||
"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（本次新增阶段条件） |
|
||
|
||
#### 请求示例
|
||
|
||
```json
|
||
{
|
||
"reason": "临近出团仍未达最低成团数（6 户）"
|
||
}
|
||
```
|
||
|
||
#### 响应示例
|
||
|
||
```json
|
||
{
|
||
"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` 为空数组（不变）：
|
||
|
||
```json
|
||
{ "code": 200, "message": "成功", "data": { "approvalStatus": "PENDING", "affectedOrderCount": 0, "estimatedRefundAmount": 0, "ccUserNames": [] }, "success": true }
|
||
```
|
||
|
||
#### 错误响应
|
||
|
||
团期已确认（`MATERIAL_PREPARING` 及之后，含已结算 / 已流团）：
|
||
|
||
```json
|
||
{
|
||
"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（不变） |
|
||
|
||
#### 请求示例
|
||
|
||
```json
|
||
{
|
||
"remark": "确认无法成团，同意流团"
|
||
}
|
||
```
|
||
|
||
#### 响应示例
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "成功",
|
||
"data": {
|
||
"approvalId": "2102949786913333999",
|
||
"groupBatchId": "2102946606599028738",
|
||
"approvalStatus": "APPROVED",
|
||
"approvalStatusName": "已通过",
|
||
"actualRefundAmount": 0.00,
|
||
"approvedByName": "admin",
|
||
"approveRemark": "确认无法成团，同意流团",
|
||
"canApprove": false
|
||
},
|
||
"success": true
|
||
}
|
||
```
|
||
|
||
#### 空数据 / 降级响应
|
||
|
||
请求体可整体不传（不变）；退款单由提交后的异步监听建出，`actualRefundAmount` 先落暂定值、提交后回读定稿（不变）。
|
||
|
||
```json
|
||
{}
|
||
```
|
||
|
||
#### 错误响应
|
||
|
||
团期在申请提交后被人工确认（或已进入出行 / 核单）：
|
||
|
||
```json
|
||
{
|
||
"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 | - | 不变 |
|
||
|
||
#### 请求示例
|
||
|
||
```http
|
||
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>
|
||
```
|
||
|
||
#### 响应示例
|
||
|
||
```json
|
||
{
|
||
"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
|
||
}
|
||
```
|
||
|
||
#### 空数据 / 降级响应
|
||
|
||
无匹配时空页（不变）：
|
||
|
||
```json
|
||
{ "code": 200, "message": "成功", "data": { "records": [], "total": 0, "pageNum": 1, "pageSize": 20 }, "success": true }
|
||
```
|
||
|
||
#### 错误响应
|
||
|
||
```json
|
||
{
|
||
"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（不变） |
|
||
|
||
#### 请求示例
|
||
|
||
```http
|
||
GET /v3/admin/order/group-batch/disband/2102949786913334001 HTTP/1.1
|
||
Host: api.test.1814.love:9443
|
||
Authorization: Bearer <admin token>
|
||
```
|
||
|
||
#### 响应示例
|
||
|
||
```json
|
||
{
|
||
"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`（不变）：
|
||
|
||
```json
|
||
{ "code": 200, "message": "成功", "data": { "approvalStatus": "PENDING", "batchNo": null, "canApprove": false }, "success": true }
|
||
```
|
||
|
||
#### 错误响应
|
||
|
||
```json
|
||
{
|
||
"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`（不变） |
|
||
|
||
#### 请求示例
|
||
|
||
```json
|
||
{
|
||
"orderIds": ["2102947020270653443"],
|
||
"target": "CONTRACT"
|
||
}
|
||
```
|
||
|
||
#### 响应示例
|
||
|
||
团期管理员调用，该户已自动出具（TEST 实测形态）：
|
||
|
||
```json
|
||
{
|
||
"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` 为空数组（不变）：
|
||
|
||
```json
|
||
{ "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 等）：
|
||
|
||
```json
|
||
{
|
||
"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 | 逐户结果（不变） |
|
||
|
||
#### 请求示例
|
||
|
||
```json
|
||
{
|
||
"orderIds": ["2102947020270653443"],
|
||
"target": "CONTRACT",
|
||
"reason": "方案选错"
|
||
}
|
||
```
|
||
|
||
#### 响应示例
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "成功",
|
||
"data": {
|
||
"totalCount": 1,
|
||
"successCount": 1,
|
||
"failCount": 0,
|
||
"skipCount": 0,
|
||
"results": [
|
||
{ "orderId": "2102947020270653443", "target": "CONTRACT", "outcome": "SUCCESS", "message": null }
|
||
]
|
||
},
|
||
"success": true
|
||
}
|
||
```
|
||
|
||
#### 空数据 / 降级响应
|
||
|
||
作废失败的户记 `FAILED`、不进重开，不影响其他户（不变）：
|
||
|
||
```json
|
||
{ "code": 200, "message": "成功", "data": { "totalCount": 1, "successCount": 0, "failCount": 1, "skipCount": 0, "results": [] }, "success": true }
|
||
```
|
||
|
||
#### 错误响应
|
||
|
||
```json
|
||
{
|
||
"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`（不变） |
|
||
|
||
#### 请求示例
|
||
|
||
```json
|
||
{
|
||
"orderIds": ["2102947020270653443"]
|
||
}
|
||
```
|
||
|
||
#### 响应示例
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "成功",
|
||
"data": {
|
||
"totalCount": 1,
|
||
"successCount": 1,
|
||
"failCount": 0,
|
||
"skipCount": 0,
|
||
"results": [
|
||
{ "orderId": "2102947020270653443", "target": "CONTRACT", "outcome": "SUCCESS", "message": null }
|
||
]
|
||
},
|
||
"success": true
|
||
}
|
||
```
|
||
|
||
#### 空数据 / 降级响应
|
||
|
||
没有已出未签的户时全部 `SKIPPED`，不发短信、不写时间线（不变）：
|
||
|
||
```json
|
||
{ "code": 200, "message": "成功", "data": { "totalCount": 1, "successCount": 0, "failCount": 0, "skipCount": 1, "results": [ { "target": "CONTRACT", "outcome": "SKIPPED", "message": "该户合同未出具或已签署，无需催签" } ] }, "success": true }
|
||
```
|
||
|
||
#### 错误响应
|
||
|
||
```json
|
||
{
|
||
"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](https://git.1814.love/wx/HL/issues/8355)；补录 [#8270](https://git.1814.love/wx/HL/issues/8270)、[#8308](https://git.1814.love/wx/HL/issues/8308)、[#8309](https://git.1814.love/wx/HL/issues/8309)
|
||
- 关联 PR: [#8272](https://git.1814.love/wx/HL/pulls/8272)、[#8313](https://git.1814.love/wx/HL/pulls/8313)、[#8315](https://git.1814.love/wx/HL/pulls/8315)、[#8312](https://git.1814.love/wx/HL/pulls/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`
|
||
|
||
## 关联 / 联系人
|
||
|
||
### 链接
|
||
|
||
- **Issue**: [#8355](https://git.1814.love/wx/HL/issues/8355)
|
||
- **PR**: [#8272](https://git.1814.love/wx/HL/pulls/8272)、[#8313](https://git.1814.love/wx/HL/pulls/8313)、[#8315](https://git.1814.love/wx/HL/pulls/8315)、[#8312](https://git.1814.love/wx/HL/pulls/8312)
|
||
- **Merge commit**: [968d80b78](https://git.1814.love/wx/HL/commit/968d80b78)、[3cd787713](https://git.1814.love/wx/HL/commit/3cd787713)、[b2e7140e3](https://git.1814.love/wx/HL/commit/b2e7140e3)、[94f2ae5a7](https://git.1814.love/wx/HL/commit/94f2ae5a7)
|
||
|
||
### 联系人
|
||
|
||
- **后端负责人**: @jw
|