wx/hl-api-changelog
1
0
派生 0
代码 工单 合并请求 工作流 软件包 项目 发布 百科 活动

docs: 纠正供应商合同独立登记交付状态 (#6544) #80

已合并
lc 于 2026-08-29 09:40:44 +08:00 将 1 次代码提交从 changelog/6544-supplier-contract-boundary 合并至 main
对话内容 0 代码提交 1 文件变动 2
+30 -27
共修改 2 个文件，包含 30 行新增和 27 行删除
下载 Patch 文件 下载 Diff 文件 展开所有文件 折叠所有文件
changelogs-v2/2026-08/26_6397_供应商注册合同聚合信息-修改接口-管理后台.md
+11 -9
查看文件
@@ -1,29 +1,31 @@
---
schema: "hl-changelog/v2"
ticket: "6397"
title: "供应商注册合同聚合信息"
title: "供应商注册合同聚合信息（已废弃）"
consumer: "admin"
author: "lc(GIT)"
change_type: "修改接口"
backend_status: "deployed"
gateway_status: "verified"
frontend_status: "verified"
frontend_status: "pending"
frontend_owner: "mmg"
frontend_ref: "002475b2"
frontend_ref: "pending"
target_release: "v2.1"
verified_at: "2026-08-27"
status_note: "PR #6405 已合并 dev-v3；Deploy Panel 任务 af3f205b 成功发布 Resource 双实例，合同接口已完成 23 项真实 Gateway 验收。TEST 工作副本存在服务器本地提交导致精确提交回读仍被阻塞，后端工单保持开启；本条只交接已经实测存在的接口契约。2026-08-26 晚 PR #6450 修正：响应 contracts[].amount 由 Number 改为 String（金额全站统一字符串输出）。前端 002475b2 已按字符串重新集成：fillForm toContractAmount 将 String 归一为 number 供表单绑定/快照比较，详情列透传渲染，提交侧 Number 不变，补 String 回填测试锁定兼容。"
updated_at: "2026-08-27"
verified_at: "2026-08-29"
status_note: "本条记录的 #6405 合同随供应商草稿/注册聚合写入语义已被业务纠正并废弃，不再是当前可联调契约。当前后端以 #6544 为准：add/update/submit 对旧 contracts 输入兼容忽略，合同只在已有 supplierId 后通过三个独立接口维护，不进入建档审批；详情继续只读返回 contracts。最终 Resource 已通过任务 ca2fe4d7 部署提交 c579c87014f56452fea2fce5075b31ae6fd12a35。旧前端 002475b2 仅作为历史记录，当前消费状态恢复 pending。"
updated_at: "2026-08-29"
base: "dev-v3"
---
# 🔧 供应商注册合同聚合信息
# ⚠️ 供应商注册合同聚合信息（已废弃）
供应商创建草稿、提交注册和基础信息详情现统一支持合同完整快照。管理端应把“合同信息”放在“资质证照”之后、现有账户区域之前，并把原“初始账户”展示标题改为“结算信息”。
> **2026-08-29 纠正：本文以下聚合写入说明仅保留为历史，不得继续用于联调或实现。** 当前契约见 [#6544 供应商合同独立登记](../2026-08/29_6544_供应商合同独立登记-新增接口-管理后台.md)：供应商草稿、资料更新和注册提交对旧 `contracts` 输入兼容接收但完全忽略；合同必须在取得 `supplierId` 后，通过独立 add/update/del 接口和独立事务维护，且不进入建档审批。`basic-info/view` 仍只读返回未软删合同，`initialAccounts` 字段保持不变。
原前端提交 `002475b2` 消费的是已撤销的聚合写语义，只作为历史事实保留，当前状态为待按独立接口重新接入。
展示名调整不改变接口字段：原请求字段仍为 `initialAccounts`，不得改成 `settlementInfo` 或其他名称。
## 二、变更接口清单
## 二、变更接口清单（历史，禁止用于当前联调）
| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
|---:|---|---|---|---|---|
changelogs-v2/2026-08/29_6544_供应商合同独立登记-新增接口-管理后台.md
+18 -17
查看文件
@@ -12,7 +12,7 @@ frontend_owner: "mmg"
frontend_ref: "pending"
target_release: "v2.1"
verified_at: "2026-08-29"
status_note: "PR #6559 已合并 dev-v3（提交 b95c15b0e，#6544）；hl-resource-service 8-28 构建已部署 TEST 并含独立合同端点，真实 SUPER_ADMIN 身份完成新增/更新/删除/版本围栏/错误码抽查。审批提交候选 v2 起不再携带 contracts，合同由独立接口维护。已知 B1：当前 TEST 构建 create 返回的 updateTime 为内存值，亚秒被全局序列化截断而 DB DATETIME(0) 四舍五入，约半数场景立即用其 update 会 395014——修复已合入 #6591（写后回读），待部署后 create 返回值即数据库真实秒级版本。"
status_note: "PR #6559、#6591、#6606 已合并 dev-v3；hl-resource-service 已通过 Deploy Panel 任务 ca2fe4d7 部署最终提交 c579c87014f56452fea2fce5075b31ae6fd12a35。#6591 的写后回读、395052–395058、金额 scale 等值与草稿合同存在门禁均已进入 TEST。#6544 基线曾完成独立合同写链路实证；本次最终提交因运行时身份缺少 supplier:update，按用户确认冻结权限依赖的真实写复测，未配置权限、未发业务写请求，不把缺失权限记为通过。"
updated_at: "2026-08-29"
base: "dev-v3"
---
@@ -184,7 +184,7 @@ Content-Type: application/json
}
```
必填字段缺失或长度超限返回 `400`（#6591 部署后改为 395052/395053 等冻结错误码，文案不变）：
正常 HTTP 请求先经过 Bean Validation；缺必填字段或长度超限仍返回 `400` 和中文字段文案。`395052`–`395056` 是 Service/事务层防旁路校验的冻结错误码，不替代 Controller 的 `400`：
```json
{
@@ -197,7 +197,7 @@ Content-Type: application/json
#### 业务边界
- 权限：可信管理员口令 + `ADMIN`/`FINANCE`/`SUPER_ADMIN` 允许的写角色 + `supplier:update` 平台权限；任一门禁失败不产生数据库写。
- 权限：可信管理员身份 + `FINANCE`/`SUPER_ADMIN` 写角色 + `supplier:update` 平台权限；`ADMIN` 或任一平台权限门禁失败均不产生数据库写。
- 合同登记只写 `supplier_contract` 单表与一条 `CREATE` 审计事实，不推进供应商主体版本，不进审批。
- 幂等：同一管理员 + 同一供应商 + 同一规范化载荷 5 秒窗口内重复提交只执行一次；锁键按供应商分区。
- 事务内先锁供应商行（FOR UPDATE），改合同必在事务中完成，失败整体回滚。
@@ -428,7 +428,7 @@ Content-Type: application/json
### 关键提示（当前 TEST 构建）
- 已登记的合同通过详情接口随供应商返回的 `contracts` 数组回显，前端不必重复维护列表状态。
- **已知 B1（#6544 合并构建）**：登记（add）响应中的 `updateTime` 来自内存填充值，亚秒被全局序列化截断，而数据库 DATETIME(0) 四舍五入进位——约一半场景下该返回值比数据库真实版本早 1 秒，立即用其 update/del 会返回 `395014`。修复 `#6591`（写后读回，返回数据库真实版本）已合并待部署；部署前若遇到 `395014`，请重新拉详情取真实 `updateTime` 再重试。
- **B1 已修复并部署**：登记（add）插入后按合同 ID 回读数据库持久化实体，响应与 CREATE 审计使用同一真实秒级 `updateTime`；该值可直接用于下一次 update/del 版本围栏。
## 五、数据库行为
@@ -443,9 +443,9 @@ Content-Type: application/json
- `supplierId`/`contractId` 非法（非数字、超长、<=0）：`400`；供应商不存在或已软删除：`395001`。
- 已归档供应商：`395031`（写入一律拒绝）。
- 未知或非生命周期状态供应商：`395005`（状态机门禁先行失败）。
- 版本不匹配：`395014`；请求无实际变化：`400`（#6591 部署后为 `395057`）。
- 删除草稿供应商仍有未删除合同：`395058`「已有合同登记，请先独立删除合同」（#6591 部署后；当前构建为 395005）。
- 参数校验错误码：当前构建走 `400` 文案；#6591 部署后为 395052/395053/395054/395055/395056 冻结码，文案不变、场景不变。
- 版本不匹配：`395014`；请求无实际变化：`395057`。
- 删除草稿供应商仍有未删除合同：`395058`「已有合同登记，请先独立删除合同」。
- Controller 的 Bean Validation/绑定失败仍返回 `400`；Service/事务层防旁路校验使用 `395052`–`395056`，其中缺失合同并发版本文案为「预期更新时间不能为空」。
## 六.5、枚举 / 数据字典
@@ -481,30 +481,31 @@ Content-Type: application/json
## 八、测试环境已验证
- 本地自动化：合同命令/事务/校验器定向测试（SupplierContractTransactionServiceTest、SupplierContractValidatorTest、SupplierContractServiceTest、SupplierAggregateWriterTest、SupplierErrorCodeContractTest）51 项零失败；每日审查修复后 `hl-resource-service` 全量 2181 项零失败、零错误（38 项条件跳过）。
- 主 PR：#6544 由 #6559 合入 dev-v3（提交 `b95c15b0e`）；每日审查修复 #6591 已合入（提交 `9eb9c96c0`，待部署）。
- TEST 部署证实：`hl-resource-service` jar（8-28 09:48 构建）含独立合同端点与校验器，双实例 8-28 21:03 重启运行中。
- 真实 Gateway（127.0.0.1:8080，SUPER_ADMIN）抽查：登记成功并返回字符串 ID/金额/秒级版本；版本围栏过期 `395014`；删除成功软删（`deleted_at` 落库）；不存在供应商 `395001` 正确；参数缺 `expectedUpdateTime` 返回 400。
- 已知缺口（已修复未部署）：登记返回值与数据库版本亚秒错位问题（B1，#6591 写后回读）在 TEST 实测复现，属当前构建已确认缺陷，非契约差异。
- 数据清理：验收使用的自建测试合同均已通过接口软删自清理，未改动同事业务数据。
- 主 PR #6559、审查修复 PR #6591 与中文版本文案补充 PR #6606 均已合入 `dev-v3`；最终 Resource 合并提交为 `d7e455492648b085445691ccde4a13198d4cd6c6`。
- TEST 部署：Deploy Panel 任务 `ca2fe4d7` 成功，预期/实际提交均为 `c579c87014f56452fea2fce5075b31ae6fd12a35`；双进程、Nacos 两实例、6 个任务期采样和两类日志门禁通过，零观测不可用采样。
- 最终自动化：合同定向 73 项、供应商真实 MySQL Testcontainers 398 项、Resource 全量 2181 项均为 0 失败/0 错误；全量保留 38 项既有条件跳过。
- Gateway 边界：#6544 基线写链路已有真实 TEST 实证；最终部署回读身份为 `SUPER_ADMIN`，但当前平台权限不含 `supplier:update`。用户明确冻结该权限依赖的写复测，本轮没有配置/绕过权限，也没有发合同业务写请求；权限与事务成功/拒绝路径以最终自动化证据补充，不宣称运行时缺失权限已通过。
- 数据清理：本轮最终部署和冻结验收未创建供应商、合同、缓存、MQ 或审批合成数据；TEST 身份已登出。
## 九、相关历史 PR
| PR | Issue | 说明 | 是否仍有效 |
|---|---|---|---|
| #6559 | #6544 | 独立合同登记三写接口 + 边界拆分 | ✅ 本次主功能 |
| #6558 | 每日审查 | 合同模块每日审查修复 7 项（写后读回/错误码/VO 文档/金额比较） | ✅ 待部署 |
| #6591 | #6604 | 合同模块每日审查修复 7 项（写后读回/错误码/VO 文档/金额比较） | ✅ 已部署 |
| #6606 | #6604 | 合同并发版本校验中文文案与全局错误码审计修复 | ✅ 已部署 |
| #6519 | #6474 | 供应商变更/审批分离（前置演进） | ✅ 不受影响 |
## 十、相关文档
- 关联 Issue：[#6544](https://git.1814.love:8443/wx/HL/issues/6544)
- 关联 PR：[#6559](https://git.1814.love:8443/wx/HL/pulls/6559) / [#6591](https://git.1814.love:8443/wx/HL/pulls/6591)
- 关联 PR：[#6559](https://git.1814.love:8443/wx/HL/pulls/6559) / [#6591](https://git.1814.love:8443/wx/HL/pulls/6591) / [#6606](https://git.1814.love:8443/wx/HL/pulls/6606)
- 管理端接入：详情页「合同」区改为直接调 add/update/del 三接口；提交审批的候选不再携带 contracts。
## 撤回
1. 管理端停止请求三个 contract 写路径，并清除详情页合同编辑入口。
2. 从最新 `dev-v3` 建独立回退分支，对主功能合并执行 `git revert -m 1 --no-edit b95c15b0e`，验证后经独立 PR 合入。
2. 从最新 `dev-v3` 建独立回退分支，按依赖逆序回退 `d7e455492648b085445691ccde4a13198d4cd6c6`、`9eb9c96c09975a3ccf4966a257cc77bdf9f743b9` 与 `be0fe8125197b759459c975d211319e10cad150c`，验证后经独立 PR 合入。
3. 仅需回退写接口时可先保留回显逻辑，只移除 add/update/del 路由与前端入口。
4. 使用 Deploy Panel 两阶段客户端仅滚动部署 `hl-resource-service`；本次无数据库、配置、Redis 或 MQ 恢复步骤。
5. 撤回后经 Gateway 验证三个写路径不可用、详情 `contracts` 回显按选定回退范围正常，并确认零写入。
@@ -515,8 +516,8 @@ Content-Type: application/json
### 链接
- **Issue**: [#6544](https://git.1814.love:8443/wx/HL/issues/6544)
- **PR**: [#6559](https://git.1814.love:8443/wx/HL/pulls/6559) / [#6591](https://git.1814.love:8443/wx/HL/pulls/6591)
- **Merge commit**: [`b95c15b0e`](https://git.1814.love:8443/wx/HL/commit/b95c15b0e3) / [`9eb9c96c0`](https://git.1814.love:8443/wx/HL/commit/9eb9c96c09975a3ccf4966a257cc77bdf9f743b9)
- **PR**: [#6559](https://git.1814.love:8443/wx/HL/pulls/6559) / [#6591](https://git.1814.love:8443/wx/HL/pulls/6591) / [#6606](https://git.1814.love:8443/wx/HL/pulls/6606)
- **Merge commit**: [`be0fe8125`](https://git.1814.love:8443/wx/HL/commit/be0fe8125197b759459c975d211319e10cad150c) / [`9eb9c96c0`](https://git.1814.love:8443/wx/HL/commit/9eb9c96c09975a3ccf4966a257cc77bdf9f743b9) / [`d7e455492`](https://git.1814.love:8443/wx/HL/commit/d7e455492648b085445691ccde4a13198d4cd6c6)
### 联系人