wx/hl-api-changelog

派生 0

文件

T

jw和Claude Opus 5.5 358be6ddb2

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

详情

docs(changelog): #8246 流团审批放开团期管理员，批后各户退款进退款审批中心二审（修改接口·管理后台）

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

2026-10-02 19:26:46 +08:00

20 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	8246	流团审批放开团期管理员，批准后各户退款进退款审批中心二审——GB-ADM-062 审批人集合与批后退款行为、GB-ADM-061 canApprove 取值同步变化	admin	jw(GIT)	修改接口	deployed	verified	not_required					jw 2026-10-02 定案，照 #8436 退单审批的做法：一是流团审批（GB-ADM-062 同意 / 拒绝）在管理员之外放行团期管理员 GROUP_BATCH_MANAGER，不新增权限码；二是同意流团后各户退款单停在 PENDING 进退款审批中心二审，不再以流团审批人身份自动放行。审批中心列表与流团详情的 canApprove 与端点同一道判定，团期管理员在待审批流团上由 false 变 true。两项都受 nacos 开关控制（默认开）：group-batch.disband.refund-second-review 关掉即回到改前自动放行，并同时收回团期管理员的流团审批权；group-batch.acl.allow.disband-approver-group-batch-manager 关掉只收回团期管理员审批权。路径、入参、出参字段名与类型零变化，错误码不变（589547 文案「仅管理员可处理流团审批」未改，与 #8436 对 589530 的处理一致）；变的是审批人集合、canApprove 取值与批后退款单状态，属行为 / 语义变化，按 jw 2026-09-18 口径推送。已合并 dev-v3（PR #8734，merge commit c4a410a94）并部署测试服。hl-ui v2.1 审批中心页已对团期管理员开放（canAccess = isAdmin \|\| isGroupBatchManager），同意 / 拒绝按钮按 canApprove 显隐，前端零改动，frontend_status 记 not_required。	2026-10-02	dev-v3

流团审批放开团期管理员与批后退款二审（管理后台）

服务: hl-order-service-v3（端口 8086/8186）

一、接口背景

团期管理员能发起流团，却批不了流团：流团审批的角色门只放管理员。退单审批已在 #8436 放开团期管理员，并把批后退款改成进退款审批中心二审；流团这次照同一做法处理。

本次两处行为变化：

流团审批（同意 / 拒绝）在管理员之外放行团期管理员；审批中心列表与流团详情的 canApprove 随之变化。
同意流团后，各户的退款单停在 PENDING，进退款审批中心由有退款审核权的人二审；改前是以流团审批人身份自动审核通过。这一条对所有审批人生效，不只团期管理员。

二、变更接口清单

#	接口	方法	路径	变更类型	说明
1	GB-ADM-062 同意流团	POST	`/v3/admin/order/group-batch/disband/{approvalId}/approve`	修改接口	审批人集合加团期管理员；批后各户退款单停在 PENDING 进二审。入参、出参、错误码零变化
2	GB-ADM-062 拒绝流团	POST	`/v3/admin/order/group-batch/disband/{approvalId}/reject`	修改接口	审批人集合加团期管理员。入参、出参、错误码零变化
3	GB-ADM-061 团期审批中心列表	GET	`/v3/admin/order/group-batch/approvals/page`	修改接口	流团行 `canApprove` 对团期管理员由 false 变 true（待审批行）；字段零变化
4	GB-ADM-061 流团申请详情	GET	`/v3/admin/order/group-batch/disband/{approvalId}`	修改接口	`canApprove` 同上；字段零变化

三、接口详情

1. GB-ADM-062 同意流团 `POST /v3/admin/order/group-batch/disband/{approvalId}/approve`

VO: DisbandApprovalRespVO

使用场景

团期审批中心「流团」行或流团详情页点「同意」。同意后才真正执行流团：团期置 CANCELLED，全团子订单取消，已付户按已付全额建退款单，释放配车占用。

入参

字段	位置	类型	必填	约束	说明
approvalId	path	Long	是	正整数，流团申请单 ID	不存在返 589545
remark	body	String	否	≤ 512 字	批复备注；整个 body 可省略

出参

