wx/hl-api-changelog

派生 0

文件

T

Mimingguang 47d93b0cf3

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

详情

chore(changelog): #8322 前端已交付 verified(ref 0ba1a273)

2026-09-24 12:03:32 +08:00

15 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	8322	团期预支核单前均可发起（放开招募中）+ 领款人限定为本团主报账人（新码 589557）；一并补 #8270 放宽说明	admin	jw(GIT)	修改接口	deployed	verified	verified	mmg	0ba1a2732022c800b2cee0711f1ed052b5e19dad	v2.1	2026-09-24	jw 2026-09-24 定两条口径：① 只要在核单前都可以发起团期预支，允许状态在 #8270（资源准备中起）基础上补招募中；② 团期预支由主报账人申领，领款人限定为本团 reporter_rank=PRIMARY 的那一人，在本团但不是主报账人（含本团未设主报账人）返新码 589557，不在本团仍 585007；领款人候选接口只返回主报账人一条，未设主报账人返回空列表。#8270（2026-09-23 合入，资源准备中放开、四项配齐门 589542 不再返回）当时未推 changelog，本条一并说明。PR #8323 已合 dev-v3（980429ac2）并部署 TEST，2026-09-24 11:47~11:49 经真实网关实测：招募中团期主报账人提交 200/SUBMITTED 落库 1 行；普通人员、次报账人、未设主报账人三种情况各返 589557 且零写入；不在本团返 585007；招募中超池返 585004；核单中、已流团团期各返 589541；候选接口部署前同一团返回 2 人、部署后只返回主报账人。前端侧：候选下拉条数变为 0 或 1，招募中与资源准备中的预支按钮若按旧规则置灰需放开，589557 需给出文案，故 frontend_status 记 pending。 \| 2026-09-24 mmg 交付:FinanceTab 阶段门白名单 3 态放宽到 6 态(RECRUITING~TRIP_FINISHED,核单中/已结算/流团置灰+tooltip),GroupAdvanceModal 空候选引导改「请先在团期人员配置中设置主报账人」(提交必然 589557 故禁用),589557 无按码分支拦截器透后端文案即引导;JSDoc/注释按 #8322+#7154 订正(589538/589539→589541,589542 删除);FinanceTab spec 11 例+新建 GroupAdvanceModal spec 2 例全绿	2026-09-24	dev-v3

团期预支：核单前均可发起 + 领款人限定为主报账人（管理后台）

服务: hl-order-service-v3（端口 8086/8186） PR: #8323（本单）、#8272（#8270，一并补说明） Issue: #8322、#8270 日期: 2026-09-24 影响范围: 管理后台团期详情页「财务」tab 的「发起预支」弹窗（领款人下拉、提交按钮可用状态、错误提示）

⚠️ 关键变化

本次是行为变更，三条都与前端此前的预期不同：

可发起预支的团期状态扩大。#8270 之前只有物料准备中至出行完毕可提，且要求房 / 车 / 导 / 摄四项配齐；#8270 起资源准备中可提、四项配齐门删除；本单起招募中也可提。现在的规则是：进入核单之前都可以发起，核单中 / 已结算 / 已流团仍返 589541。
领款人只能是本团主报账人。以前本团任一已配人员都能当领款人；现在在本团但不是主报账人的（次报账人、普通人员、本团还没设主报账人）一律返新码 589557。不在本团仍是 585007。
领款人候选只返回主报账人一条。以前返回本团全部人员、主报账人排首；现在只返回主报账人，本团未设主报账人时返回空列表。前端下拉要能处理 0 条（提示去团期人员配置里设主报账人）。

一、背景

团期预支复用订单预支 order_advance（#7154，scope=GROUP_BATCH）。本期 wx 在做团期主报账人功能，由主报账人发起预支申领，jw 2026-09-24 据此定：领款人限定为本团主报账人；同时预支入口前移到招募中，只要团期还没进核单都可以发起。

主报账人在团期人员配置里设置（PUT /v3/admin/group-batch/{productBatchId}/staff/{staffId}/reporter-rank），招募中、资源准备中可设，确认后锁定（#8231 / #8269）。

二、变更接口清单

#	接口	方法	路径	变更类型	说明
1	发起团期预支（GB-ADM-042）	POST	`/v3/admin/order/group-batch/{groupBatchId}/advance`	修改	允许状态补招募中；领款人须为本团主报账人，否则新码 589557；#8270 起资源准备中可提、589542 不再返回
2	团期预支领款人候选	GET	`/v3/admin/order/group-batch/{groupBatchId}/advance/payee-candidates`	修改	只返回主报账人一条；未设主报账人返回空列表

三、接口详情

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

VO: CreateGroupBatchAdvanceReqVO → OrderAdvanceRespVO

使用场景

团期详情页「财务」tab 点「发起预支」，选领款人（主报账人）、借款类型、金额后提交，创建一条团期级预支单，直接进入站内财务待审批（SUBMITTED）。入参与出参结构均未改，变的是允许状态与领款人校验。

