---
schema: "hl-changelog/v2"
ticket: "6669"
title: "供应商草稿结算信息编辑与可选字段清空"
consumer: "admin"
author: "lc(GIT)"
change_type: "修改接口"
backend_status: "deployed"
gateway_status: "verified"
frontend_status: "verified"
frontend_owner: "mmg"
frontend_ref: "6678b97f"
target_release: "v2.1"
verified_at: "2026-08-29"
status_note: "#6669 与补充工单 #6676 已合并 dev-v3；最终提交 af5ea05df3d7490c97e6f4329c145a4014396bee 已由 Deploy Panel 任务 9be3a694 部署 TEST。真实 Gateway 已验证草稿结算创建、回读、修改、六个可选字段清空、整项清空、并发失败零写入和数据清理。当前状态：待前端处理。"
updated_at: "2026-08-29"
base: "dev-v3"
---

# 供应商草稿结算信息编辑与可选字段清空

供应商编辑接口新增 `initialAccounts` 完整快照。新建时登记的初始结算信息现在可在草稿编辑页读回、修改或清空；`changeReason` 和 `expectedUpdateTime` 继续必填。

## 二、变更接口清单

| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
|---:|---|---|---|---|---|
| 1 | 编辑供应商 | PUT | `/admin/supplier/items/{supplierId}/update` | 修改请求与响应 | 新增可选 `initialAccounts` 完整快照，仅草稿态可维护 |
| 2 | 查询供应商账户列表 | GET | `/admin/supplier/items/{supplierId}/account-info/list` | 修改响应语义 | 草稿供应商可读回其 `DRAFT` 初始账户 |
| 3 | 查询收款账户详情 | GET | `/admin/supplier/bank-accounts/{accountId}/view` | 修改响应语义 | 所属供应商为草稿时可读回 `DRAFT` 账户详情 |

## 三、接口详情

### 1. 编辑供应商 `PUT /admin/supplier/items/{supplierId}/update`

**VO**: `SupplierUpdateReqVO / SupplierWriteRespVO`

#### 使用场景

在供应商草稿编辑页维护与新建供应商相同的一项初始结算信息。省略 `initialAccounts` 不修改结算信息，空数组清空，1 项执行完整替换。

#### 入参

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---:|---|---|
| `supplierId` | Path | String | 是 | 正整数 ID 字符串 | 目标供应商 |
| `initialAccounts` | Body | Array | 否 | 最多 1 项 | 省略不修改；`[]` 清空；1 项完整替换 |
| `initialAccounts[].accountType` | Body | String | 项内是 | `CORPORATE` / `PERSONAL` | 账户类型 |
| `initialAccounts[].bankName` | Body | String | 项内是 | 最长 500 字符 | 开户银行 |
| `initialAccounts[].accountNo` | Body | String | 项内是 | 规范化后 8 至 32 位数字 | 收款账号 |
| `initialAccounts[].bankBranch` | Body | String/null | 否 | 最长 500 字符 | 省略或 `null` 可清空 |
| `initialAccounts[].proofFileUrls` | Body | Array/null | 否 | 最多 20 项 HTTPS 地址 | 省略、`null` 或 `[]` 可清空 |
| `initialAccounts[].settleMode` | Body | String/null | 否 | `PREPAY` / `MONTHLY` / `SINGLE` | 可清空 |
| `initialAccounts[].accountPeriod` | Body | String/null | 否 | 最长 50 字符 | 仅月结时填写，可清空 |
| `initialAccounts[].invoiceType` | Body | String/null | 否 | `SPECIAL` / `NORMAL` / `NONE` | 可清空 |
| `initialAccounts[].taxRate` | Body | String/null | 否 | 0% 至 100%，最多两位小数 | 可清空 |
| `changeReason` | Body | String | 是 | 去空白后非空，最长 500 字符 | 审计原因，继续必填 |
| `expectedUpdateTime` | Body | String | 是 | `yyyy-MM-dd HH:mm:ss` | 供应商主体并发版本，继续必填 |

