From 8696bbb08394437e7ad3117c635717d14377e537 Mon Sep 17 00:00:00 2001
From: lc <liuchang@1814.love>
Date: Fri, 4 Sep 2026 16:52:18 +0800
Subject: [PATCH] =?UTF-8?q?=E8=A1=A5=E5=85=85=E4=BE=9B=E5=BA=94=E5=95=86?=
 =?UTF-8?q?=E6=96=B0=E5=BB=BA=E4=BF=AE=E6=94=B9=E5=BF=85=E5=A1=AB=E8=B5=84?=
 =?UTF-8?q?=E6=96=99=E8=AF=B4=E6=98=8E=EF=BC=88#7087=EF=BC=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 ...”商新建修改必填资料校验-修改接å�£-管ç�†å�Žå�°.md | 267 ++++++++++++++++++
 1 file changed, 267 insertions(+)
 create mode 100644 changelogs-v2/2026-09/04_7087_供应商新建修改必填资料校验-修改接�-管���.md

diff --git a/changelogs-v2/2026-09/04_7087_供应商新建修改必填资料校验-修改接�-管���.md b/changelogs-v2/2026-09/04_7087_供应商新建修改必填资料校验-修改接�-管���.md
new file mode 100644
index 00000000..2512a167
--- /dev/null
+++ b/changelogs-v2/2026-09/04_7087_供应商新建修改必填资料校验-修改接�-管���.md
@@ -0,0 +1,267 @@
+---
+schema: "hl-changelog/v2"
+ticket: "7087"
+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: "�端已部署并通过 TEST；�端需为供应商新建和编辑表�补�主体资料��系人�结算账户必填校验。"
+updated_at: "2026-09-04"
+base: "dev-v3"
+---
+
+# 供应商模�：新建与修改补�必填资料校验
+
+`POST /admin/supplier/items/add` 新建时必须一次�交完整资料；`PUT /admin/supplier/items/{supplierId}/update` �是增�接�，但�存�的供应商��必须完整。�端需�步补�表�必填标识和�交�校验。
+
+## 二��更接�清�
+
+| # | 接� | 方法 | 路径 | �更类型 | 说明 |
+|---|---|---|---|---|---|
+| 1 | 新建供应商�稿 | POST | `/admin/supplier/items/add` | 必填校验收紧 | 主体资料完整，且至少一��系人�一个�始账户 |
+| 2 | 修改供应商资料 | PUT | `/admin/supplier/items/{supplierId}/update` | ��完整性校验 | �略字段�留现值；显�空类型��系人或账户拒� |
+
+## 三�接�详情
+
+### 1. 新建供应商�稿 `POST /admin/supplier/items/add`
+
+**VO**: `SupplierDraftSaveReqVO → SupplierWriteRespVO`
+
+#### 使用场景
+
+管�端完�供应商新建表���存�稿。
+
+#### 入�
+
+| 字段 | �置 | 类型 | 必填 | 约� | 说明 |
+|---|---|---|---|---|---|
+| `fullName` | Body | String | 是 | �空，最长 500 | 供应商全称 |
+| `taxNo` | Body | String | 是 | �法主体�件� | 统一社会信用代� |
+| `types` | Body | Array | 是 | 至少 1 项，最多 15 项 | `typeCode` � `supplier_type` 生效字典值 |
+| `legalRepresentative` | Body | String | 是 | �空 | 法定代表人 |
+| `legalRepresentativeIdNo` | Body | String | 是 | �法 18 �居民身份�� | 法人身份�� |
+| `legalRepresentativeIdCardFrontUrl` | Body | String | 是 | 公网 HTTPS 永久地� | 身份�人�� |
+| `legalRepresentativeIdCardBackUrl` | Body | String | 是 | 公网 HTTPS 永久地� | 身份�国徽� |
+| `contactPhone` | Body | String | 是 | �法手机��座机或 400/800 �� | 法人�系电� |
+| `establishDate` | Body | String | 是 | `yyyy-MM-dd`，�得晚于当天 | �立日期 |
+| `balance` | Body | Number | 是 | 最多 16 �整数�2 ��数 | 余�，�为正数�0 或负数 |
+| `paymentType` | Body | String | 是 | `supplier_payment_type` 生效字典值 | 支付类型 |
+| `mainCooperation` | Body | String | 是 | �空 | 主��作内容 |
+| `licenseImageUrl` | Body | String | 是 | �空 | �业执照影�地� |
+| `address` | Body | String | 是 | �空，最长 500 | 注册地� |
+| `contacts` | Body | Array | 是 | 至少 1 项，最多 100 项 | �项填写姓��电�� `sup_content_role` 角色 |
+| `initialAccounts` | Body | Array | 是 | 当�必须且�能 1 项 | �项填写账户类型�银行和账� |
+
+#### 出�
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `data.supplierId` | String | 供应商 ID |
+| `data.supplierNo` | String | 供应商编� |
+| `data.status` | String | 新建�功为 `DRAFT` |
+| `data.initialAccounts` | Array | �始账户摘� |
+| `data.updateTime` | String | �续修改使用的并�版本 |
+
+#### 请求示例
+
+```json
+{
+  "fullName": "示例供应商有�公�",
+  "taxNo": "91350211M000100Y46",
+  "types": [{"typeCode": "HOTEL"}],
+  "legalRepresentative": "张三",
+  "legalRepresentativeIdNo": "11010519491231002X",
+  "legalRepresentativeIdCardFrontUrl": "https://example.com/supplier/id-front.jpg",
+  "legalRepresentativeIdCardBackUrl": "https://example.com/supplier/id-back.jpg",
+  "contactPhone": "13800138000",
+  "establishDate": "2020-01-02",
+  "balance": 0,
+  "paymentType": "1",
+  "mainCooperation": "酒店资��作",
+  "licenseImageUrl": "https://example.com/supplier/license.jpg",
+  "address": "厦门市�明区示例路 1 �",
+  "contacts": [{"contactName": "�四", "contactPhone": "13800138001", "contactRole": "contentBus", "isPrimary": true}],
+  "initialAccounts": [{"accountType": "CORPORATE", "bankName": "示例银行", "accountNo": "6222000012345678"}]
+}
+```
+
+#### �应示例
+
+```json
+{
+  "code": 200,
+  "message": "�功",
+  "success": true,
+  "data": {
+    "supplierId": "2095000000000000001",
+    "supplierNo": "SUP2095000000000000001",
+    "status": "DRAFT",
+    "initialAccounts": [{"accountId": "2095000000000000002", "status": "DRAFT"}],
+    "updateTime": "2026-09-04 16:48:49"
+  }
+}
+```
+
+#### 空数� / �级�应
+
+写接�没有空数��功或�级�功；任一必填项缺失时返回失败�应。
+
+#### 错误�应
+
+```json
+{"code":400,"message":"�系人�能为空","data":null,"success":false}
+```
+
+#### 业务边界
+
+- 未登录返回业务� `401`；写入��求 `FINANCE` 或 `SUPER_ADMIN` � `supplier:create` ��。
+- `types`�`contacts`�`initialAccounts` 传 `null`��略或空数组�视为缺失。
+- 校验失败�创建供应商或�项；�应�能使用 HTTP 200，必须�时检查 `code` 与 `success`。
+
+### 2. 修改供应商资料 `PUT /admin/supplier/items/{supplierId}/update`
+
+**VO**: `SupplierUpdateReqVO → SupplierWriteRespVO`
+
+#### 使用场景
+
+管�端编辑既有供应商资料并按最新版本�存。
+
+#### 入�
+
+| 字段 | �置 | 类型 | 必填 | 约� | 说明 |
+|---|---|---|---|---|---|
+| `supplierId` | Path | String | 是 | 正整数 ID | 目标供应商 |
+| `expectedUpdateTime` | Body | String | 是 | `yyyy-MM-dd HH:mm:ss` | �详情最新 `updateTime` |
+| 主体必填资料 | Body | 原类型 | �件必填 | 与新建接�相� | �略表示�留现值；�存�的有效值必须完整 |
+| `types` | Body | Array | �件必填 | 显��交时至少 1 项 | �略�留存�，`[]` 拒� |
+| `contacts` | Body | Array | �件必填 | 显��交时至少 1 项 | �略�留存�，`[]` 拒� |
+| `initialAccounts` | Body | Array | �件必填 | 显��交时当�必须且�能 1 项 | �略�留存�，`[]` 拒� |
+| `changeReason` | Body | String | �件必填 | 最长 500 | `DRAFT` ��略，其他�修改状�沿用既有规则 |
+
+主体必填资料指：`fullName`�`taxNo`�`legalRepresentative`�`legalRepresentativeIdNo`�`legalRepresentativeIdCardFrontUrl`�`legalRepresentativeIdCardBackUrl`�`contactPhone`�`establishDate`�`balance`�`paymentType`�`mainCooperation`�`licenseImageUrl`�`address`。
+
+#### 出�
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `data.supplierId` | String | 供应商 ID |
+| `data.status` | String | �存�的状� |
+| `data.initialAccounts` | Array | 当��始账户摘� |
+| `data.updateTime` | String | �存�的新并�版本 |
+
+#### 请求示例
+
+```json
+{
+  "shortName": "示例供应商",
+  "expectedUpdateTime": "2026-09-04 16:48:49"
+}
+```
+
+#### �应示例
+
+```json
+{
+  "code": 200,
+  "message": "�功",
+  "success": true,
+  "data": {
+    "supplierId": "2095000000000000001",
+    "status": "DRAFT",
+    "initialAccounts": [{"accountId": "2095000000000000002", "status": "DRAFT"}],
+    "updateTime": "2026-09-04 16:49:16"
+  }
+}
+```
+
+#### 空数� / �级�应
+
+�略未修改字段会�留已存值；接�没有空数��功或�级�功。
+
+#### 错误�应
+
+```json
+{"code":400,"message":"供应商类型�能为空","data":null,"success":false}
+```
+
+#### 业务边界
+
+- 写入��求 `FINANCE` 或 `SUPER_ADMIN` � `supplier:update` ��。
+- �存�按“请求值 + 已存值�校验完整��；存�资料缺项时，必须补���能�存其他修改。
+- ��稿账户继续走独立账户审批；本次�改�状��并��审批�幂等或审计规则。
+- `expectedUpdateTime` 过期返回既有业务� `395014`，失败�更新任何��数�。
+
+## 四�契约约�与正确调用方�（接�类必写）
+
+| 场景 | 正确调用 |
+|---|---|
+| 新建 | 一次�交全部主体必填资料��空 `types`��空 `contacts` 和一个 `initialAccounts` |
+| 修改普通字段 | 先查询详情；已存��完整时，��交�化字段和最新 `expectedUpdateTime` |
+| 修改关系快照 | �交完整�空快照；�修改关系时�略对应字段 |
+| 字典字段 | �交字典接�返回的 `dictValue`，���交中文标签或�端硬编�默认值 |
+
+支付类型当�字典值为 `1`（现付）�`2`（签�）�`3`（月付）；供应商类型和�系人角色分别从 `supplier_type`�`sup_content_role` 动�字典读�。
+
+## 五�数�库行为
+
+- 校验失败�新增或更新供应商��数�。
+- 本次没有表结构�字段�空约��数��移或历�数�回填。
+
+## 六�边界行为
+
+- 业务失败�能�为 HTTP 200；�端必须检查 `success=false` 和业务 `code/message`。
+- 必填文本为空白�必填值为 `null`�必填集�为空时�拒�。
+- 更新�略字段表示�留，�等于清空；完整性按�存�的有效��判断。
+- 超过列表上��字典值失效�身份�/电�/URL 格���法时继续使用既有校验错误。
+
+## 六.6�修改��对比
+
+| 行为 | 改� | 改� |
+|---|---|---|
+| 新建缺主体资料 | 部分字段�缺失并�存�稿 | 任一约定主体必填资料缺失�拒� |
+| 新建缺关系资料 | 类型��系人或账户�能为空 | 三类�必须�空 |
+| 修改显�空关系快照 | �清空部分关系 | `types: []`�`contacts: []`�`initialAccounts: []` �拒� |
+| 修改�略未�化字段 | �留现值 | ��留现值，并校验最终��完整性 |
+
+## 六.7�影�评估
+
+- **是�破���兼容**: 是。�赖�完整�稿或显�清空类型��系人��始账户的旧请求会被拒�。
+- **�端是�必须�步上线**: 是。新建和编辑表��需补�必填标识�校验�示和�交数�。
+- **�端 workaround 清�点**: ���许以空数组清空供应商类型��系人或�始账户。
+
+## 七��影�范围
+
+- �应结构和字段���。
+- �改�供应商注册�交接����矩阵�状�机�审批��并�版本�幂等与审计语义。
+- �改���稿账户独立审批入�，也�修改数�库约�。
+
+## 八�测试环境已验�
+
+- 新建缺注册地���系人或账户分别返回业务� `400`，且无业务数�写入；完整资料创建�功。
+- 修改显�空类型��系人�账户或清空�业执照分别返回业务� `400`，资料与版本��；完整存�上的增�修改�功。
+- 匿�新建返回业务� `401`；验收�稿已通过应用删除接�清�，有效��数�为零。
+
+## ��相关文档
+
+- [�端 Issue #7087](https://git.1814.love:8443/wx/HL/issues/7087)
+- [�端 PR #7093](https://git.1814.love:8443/wx/HL/pulls/7093)
+- [历�契约 #6343](https://git.1814.love:8443/wx/HL/issues/6343)：其中“新建�空类型�修改�显�清空类型�已被本工��代。
+
+## 关� / �系人
+
+### 链接
+
+- **Issue**: [#7087](https://git.1814.love:8443/wx/HL/issues/7087)
+- **PR**: [#7093](https://git.1814.love:8443/wx/HL/pulls/7093)
+- **Merge commit**: [e8b96e9a5](https://git.1814.love:8443/wx/HL/commit/e8b96e9a5dd0c75e65157bf889336ef740533da4)
+
+### �系人
+
+- **�端负责人**: @lc