---
schema: "hl-changelog/v2"
ticket: "6153"
title: "供应商注册、资料维护与收款账户管理接口"
consumer: "admin"
author: "lc(GIT)"
change_type: "新增接口"
backend_status: "deployed"
gateway_status: "verified"
frontend_status: "verified"
frontend_owner: "mmg"
frontend_ref: "9e1aba14"
target_release: ""
verified_at: "2026-08-23"
status_note: "#6153 与 #6161-#6164 已合并 dev-v3，并随当前目标提交 03685ac245 完成隔离 TEST。13 个接口均经真实管理员登录、Gateway、角色切换、数据库和同步敏感读取审计验证；归档接口按 #6174 在权威清账契约交付前固定失败关闭。"
updated_at: "2026-08-23"
base: "dev-v3"
---

# 供应商注册、资料维护与收款账户管理

本次在 Resource 服务交付供应商主档注册、资料维护和收款账户管理能力。所有接口统一经过 Gateway 强制认证，并在服务端同时校验可信角色与 User 权限；请求体或请求头中的自报身份不能替代登录态。

## 变更接口

| 编号 | 方法 | 路径 | 权限 | 说明 |
|------|------|------|------|------|
| SUP-ADM-001 | GET | `/admin/supplier/items/page` | `supplier:list` | 分页查询供应商 |
| SUP-ADM-043 | GET | `/admin/supplier/items/list` | `supplier:list` | 最多 200 条的有界列表 |
| SUP-ADM-002 | GET | `/admin/supplier/items/{supplierId}/basic-info/view` | `supplier:view` | 查询脱敏聚合详情 |
| SUP-ADM-003 | POST | `/admin/supplier/items/add` | `supplier:create` | 创建 DRAFT 注册草稿 |
| SUP-ADM-004 | PUT | `/admin/supplier/items/{supplierId}/update` | `supplier:update` | 按版本增量更新资料 |
| SUP-ADM-007 | POST | `/admin/supplier/items/{supplierId}/submit` | `supplier:update` + `supplier:approval:submit` | 提交注册审批 |
| SUP-ADM-010 | POST | `/admin/supplier/items/{supplierId}/archive` | `supplier:status:manage` | 清账契约交付前返回 `395032` |
| SUP-ADM-011 | DELETE | `/admin/supplier/items/{supplierId}/del` | `supplier:delete` | 软删除从未提交的草稿 |
| SUP-ADM-012 | GET | `/admin/supplier/items/{supplierId}/approval-records/page` | `supplier:approval:read` | 查询审批关联变更记录 |
| SUP-ADM-013 | GET | `/admin/supplier/items/{supplierId}/account-info/list` | `supplier:view` | 查询脱敏账户列表 |
| SUP-ADM-014 | POST | `/admin/supplier/items/{supplierId}/bank-accounts/add` | `supplier:account:manage` + `supplier:approval:submit` | 批量新增 1 至 50 个账户 |
| SUP-ADM-015 | GET | `/admin/supplier/bank-accounts/{accountId}/view` | `supplier:view`；证明附件另需 `supplier:account:proof:read` | 查询账户详情 |
| SUP-ADM-016 | PUT | `/admin/supplier/bank-accounts/{accountId}/default/update` | `supplier:account:manage` | 切换唯一默认账户 |

## 角色与权限

- `ADMIN` 可查询供应商、审批记录和脱敏账户，但不能创建、更新、提交、删除、维护账户或读取证明附件。
- `FINANCE` 可完成供应商注册、资料维护、草稿删除、账户维护与证明附件读取，但不能执行生命周期归档。
- `SUPER_ADMIN` 拥有上述全部权限；归档仍受权威清账门禁约束。
- 其他角色无供应商权限。菜单或按钮显隐不能替代服务端授权。

账户证明附件是独立敏感权限：无权限时 `proofFileUrls` 字段不序列化；有权限时，Resource 必须先同步写入不含 URL 和账号的 User 操作审计，审计失败则不返回附件。

## 主要业务语义

### 注册与资料

- 创建固定为 `DRAFT`、信用等级 `B`，返回的 `updateTime` 是后续更新或提交必须原样回传的并发版本。
- 注册提交采用准备事务、事务外审批 Provider、结果事务三阶段流程。本期 `LOCAL_AUTO` 成功后，供应商进入 `ACTIVE`，初始账户进入 `ACTIVE`，首个账户成为唯一默认账户。
- `ACTIVE` 后供应商全称和统一社会信用代码不可修改，返回 `395033`；旧版本返回 `395014`，均不产生业务写入。
- 草稿删除使用软删除并保留审批、创建和删除审计。非草稿状态删除返回 `395005`。
- 税号、电话、证照号和收款账号加密存储；查询只返回脱敏值。Snowflake ID 统一按 JSON String 返回。

### 收款账户

