339 行
15 KiB
Markdown
339 行
15 KiB
Markdown
---
|
||
schema: "hl-changelog/v2"
|
||
ticket: "8322"
|
||
title: "团期预支核单前均可发起（放开招募中）+ 领款人限定为本团主报账人（新码 589557）；一并补 #8270 放宽说明"
|
||
consumer: "admin"
|
||
author: "jw(GIT)"
|
||
change_type: "修改接口"
|
||
backend_status: "deployed"
|
||
gateway_status: "verified"
|
||
frontend_status: "verified"
|
||
frontend_owner: "mmg"
|
||
frontend_ref: "0ba1a2732022c800b2cee0711f1ed052b5e19dad"
|
||
target_release: "v2.1"
|
||
verified_at: "2026-09-24"
|
||
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。 | 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 例全绿"
|
||
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
|