diff --git a/changelogs-v2/2026-09/30_8657_收款方类型删STAFF拆为司机导游摄影领队-修改接口-管理后台.md b/changelogs-v2/2026-09/30_8657_收款方类型删STAFF拆为司机导游摄影领队-修改接口-管理后台.md new file mode 100644 index 00000000..463eabf7 --- /dev/null +++ b/changelogs-v2/2026-09/30_8657_收款方类型删STAFF拆为司机导游摄影领队-修改接口-管理后台.md @@ -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 +- **前端对接(管理后台)**: 待认领