- 列表只返回未删除的 `PENDING/ACTIVE/DISABLED` 账户，默认账户优先，其余按 `createTime DESC、accountId DESC` 稳定排序。
- 批量新增先整体校验，再为每个账户生成独立审批记录；成功账户为 `ACTIVE/NO`，响应顺序与请求顺序一致。
- 重复账号返回 `395027`，不存在账户返回 `395001`，失败不新增账户或审批记录。
- 默认账户切换在供应商聚合锁和数据库行锁内完成，只允许 `ACTIVE` 供应商的 `ACTIVE` 账户。重复设置当前唯一默认账户按业务幂等成功，不更新时间也不写审计。

### 归档

`SUP-ADM-010` 已存在，但在 #6173 提供权威清账契约前固定返回 `395032`。该失败发生在归档审批、状态变更和供应商数据库写入之前，不能通过本地假定“已清账”降级放行。

## 主要错误码

| 业务码 | 含义 |
|-------:|------|
| `395001` | 供应商或账户不存在 |
| `395002` | 无供应商普通写权限 |
| `395005` | 当前状态不允许执行该操作 |
| `395006` | 主体证件号已建档 |
| `395014` | 并发版本已变化 |
| `395027` | 收款账号已被占用 |
| `395032` | 无法确认权威清账，归档失败关闭 |
| `395033` | 审批中或审批后主体身份字段不可修改 |

统一响应可能以 HTTP 200 承载业务失败，调用方必须同时检查 `code`、`success` 和 `data`。

## 验证证据

- 当前 TEST 部署目标提交：`03685ac24520dea5917c708cda76942dee89c2e2`，Nacos 中 Resource 仅有一个健康实例。
- 自动化回归：Supplier 聚焦测试 `150/150`，Resource 全量 `1906` 项零失败（38 项仓库既有条件跳过），Gateway 路由与 JWT 供应商测试 `8/8`；#6205 定向回归 `5/5`。
- 真实 Gateway E2E 共 `105` 个断言通过，覆盖匿名与伪造身份 `401`、ADMIN/FINANCE/SUPER_ADMIN 真实角色切换、参数和越权零写入、草稿创建与立即提交、审批状态、乐观锁、主体门禁、软删除、账户批量审批、敏感读取同步审计、唯一默认与幂等、归档失败关闭。
- 数据核对确认税号、电话、证照号、账号和审批候选均无明文落库；响应与服务日志未发现测试税号、账号或令牌。
- 验收使用独立一次性 User/Resource schema，原始 Resource schema 全程保持 0 张 `supplier_*` 表；一次性业务数据在证据核对后清理。
- HL 仓库未配置 Gitea workflow/status context；远端证据为 PR 合并态、目标分支包含关系和提交完整性核对，不将其表述为已运行远端 CI。

## 前端接入提示

- 更新和提交必须使用最近一次创建、更新或详情响应中的 `updateTime`，收到 `395014` 后重新查询。
- ADMIN 不展示供应商写操作、账户维护和证明附件；FINANCE 不展示归档；服务端仍会独立拒绝越权调用。
- 账户详情必须容忍 `proofFileUrls` 整个字段缺失，而不是把缺失视为接口异常。
- 归档按钮在 #6173 交付前应按不可用处理，不能重试绕过 `395032`。

## 撤回

1. 停止 13 个管理端接口的新流量，按账户管理、供应商主档、Gateway/权限依赖的逆序回退对应合并提交并重新部署。
2. 已应用的 13 张供应商表 migration 不修改、不删除；旧版本忽略新增表。已产生的主体、审批和审计数据保留，业务恢复通过后续受审计补偿操作完成，不直接改库。
3. 已应用的 User 权限和字典 migration 使用更高版本 migration 撤销精确角色绑定，不修改既有 Flyway 历史。
4. 锁、幂等和权限缓存仅按精确管理员或供应商键清理并验证，无 MQ 恢复项。
5. 回退后经 Gateway 验证新接口不可达，并复验既有 Resource、User 和 Gateway 路由。

## 关联 / 联系人

### 链接

- **供应商主档 Issue / PR**: [#6153](https://git.1814.love:8443/wx/HL/issues/6153) / [#6171](https://git.1814.love:8443/wx/HL/pulls/6171)
- **账户接口 Issues**: [#6161](https://git.1814.love:8443/wx/HL/issues/6161)、[#6162](https://git.1814.love:8443/wx/HL/issues/6162)、[#6163](https://git.1814.love:8443/wx/HL/issues/6163)、[#6164](https://git.1814.love:8443/wx/HL/issues/6164)
- **账户接口 PR**: [#6181](https://git.1814.love:8443/wx/HL/pulls/6181)
- **Gateway 与权限依赖**: [#6191](https://git.1814.love:8443/wx/HL/issues/6191)
- **归档失败关闭**: [#6174](https://git.1814.love:8443/wx/HL/issues/6174)
- **当前 TEST 目标提交**: [03685ac245](https://git.1814.love:8443/wx/HL/commit/03685ac24520dea5917c708cda76942dee89c2e2)

### 联系人

- **后端负责人**: @lc