字段	类型	说明
approvalStatus	String	同意后为 `APPROVED`
approvedById / approvedByName	Long / String	本次审批人；团期管理员现在也会出现在这里
estimatedRefundAmount	BigDecimal	提交时的预估退款合计（既有字段，未改）
actualRefundAmount	BigDecimal	实际进退款的合计，由对账定稿（既有字段，未改）。现在是「已建退款单、待二审」的金额，不是已退出的钱
canApprove	Boolean	已处理后恒为 false
其余字段	—	与流团详情相同，未改

请求示例

POST /v3/admin/order/group-batch/disband/2105977953445969921/approve HTTP/1.1
Host: api.test.1814.love
Authorization: Bearer <团期管理员 token>
Content-Type: application/json

{"remark": "确认无法成团"}

响应示例

{
  "code": 200,
  "message": "成功",
  "data": {
    "approvalId": "2105977953445969921",
    "groupBatchId": "2105974855696547842",
    "batchNo": "T26-7048",
    "batchName": "11月26日海拉尔-额尔古纳4日团",
    "approvalStatus": "APPROVED",
    "approvalStatusName": "已通过",
    "reason": "临近出团报名不足 6 户，无法成团",
    "affectedOrderCount": 2,
    "participantCount": 4,
    "estimatedRefundAmount": 3360.0,
    "actualRefundAmount": 3360.0,
    "applicantId": "2102259564525301761",
    "applicantName": "gbm8154test",
    "approvedById": "2102259564525301761",
    "approvedByName": "gbm8154test",
    "approveRemark": "确认无法成团",
    "canApprove": false
  }
}

空数据 / 降级响应

团里没有已付户时不建任何退款单，actualRefundAmount 为 0.00。退款单建单失败的户不计入 actualRefundAmount，由对账 Job 兜底补建；接口本身仍返回成功（流团已提交，不回滚）。

{
  "code": 200,
  "message": "成功",
  "data": {
    "approvalStatus": "APPROVED",
    "affectedOrderCount": 1,
    "estimatedRefundAmount": 0.0,
    "actualRefundAmount": 0.0,
    "canApprove": false
  }
}

错误响应

{
  "code": 589547,
  "message": "仅管理员可处理流团审批",
  "data": null
}

错误码	触发条件
589547	当前角色不是管理员 / 超级管理员 / 团期管理员（如定制师、财务）；或有请求但网关未透传角色；或团期管理员放行开关已关
589545	流团申请不存在
589546	申请已被处理（并发时后到者）
589544	团期已确认或更靠后，不可批复流团

业务边界

团期管理员按「任一团期管理员」放行，系统里还没有「本团团期管理员」关系，与 #8436 退单一致。
不禁止自审：团期管理员可以批自己提交的申请；applicant* 与 approvedBy* 分开落库。
批后各户退款单为 PENDING，calculatedAmount = 该户已付全额（流团按已付全额退，不扣违约金），审核人在退款审批中心不填金额直接同意即按此额退。
退款审核端点 POST /v3/admin/refund/review 仍禁止团期管理员（581008），所以团期管理员批了流团也退不出钱，钱的出口由退款审核人把关。

2. GB-ADM-062 拒绝流团 `POST /v3/admin/order/group-batch/disband/{approvalId}/reject`

VO: DisbandApprovalRespVO

使用场景

团期审批中心「流团」行或流团详情页点「拒绝」。只改申请单状态，团期继续正常招募，订单与钱一律不动。

入参

字段	位置	类型	必填	约束	说明
approvalId	path	Long	是	正整数，流团申请单 ID	不存在返 589545
remark	body	String	是	非空白，≤ 512 字	拒绝原因，写进团期时间线

出参

字段	类型	说明
approvalStatus	String	拒绝后为 `REJECTED`
approvedById / approvedByName	Long / String	本次审批人；团期管理员现在也会出现在这里
approveRemark	String	拒绝原因
canApprove	Boolean	已处理后恒为 false

请求示例

POST /v3/admin/order/group-batch/disband/2105980238163030017/reject HTTP/1.1
Host: api.test.1814.love
Authorization: Bearer <团期管理员 token>
Content-Type: application/json

{"remark": "本周还有两户在咨询，继续招募到下周一再定"}

响应示例

