From 8821d1df6f1860baecd37079cf11ce5d219a687c Mon Sep 17 00:00:00 2001
From: lc <liuchang@1814.love>
Date: Sun, 30 Aug 2026 08:18:42 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E4=BA=A4=E4=BB=98=E4=BE=9B=E5=BA=94?=
 =?UTF-8?q?=E5=95=86=E8=8D=89=E7=A8=BF=E5=8F=98=E6=9B=B4=E5=8E=9F=E5=9B=A0?=
 =?UTF-8?q?=E5=A5=91=E7=BA=A6=20(#6684)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 ...¾‘å�˜æ›´åŽŸå› å�¯é€‰ä¸”ä¸�写å�˜æ›´è®°å½•-修改接å�£-管ç�†å�Žå�°.md | 208 ++++++++++++++++++
 1 file changed, 208 insertions(+)
 create mode 100644 changelogs-v2/2026-08/30_6684_供应商�稿编辑�更原因�选且�写�更记录-修改接�-管���.md

diff --git a/changelogs-v2/2026-08/30_6684_供应商�稿编辑�更原因�选且�写�更记录-修改接�-管���.md b/changelogs-v2/2026-08/30_6684_供应商�稿编辑�更原因�选且�写�更记录-修改接�-管���.md
new file mode 100644
index 00000000..ccd30ea0
--- /dev/null
+++ b/changelogs-v2/2026-08/30_6684_供应商�稿编辑�更原因�选且�写�更记录-修改接�-管���.md
@@ -0,0 +1,208 @@
+---
+schema: "hl-changelog/v2"
+ticket: "6684"
+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-30"
+status_note: "PR #6686 已�并 dev-v3，�并�交 ae7226ac8e2a23f0ce79ddda1a3a892542b81996 已由 Deploy Panel 任务 da7ffb3a 精确部署 TEST。真实 Gateway 已验� DRAFT �稿�传 changeReason ��功�存�详情回读状�与修改值正确�主体�更记录�为 0，并已删除���稿。当�状�：待�端处�。"
+updated_at: "2026-08-30"
+base: "dev-v3"
+---
+
+# 🔧 供应商�稿编辑�更原因�选且�写�更记录
+
+供应商当�状�为 `DRAFT` 时，编辑接����求填写 `changeReason`，并且本次�稿编辑�会新增主体�更记录。其他状�继续�求�空�更原因并�留原审计行为。
+
+管�端需�按详情返回的当�状�调整表�校验：�稿��或�消“�更原因�必填，��稿继续必填。
+
+## 二��更接�清�
+
+| # | 接� | 方法 | 路径 | �更类型 | 说明 |
+|---:|---|---|---|---|---|
+| 1 | 编辑供应商 | PUT | `/admin/supplier/items/{supplierId}/update` | 修改请求校验与写入行为 | `DRAFT` ��略 `changeReason` 且�新增主体�更记录；其他状��� |
+
+## 三�接�详情
+
+### 1. 编辑供应商 `PUT /admin/supplier/items/{supplierId}/update`
+
+**VO**: `SupplierUpdateReqVO / SupplierWriteRespVO`
+
+#### 使用场景
+
+在供应商编辑页继续完善尚未�交审批的�稿资料。调用方先读�供应商详情�得当� `status` 和 `updateTime`，�按当�状�决定是����更原因。
+
+#### 入�
+
+| 字段 | �置 | 类型 | 必填 | 约� | 说明 |
+|---|---|---|---:|---|---|
+| `supplierId` | Path | String | 是 | 正整数 ID 字符串 | 目标供应商 |
+| `changeReason` | Body | String | �件必填 | 最长 500 字符 | �务端当�状�为 `DRAFT` 时��略或为空；其他状�去空白�必须�空 |
+| `expectedUpdateTime` | Body | String | 是 | `yyyy-MM-dd HH:mm:ss` | 最近一次详情或写�应返回的并�版本 |
+| `fullName`�`shortName` 等资料字段 | Body | 对应类型 | � | 沿用既有字段规则 | 仅��本次需�修改的字段；示例使用 `remark` |
+
+请求体�接收客户端自报的供应商状�；是�为�稿由�务端�定并读�当�供应商�判定。
+
+#### 出�
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `code` | Number | 业务�；�功为 `200` |
+| `success` | Boolean | 业务是��功 |
+| `data.supplierId` | String | 供应商 ID |
+| `data.supplierNo` | String | 供应商业务编� |
+| `data.status` | String | �存�的当�状�；本场景为 `DRAFT` |
+| `data.onboardingStage` | String | �稿为 `PROFILE_DRAFT` |
+| `data.initialAccounts` | Array | 当��始结算账户摘�，未登记时为空数组 |
+| `data.updateTime` | String | �存�的新并�版本 |
+
+#### 请求示例
+
+`DRAFT` �稿请求体完全��� `changeReason`：
+
+```json
+{
+  "remark": "补充�稿内部备注",
+  "expectedUpdateTime": "2026-08-30 08:15:29"
+}
+```
+
+#### �应示例
+
+```json
+{
+  "code": 200,
+  "message": "�功",
+  "success": true,
+  "data": {
+    "supplierId": "2093855088501035010",
+    "supplierNo": "SUP2093855088501035010",
+    "status": "DRAFT",
+    "onboardingStage": "PROFILE_DRAFT",
+    "initialAccounts": [],
+    "updateTime": "2026-08-30 08:15:45"
+  }
+}
+```
+
+#### 空数� / �级�应
+
+- `DRAFT` 时�略 `changeReason`�传 `null` 或�传空白，�会因�更原因被拒�。
+- �略其他�选资料字段�表示“�修改该字段�，�自动清空既有值。
+- �赖�务异常继续按既有失败关闭语义返回，�把未完�写入伪装��功。
+
+#### 错误�应
+
+� `DRAFT` 供应商�略或传空白 `changeReason`，继续返回原业务错误且零写入：
+
+```json
+{
+  "code": 400,
+  "message": "�更原因�能为空",
+  "success": false,
+  "data": null
+}
+```
+
+并�版本过期继续返回既有错误：
+
+```json
+{
+  "code": 395014,
+  "message": "数�已被他人修改，请刷新��试",
+  "success": false,
+  "data": null
+}
+```
+
+#### 业务边界
+
+- 接�继续�求有效管�端身份�既有�信角色� `supplier:update` �务端��。
+- �稿判定使用�务端�定�读�到的�久状�，�能通过请求体伪造 `DRAFT` 绕过��稿审计。
+- `DRAFT` �功编辑�更新�稿资料与并�版本，�新增主体�更记录。
+- � `DRAFT` 的原因必填�主体�更记录�事务�����幂等和�观并�规则���。
+- �数����状�或并�校验失败时�产生部分资料写入或�更记录。
+
+## 四�契约约�与正确调用方�
+
+1. 进入编辑页先调用 `GET /admin/supplier/items/{supplierId}/basic-info/view`，使用返回的 `status` 和 `updateTime`。
+2. `status=DRAFT` 时�以�渲染�更原因输入框，或�消其必填校验；�存请求�完全�略 `changeReason`。
+3. `status` �是 `DRAFT` 时继续收集�空 `changeReason`，��把�稿规则扩展到其他状�。
+4. �次�功�存�使用�应中的新 `updateTime` 作为下一次编辑的 `expectedUpdateTime`。
+
+| 场景 | payload | 结果 |
+|---|---|---|
+| `DRAFT` �略原因 | `{ "remark": "补充资料", "expectedUpdateTime": "2026-08-30 08:15:29" }` | �功，�新增主体�更记录 |
+| `DRAFT` 显�空原因 | `{ "changeReason": "", "expectedUpdateTime": "2026-08-30 08:15:29" }` | �功，�新增主体�更记录 |
+| � `DRAFT` �略原因 | `{ "remark": "调整资料", "expectedUpdateTime": "2026-08-30 08:15:29" }` | `400`，�更原因�能为空 |
+| � `DRAFT` �供原因 | `{ "changeReason": "更新登记资料", "expectedUpdateTime": "2026-08-30 08:15:29" }` | 按既有编辑与审计规则处� |
+
+## 五�数�库行为
+
+| �务端当�状� | 资料�存 | 主体�更记录 |
+|---|---|---|
+| `DRAFT` | 按既有增�编辑和并�规则�存 | �新增本次编辑记录 |
+| � `DRAFT` 且原因有效 | 按既有编辑规则�存 | 继续新增完整�更记录并�留原因 |
+| � `DRAFT` 且原因为空 | ��存 | �新增记录 |
+
+本次�新增数�库 migration，�改历�记录，�执行跨�务写入，也�引入 Redis�MQ 或�置写行为。
+
+## 六�边界行为
+
+- 未登录请求继续由 Gateway 拒�；本次�改�认�级别。
+- 无供应商写���供应商�存在�状���许或并�版本过期时继续按既有错误语义失败。
+- `changeReason` 长度上��为 500 字符；��稿�传空白等�未填写。
+- �稿�功编辑�，详情回读应�� `status=DRAFT` 并返回本次修改值与新版本。
+- �稿的主体�更记录分页在本次�存��数�����。
+
+## 六.6�修改��对比
+
+| 项目 | 修改� | 修改� |
+|---|---|---|
+| `DRAFT` 的 `changeReason` | 请求模型无�件必填，�略�返回“�更原因�能为空� | ��略�为 `null` 或空白 |
+| `DRAFT` 编辑审计 | �次�功编辑都会新增主体�更记录 | �新增主体�更记录 |
+| � `DRAFT` 的 `changeReason` | 必填 | 继续必填 |
+| � `DRAFT` 编辑审计 | �功�记录完整�化与原因 | ���� |
+
+## 六.7�影�评估
+
+- **是�破���兼容**：�；原�已�� `changeReason` 的�稿请求继续�用，��稿契约��。
+- **�端是�必须�步上线**：是；管�端当��稿编辑表��把“�更原因�显示为必填，需�按详情 `status` �消�稿必填。
+- **�端 workaround 清�点**：删除 `DRAFT` �稿�存�对 `changeReason` 的必填拦截；�得删除��稿校验。
+- **�应与错误�影�**：�功�应字段��；�移除�稿缺少原因时的 `400`，�新增错误�。
+
+## 七��影�范围
+
+- �修改供应商创建�注册�交��稿删除�暂��拉黑�归档����账户或资�关系接�。
+- �修改��稿资料编辑的�更原因与主体�更记录语义。
+- �修改 Gateway 路由�认�策略�角色或��点。
+- �新增数�库结构�历�数�回填�Redis�MQ�Nacos 或�置�更。
+- 本工�仅交付�端和接� Changelog，�修改任何�端��或资�。
+
+## 八�测试环境已验�
+
+- �并�交 `ae7226ac8e2a23f0ce79ddda1a3a892542b81996` 已由 Deploy Panel 任务 `da7ffb3a` 精确部署到 TEST，Resource �实例与 Nacos 注册��康。
+- 通过真实 TEST Gateway 创建�� `DRAFT` �稿，并用完全�� `changeReason` 的请求修改 `remark`；返回 `code=200`�`success=true`�`status=DRAFT` 和新的 `updateTime`。
+- �存��次查询详情，`remark` 为本次修改值且状��为 `DRAFT`。
+- �存��查询该供应商的 `UPDATE` 主体�更记录�返回 `total=0`�`records=[]`。
+- 验收�通过�稿删除接�清���数�；详情返回“供应商�存在�，按供应商编�查询列表为空。
+
+## ��相关文档
+
+- Issue [#6684](https://git.1814.love:8443/wx/HL/issues/6684)
+- PR [#6686](https://git.1814.love:8443/wx/HL/pulls/6686)
+- �并�交 [ae7226ac8e2a23f0ce79ddda1a3a892542b81996](https://git.1814.love:8443/wx/HL/commit/ae7226ac8e2a23f0ce79ddda1a3a892542b81996)
+
+## 关� / �系人
+
+### �系人
+
+- **�端负责人**：@lc
+- **当�状�**：待�端处