docs(changelog): 记录供应商备注字段契约变更

2026-08-24 17:46:33 +08:00
@@ -0,0 +1,74 @@
 ---
 schema: "hl-changelog/v2"
 ticket: "6265"
 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: "2026-08-24"
 status_note: "PR #6267 已合并 dev-v3，合并提交 15340bfc0 已随 Resource 双实例滚动部署到 TEST。供应商创建、更新和注册提交请求不再暴露 approveNote，提交请求同时不再暴露 submitNote；仅保留内部 remark。旧客户端继续携带两个废弃字段时，服务端显式忽略且不写入业务、审计或审批数据。"
 updated_at: "2026-08-24"
 base: "dev-v3"
 ---
 # 供应商移除审批备注与提交说明
 供应商新增、修改和注册提交统一移除审批备注 `approveNote`，注册提交同时移除提交审批说明 `submitNote`。`remark` 是唯一保留的内部备注，不会转换为审批原因或发送给审批提供方。
 ## 变更接口
 | 方法 | 路径 | 行为变化 |
 |---|---|---|
 | POST | `/admin/supplier/items/add` | 请求契约移除 `approveNote`，继续保留 `remark` |
 | PUT | `/admin/supplier/items/{supplierId}/update` | 请求契约移除 `approveNote`，继续保留 `remark` |
 | POST | `/admin/supplier/items/{supplierId}/submit` | 请求契约移除 `approveNote`、`submitNote`，继续保留 `remark` |
 三个接口的路径、方法、统一响应结构和其余请求字段均未变化。
 ## 字段语义与兼容性
 - `remark` 仅用于供应商内部备注，按原有新增、修改和完整提交语义持久化。
 - 新请求模型和 Swagger 不再声明 `approveNote`、`submitNote`。
 - 为兼容尚未同步的旧管理端，请求中继续携带 `approveNote` 或 `submitNote` 时不会报未知字段错误；服务端会显式忽略，不产生主体、审批记录、变更记录或审批候选写入。
 - `remark` 不会替代已移除字段，也不会进入审批原因。
 - 提交前完整表单审计原因固定为 `提交注册前保存完整表单`。
 - 发起注册审批的候选原因固定为 `提交供应商注册审批`。
 - 旧加密审批候选 JSON 即使包含 `approveNote` 仍可读取和重放，原幂等、并发和状态门禁保持不变。
 ## 数据兼容与未变化范围
 - 不执行数据库 migration、DDL 或 DML。
 - `supplier_main`、`supplier_approval_log`、`supplier_change_log` 中既有 `approve_note` 物理列和历史值保留，本次部署后不再由新链路写入。
 - 不清理、不回写历史审批备注或提交说明。
 - 写权限不变：`FINANCE`、`SUPER_ADMIN` 继续使用既有成功路径，`ADMIN` 继续按既有权限错误语义拒绝。
 - 不修改 Gateway 路由、认证策略、供应商状态机、事务、聚合锁、幂等、软删除、Redis、MQ、Nacos 或跨服务契约。
 - 本工单仅交付后端；管理端需移除新增、修改和提交表单中的废弃字段，仅保留内部备注。
 ## 验证证据
 - 自动化：定向 57 项零失败；Resource 全量 1944 项零失败、38 项仓库既有条件跳过；合并提交独立审计再跑 57 项零失败。
 - 部署：TEST 部署任务 `8301cec0` 退出码 0，`hl-resource-service` 的 8182、8082 双实例依次健康；部署服务器 HEAD `d1546d477` 包含目标合并提交 `15340bfc0` 和功能提交 `d7a2e98eb`。
 - 真实 Gateway：以有效管理端身份携带旧 `approveNote` 完成草稿创建，并在更新时同时提交旧 `approveNote` 与新的 `remark`，创建和更新均成功，供应商保持草稿状态。
 - 认证失败：列表、创建、更新和提交在缺少 Authorization 时统一返回业务码 `401`、`success=false`，未产生业务写入。
 - 提交安全：未在 TEST 发起真实注册审批，避免产生企业微信审批和附件等外部副作用；废弃 `submitNote` 的忽略、固定审批原因及零差异由部署契约和自动化测试覆盖。
 - 清理：合成草稿删除成功，供应商列表从 4 条恢复到测试前的 3 条，无供应商业务数据残留。
 ## 撤回
 1. 从最新 `dev-v3` 创建回退分支，执行 `git revert -m 1 --no-edit 15340bfc0e98b1eb64723441bf41e645f9cbe7d5`，经独立 PR 合入。
 2. 重新构建并滚动部署 `hl-resource-service`；无需恢复数据库、配置、Redis 或 MQ。
 3. 回退后请求契约会恢复 `approveNote`、`submitNote` 及原审批原因逻辑；既有物理列和历史值始终保留，不需要数据回写。
 4. 经 Gateway 复测新增、修改、提交、内部备注、旧字段绑定、审批原因和旧候选重放。
 ## 关联 / 联系人
 - **Issue**: [#6265](https://git.1814.love:8443/wx/HL/issues/6265)
 - **PR**: [#6267](https://git.1814.love:8443/wx/HL/pulls/6267)
 - **合并提交**: [15340bfc0](https://git.1814.love:8443/wx/HL/commit/15340bfc0e98b1eb64723441bf41e645f9cbe7d5)
 - **后端负责人**: @lc