入参

字段	位置	类型	必填	约束	说明
groupBatchId	path	Long	是	运营团期 ID	订单侧团期 ID
payeeStaffId	body	Long	是	须为本团主报账人的 staffId	取候选接口返回的 `id`；非主报账人返 589557
advanceType	body	String	是	字典 `advance_type`	借款类型，如 `TICKET`
amount	body	BigDecimal	是	≥ 0.01，且 ≤ 团期统一池可用余额	超额返 585004
purpose	body	String	否	≤ 255 字	用途说明
voucherUrl	body	String	否	≤ 512 字符	凭证 URL

出参

字段	类型	说明
id	Long(String)	预支单 ID
orderId	Long	团期级预支恒为 null
payeeStaffId	Long(String)	领款人 staffId（即主报账人）
payeeName	String	领款人姓名快照
payeeRole / payeeRoleText	String	领款人角色及中文
advanceType	String	借款类型
amount	BigDecimal	预支金额
purpose	String	用途说明
status / statusText	String	创建后恒为 `SUBMITTED` / 「待审批」
createdByName	String	发起人
createTime / submittedAt	String	创建 / 提交时间

请求示例

POST /v3/admin/order/group-batch/2102967993891979266/advance
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",
    "payeeRoleText": "GUIDE",
    "advanceType": "TICKET",
    "amount": 100,
    "purpose": "门票备用金",
    "voucherUrl": null,
    "status": "SUBMITTED",
    "statusText": "待审批",
    "rejectReason": null,
    "createdByName": "admin",
    "createTime": "2026-09-24 11:48:00",
    "submittedAt": "2026-09-24 11:48:00",
    "approvedAt": null,
    "approvedBy": null
  },
  "success": true
}

空数据 / 降级响应

写接口，无空数据形态。校验不通过时不落库，返回下方错误码之一。

错误响应

code	触发条件	前端建议
`589557`	新增。领款人在本团，但不是主报账人（次报账人 / 普通人员），或本团还没设主报账人	提示「请先在团期人员配置中设置主报账人」，引导去配人
`585007`	领款人不在本团人员名单里	同前，刷新候选
`589541`	团期处于核单中 / 已结算 / 已流团；文案改为「当前团期状态不可发起预支（进入核单后关闭）」	隐藏或置灰「发起预支」
`585004`	金额超过团期统一池可用余额	提示可用余额（财务面板 `advanceAvailable`）
`589542`	#8270 起不再返回（四项配齐门已删除，码位保留不复用）	前端若有针对它的分支可删除

{
  "code": 589557,
  "message": "领款人须为本团主报账人，请先在团期人员配置中设置主报账人",
  "data": null,
  "success": false
}

业务边界

允许状态：招募中、资源准备中、物料准备中、待出发、出行中、出行完毕；核单中 / 已结算 / 已流团拒绝。
校验顺序：团期状态（589541）→ 领款人在本团（585007）→ 领款人是主报账人（589557）→ 借款类型 → 金额上限（585004）。
上限规则不变：团期级与各子订单级预支共用一个团期尾款池。
只影响团期级预支；订单级预支（POST /v3/admin/order/{orderId}/advance）的领款人规则不变。

2. 团期预支领款人候选 `GET /v3/admin/order/group-batch/{groupBatchId}/advance/payee-candidates`

VO: List<AdvancePayeeCandidateVO>

使用场景

「发起预支」弹窗打开时拉取领款人下拉。本单起只会返回主报账人一条，前端可直接默认选中；返回空列表说明本团还没设主报账人。

入参

字段	位置	类型	必填	约束	说明
groupBatchId	path	Long	是	运营团期 ID	订单侧团期 ID，服务端内部换算产品侧排期

出参

字段	类型	说明
id	Long(String)	资源域 staffId，即发起预支的 `payeeStaffId`
staffName	String	姓名
staffRole / staffRoleText	String	角色及中文
reporterRank	String	恒为 `PRIMARY`
isDefault	Boolean	恒为 `true`

请求示例

GET /v3/admin/order/group-batch/2102967993891979266/advance/payee-candidates
Authorization: Bearer <admin token>

响应示例

{
  "code": 200,
  "message": "成功",
  "data": [
    {
      "id": "1002",
      "staffName": "李雪梅",
      "staffRole": "GUIDE",
      "staffRoleText": "GUIDE",
      "reporterRank": "PRIMARY",
      "isDefault": true
    }
  ],
  "success": true
}

空数据 / 降级响应

本团未配人员，或配了人但没设主报账人，返回空列表：

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

错误响应

判权与团期存在性校验未改动。

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

业务边界

条数只会是 0 或 1；不再返回次报账人与普通人员，也不再排序。
字段结构不变，前端按字段取值的代码不用改。

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

