Mimingguang
2f6a989fcf
changelog-filename-gate / validate (push) Failing after 2s
11 条有业务交付改判 verified(#6397/6903/6904/6905/6950/6979/6986/7013/7029/7036/7066,owner=mmg+对应业务 commit ref+交付日 verified_at); 6 条实证零改动改判 not_required(#6014/6016/6140/6938/6842/7087,仅翻 frontend_status 不填 owner/ref)。 #5935 挂起待后端补字段,保持 pending 不动。sync-log 均已记账。
235 行
10 KiB
Markdown
235 行
10 KiB
Markdown
---
|
||
schema: "hl-changelog/v2"
|
||
ticket: "7087"
|
||
title: "供应商账户修改入口与删除限制"
|
||
consumer: "admin"
|
||
author: "lc(GIT)"
|
||
change_type: "修改接口"
|
||
backend_status: "deployed"
|
||
gateway_status: "verified"
|
||
frontend_status: "not_required"
|
||
frontend_owner: ""
|
||
frontend_ref: ""
|
||
target_release: ""
|
||
verified_at: ""
|
||
status_note: "现有接口说明与历史口径纠正；前端按草稿账户修改入口接入，取消空数组删除账户。既有 TEST 业务实测及本次只读复核范围见正文。"
|
||
updated_at: "2026-09-06"
|
||
base: "dev-v3"
|
||
---
|
||
|
||
# 供应商账户：修改入口与删除限制
|
||
|
||
> **影响范围**：管理后台供应商账户编辑、删除操作。当前状态：后端已部署；前端待核对接入。
|
||
|
||
## ⚠️ 关键变化
|
||
|
||
草稿初始账户通过供应商更新接口修改，必须保留一项账户。**旧 #6669 文档的 `initialAccounts: []` 删除方式已被 #7087 收紧，当前返回 `400 / 账户不能为空`。** 草稿的 `changeReason` 现可省略。
|
||
|
||
| 操作 | 当前支持情况 |
|
||
|---|---|
|
||
| 修改草稿初始账户 | 支持，使用下文接口，供应商及其已有账户必须均为 `DRAFT` |
|
||
| 修改已提交或已生效账户资料 | 未提供独立接口；不能通过供应商更新绕过状态限制 |
|
||
| 单独删除账户 | 未提供接口；不能提交空数组清空最后一项账户 |
|
||
| 设置默认账户 | 已有 `PUT /admin/supplier/bank-accounts/{accountId}/default/update`，仅改变默认标记 |
|
||
|
||
## 二、变更接口清单
|
||
|
||
| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
|
||
|---|---|---|---|---|---|
|
||
| 1 | 修改草稿初始账户 | PUT | `/admin/supplier/items/{supplierId}/update` | 现有契约说明 | 通过 `initialAccounts` 完整替换唯一草稿账户；禁止空数组删除 |
|
||
|
||
## 三、接口详情
|
||
|
||
### 1. 修改草稿初始账户 `PUT /admin/supplier/items/{supplierId}/update`
|
||
|
||
**VO**: `SupplierUpdateReqVO / SupplierBankAccountReqVO / SupplierWriteRespVO`
|
||
|
||
#### 使用场景
|
||
|
||
在资料完整的草稿供应商下修改初始账户。本节列出账户编辑所需载荷；其余主体资料省略时保留现值。保存后主体必填资料、供应商类型、联系人、账户仍须完整。
|
||
|
||
#### 入参
|
||
|
||
| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|
||
|---|---|---|---|---|---|
|
||
| `supplierId` | Path | String | 是 | 正整数 ID | 供应商 ID |
|
||
| `expectedUpdateTime` | Body | String | 是 | `yyyy-MM-dd HH:mm:ss` | 供应商主体版本，不能使用账户版本 |
|
||
| `initialAccounts` | Body | Array | 本场景是 | 恰好 1 项 | 省略或 `null` 保留现值；`[]` 拒绝 |
|
||
| `initialAccounts[].accountType` | Body | String | 是 | `CORPORATE` / `PERSONAL` | 对公 / 对私 |
|
||
| `initialAccounts[].bankName` | Body | String | 是 | 非空，最长 500 字符 | 开户银行 |
|
||
| `initialAccounts[].accountNo` | Body | String | 是 | 去空白和连字符后 8～32 位数字 | 收款账号 |
|
||
| `initialAccounts[].bankBranch` | Body | String/null | 否 | 最长 500 字符 | 开户支行，可清空 |
|
||
| `initialAccounts[].proofFileUrls` | Body | Array/null | 否 | 最多 20 个不重复的公网 HTTPS 地址，每项最长 1000 字符；不带查询参数或片段 | 证明附件，省略或 `[]` 清空 |
|
||
| `initialAccounts[].settleMode` | Body | String/null | 否 | `PREPAY` / `MONTHLY` / `SINGLE` | 结算方式 |
|
||
| `initialAccounts[].accountPeriod` | Body | String/null | 条件必填 | 最长 50 字符；仅 `MONTHLY` 必填，其他方式须为空 | 月结账期 |
|
||
| `initialAccounts[].invoiceType` | Body | String/null | 否 | `SPECIAL` / `NORMAL` / `NONE` | 发票类型 |
|
||
| `initialAccounts[].taxRate` | Body | String/null | 条件必填 | 0%～100%，最多两位小数 | 可开票时必填；`NONE` 或未选发票类型时须为空 |
|
||
| `changeReason` | Body | String | 否 | 最长 500 字符 | 此处为 `DRAFT`，允许省略 |
|
||
|
||
不提交 `accountId`、`accountName` 或账户状态；户名由供应商全称确定。
|
||
|
||
#### 出参
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| `code` / `message` / `success` | Integer / String / Boolean | 业务结果；成功为 `200`、`成功`、`true` |
|
||
| `data.supplierId` / `data.supplierNo` | String | 供应商 ID / 编号 |
|
||
| `data.status` / `data.statusName` | String | 本场景为 `DRAFT` / `草稿` |
|
||
| `data.onboardingStage` | String | 本场景为 `PROFILE_DRAFT` |
|
||
| `data.initialAccounts` | Array | 保存后的初始账户摘要 |
|
||
| `data.initialAccounts[].accountId` | String | 当前账户 ID，替换账号后应重新读取 |
|
||
| `data.initialAccounts[].accountNo` | String | 完整账号 |
|
||
| `data.initialAccounts[].accountNoMask` | String | 废弃兼容字段，实际同样为完整账号；使用 `accountNo` |
|
||
| `data.initialAccounts[].status` | String | 本场景为 `DRAFT` |
|
||
| `data.approval` | null | 草稿直接保存，不发起审批 |
|
||
| `data.updateTime` | String | 保存后的供应商版本，供下次编辑使用 |
|
||
|
||
#### 请求示例
|
||
|
||
以下 ID、账号和时间均为示例值。
|
||
|
||
```http
|
||
PUT /admin/supplier/items/2095000000000000001/update
|
||
Authorization: Bearer <当前有效凭证>
|
||
Content-Type: application/json
|
||
|
||
{
|
||
"expectedUpdateTime": "2026-09-06 10:00:00",
|
||
"initialAccounts": [{
|
||
"accountType": "CORPORATE",
|
||
"bankName": "示例银行",
|
||
"accountNo": "6222000012345678",
|
||
"bankBranch": "示例支行",
|
||
"proofFileUrls": [],
|
||
"settleMode": "MONTHLY",
|
||
"accountPeriod": "月结30天",
|
||
"invoiceType": "SPECIAL",
|
||
"taxRate": "6%"
|
||
}]
|
||
}
|
||
```
|
||
|
||
#### 响应示例
|
||
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "成功",
|
||
"success": true,
|
||
"data": {
|
||
"supplierId": "2095000000000000001",
|
||
"supplierNo": "SUP2095000000000000001",
|
||
"status": "DRAFT",
|
||
"statusName": "草稿",
|
||
"onboardingStage": "PROFILE_DRAFT",
|
||
"initialAccounts": [{
|
||
"accountId": "2095000000000000002",
|
||
"accountNo": "6222000012345678",
|
||
"accountNoMask": "6222000012345678",
|
||
"status": "DRAFT"
|
||
}],
|
||
"approval": null,
|
||
"updateTime": "2026-09-06 10:00:01"
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 空数据 / 降级响应
|
||
|
||
成功响应包含账户摘要。编辑表单完整回显使用 `GET /admin/supplier/items/{supplierId}/account-info/list` 的 `data.bankAccounts`，主体版本取该响应的 `data.updateTime`。摘要不包含银行、附件和结算字段，不能直接作为下次完整账户载荷。
|
||
|
||
#### 错误响应
|
||
|
||
提交 `initialAccounts: []`：
|
||
|
||
```json
|
||
{"code":400,"message":"账户不能为空","success":false,"data":null}
|
||
```
|
||
|
||
其他常见业务码：`395002` 无写权限；`395005` 非草稿或主体企微审批未结束；`395009` 已有账户不是草稿；`395014` 主体版本过期；`395027` 账号已占用；`400` 缺版本、字段或结算组合不合法。完全未改变数据也返回 `400 / 未检测到实际变化`。
|
||
|
||
#### 业务边界
|
||
|
||
- 要求 `FINANCE` 或 `SUPER_ADMIN` 且具有 `supplier:update`；`ADMIN` 被拒绝。
|
||
- 仅可维护草稿初始账户；已提交、已生效、已驳回账户没有资料修改或删除入口。
|
||
- 一项账户是完整快照：未提交的可选字段会被清空，需保留的字段必须一并带回。
|
||
- 相同账号保留账户 ID；换成新账号会替换旧草稿账户，成功后刷新列表和版本。
|
||
|
||
## 四、契约约束与正确调用方式
|
||
|
||
1. 按供应商读取账户列表和主体版本，草稿页面提交一项完整账户。
|
||
2. 从月结切换为其他结算方式时同步清空 `accountPeriod`；选不开票时同步清空 `taxRate`。
|
||
3. 保存成功刷新账户；版本冲突先重新读取。前端移除空数组删除逻辑，不生成不存在的账户删除路径。
|
||
|
||
## 五、数据库行为
|
||
|
||
修改成功保留一项草稿账户并刷新供应商版本；更换账号时旧草稿账户不再出现在有效列表。校验失败不改变账户；空数组请求不会删除数据。
|
||
|
||
## 六、边界行为
|
||
|
||
未登录或登录失效按认证失败处理；必须检查响应体 `code`、`success`，不能仅凭 HTTP 200 判断保存成功。既有主体资料不完整时，账户编辑同样会被必填校验拒绝。
|
||
|
||
## 六.5、枚举 / 数据字典
|
||
|
||
### `accountType`
|
||
|
||
| 值 | 中文 | 说明 |
|
||
|---|---|---|
|
||
| `CORPORATE` | 对公 | 必填账户类型之一 |
|
||
| `PERSONAL` | 对私 | 必填账户类型之一 |
|
||
|
||
### `settleMode`
|
||
|
||
| 值 | 中文 | 说明 |
|
||
|---|---|---|
|
||
| `PREPAY` | 预付 | 账期须为空 |
|
||
| `MONTHLY` | 月结 | 必填账期 |
|
||
| `SINGLE` | 单次结算 | 账期须为空 |
|
||
| `null` | 未登记 | 账期须为空 |
|
||
|
||
### `invoiceType`
|
||
|
||
| 值 | 中文 | 说明 |
|
||
|---|---|---|
|
||
| `SPECIAL` | 专票 | 必填税率 |
|
||
| `NORMAL` | 普票 | 必填税率 |
|
||
| `NONE` | 不开票 | 税率须为空 |
|
||
| `null` | 未登记 | 税率须为空 |
|
||
|
||
## 六.6、修改前后对比
|
||
|
||
本次补充文档，后端无新增变更。
|
||
|
||
| 字段 / 行为 | 旧 #6669 说明 | 当前契约 |
|
||
|---|---|---|
|
||
| `initialAccounts: []` | 可清空账户 | #7087 起拒绝，必须保留账户 |
|
||
| 草稿 `changeReason` | 必填 | #6684 起可省略 |
|
||
| `expectedUpdateTime` | 必填 | 仍必填，使用供应商主体版本 |
|
||
| 独立账户修改 / 删除 | 无独立接口 | 仍无独立接口；草稿修改走主体更新 |
|
||
|
||
## 六.7、影响评估
|
||
|
||
- 本次没有新增兼容性变化；前端须遵守已部署的账户非空约束。
|
||
- 无需与后端同步上线；清理旧的 `[]` 删除调用，按上述状态控制编辑入口。
|
||
|
||
## 七、不影响范围
|
||
|
||
本次说明覆盖草稿初始账户维护；新增账户审批、默认账户切换和合同契约保持现状。
|
||
|
||
## 八、测试环境已验证
|
||
|
||
- 既有业务实测：#6654 最终证据记录草稿账户修改、可选字段清空与版本失败零写入；#7087 记录显式空账户被拒绝、至少一项账户保存成功。旧证据中的整项清空已被 #7087 覆盖。
|
||
- 本次于 2026-09-06 通过 TEST Gateway 只读核对 Resource Swagger：主体更新路径及账户请求/摘要字段存在，未发布独立账户修改、删除路径；同时核对最新 `dev-v3` 源码。此次未重复执行共享环境业务写操作。
|
||
|
||
## 十、相关文档
|
||
|
||
- [账户修改既有实测 #6654](https://git.1814.love:8443/wx/HL/issues/6654#issuecomment-43820)
|
||
- [账户非空约束与实测 #7087](https://git.1814.love:8443/wx/HL/issues/7087#issuecomment-46744)
|
||
- [草稿免填变更原因 #6684](https://git.1814.love:8443/wx/HL/issues/6684)
|
||
|
||
## 关联 / 联系人
|
||
|
||
- **Issue**: [#7087](https://git.1814.love:8443/wx/HL/issues/7087)
|
||
- **PR**: [#7093](https://git.1814.love:8443/wx/HL/pulls/7093)
|
||
- **后端负责人**: @lc
|