8.7 KiB
8.7 KiB
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 | 6153 | 供应商注册、资料维护与收款账户管理接口 | admin | lc(GIT) | 新增接口 | deployed | verified | verified | mmg | 9e1aba14 | 2026-08-23 | #6153 与 #6161-#6164 已合并 dev-v3，并随当前目标提交 03685ac245 完成隔离 TEST。13 个接口均经真实管理员登录、Gateway、角色切换、数据库和同步敏感读取审计验证；归档接口按 #6174 在权威清账契约交付前固定失败关闭。 | 2026-08-23 | 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。
撤回
- 停止 13 个管理端接口的新流量，按账户管理、供应商主档、Gateway/权限依赖的逆序回退对应合并提交并重新部署。
- 已应用的 13 张供应商表 migration 不修改、不删除；旧版本忽略新增表。已产生的主体、审批和审计数据保留，业务恢复通过后续受审计补偿操作完成，不直接改库。
- 已应用的 User 权限和字典 migration 使用更高版本 migration 撤销精确角色绑定，不修改既有 Flyway 历史。
- 锁、幂等和权限缓存仅按精确管理员或供应商键清理并验证，无 MQ 恢复项。
- 回退后经 Gateway 验证新接口不可达，并复验既有 Resource、User 和 Gateway 路由。
关联 / 联系人
链接
- 供应商主档 Issue / PR: #6153 / #6171
- 账户接口 Issues: #6161、#6162、#6163、#6164
- 账户接口 PR: #6181
- Gateway 与权限依赖: #6191
- 归档失败关闭: #6174
- 当前 TEST 目标提交: 03685ac245
联系人
- 后端负责人: @lc