#### 出参

| 字段 | 类型 | 说明 |
|---|---|---|
| `data.supplierId` | String | 供应商雪花 ID |
| `data.status` | String | 当前为 `DRAFT` |
| `data.initialAccounts` | Array | 保存后的 0 或 1 项账户摘要 |
| `data.updateTime` | String | 新的供应商并发版本 |

雪花 ID 均按字符串处理。

#### 请求示例

```json
{
  "changeReason": "维护草稿结算信息",
  "expectedUpdateTime": "2026-08-29 17:01:00",
  "initialAccounts": [
    {
      "accountType": "PERSONAL",
      "bankName": "示例银行",
      "accountNo": "6222000012345678"
    }
  ]
}
```

#### 响应示例

```json
{
  "code": 200,
  "message": "成功",
  "success": true,
  "data": {
    "supplierId": "2094000000000000000",
    "status": "DRAFT",
    "initialAccounts": [
      {
        "accountId": "2094000000000000001",
        "accountType": "PERSONAL",
        "bankName": "示例银行",
        "bankBranch": null,
        "accountNo": "6222000012345678",
        "settleMode": null,
        "accountPeriod": null,
        "invoiceType": null,
        "taxRate": null
      }
    ],
    "updateTime": "2026-08-29 17:01:01"
  }
}
```

#### 空数据 / 降级响应

- 省略 `initialAccounts`：不修改现有初始账户。
- 传 `initialAccounts: []`：软删除草稿初始账户，写响应返回空数组。
- 1 项中省略 6 个可选字段：`bankBranch`、`proofFileUrls`、`settleMode`、`accountPeriod`、`invoiceType`、`taxRate` 均清空；附件在读取响应中表现为空数组。

#### 错误响应

缺少审计或并发字段时失败且账户零写入：

```json
{ "code": 400, "message": "变更原因不能为空", "success": false, "data": null }
```

```json
{ "code": 400, "message": "expectedUpdateTime不能为空", "success": false, "data": null }
```

过期版本继续返回既有并发错误：

```json
{ "code": 395014, "message": "数据已被他人修改，请刷新后重试", "success": false, "data": null }
```

#### 业务边界

- `initialAccounts` 仅允许供应商为 `DRAFT` 时维护；否则返回既有状态错误 `395005`，账户零写入。
- 同账号完整替换保留原 `accountId`；账号全局唯一、事务、行锁、幂等和账户审计保持不变。
- 生效后的账户继续走独立新增与审批接口，供应商编辑不得绕过账户状态机。

### 2. 查询供应商账户列表 `GET /admin/supplier/items/{supplierId}/account-info/list`

**VO**: `SupplierAccountInfoRespVO / SupplierBankAccountRespVO`

#### 使用场景

进入供应商编辑页时加载“结算信息”table。供应商为草稿时，列表包含其初始 `DRAFT` 账户。

#### 入参

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---:|---|---|
| `supplierId` | Path | String | 是 | 正整数 ID 字符串 | 目标供应商 |

无 Query 参数，无请求体。

#### 出参

| 字段 | 类型 | 说明 |
|---|---|---|
| `data.supplierId` | String | 供应商雪花 ID |
| `data.bankAccounts` | Array | 当前可读账户列表 |
| `data.bankAccounts[].status` | String | 草稿初始账户为 `DRAFT` |
| `data.bankAccounts[].isDefault` | String | 草稿初始账户为 `NO` |
| `data.updateTime` | String | 供应商主体并发版本 |

#### 请求示例

```http
GET /admin/supplier/items/2094000000000000000/account-info/list
Authorization: Bearer <admin-token>
```

#### 响应示例

