@@ -0,0 +1,124 @@
|
||||
---
|
||||
schema: "hl-changelog/v2"
|
||||
ticket: "6153"
|
||||
title: "供应商注册、资料维护与收款账户管理接口"
|
||||
consumer: "admin"
|
||||
author: "lc(GIT)"
|
||||
change_type: "新增接口"
|
||||
backend_status: "deployed"
|
||||
gateway_status: "verified"
|
||||
frontend_status: "pending"
|
||||
frontend_owner: ""
|
||||
frontend_ref: ""
|
||||
target_release: ""
|
||||
verified_at: ""
|
||||
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
|
||||
@@ -0,0 +1,64 @@
|
||||
---
|
||||
schema: "hl-changelog/v2"
|
||||
ticket: "6205"
|
||||
title: "供应商草稿创建响应与持久化版本时间保持一致"
|
||||
consumer: "admin"
|
||||
author: "lc(GIT)"
|
||||
change_type: "修改接口"
|
||||
backend_status: "deployed"
|
||||
gateway_status: "verified"
|
||||
frontend_status: "not_required"
|
||||
frontend_owner: ""
|
||||
frontend_ref: ""
|
||||
target_release: ""
|
||||
verified_at: ""
|
||||
status_note: "PR #6206 已合并 dev-v3，提交 03685ac245 已部署隔离 TEST。创建响应 updateTime、立即 GET 与数据库秒级版本完全一致，并可直接用于紧随其后的提交；请求和响应结构、错误码及前端字段解析均未变化。"
|
||||
updated_at: "2026-08-23"
|
||||
base: "dev-v3"
|
||||
---
|
||||
|
||||
# 供应商草稿创建版本时间一致性
|
||||
|
||||
本次修正供应商草稿创建响应中的并发版本时间。此前创建对象依赖插入填充和数据库时间，在跨秒边界可能出现响应 `updateTime` 比实际持久化版本早一秒，导致客户端立即提交时误报 `395014`。
|
||||
|
||||
## 行为变化
|
||||
|
||||
| 方法 | 路径 | 修改前 | 修改后 |
|
||||
|------|------|--------|--------|
|
||||
| POST | `/admin/supplier/items/add` | 极少数跨秒创建响应的 `updateTime` 与数据库值不同 | 创建前显式生成同一秒级 `createTime/updateTime`，响应、立即查询和数据库值一致 |
|
||||
|
||||
请求字段、响应字段、JSON 类型、时间格式、权限、状态机和业务错误码均未改变。`updateTime` 仍为 `yyyy-MM-dd HH:mm:ss`，客户端继续原样回传即可。
|
||||
|
||||
## 兼容性
|
||||
|
||||
- 修复向后兼容，不要求前端同步发布，也不新增字段。
|
||||
- 创建后的 `updateTime` 可直接用于 `POST /admin/supplier/items/{supplierId}/submit` 或后续更新。
|
||||
- 真实旧版本仍返回 `395014`；本次没有放宽乐观锁，也没有改变事务、幂等、审批或审计语义。
|
||||
- 不涉及数据库 migration、配置、Redis、MQ 或其他服务。
|
||||
|
||||
## 验证证据
|
||||
|
||||
- #6205 定向回归 `5/5`；Supplier 聚焦测试 `150/150`；Resource 全量 `1906` 项零失败（38 项仓库既有条件跳过）；Gateway 供应商路由与 JWT 测试 `8/8`。
|
||||
- 独立审计确认仅修改 Resource 的供应商聚合创建时间初始化及对应测试，没有新增入口、绕过权限、修改状态机或跨 schema 写入。
|
||||
- 当前部署提交 `03685ac24520dea5917c708cda76942dee89c2e2` 的真实 Gateway E2E 中：创建响应 `updateTime`、立即 GET 和 MySQL 值完全一致；使用创建响应版本立即提交成功并完成 `LOCAL_AUTO / APPROVED / APPLIED`；刻意使用旧版本仍返回 `395014` 且零写入。
|
||||
- TEST 输出和服务日志未发现测试税号、账号或令牌；原始 Resource schema 未受影响。
|
||||
- HL 仓库未配置 Gitea workflow/status context；已核对 PR 合并态、远端目标提交和文件清单，不宣称不存在的远端 CI。
|
||||
|
||||
## 撤回
|
||||
|
||||
1. 停止供应商创建流量，从最新 `dev-v3` 创建回退分支并 revert #6205 合并提交 `03685ac24520dea5917c708cda76942dee89c2e2`，经独立 PR 合入。
|
||||
2. 重新构建并部署 `hl-resource-service`，无需恢复数据库、配置、Redis 或 MQ。
|
||||
3. 回退会恢复旧的跨秒版本漂移风险，但响应结构保持兼容。
|
||||
4. 回退后经 Gateway 重跑创建、立即查询、立即提交和真实旧版本冲突用例，并核对失败零写入。
|
||||
|
||||
## 关联 / 联系人
|
||||
|
||||
### 链接
|
||||
|
||||
- **Issue**: [#6205](https://git.1814.love:8443/wx/HL/issues/6205)
|
||||
- **PR**: [#6206](https://git.1814.love:8443/wx/HL/pulls/6206)
|
||||
- **合并提交**: [03685ac245](https://git.1814.love:8443/wx/HL/commit/03685ac24520dea5917c708cda76942dee89c2e2)
|
||||
|
||||
### 联系人
|
||||
|
||||
- **后端负责人**: @lc
|
||||
在新工单中引用
屏蔽一个用户