From 1fe976a7a641ff159c498731d94d7f6a9278f8a7 Mon Sep 17 00:00:00 2001 From: jw Date: Thu, 24 Sep 2026 11:51:19 +0800 Subject: [PATCH] =?UTF-8?q?docs(changelog):=20#8322=20=E5=9B=A2=E6=9C=9F?= =?UTF-8?q?=E9=A2=84=E6=94=AF=E6=A0=B8=E5=8D=95=E5=89=8D=E5=9D=87=E5=8F=AF?= =?UTF-8?q?=E5=8F=91=E8=B5=B7+=E9=A2=86=E6=AC=BE=E4=BA=BA=E9=99=90?= =?UTF-8?q?=E5=AE=9A=E4=B8=BB=E6=8A=A5=E8=B4=A6=E4=BA=BA=EF=BC=88589557?= =?UTF-8?q?=EF=BC=89=EF=BC=8C=E8=A1=A5=20#8270=20=E6=94=BE=E5=AE=BD?= =?UTF-8?q?=E8=AF=B4=E6=98=8E=EF=BC=8C=E8=AE=A2=E6=AD=A3=20#7154=20?= =?UTF-8?q?=E9=94=99=E8=AF=AF=E7=A0=81=20589538/589539=E2=86=92589541/5895?= =?UTF-8?q?42?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Opus 5.5 (1M context) --- ...务总览与预支复用订单预支-新增接口-管理后台.md | 18 +- ...均可发起与领款人限定主报账人-修改接口-管理后台.md | 338 ++++++++++++++++++ 2 files changed, 347 insertions(+), 9 deletions(-) create mode 100644 changelogs-v2/2026-09/24_8322_团期预支核单前均可发起与领款人限定主报账人-修改接口-管理后台.md diff --git a/changelogs-v2/2026-09/06_7154_团期财务总览与预支复用订单预支-新增接口-管理后台.md b/changelogs-v2/2026-09/06_7154_团期财务总览与预支复用订单预支-新增接口-管理后台.md index 012c2bd9..3ec62eb6 100644 --- a/changelogs-v2/2026-09/06_7154_团期财务总览与预支复用订单预支-新增接口-管理后台.md +++ b/changelogs-v2/2026-09/06_7154_团期财务总览与预支复用订单预支-新增接口-管理后台.md @@ -10,10 +10,10 @@ gateway_status: "verified" frontend_status: "verified" frontend_owner: "mmg" frontend_ref: "af7cc62b" -target_release: "" +target_release: "hl-ui@af7cc62b" verified_at: "2026-09-08" status_note: "后端 PR #7170 已合 dev-v3 并部署测试服(网关 finance/advances/payee-candidates 实测 200),原 backend_status/gateway_status=pending 系 09-06 陈旧快照已修正为 deployed/verified。前端团期财务 Tab 与预支接真已交付:groupBatchFinance.js 五端点+FinanceTab(四金额卡/逐户付款表/预支记录/整团核算口径行)+GroupAdvanceModal+detail 挂财务 Tab+store 键缓存+AdvanceApprovalList scope 筛选;金额全后端权威值零反算。ref af7cc62b,checkpoint 全绿含 Vitest 全量+生产构建。" -updated_at: "2026-09-08" +updated_at: "2026-09-24" base: "dev-v3" --- @@ -378,8 +378,8 @@ POST /v3/admin/order/group-batch/90211/advance |---|---| | `589500` | 团期不存在 | | `589507` | 缺 `group-batch:finance:advance` 权限 | -| `589538` | 团期状态不可发起预支（须为物料准备中 / 待出发 / 出行中） | -| `589539` | 房 / 车 / 导 / 摄四项未配齐 | +| `589541` | 团期状态不可发起预支。⚠️ 2026-09-24 订正：原文误写为 `589538`（号段顺延后实际落 589541）；允许状态已两次放宽，现为「进入核单前都可以」（#8270 / #8322） | +| `589542` | 房 / 车 / 导 / 摄四项未配齐。⚠️ 2026-09-24 订正：原文误写为 `589539`（该号实为 #7178「名额调整量不能为 0」）；**#8270 起本码不再返回** | | `585003` | 预支金额必须大于 0 | | `585004` | 预支金额超过可用余额上限 | | `585006` | 借款类型非法 | @@ -391,7 +391,7 @@ POST /v3/admin/order/group-batch/90211/advance #### 业务边界 -- **双前置闸门**：团期状态 + 四项资源全就绪，缺一即拒（此前服务端两道都没有，只有前端做了置灰）。 +- **双前置闸门**：团期状态 + 四项资源全就绪，缺一即拒（此前服务端两道都没有，只有前端做了置灰）。⚠️ 已变更：#8270 删除四项配齐门，#8322 起进入核单前都可发起，且领款人限定为本团主报账人（589557），见 `24_8322_…` 条目。 - **上限走团期统一池**：团期级与各子订单级**共扣一池**。团期把整团尾款预支满后，该团任一子订单再发起订单级预支同样会被 `585004` 拒——这是本次修复的超支漏洞。 - 创建后进入**站内财务审批**，走既有 `advance-approvals` 列表与 approve / reject / 撤回三端点，与订单级完全一致。 - 一期仍**只记账不出款**，实际出款走财务既有付款流程。 @@ -583,8 +583,8 @@ GET /v3/admin/order/group-batch/90211/settlement/summary | 团期无活跃子订单 | 六个金额字段 `0.00`，`items` 空数组 | | 子订单已取消 | 不进金额、不进 `items`，只计入 `withdrawnCount` | | 未设置报账人 | `primaryPayeeName` 为 `null`，后端不兜底默认导游 | -| 团期状态为招募中 / 核单中 | 发起预支返回 `589538` | -| 四项资源缺任一 | 发起预支返回 `589539` | +| 团期状态为招募中 / 核单中 | 发起预支返回 `589541`（2026-09-24 订正码值；#8322 起招募中已可发起，仅核单中及之后返回） | +| 四项资源缺任一 | 原返回 `589542`（2026-09-24 订正码值）；#8270 起不再拦截 | | 团期尾款池已被预支占满 | 团期级与该团任一子订单级预支**均**返回 `585004` | | 数据字典服务不可用 | 借款类型降级到内置集合校验，正常类型仍可提交 | | 审批列表出现团期级行 | `orderId` / `orderNo` / `consultantName` / 订单四态均为 `null` | @@ -611,7 +611,7 @@ GET /v3/admin/order/group-batch/90211/settlement/summary 1. 财务 Tab 四张卡与逐户表末行合计一致，且与团期详情、看板列表三处应收同源。 2. **超支被堵死**：团期级把整团尾款预支满 → 该团任一子订单再发起订单级预支被 `585004` 拒。 3. **核单零重复扣**：团期级预支 5,000 通过 + 某户订单级预支 2,000 通过 → 该户报销单含 2,000，整团 `groupAdvanceApproved` 仍是 5,000；`grandTotalCost` 不变。 -4. 两道闸门各拒一次（`589538` / `589539`）。 +4. 两道闸门各拒一次（`589541` / `589542`，2026-09-24 订正码值）。 5. 团期级预支出现在预支审批列表，「团号 / 产品」「行程」两列有值，按团期号搜得到，就地通过 / 驳回 / 撤回正常。 6. 订单级预支五端点回归无变化。 @@ -627,7 +627,7 @@ GET /v3/admin/order/group-batch/90211/settlement/summary | 处 | 文档现状 | 实际 | |---|---|---| -| §0B.9 错误码 | 「统一用 `AdvanceErrorCode`（585 段）」 | 改落 `589538` / `589539`；585 段被 v2/v3 整段重叠声明且 585001-585010 已被 order-v2 实占 | +| §0B.9 错误码 | 「统一用 `AdvanceErrorCode`（585 段）」 | 改落 `589541` / `589542`（原拟 589538 / 589539，被 #7158 / #7178 先占后顺延，2026-09-24 订正）；585 段被 v2/v3 整段重叠声明且 585001-585010 已被 order-v2 实占 | | GB-ADM-040 出参 | `payStatus` 写五值含 `REFUNDING` / `REFUNDED` | 代码只有三值；结清状态另出 `settleStatus` 字段 | | GB-ADM-040 出参 | 含 `advanceTotal` | 已废，改三个数 | | GB-ADM-042 | 返回 `GroupBatchWriteResultVO`、不回传 `advanceId` | 改返 `OrderAdvanceRespVO` 并回传 `advanceId` | diff --git a/changelogs-v2/2026-09/24_8322_团期预支核单前均可发起与领款人限定主报账人-修改接口-管理后台.md b/changelogs-v2/2026-09/24_8322_团期预支核单前均可发起与领款人限定主报账人-修改接口-管理后台.md new file mode 100644 index 00000000..586d76a0 --- /dev/null +++ b/changelogs-v2/2026-09/24_8322_团期预支核单前均可发起与领款人限定主报账人-修改接口-管理后台.md @@ -0,0 +1,338 @@ +--- +schema: "hl-changelog/v2" +ticket: "8322" +title: "团期预支核单前均可发起（放开招募中）+ 领款人限定为本团主报账人（新码 589557）；一并补 #8270 放宽说明" +consumer: "admin" +author: "jw(GIT)" +change_type: "修改接口" +backend_status: "deployed" +gateway_status: "verified" +frontend_status: "pending" +frontend_owner: "mmg" +frontend_ref: "" +target_release: "" +verified_at: "" +status_note: "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。" +updated_at: "2026-09-24" +base: "dev-v3" +--- + +# 团期预支：核单前均可发起 + 领款人限定为主报账人（管理后台） + +> **服务**: hl-order-service-v3（端口 8086/8186） +> **PR**: #8323（本单）、#8272（#8270，一并补说明） +> **Issue**: #8322、#8270 +> **日期**: 2026-09-24 +> **影响范围**: 管理后台团期详情页「财务」tab 的「发起预支」弹窗（领款人下拉、提交按钮可用状态、错误提示） + +--- + +## ⚠️ 关键变化 + +本次是**行为变更**，三条都与前端此前的预期不同： + +1. **可发起预支的团期状态扩大**。#8270 之前只有物料准备中至出行完毕可提，且要求房 / 车 / 导 / 摄四项配齐；#8270 起资源准备中可提、四项配齐门删除；**本单起招募中也可提**。现在的规则是：**进入核单之前都可以发起**，核单中 / 已结算 / 已流团仍返 `589541`。 +2. **领款人只能是本团主报账人**。以前本团任一已配人员都能当领款人；现在在本团但不是主报账人的（次报账人、普通人员、本团还没设主报账人）一律返新码 **`589557`**。不在本团仍是 `585007`。 +3. **领款人候选只返回主报账人一条**。以前返回本团全部人员、主报账人排首；现在只返回主报账人，**本团未设主报账人时返回空列表**。前端下拉要能处理 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 | 创建 / 提交时间 | + +#### 请求示例 + +```http +POST /v3/admin/order/group-batch/2102967993891979266/advance +Authorization: Bearer +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", + "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 起不再返回**（四项配齐门已删除，码位保留不复用） | 前端若有针对它的分支可删除 | + +```json +{ + "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` + +#### 使用场景 + +「发起预支」弹窗打开时拉取领款人下拉。本单起只会返回主报账人一条，前端可直接默认选中；返回空列表说明本团还没设主报账人。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|---|---|---|---|---|---| +| groupBatchId | path | Long | 是 | 运营团期 ID | 订单侧团期 ID，服务端内部换算产品侧排期 | + +#### 出参 + +| 字段 | 类型 | 说明 | +|---|---|---| +| id | Long(String) | 资源域 staffId，即发起预支的 `payeeStaffId` | +| staffName | String | 姓名 | +| staffRole / staffRoleText | String | 角色及中文 | +| reporterRank | String | 恒为 `PRIMARY` | +| isDefault | Boolean | 恒为 `true` | + +#### 请求示例 + +```http +GET /v3/admin/order/group-batch/2102967993891979266/advance/payee-candidates +Authorization: Bearer +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "data": [ + { + "id": "1002", + "staffName": "李雪梅", + "staffRole": "GUIDE", + "staffRoleText": "GUIDE", + "reporterRank": "PRIMARY", + "isDefault": true + } + ], + "success": true +} +``` + +#### 空数据 / 降级响应 + +本团未配人员，或配了人但没设主报账人，返回空列表： + +```json +{ + "code": 200, + "message": "成功", + "data": [], + "success": true +} +``` + +#### 错误响应 + +判权与团期存在性校验未改动。 + +```json +{ + "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