```json
{
  "code": 200,
  "message": "成功",
  "success": true,
  "data": {
    "supplierId": "2094000000000000000",
    "bankAccounts": [
      {
        "accountId": "2094000000000000001",
        "accountType": "PERSONAL",
        "bankName": "示例银行",
        "bankBranch": null,
        "accountNo": "6222000012345678",
        "proofFileUrls": [],
        "settleMode": null,
        "accountPeriod": null,
        "invoiceType": null,
        "taxRate": null,
        "status": "DRAFT",
        "isDefault": "NO"
      }
    ],
    "updateTime": "2026-08-29 17:01:01"
  }
}
```

#### 空数据 / 降级响应

没有可读账户时 `data.bankAccounts` 返回空数组。可选文本字段为空时返回 `null`；已获附件读取权限且附件为空时 `proofFileUrls` 返回空数组。

#### 错误响应

```json
{ "code": 395001, "message": "供应商不存在", "success": false, "data": null }
```

#### 业务边界

- 仅当供应商当前为 `DRAFT` 时才扩展读取草稿账户；其他状态的既有可见范围不变。
- 证明附件继续受独立权限和同步敏感读取审计约束；无权时不序列化附件原值。
- 查询不推进供应商或账户版本，不产生业务写副作用。

### 3. 查询收款账户详情 `GET /admin/supplier/bank-accounts/{accountId}/view`

**VO**: `SupplierBankAccountDetailRespVO`

#### 使用场景

草稿编辑页需要查看单个初始账户完整字段时，按列表返回的字符串 `accountId` 查询详情。

#### 入参

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---:|---|---|
| `accountId` | Path | String | 是 | 正整数 ID 字符串 | 目标账户 |

无 Query 参数，无请求体。

#### 出参

| 字段 | 类型 | 说明 |
|---|---|---|
| `data.accountId` | String | 账户雪花 ID |
| `data.accountType` 等账户字段 | 对应类型/null | 完整账户业务值，6 个可选字段允许为空 |
| `data.status` | String | 草稿初始账户为 `DRAFT` |
| `data.isDefault` | String | 草稿初始账户为 `NO` |
| `data.updateTime` | String | 账户当前版本 |

#### 请求示例

```http
GET /admin/supplier/bank-accounts/2094000000000000001/view
Authorization: Bearer <admin-token>
```

#### 响应示例

```json
{
  "code": 200,
  "message": "成功",
  "success": true,
  "data": {
    "accountId": "2094000000000000001",
    "accountType": "PERSONAL",
    "bankName": "示例银行",
    "bankBranch": null,
    "accountNo": "6222000012345678",
    "proofFileUrls": [],
    "settleMode": null,
    "accountPeriod": null,
    "invoiceType": null,
    "taxRate": null,
    "status": "DRAFT",
    "isDefault": "NO",
    "updateTime": "2026-08-29 17:01:01"
  }
}
```

#### 空数据 / 降级响应

目标账户不存在、已软删除或不在当前供应商状态允许的读取范围时，不返回部分对象；统一按不存在失败关闭。

#### 错误响应

```json
{ "code": 395001, "message": "供应商不存在", "success": false, "data": null }
```

#### 业务边界

- 草稿详情可见性由所属供应商当前状态决定，不能仅凭 `accountId` 绕过主体边界。
- 完整账号沿用当前管理端授权语义；证明附件仍需独立权限与同步审计。
- 详情查询不改变账户、供应商、审批或默认账户状态。

## 四、契约约束与正确调用方式

- 编辑页先调用账户列表接口加载结算 table，再把用户实际编辑后的 0 或 1 项完整快照放入供应商更新请求的 `initialAccounts`。
- 用户未操作结算区域时可以省略 `initialAccounts`，避免无意义改写；明确清空时必须发送空数组。
- 保存必须同时发送非空 `changeReason` 与最近读取到的供应商 `expectedUpdateTime`。
- 账户业务字段使用与新建供应商一致的字段名；`supplierId`、`accountId` 按字符串处理，禁止转为 JavaScript Number。

## 五、数据库行为

