wx/hl-api-changelog
1
0
派生 0
代码 工单 合并请求 工作流 软件包 项目 发布 百科 活动
文件
0b2853224e3ed7b16df6c84d9d378793c90c7d4a
hl-api-changelog/changelogs-v2/2026-09/09_7003_资金账户-新增接口-管理后台.md
T
Mimingguang b99b783557
changelog-filename-gate / validate (push) Failing after 2s
详情
chore(changelog): #7003 资金账户 verified (hl-admin ref 49359412)
2026-09-09 17:02:38 +08:00

8.5 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 7003 资金账户（增改停删 + 盘盈盘亏 + 期初调整 + 统计/下拉） admin yst 新增接口 deployed verified verified mmg 49359412 2026-09-09 后端已合 dev-v3（#7003 account 域 + #7146 三字段字典化）并部署测试服；网关实测 E2E 通过。账户类型不可改、基本户唯一不可停用/改性质、有流水仅可停用。 2026-09-09 dev-v3

资金账户

1. 接口背景

财务域「资金账户」：公司收付款的资金账户（银行户/现金户/第三方支付户/内部虚拟户）全生命周期管理——建档、编辑、停用、删除、盘盈盘亏、期初结存调整、结存统计、下拉选项。属 Epic 财务域 account 资金账户域（#7003），并经 #7141 三字段字典化增强（type/nature/channel 中文标签 + 下拉）。

2. 变更清单

类型 接口 说明
新增 GET /admin/finance/fund-accounts/page 账户分页列表（类型/性质/状态/关键词筛选）
新增 GET /admin/finance/fund-accounts/stats 结存统计（总计/按类型/退款预留预警）
新增 GET /admin/finance/fund-accounts/options 三组下拉（类型/性质/渠道，字典化）
新增 POST /admin/finance/fund-accounts 新建账户
新增 GET /admin/finance/fund-accounts/{id} 账户详情
新增 PUT /admin/finance/fund-accounts/{id} 编辑账户
新增 POST /admin/finance/fund-accounts/{id}/disable 停用账户
新增 DELETE /admin/finance/fund-accounts/{id} 删除账户（无流水才可删）
新增 POST /admin/finance/fund-accounts/{id}/inventory-adjust 盘盈盘亏
新增 POST /admin/finance/fund-accounts/{id}/opening-adjust 期初结存调整

3. 接口详情

3.1 分页列表 GET /page

入参（Query + 分页）：accountType(BANK/CASH/THIRD_PARTY/INTERNAL_VIRTUAL) / nature(BASIC/GENERAL) / status(ACTIVE/DISABLED) / keyword(账号或账户名模糊) / pageNo / pageSize。

出参行（FundAccountRowRespVO，Long ID 均 String）：

字段 类型 说明
id String 账户ID
accountName String 账户名称
accountNo String 账号（展示层脱敏）
bankName String 开户行
accountType String 账户类型（枚举大写）
accountTypeName String 账户类型中文名（字典 fin_fund_account_type 标签，字典不可用为 null）
nature String 账户性质（仅 BANK，其余 null）
natureName String 性质中文名（字典标签）
channel String 第三方渠道（仅 THIRD_PARTY，其余 null）
channelName String 渠道中文名（字典标签）
shortName String 账户简称
displayName String 对外展示名（空则展示账户名称）
sortOrder Integer 排序（越小越靠前）
feeRate BigDecimal 手续费率（仅 THIRD_PARTY，如 0.006）
refundReserve BigDecimal 退款预留额度（仅 THIRD_PARTY）
openingBalance BigDecimal 期初结存
balance BigDecimal 当前结存
currency String 币种（默认 CNY）
scopeCompanies String 适用公司范围
status String ACTIVE / DISABLED

3.2 统计 GET /stats

出参：totalBalance（全部生效账户结存总计）/ byType[]（accountType + accountTypeName + accountCount + balance）/ reserveWarnings[]（余额低于 refundReserve 的三方户：accountId/accountName/当前结存）。

3.3 下拉 GET /options

出参三组：accountTypes[] / natures[] / channels[]，元素 OptionItem{value, label, sortOrder}（value=枚举大写名如 BANK/BASIC/WXPAY，label=中文，sortOrder 升序，仅 ACTIVE）。账户性质仅 BANK 用、渠道仅 THIRD_PARTY 用，前端按 accountType 联动展示。

3.4 新建 POST /

入参（FundAccountCreateReqVO）：

