docs(changelog): #8322 团期预支核单前均可发起+领款人限定主报账人（589557），补 #8270 放宽说明，订正 #7154 错误码 589538/589539→589541/589542
changelog-filename-gate / validate (push) Failing after 2s
changelog-filename-gate / validate (push) Failing after 2s
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
这个提交包含在：
Claude Opus 5.5
@@ -10,10 +10,10 @@ gateway_status: "verified"
|
|||||||
frontend_status: "verified"
|
frontend_status: "verified"
|
||||||
frontend_owner: "mmg"
|
frontend_owner: "mmg"
|
||||||
frontend_ref: "af7cc62b"
|
frontend_ref: "af7cc62b"
|
||||||
target_release: ""
|
target_release: "hl-ui@af7cc62b"
|
||||||
verified_at: "2026-09-08"
|
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 全量+生产构建。"
|
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"
|
base: "dev-v3"
|
||||||
---
|
---
|
||||||
|
|
||||||
@@ -378,8 +378,8 @@ POST /v3/admin/order/group-batch/90211/advance
|
|||||||
|---|---|
|
|---|---|
|
||||||
| `589500` | 团期不存在 |
|
| `589500` | 团期不存在 |
|
||||||
| `589507` | 缺 `group-batch:finance:advance` 权限 |
|
| `589507` | 缺 `group-batch:finance:advance` 权限 |
|
||||||
| `589538` | 团期状态不可发起预支（须为物料准备中 / 待出发 / 出行中） |
|
| `589541` | 团期状态不可发起预支。⚠️ 2026-09-24 订正：原文误写为 `589538`（号段顺延后实际落 589541）；允许状态已两次放宽，现为「进入核单前都可以」（#8270 / #8322） |
|
||||||
| `589539` | 房 / 车 / 导 / 摄四项未配齐 |
|
| `589542` | 房 / 车 / 导 / 摄四项未配齐。⚠️ 2026-09-24 订正：原文误写为 `589539`（该号实为 #7178「名额调整量不能为 0」）；**#8270 起本码不再返回** |
|
||||||
| `585003` | 预支金额必须大于 0 |
|
| `585003` | 预支金额必须大于 0 |
|
||||||
| `585004` | 预支金额超过可用余额上限 |
|
| `585004` | 预支金额超过可用余额上限 |
|
||||||
| `585006` | 借款类型非法 |
|
| `585006` | 借款类型非法 |
|
||||||
@@ -391,7 +391,7 @@ POST /v3/admin/order/group-batch/90211/advance
|
|||||||
|
|
||||||
#### 业务边界
|
#### 业务边界
|
||||||
|
|
||||||
- **双前置闸门**：团期状态 + 四项资源全就绪，缺一即拒（此前服务端两道都没有，只有前端做了置灰）。
|
- **双前置闸门**：团期状态 + 四项资源全就绪，缺一即拒（此前服务端两道都没有，只有前端做了置灰）。⚠️ 已变更：#8270 删除四项配齐门，#8322 起进入核单前都可发起，且领款人限定为本团主报账人（589557），见 `24_8322_…` 条目。
|
||||||
- **上限走团期统一池**：团期级与各子订单级**共扣一池**。团期把整团尾款预支满后，该团任一子订单再发起订单级预支同样会被 `585004` 拒——这是本次修复的超支漏洞。
|
- **上限走团期统一池**：团期级与各子订单级**共扣一池**。团期把整团尾款预支满后，该团任一子订单再发起订单级预支同样会被 `585004` 拒——这是本次修复的超支漏洞。
|
||||||
- 创建后进入**站内财务审批**，走既有 `advance-approvals` 列表与 approve / reject / 撤回三端点，与订单级完全一致。
|
- 创建后进入**站内财务审批**，走既有 `advance-approvals` 列表与 approve / reject / 撤回三端点，与订单级完全一致。
|
||||||
- 一期仍**只记账不出款**，实际出款走财务既有付款流程。
|
- 一期仍**只记账不出款**，实际出款走财务既有付款流程。
|
||||||
@@ -583,8 +583,8 @@ GET /v3/admin/order/group-batch/90211/settlement/summary
|
|||||||
| 团期无活跃子订单 | 六个金额字段 `0.00`，`items` 空数组 |
|
| 团期无活跃子订单 | 六个金额字段 `0.00`，`items` 空数组 |
|
||||||
| 子订单已取消 | 不进金额、不进 `items`，只计入 `withdrawnCount` |
|
| 子订单已取消 | 不进金额、不进 `items`，只计入 `withdrawnCount` |
|
||||||
| 未设置报账人 | `primaryPayeeName` 为 `null`，后端不兜底默认导游 |
|
| 未设置报账人 | `primaryPayeeName` 为 `null`，后端不兜底默认导游 |
|
||||||
| 团期状态为招募中 / 核单中 | 发起预支返回 `589538` |
|
| 团期状态为招募中 / 核单中 | 发起预支返回 `589541`（2026-09-24 订正码值；#8322 起招募中已可发起，仅核单中及之后返回） |
|
||||||
| 四项资源缺任一 | 发起预支返回 `589539` |
|
| 四项资源缺任一 | 原返回 `589542`（2026-09-24 订正码值）；#8270 起不再拦截 |
|
||||||
| 团期尾款池已被预支占满 | 团期级与该团任一子订单级预支**均**返回 `585004` |
|
| 团期尾款池已被预支占满 | 团期级与该团任一子订单级预支**均**返回 `585004` |
|
||||||
| 数据字典服务不可用 | 借款类型降级到内置集合校验，正常类型仍可提交 |
|
| 数据字典服务不可用 | 借款类型降级到内置集合校验，正常类型仍可提交 |
|
||||||
| 审批列表出现团期级行 | `orderId` / `orderNo` / `consultantName` / 订单四态均为 `null` |
|
| 审批列表出现团期级行 | `orderId` / `orderNo` / `consultantName` / 订单四态均为 `null` |
|
||||||
@@ -611,7 +611,7 @@ GET /v3/admin/order/group-batch/90211/settlement/summary
|
|||||||
1. 财务 Tab 四张卡与逐户表末行合计一致，且与团期详情、看板列表三处应收同源。
|
1. 财务 Tab 四张卡与逐户表末行合计一致，且与团期详情、看板列表三处应收同源。
|
||||||
2. **超支被堵死**：团期级把整团尾款预支满 → 该团任一子订单再发起订单级预支被 `585004` 拒。
|
2. **超支被堵死**：团期级把整团尾款预支满 → 该团任一子订单再发起订单级预支被 `585004` 拒。
|
||||||
3. **核单零重复扣**：团期级预支 5,000 通过 + 某户订单级预支 2,000 通过 → 该户报销单含 2,000，整团 `groupAdvanceApproved` 仍是 5,000；`grandTotalCost` 不变。
|
3. **核单零重复扣**：团期级预支 5,000 通过 + 某户订单级预支 2,000 通过 → 该户报销单含 2,000，整团 `groupAdvanceApproved` 仍是 5,000；`grandTotalCost` 不变。
|
||||||
4. 两道闸门各拒一次（`589538` / `589539`）。
|
4. 两道闸门各拒一次（`589541` / `589542`，2026-09-24 订正码值）。
|
||||||
5. 团期级预支出现在预支审批列表，「团号 / 产品」「行程」两列有值，按团期号搜得到，就地通过 / 驳回 / 撤回正常。
|
5. 团期级预支出现在预支审批列表，「团号 / 产品」「行程」两列有值，按团期号搜得到，就地通过 / 驳回 / 撤回正常。
|
||||||
6. 订单级预支五端点回归无变化。
|
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 出参 | `payStatus` 写五值含 `REFUNDING` / `REFUNDED` | 代码只有三值；结清状态另出 `settleStatus` 字段 |
|
||||||
| GB-ADM-040 出参 | 含 `advanceTotal` | 已废，改三个数 |
|
| GB-ADM-040 出参 | 含 `advanceTotal` | 已废，改三个数 |
|
||||||
| GB-ADM-042 | 返回 `GroupBatchWriteResultVO`、不回传 `advanceId` | 改返 `OrderAdvanceRespVO` 并回传 `advanceId` |
|
| GB-ADM-042 | 返回 `GroupBatchWriteResultVO`、不回传 `advanceId` | 改返 `OrderAdvanceRespVO` 并回传 `advanceId` |
|
||||||
|
|||||||
@@ -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 <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",
|
||||||
|
"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<AdvancePayeeCandidateVO>`
|
||||||
|
|
||||||
|
#### 使用场景
|
||||||
|
|
||||||
|
「发起预支」弹窗打开时拉取领款人下拉。本单起只会返回主报账人一条，前端可直接默认选中；返回空列表说明本团还没设主报账人。
|
||||||
|
|
||||||
|
#### 入参
|
||||||
|
|
||||||
|
| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|
||||||
|
|---|---|---|---|---|---|
|
||||||
|
| 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 <admin token>
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 响应示例
|
||||||
|
|
||||||
|
```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
|
||||||
在新工单中引用
屏蔽一个用户