---
schema: "hl-changelog/v2"
ticket: "8657"
title: "收款方类型 payeeType 枚举重构：删 STAFF，个人类拆为 GUIDE/DRIVER/PHOTOGRAPHER/LEADER（导游/司机/摄影/领队），保留 FLEET/GUIDE_CO/SUPPLIER（#8657）"
consumer: "admin"
author: "yst(GIT)"
change_type: "修改接口"
backend_status: "deployed"
gateway_status: "not_required"
frontend_status: "implemented"
frontend_owner: "hl-admin(claude-opus-4-8)"
frontend_ref: "adfd68151163824338fa4ee6faef38c84a5bb006"
target_release: ""
verified_at: "2026-09-30"
status_note: "财务「资金账户→收款账户」的「收款方类型」（payeeType，枚举非数据字典）重理口径。原 STAFF 标「司导/员工个人」表述错误：司导（导游/司机/摄影/领队）是带团服务人员、非内部员工（与司导往来账 GuideStaffRoleEnum 同源口径，员工借款不纳入）。个人类按带团角色拆为 GUIDE/DRIVER/PHOTOGRAPHER/LEADER 四类；FLEET 车队/GUIDE_CO 导游公司/SUPPLIER 供应商三个组织类保留。⚠️破坏性：删除 STAFF 枚举值——前端若写死 STAFF 选项需清理；新增 4 个个人类值需补充到下拉选项与 label 映射。后端校验 PayeeTypeEnum.of() 随枚举自动生效，传 STAFF 现报非法。;前端已交付:PAYEE_TYPES 删 STAFF 拆 GUIDE/DRIVER/PHOTOGRAPHER/LEADER 四角色(label §12 映射),checkpoint 全量档全绿"
updated_at: "2026-09-30"
base: "dev-v3"
---

# finance：收款方类型 payeeType 枚举重构（管理后台）

> ⚠️ **破坏性变更**：`payeeType` 删除枚举值 `STAFF`，新增 `GUIDE`/`DRIVER`/`PHOTOGRAPHER`/`LEADER`。前端如有写死的 payeeType 选项/label 映射需同步更新。

## 1. 接口背景

财务「资金账户 → 收款账户」登记收款方账户时，「收款方类型」（`payeeType`）标识「钱打给谁的结算主体」。

原枚举 `STAFF` 注释中文标「司导/员工个人」——**表述错误**：司导（导游/司机/摄影/领队）是带团服务人员，**非内部员工**（与司导往来账口径一致，员工借款不纳入司导范围）。且「个人」粒度过粗。

本次把个人类按带团角色直接拆分为 **司机/导游/摄影/领队** 四类，与 `GuideStaffRoleEnum`（司导角色）同源。

## 2. 变更清单

| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
|---|------|------|------|----------|------|
| 1 | 收款方账户分页 | GET | `/admin/finance/payee-accounts/page` | 修改接口 | `payeeType` 过滤值集合变化 |
| 2 | 登记收款方账户 | POST | `/admin/finance/payee-accounts` | 修改接口 | `payeeType` 入参枚举值集合变化 |

> 两个接口路径/方法/其他字段不变，仅 `payeeType` 字段的**合法取值集合**变化。

## 3. 接口详情

### 3.1 收款方账户分页

- **使用场景**：收款账户列表，按收款方类型/名称/账户类型过滤
- **认证**：JWT（管理后台）
- **入参（query）**：`payeeType`（可选过滤，取值见 §6）/ `payeeName`（名称模糊）/ `accountType` / `pageNo` / `pageSize`
- **出参**：`data.records[].payeeType` 返回枚举码（GUIDE/DRIVER/...）

### 3.2 登记收款方账户

- **使用场景**：新增一条收款方账户（个人码/银行卡/对公）
- **认证**：JWT（管理后台）
- **入参（body）**：`payeeType`（必填，取值见 §6）/ `payeeRefId` / `payeeName` / `accountType` / `qrUrl` / `bankAccount` / `bankName` / `isDefault`
- **校验**：`payeeType` 非法（含已删除的 `STAFF`）→ `595202`

## 4. 接口入参

### 4.1 请求体关键字段（登记）

| 字段 | 类型 | 必填 | 说明 | 校验规则 |
|------|------|------|------|----------|
| payeeType | string | 是 | 收款方类型（见 §6） | 须为合法枚举值，否则 595202 |

## 5. 出参（响应）

| 字段 | 类型 | 说明 |
|------|------|------|
| payeeType | string | 收款方类型枚举码（见 §6） |

## 6. 枚举 / 数据字典

### 6.1 payeeType（收款方类型，PayeeTypeEnum）

**所属字段**：`payeeType` | **类型**：`String` | **必填**：✅（登记时）