{
  "code": 200,
  "message": "成功",
  "data": {
    "approvalId": "2105980238163030017",
    "groupBatchId": "2105980235310923777",
    "batchNo": "T26-9826",
    "approvalStatus": "REJECTED",
    "approvalStatusName": "已拒绝",
    "approvedByName": "gbm8154test",
    "approveRemark": "本周还有两户在咨询，继续招募到下周一再定",
    "canApprove": false
  }
}

空数据 / 降级响应

无降级分支：拒绝只写申请单一行和一条时间线，失败即整体回滚并返回错误码。

{
  "code": 589546,
  "message": "该流团申请已处理，不可重复操作",
  "data": null
}

错误响应

{
  "code": 589547,
  "message": "仅管理员可处理流团审批",
  "data": null
}

错误码	触发条件
589547	同「同意流团」
589545	流团申请不存在
589546	申请已被处理
400	`remark` 为空或超长

业务边界

拒绝后同一团期可以再次提交流团。提交接口有防重窗口，拒绝后立刻重提会返回 100502「请勿重复提交」，隔几秒再提即可（既有行为，本次未改）。
审批人范围与「同意流团」完全一致，共用同一道角色门。

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

VO: GroupBatchApprovalItemRespVO

使用场景

团期审批中心页的统一列表（流团 + 退单两类）。前端按行的 canApprove 决定是否显示「同意 / 拒绝」。

入参

字段	位置	类型	必填	约束	说明
bizType	query	String	否	`DISBAND` / `WITHDRAW`	业务类型
approvalStatus	query	String	否	`PENDING` / `APPROVED` / `REJECTED` / `CANCELLED`	审批状态
groupBatchId	query	Long	否	正整数	按团期筛
batchName	query	String	否	—	团期名称关键字
pageNum	query	Integer	否	≥ 1，默认 1	页码
pageSize	query	Integer	否	默认 20	每页条数

出参

字段	类型	说明
records[].canApprove	Boolean	本次取值变化：流团行 = 待审批 + 团期仍可流团 + 当前人过 GB-ADM-062 的角色门。团期管理员在待审批流团行上由 false 变 true；退单行口径不变
records[].approvedByName	String	审批人，团期管理员现在也会出现
其余字段	—	未改

请求示例

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

响应示例

{
  "code": 200,
  "message": "成功",
  "data": {
    "records": [
      {
        "approvalId": "2105977252741349378",
        "bizType": "DISBAND",
        "bizTypeName": "流团",
        "groupBatchId": "2105974855696547842",
        "batchNo": "T26-7048",
        "batchName": "11月26日海拉尔-额尔古纳4日团",
        "approvalStatus": "PENDING",
        "approvalStatusName": "待审批",
        "affectedOrderCount": 2,
        "participantCount": 4,
        "estimatedRefundAmount": 3360.0,
        "reason": "临近出团报名不足 6 户，无法成团",
        "applicantName": "gbm8154test",
        "canApprove": true
      }
    ],
    "total": 1,
    "page": 1,
    "pageSize": 20
  }
}

空数据 / 降级响应

没有匹配的申请时返回空页。

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

错误响应

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

错误码	触发条件
589507	无 `group-batch:view` 权限码（读端点判权码，与审批角色门无关，本次未改）

业务边界

canApprove 整页只算一次，与行数无关。
定制师、财务等角色在流团行上仍为 false；管理员 / 超级管理员仍为 true。
团期管理员放行开关关掉时，团期管理员在流团行上回到 false。

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

VO: DisbandApprovalRespVO

使用场景

审批中心点进流团详情；详情页的「同意 / 拒绝」按钮按 canApprove 显隐。

入参

字段	位置	类型	必填	约束	说明
approvalId	path	Long	是	正整数，流团申请单 ID	不存在返 589545

出参

字段	类型	说明
canApprove	Boolean	本次取值变化，口径同列表：待审批 + 团期仍可流团 + 过角色门。团期管理员由 false 变 true
其余字段	—	未改

请求示例

GET /v3/admin/order/group-batch/disband/2105980238163030017 HTTP/1.1
Host: api.test.1814.love
Authorization: Bearer <团期管理员 token>

响应示例

