收款方类型 payeeType 删 STAFF 拆为司机/导游/摄影/领队四类个人，保留 FLEET/GUIDE_CO/SUPPLIER（#8657）

2026-09-30 15:55:25 +08:00
@@ -0,0 +1,194 @@
+---
+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: "pending"
+frontend_owner: ""
+frontend_ref: ""
+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 现报非法。"
+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
+- **前端对接（管理后台）**: 待认领