字段 必填 说明
accountName 是 账户名称（全称化口径）
accountNo 是 账号（原值入库，展示脱敏）
bankName 否 开户行
accountType 是 BANK / CASH / THIRD_PARTY / INTERNAL_VIRTUAL
nature BANK 必填 BASIC / GENERAL
channel THIRD_PARTY 必填 WXPAY / ALIPAY
settleAccountNo 否 绑定结算卡（仅 THIRD_PARTY，原值入库展示脱敏）
refundReserve 否 退款预留额度（仅 THIRD_PARTY，默认 0）
shortName 否 账户简称
displayName 否 对外展示名（空则展示账户名称）
sortOrder 否 排序（越小越靠前）
openingBalance 否 期初结存（默认 0）
feeRate 否 手续费率（仅 THIRD_PARTY，如 0.006）
overdraftAllowed 否 是否允许透支（布尔）
payQrUrl 否 收款码影像 URL（仅 CASH/THIRD_PARTY 收款场景）
remark 否 备注

出参：{id}（新账户ID，String）。

3.5 详情 GET /{id}

出参 = Row 全字段 + settleAccountNo（结算卡脱敏）/ overdraftAllowed / payQrUrl / remark / flows[]（最近资金流水行）。

3.6 编辑 PUT /{id}

入参同新建（FundAccountUpdateReqVO，accountType 不可改；BASIC 基本户 nature 不可改成其他）。

3.7 停用 POST /{id}/disable

无入参。唯一基本户不允许停用（595005）；已停用重复停用幂等。

3.8 删除 DELETE /{id}

有流水账户不可删（595003），仅可停用。

3.9 盘盈盘亏 POST /{id}/inventory-adjust

入参：direction（SURPLUS 盘盈补收 / DEFICIT 盘亏补付，必填）/ amount（差额>0，必填）/ reason（原因，必填，进留痕）/ voucherUrl（佐证影像，选填）。

3.10 期初调整 POST /{id}/opening-adjust

入参：newOpeningBalance（新期初结存≥0，必填；调整后结存=新期初+历史流水净影响）/ reason（可空，缺省生成「期初调整 旧→新」）/ voucherUrl（选填）。

4. 枚举 / 数据字典

字段 取值 字典表
accountType BANK 银行 / CASH 现金 / THIRD_PARTY 第三方支付 / INTERNAL_VIRTUAL 内部虚拟户（预留） fin_fund_account_type
nature BASIC 基本户 / GENERAL 一般户（仅 BANK） fin_fund_account_nature
channel WXPAY 微信支付 / ALIPAY 支付宝（仅 THIRD_PARTY） fin_fund_account_channel
status ACTIVE 生效 / DISABLED 停用 -
direction SURPLUS 盘盈 / DEFICIT 盘亏 -

字典建在 user-service（部署顺序：先 user-service 后 order-v3）。建议前端用 /options 拉下拉，channel 已彻底字典化（后续加渠道零发版）。

5. 错误码（段位 595000-595099）

码 含义
595001 账户不存在
595002 基本户每公司唯一，已存在其他基本户
595003 有流水账户不可删除，仅可停用
595004 互转两方账户不能相同
595005 唯一基本户不允许停用
595006 账户已停用
595007 账户字段组合不合法（银行户必填账户性质，三方户必填渠道）
595008 取现出账账户须为基本户
595009 存取方式无效
595010 存取方式与转出/转入账户类型不匹配

6. 示例

新建银行基本户

POST /admin/finance/fund-accounts
{"accountName":"呼伦贝尔XX公司基本户","accountNo":"150XXX","bankName":"中国银行","accountType":"BANK","nature":"BASIC"}
→ 200 {"id":"2097..."}

三方户缺渠道（异常）

POST /admin/finance/fund-accounts  {"accountName":"微信商户","accountNo":"...","accountType":"THIRD_PARTY"}
→ 595007 账户字段组合不合法

删除有流水账户（异常）

DELETE /admin/finance/fund-accounts/{id}  → 595003 有流水账户不可删除，仅可停用

盘盈

POST /admin/finance/fund-accounts/{id}/inventory-adjust
{"direction":"SURPLUS","amount":100.00,"reason":"盘点溢余"}
→ 200

7. 注意事项

  • 账号/结算卡原值入库、展示层脱敏，出参 accountNo 为脱敏值。
  • 全部长整型 ID 序列化为字符串。
  • 账户类型不可改；基本户唯一且不可停用/不可改性质。
  • 删除仅限无流水账户，有流水走停用。

8. 关联 / 联系人

在新工单中引用 查看 Git Blame 复制永久链接