{
  "code": 200,
  "message": "成功",
  "data": {
    "approvalId": "2105980238163030017",
    "groupBatchId": "2105980235310923777",
    "batchNo": "T26-9826",
    "batchName": "12月10日海拉尔-额尔古纳4日团",
    "approvalStatus": "PENDING",
    "approvalStatusName": "待审批",
    "reason": "临近出团报名不足 6 户，无法成团",
    "affectedOrderCount": 2,
    "participantCount": 4,
    "estimatedRefundAmount": 3360.0,
    "applicantName": "gbm8154test",
    "canApprove": true
  }
}

空数据 / 降级响应

申请已处理（通过 / 拒绝 / 撤销）或团期已不可流团时，canApprove 为 false，其余字段照常返回。

{
  "code": 200,
  "message": "成功",
  "data": {
    "approvalId": "2105980238163030017",
    "approvalStatus": "REJECTED",
    "approvalStatusName": "已拒绝",
    "canApprove": false
  }
}

错误响应

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

错误码	触发条件
589545	申请不存在
589507	无 `group-batch:view` 权限码

业务边界

canApprove 与 GB-ADM-062 走同一个判定方法，不会出现「显示了按钮、点下去 589547」。
缺角色时会打一条 GB_APPROVAL_ROLE_CLAIM_MISSING WARN，canApprove 返回 false。

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

前端按 canApprove 显隐「同意 / 拒绝」，不要按角色自己判：团期管理员能否审批受 nacos 开关控制，角色相同、结果可能不同。
同意流团的响应里 actualRefundAmount 现在表示「已建退款单、待二审」的合计，不代表钱已退出。要看每户退款进度，查退款审批中心（GET /v3/admin/refund/application/page）或订单退款列表。
退款审批中心会多出流团产生的 PENDING 退款单，申请人类型为 SYSTEM，原因文案是流团原因。审核人可直接同意（按 calculatedAmount 即已付全额退），也可改额或拒绝。
团期管理员不能审核退款（581008），流团退款的二审要由财务 / 管理员等有退款审核权的人处理。

五、数据库行为

零 schema 变更，无 Flyway 迁移。
同意流团的写入集合不变：申请单、团期、子订单、时间线、配车释放 outbox 照旧；退款单照旧由取消事件建出。
唯一变化是退款单的落库状态：改前建单后同一流程里自动写一条 refund_review（审核人 = 流团审批人）并把 refund_application.status 推到 APPROVED；改后只建 PENDING 单，refund_review 零行、reviewed_at 为空，等退款审批中心处理。
流团退款对账建单时写入的 calculated_amount 由「按退款政策算」改为「该户已付全额」，与通用建单路径写同一个数。
拒绝流团的写入不变：只改申请单一行 + 一条时间线。

六、边界行为

两个 nacos 开关，默认都开：
- group-batch.disband.refund-second-review：关掉时，退款回到改前自动放行，每次同意都打 GB_DISBAND_REFUND_SECOND_REVIEW_OFF WARN；同时收回团期管理员的流团审批权（否则团期管理员一个人就能把整团的钱自动退出去）。
- group-batch.acl.allow.disband-approver-group-batch-manager：关掉时只收回团期管理员的流团审批权，二审保留；团期管理员被拒时打 GB_DISBAND_APPROVER_GBM_DISABLED WARN。
流团这对开关与退单（#8436）那对开关互不牵动，两类审批分别回滚。
开关取不到（容器未绑定）时按更严处理：不放团期管理员。
未付户随流团取消，不建退款单（既有行为）。

六.6、修改前后对比

场景	改前	改后
团期管理员同意 / 拒绝流团	589547	成功，审批人记为团期管理员
定制师 / 财务同意 / 拒绝流团	589547	589547（不变）
管理员同意 / 拒绝流团	成功	成功（不变）
同意流团后已付户的退款单	`APPROVED`，带 1 条审核记录（审核人 = 流团审批人）	`PENDING`，0 条审核记录，`calculated_amount` = 已付全额
审批中心 / 流团详情 `canApprove`（团期管理员，待审批流团）	false	true
审批中心 / 流团详情 `canApprove`（定制师）	false	false（不变）

六.7、影响评估

前端：零改动。审批中心页已对团期管理员开放，按钮按 canApprove 显隐，后端放开后按钮自动出现。
财务 / 退款审核人：退款审批中心多出流团退款单，需要人工审核后才会退款，流团退款到账时间会因此延后。这是本次的目的。
回滚：改 nacos 开关即可，不需要发版。

