---
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