wx/hl-api-changelog

派生 0

文件

T

Mimingguang be4e9e76fa

changelog-filename-gate / validate (push) Failing after 2s

详情

chore(changelog): #8657 回写 implemented(hl-admin adfd6815)

2026-09-30 18:24:34 +08:00

8.0 KiB

原始文件 Blame 文件历史

schema, ticket, title, consumer, author, change_type, backend_status, gateway_status, frontend_status, frontend_owner, frontend_ref, target_release, verified_at, status_note, updated_at, base

schema	ticket	title	consumer	author	change_type	backend_status	gateway_status	frontend_status	frontend_owner	frontend_ref	target_release	verified_at	status_note	updated_at	base
hl-changelog/v2	8657	收款方类型 payeeType 枚举重构：删 STAFF，个人类拆为 GUIDE/DRIVER/PHOTOGRAPHER/LEADER（导游/司机/摄影/领队），保留 FLEET/GUIDE_CO/SUPPLIER（#8657）	admin	yst(GIT)	修改接口	deployed	not_required	implemented	hl-admin(claude-opus-4-8)	adfd68151163824338fa4ee6faef38c84a5bb006		2026-09-30	财务「资金账户→收款账户」的「收款方类型」（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 全量档全绿	2026-09-30	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：

{
  "payeeType": "GUIDE",
  "payeeName": "张三",
  "accountType": "WECHAT_QR",
  "qrUrl": "https://oss.example.com/qr/zhangsan.png",
  "isDefault": 1
}

响应：

{ "code": 200, "message": "成功", "data": { "id": "2105..." }, "success": true }

8.2 边界（车队组织账户）

请求 POST /admin/finance/payee-accounts：

{
  "payeeType": "FLEET",
  "payeeName": "XX 车队",
  "accountType": "CORP_ACCOUNT",
  "bankAccount": "6222...",
  "bankName": "工商银行海拉尔支行"
}

响应：

{ "code": 200, "message": "成功", "data": { "id": "2105..." }, "success": true }

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

请求 POST /admin/finance/payee-accounts：

{
  "payeeType": "STAFF",
  "payeeName": "张三",
  "accountType": "WECHAT_QR"
}

响应：

{ "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=供应商。

8.0 KiB

原始文件 Blame 文件历史

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

1. 接口背景

2. 变更清单

3. 接口详情

3.1 收款方账户分页

3.2 登记收款方账户

4. 接口入参

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

5. 出参（响应）

6. 枚举 / 数据字典

6.1 payeeType（收款方类型，PayeeTypeEnum）

7. 错误码

8. 示例（3 组）

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

8.2 边界（车队组织账户）

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

9. 业务边界

10. 修改前后对比

10.1 枚举值集合对比

10.2 行为级对比

11. 影响评估 / 回滚

12. 注意事项

13. 关联 / 联系人

13.1 链接

13.2 联系人

8.0 KiB 原始文件 Blame 文件历史 Unescape Escape

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

1. 接口背景

2. 变更清单

3. 接口详情

3.1 收款方账户分页

3.2 登记收款方账户

4. 接口入参

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

5. 出参（响应）

6. 枚举 / 数据字典

6.1 payeeType（收款方类型，PayeeTypeEnum）

7. 错误码

8. 示例（3 组）

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

8.2 边界（车队组织账户）

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

9. 业务边界

10. 修改前后对比

10.1 枚举值集合对比

10.2 行为级对比

11. 影响评估 / 回滚

12. 注意事项

13. 关联 / 联系人

13.1 链接

13.2 联系人

8.0 KiB

原始文件 Blame 文件历史