diff --git a/changelogs-v2/2026-08/23_6153_供应商注册与收款账户管理-新增接口-管理后台.md b/changelogs-v2/2026-08/23_6153_供应商注册与收款账户管理-新增接口-管理后台.md new file mode 100644 index 00000000..4b809047 --- /dev/null +++ b/changelogs-v2/2026-08/23_6153_供应商注册与收款账户管理-新增接口-管理后台.md @@ -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 diff --git a/changelogs-v2/2026-08/23_6205_供应商草稿创建版本时间一致性-修改接口-管理后台.md b/changelogs-v2/2026-08/23_6205_供应商草稿创建版本时间一致性-修改接口-管理后台.md new file mode 100644 index 00000000..3c47eecd --- /dev/null +++ b/changelogs-v2/2026-08/23_6205_供应商草稿创建版本时间一致性-修改接口-管理后台.md @@ -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