| 值 | 中文 | 类别 | 说明 |
|----|------|------|------|
| `GUIDE` | 导游 | 个人 | 🆕 打给导游个人（非内部员工） |
| `DRIVER` | 司机 | 个人 | 🆕 打给司机个人（非内部员工） |
| `PHOTOGRAPHER` | 摄影 | 个人 | 🆕 打给摄影个人（非内部员工） |
| `LEADER` | 领队 | 个人 | 🆕 打给领队个人（非内部员工） |
| `FLEET` | 车队 | 组织 | 司机挂车队，打给车队再分（保留） |
| `GUIDE_CO` | 导游公司 | 组织 | 导游挂公司，打给公司再分（保留） |
| `SUPPLIER` | 供应商 | 组织 | 预留（保留） |
| ~~`STAFF`~~ | ~~司导/员工个人~~ | — | ❌ **已删除**（语义混乱：司导非员工） |

## 7. 错误码

| code | 含义 | 触发场景 |
|------|------|----------|
| 595202 | 收款方类型/账户类型非法等组合校验失败 | `payeeType` 传非法值（含已删除的 `STAFF`） |

## 8. 示例（3 组）

### 8.1 典型成功（登记导游个人收款账户）

**请求** `POST /admin/finance/payee-accounts`：
```json
{
  "payeeType": "GUIDE",
  "payeeName": "张三",
  "accountType": "WECHAT_QR",
  "qrUrl": "https://oss.example.com/qr/zhangsan.png",
  "isDefault": 1
}
```

**响应**：
```json
{ "code": 200, "message": "成功", "data": { "id": "2105..." }, "success": true }
```

### 8.2 边界（车队组织账户）

**请求** `POST /admin/finance/payee-accounts`：
```json
{
  "payeeType": "FLEET",
  "payeeName": "XX 车队",
  "accountType": "CORP_ACCOUNT",
  "bankAccount": "6222...",
  "bankName": "工商银行海拉尔支行"
}
```

**响应**：
```json
{ "code": 200, "message": "成功", "data": { "id": "2105..." }, "success": true }
```

### 8.3 业务失败（传已删除的 STAFF）

**请求** `POST /admin/finance/payee-accounts`：
```json
{
  "payeeType": "STAFF",
  "payeeName": "张三",
  "accountType": "WECHAT_QR"
}
```

**响应**：
```json
{ "code": 595202, "message": "收款方类型非法", "success": false }
```

## 9. 业务边界

- ✅ 个人类收款方：用 `GUIDE`/`DRIVER`/`PHOTOGRAPHER`/`LEADER`（按带团角色选）。
- ✅ 组织类收款方：司机挂车队用 `FLEET`、导游挂公司用 `GUIDE_CO`。
- ❌ `STAFF` 已不可用，传了报 `595202`。
- ⚠️ 内部员工（非带团服务人员）不在本收款方类型范围；员工借款走单独的 fin_staff_loan 流程，不在此登记。

## 10. 修改前后对比

### 10.1 枚举值集合对比

| 类别 | 改前 | 改后 |
|------|------|------|
| 个人 | `STAFF`（司导/员工，1 个粗粒度值） | `GUIDE`/`DRIVER`/`PHOTOGRAPHER`/`LEADER`（4 个角色值） |
| 组织 | `FLEET`/`GUIDE_CO`/`SUPPLIER` | 不变 |

### 10.2 行为级对比

| 行为 | 改前 | 改后 |
|------|------|------|
| 传 `STAFF` 登记 | 合法 | 报 `595202` 非法 |
| 个人类收款方粒度 | 只有「司导/员工」一项 | 按导游/司机/摄影/领队四角色细分 |

## 11. 影响评估 / 回滚

- **是否破坏向后兼容**：**是**（删 `STAFF` 枚举值）。
- **前端是否必须同步上线**：是。前端如有写死的 `payeeType` 选项/label 映射需更新：① 删 `STAFF` 选项；② 补 `GUIDE/DRIVER/PHOTOGRAPHER/LEADER` 四项及中文 label。
- **影响已有数据**：测试库 `fin_payee_account` 无 STAFF 存量数据，无需迁移。
- **回滚方式**：revert PR #8658。

## 12. 注意事项

- **前端 workaround 清理点**：若前端此前把 `STAFF` 硬编码为唯一个人类选项，请改为按导游/司机/摄影/领队四项。
- 中文 label 由前端映射（后端只下发枚举码）：`GUIDE=导游 / DRIVER=司机 / PHOTOGRAPHER=摄影 / LEADER=领队 / FLEET=车队 / GUIDE_CO=导游公司 / SUPPLIER=供应商`。

## 13. 关联 / 联系人

### 13.1 链接

- **Issue**: [#8657](https://git.1814.love/wx/HL/issues/8657)
- **PR**: [#8658](https://git.1814.love/wx/HL/pulls/8658)
- **Merge commit**: [8c7520d0da](https://git.1814.love/wx/HL/commit/8c7520d0da)

### 13.2 联系人

- **后端负责人**: @yst
- **前端对接（管理后台）**: 待认领