七、不影响范围

发起流团 GB-ADM-060：判权（group-batch:manage 权限码）与行为不变。
退单审批 GB-ADM-072 ~ 075：判定、开关、二审都不变，#8436 的那对开关不受本次影响。
退款审核端点 POST /v3/admin/refund/review：仍禁止团期管理员。
单笔取消订单、C 端申请退款等其他建退款单的路径：不变。

八、测试环境已验证

部署：dev-v3 @ c4a410a94，2026-10-02 19:01 部署 hl-order-service-v3。运行字节探针在 8086 / 8186 两个实例上都命中本次新增的 GB_DISBAND_APPROVER_GBM_DISABLED 与 GB_DISBAND_REFUND_SECOND_REVIEW_OFF；进程 jar 与磁盘 jar 为同一 inode。

判权一律用低权限角色声明取证：团期管理员用 TEST 上当前角色即团期管理员的 gbm8154test；不用超级管理员。

场景	改前（`1f8b1dacd`，团期 `T26-0659`）	改后（`c4a410a94`，团期 `T26-7048` / `T26-3437` / `T26-9826`）
团期管理员同意 / 拒绝真实待审批流团	589547 / 589547	拒绝成功（`T26-7048` 申请 `2105977252741349378`）；同意成功（申请 `2105977953445969921`）
定制师同意 / 拒绝	589547 / 589547	589547 / 589547，申请单仍 PENDING
管理员同意	成功	成功（申请 `2105977508052828161`）
已付户退款单（全款 3360.00）	`APPROVED`，`refund_review` 1 行	团期管理员批、管理员批两例都是 `PENDING`，`calculated_amount=3360.00`，`refund_review` 0 行，`reviewed_at` 为空
退款审批中心 PENDING 列表	—	两张流团退款单都在列
审批中心 `canApprove`（团期管理员 / 定制师）	false / —	true / false
流团详情 `canApprove`（团期管理员 / 定制师 / 管理员）	—	true / false / true；拒绝后 false
团期管理员调退款审核端点	—	581008，钱的出口仍挡住团期管理员

全部调用 HTTP 200；审批单 actual_refund_amount 两例都定稿为 3360.00。

十、相关文档

工单：wx/HL#8246
PR：wx/HL#8734（merge commit c4a410a94）
参照：#8436 退单审批放开团期管理员 + 退款二审
代码：WithdrawApprovalGuard#assertDisbandApproverRole、GroupBatchDisbandApprovalService#approveInTx、GroupBatchAclToggle

关联 / 联系人

后端：jw
前端：无需改动（hl-ui v2.1 已按 canApprove 显隐）
关联工单：#8436、#8253、#7294、#7609

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

流团审批放开团期管理员与批后退款二审（管理后台）

一、接口背景

二、变更接口清单

三、接口详情

1. GB-ADM-062 同意流团 POST /v3/admin/order/group-batch/disband/{approvalId}/approve

使用场景

入参

出参

请求示例

响应示例

空数据 / 降级响应

错误响应

业务边界

2. GB-ADM-062 拒绝流团 POST /v3/admin/order/group-batch/disband/{approvalId}/reject

使用场景

入参

出参

请求示例

响应示例

空数据 / 降级响应

错误响应

业务边界

3. GB-ADM-061 团期审批中心列表 GET /v3/admin/order/group-batch/approvals/page

使用场景

入参

出参

请求示例

响应示例

空数据 / 降级响应

错误响应

业务边界

4. GB-ADM-061 流团申请详情 GET /v3/admin/order/group-batch/disband/{approvalId}

使用场景

入参

出参

请求示例

响应示例

空数据 / 降级响应

错误响应

业务边界

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

五、数据库行为

六、边界行为

六.6、修改前后对比

六.7、影响评估

七、不影响范围

八、测试环境已验证

十、相关文档

关联 / 联系人

20 KiB

原始文件 Blame 文件历史

1. GB-ADM-062 同意流团 `POST /v3/admin/order/group-batch/disband/{approvalId}/approve`

2. GB-ADM-062 拒绝流团 `POST /v3/admin/order/group-batch/disband/{approvalId}/reject`

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

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