docs(changelog): #6397 对齐 CHANGELOG_TEMPLATE 必备章节(二/三/四/六/七/八/十)

2026-08-26 23:56:51 +08:00
@@ -23,7 +23,7 @@ base: "dev-v3"

 展示名调整不改变接口字段：原请求字段仍为 `initialAccounts`，不得改成 `settlementInfo` 或其他名称。

-## 变更接口清单
+## 二、变更接口清单

 | # | 接口 | 方法 | 路径 | 变化 |
 |---:|---|---|---|---|
@@ -39,7 +39,11 @@ base: "dev-v3"
 - **请求侧不变**：`contracts[].amount` 请求仍按 Number 传（字符串同值也可被兼容解析），无需改表单提交。
 - 前端处理：详情/列表展示处把 amount 当字符串渲染即可，参与运算前 `Number(...)` 转换。

-## 公共合同字段
+## 三、接口详情
+
+三个接口的合同字段完全一致，统一在「公共合同字段」约定；各接口的使用场景、请求/响应示例与错误码分节详述。
+
+### 公共合同字段

 ### 请求字段 `contracts[]`

@@ -355,6 +359,16 @@ Authorization: Bearer <admin-token>
 | 可信角色或 `supplier:view` 平台权限不足 | `403` | 展示无权限状态 |
 | 供应商不存在或已删除 | `395001` | 返回列表并刷新 |

+## 六、边界行为
+
+- `contracts` 省略、`null` 与空数组语义不同：省略/传 `null` = 不处理合同（旧客户端兼容）；`[]` = 明确清空全部合同。
+- 合同非空时单请求最多 100 项；合同与供应商主体、资质、`initialAccounts` 同事务，一起成功或一起失败。
+- 创建草稿禁止携带 `contractId`（每个合同都是新项）；提交既有合同必须原样带回字符串 `contractId`，外部/他人合同 ID 触发整体回滚零写入。
+- `endDate` 早于 `startDate` 直接校验失败，零写入。
+- `amount` 边界：大于等于 0，最多 10 位整数和 2 位小数；响应按字符串输出（PR #6450 起）。
+- 历史只读状态 `TERMINATED` 仅可返回，创建/提交发送该状态会被拒绝。
+- 越权：仅可信 `FINANCE`、`SUPER_ADMIN` 且拥有对应平台权限可写；普通 ADMIN 调用写接口返回越权错误。
+
 ## 修改前后对比

 | 场景 | 修改前 | 修改后 |
@@ -365,7 +379,7 @@ Authorization: Bearer <admin-token>
 | 账户区域标题 | 页面显示“初始账户” | 页面应显示“结算信息”，接口字段仍为 `initialAccounts` |
 | 页面区块顺序 | 资质后直接进入账户区域 | 资质证照 → 合同信息 → 结算信息 |

-## 兼容性与管理端接入事项
+## 四、契约约束与正确调用方式

 1. 在“资质证照”区域之后新增“合同信息”表格，在合同之后显示原账户表格。
 2. 原账户表格标题改为“结算信息”；所有请求和响应继续使用 `initialAccounts`，不要改字段名。
@@ -375,7 +389,15 @@ Authorization: Bearer <admin-token>
 6. 本次不新增接口路径、权限点或业务错误码；旧客户端省略 `contracts` 时继续可用。
 7. 管理端源码不在本后端工单中修改，前端状态保持 `pending`，直至完成页签、标题和表格接入并提供前端引用。

-## TEST 验证证据
+## 七、不影响范围
+
+- 不新增接口路径、权限点或业务错误码；旧客户端省略 `contracts` 时行为完全不变。
+- `initialAccounts` 字段名、类型与语义不变（仅页面展示标题由「初始账户」改「结算信息」，属前端文案）。
+- 请求侧 `contracts[].amount` 仍按 Number 传，PR #6450 只改响应输出，不改请求解析。
+- 供应商其余模块（资源信息、审批记录、账户证明）的接口与字段不受影响。
+- 数据库结构无变更（复用既有快照列），无 Redis/MQ 行为变化。
+
+## 八、测试环境已验证

 - 自动化：供应商定向测试 115 项通过；`hl-resource-service` 全量 2,111 项，0 失败、0 错误，38 项条件跳过；`hl-verify` 与差异检查通过。
 - 部署：Deploy Panel API 任务 `af3f205b` 终态 `success`、退出码 0、`has_build_error=false`，未发现 Maven、编译或滚动发布错误。
@@ -392,6 +414,12 @@ Authorization: Bearer <admin-token>
 4. 已保存的合同资料保留，不做破坏性批量清理；回退后旧客户端继续按省略 `contracts` 的路径工作。
 5. 经 Gateway 复测创建、提交、基础信息、未认证、越权、非法合同 ID、失败零写入和旧客户端兼容，并确认双实例与 Nacos 健康。

+## 十、相关文档
+
+- 设计/API 说明：仓库 `docs/supplier/API-CHANGE-6397.html`
+- 同日修正 PR：[#6450](https://git.1814.love:8443/wx/HL/pulls/6450)（响应 `contracts[].amount` Number→String，每日审查红线修复）
+- 供应商暂停/拉黑原因必填（同属供应商状态域）：`changelogs-v2/2026-08/26_6392_供应商暂停合作与拉黑原因必填接口-新增接口-管理后台.md`
+
 ## 关联 / 联系人

 - **Issue**: [#6397](https://git.1814.love:8443/wx/HL/issues/6397)