- 草稿账户完整替换会把省略的 6 个可选字段持久化为空；重新查询不再回读旧值。
- 空数组对草稿初始账户执行软删除；供应商、账户和审计仍在同一服务事务内提交或回滚。
- 本次没有新增 migration、跨 schema 写入、Redis、MQ 或配置行为。

## 六、边界行为

- `accountType`、`bankName`、`accountNo` 仍为账户项必填字段；“可清空”只适用于其余 6 个可选字段。
- `MONTHLY` 与 `accountPeriod`、开票类型与税率的既有组合校验继续生效。
- 更新完整快照时未提供的可选字段保存为空，不是保持数据库旧值。
- 写失败时供应商、账户和审计均在同一事务回滚；过期版本和非草稿状态均零写入。

## 六.6、修改前后对比

| 项目 | 修改前 | 修改后 |
|---|---|---|
| 供应商编辑请求 | 无 `initialAccounts`，不能维护新建时的初始结算信息 | 可选完整快照：省略不改、空数组清空、1 项替换 |
| 草稿账户列表/详情 | `DRAFT` 初始账户不在管理端账户读取范围 | 所属供应商为 `DRAFT` 时可读回 |
| 可选字段清空 | 实体值虽置空，但默认更新策略可能保留数据库旧值 | 6 个可选字段显式持久化为空 |
| 审计与并发字段 | `changeReason`、`expectedUpdateTime` 必填 | 继续必填 |

## 六.7、影响评估

- **是否向后兼容**：是；不发送 `initialAccounts` 的原调用方保持原更新语义。
- **前端是否需要接入**：是；编辑页结算 table 需调用账户列表并按完整快照保存。
- **状态机影响**：无；仅草稿态开放聚合维护，其他状态继续走独立账户审批。
- **撤回影响**：撤回后编辑页应停止发送 `initialAccounts`，草稿账户也不再通过账户列表/详情读回。

## 七、不影响范围

- 不修改非草稿供应商的独立账户新增、审批、默认账户和账户状态机。
- 不修改合同独立登记接口、供应商提交审批流程或合同字段可空契约。
- 不新增错误码、数据库 migration、Gateway 路由、Redis、MQ、Nacos 或配置变更。
- 不修改任何前端源码；页面 table 排列和字段消费由前端按本契约处理。

## 八、测试环境已验证

- 新建草稿携带完整初始结算信息后，列表可读回相同字段。
- 草稿编辑把完整账户改为仅保留三个必填字段后，6 个可选字段保存并重新回读为空，账户 ID 保持不变。
- 缺少 `changeReason`、缺少 `expectedUpdateTime` 和使用过期版本均失败且账户零写入。
- 发送空数组后写响应和列表均为空；测试供应商删除后详情不可读，所有可恢复测试数据已清理。

## 十、相关文档

- Issue [#6669](https://git.1814.love:8443/wx/HL/issues/6669)
- 补充 Issue [#6676](https://git.1814.love:8443/wx/HL/issues/6676)
- PR [#6674](https://git.1814.love:8443/wx/HL/pulls/6674)，合并提交 `35dba63d6a92159d933b38385fee057f617bdfed`
- PR [#6677](https://git.1814.love:8443/wx/HL/pulls/6677)，合并提交 `af5ea05df3d7490c97e6f4329c145a4014396bee`

## 关联 / 联系人

- **后端负责人**：@lc
- **前端负责人**：@mmg
- **当前状态**：已消费（`frontend_status: verified`)。SupplierEditModal 结算 Tab 放开为「新建 || (编辑 && DRAFT)」，草稿编辑拉账户列表回读初始账户（含 accountId,accountNo 完整值可回填）,buildEditBody 仅 DRAFT 按快照比对携带 initialAccounts（未动省略/清空 `[]`/1 项整份替换保留 accountId,6 可选字段+proofFileUrls 省略即显式清空），非 DRAFT 不开放不携带。