发起预支的 payeeStaffId 一律取候选接口返回的那一条，不要从团期人员列表里自己挑。
候选为空时不要让用户提交（必然 589557），提示去团期人员配置里设置主报账人。
「发起预支」按钮的可用状态按团期状态判断：进入核单（REVIEWING）之前都可用，不再要求四项资源配齐。

五、数据库行为

零表结构变更、零迁移脚本。
发起预支成功时照旧向 order_advance 写一行（scope=GROUP_BATCH、order_id=NULL、payee_ref_type=BATCH_STAFF）；任何校验失败零写入（TEST 实测前后计数一致）。
主报账人读自团期人员配置 order_batch_staff.reporter_rank，只读不写。

六、边界行为

主报账人在确认后锁定；取消成团（资源准备中 → 招募中）会回收导摄配置，主报账人可能随之被清掉，此时候选为空、发起预支返 589557，需重新配置。
已发起的预支保存领款人快照，事后主报账人变更不影响已有单据。

六.6、修改前后对比

项	#8270 之前	#8270（09-23）	本单（09-24）
可发起状态	物料准备中 ~ 出行完毕	资源准备中 ~ 出行完毕	招募中 ~ 出行完毕
四项配齐门	要求，否则 589542	删除，589542 不再返回	同 #8270
领款人	本团任一已配人员	同左	仅本团主报账人，否则 589557
候选接口	本团全部人员，主报账人排首	同左	仅主报账人一条 / 空列表
589541 文案	列出允许状态区间	同左	「当前团期状态不可发起预支（进入核单后关闭）」

六.7、影响评估

前端：候选下拉要处理 0 条；「发起预支」按钮若仍按旧规则（四项配齐 / 物料准备中起）置灰，需放开到核单前；新增 589557 文案。不改的话，功能按旧规则被前端挡住，但后端不会出错。
已有数据：不回填、不改存量预支单。
订单级预支、审批中心、结算核单均不受影响。

七、不影响范围

订单级预支 6 个端点（/v3/admin/order/{orderId}/advance*、审批中心列表、通过 / 驳回）。
团期财务总览 GET /v3/admin/order/group-batch/{groupBatchId}/finance、团期预支记录 GET .../advances。
团期人员配置与报账人等级接口。

八、测试环境已验证

部署 dev-v3 @ 980429ac2（含 PR #8323）到 TEST 后，2026-09-24 11:47~11:49 经真实网关 https://api.test.1814.love 实测（自造招募中团期 2102967993891979266，四项资源全未配，主报账人 1002、另配摄影 1003）：

用例	期望	实测
构建身份：样本团 `2100509904627191810` 候选接口	部署前 2 人 → 部署后仅主报账人	部署前 `[1002, 1003]`，部署后 6 次均 `[1002]`
候选接口（有主报账人）	仅 1002，`isDefault=true`	通过
招募中 + 主报账人 1002 提交 100	200，`SUBMITTED`，落库 1 行	通过，`order_advance` 0→1
领款人 1003（普通人员）	589557，零写入	通过
领款人 1003（设为次报账人后）	589557，零写入	通过
撤掉主报账人后候选 / 提交	候选 `[]`；提交 589557	通过
领款人 1005（不在本团）	585007	通过
招募中提交 6000（池 5400）	585004	通过
核单中团期 `2100891433836675073`	589541（新文案）	通过
已流团团期 `2102949787102076929`	589541	通过
不带 token	401	通过

造数已清理：预支单驳回、订单取消、产品侧班期取消。

十、相关文档

Issue #8322、PR #8323；#8270 / PR #8272
团期预支复用订单预支：changelogs-v2/2026-09/06_7154_团期财务总览与预支复用订单预支-新增接口-管理后台.md
报账人等级：changelogs-v2/2026-09/23_8231_配导游配摄影物资放开到出行前四态-修改接口-管理后台.md

关联 / 联系人

后端：jw
前端：mmg
团期主报账人功能：wx

15 KiB 原始文件 永久链接 Blame 文件历史 Unescape Escape

团期预支：核单前均可发起 + 领款人限定为主报账人（管理后台）

⚠️ 关键变化

一、背景

二、变更接口清单

三、接口详情

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

使用场景

入参

出参

请求示例

响应示例

空数据 / 降级响应

错误响应

业务边界

2. 团期预支领款人候选 GET /v3/admin/order/group-batch/{groupBatchId}/advance/payee-candidates

使用场景

入参

出参

请求示例

响应示例

空数据 / 降级响应

错误响应

业务边界

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

五、数据库行为

六、边界行为

六.6、修改前后对比

六.7、影响评估

七、不影响范围

八、测试环境已验证

十、相关文档

关联 / 联系人

15 KiB

原始文件永久链接 Blame 文件历史

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

2. 团期预支领款人候选 `GET /v3/admin/order/group-batch/{groupBatchId}/advance/payee-candidates`