209 行
9.8 KiB
Markdown
209 行
9.8 KiB
Markdown
---
|
||
schema: "hl-changelog/v2"
|
||
ticket: "6684"
|
||
title: "供应商草稿编辑变更原因可选且不写变更记录"
|
||
consumer: "admin"
|
||
author: "lc(GIT)"
|
||
change_type: "修改接口"
|
||
backend_status: "deployed"
|
||
gateway_status: "verified"
|
||
frontend_status: "verified"
|
||
frontend_owner: "mmg"
|
||
frontend_ref: "646a1565"
|
||
target_release: "v2.1"
|
||
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
|
||
- **当前状态**：已消费（`frontend_status: verified`)。SupplierEditModal 变更原因必填改仅非 DRAFT(mainLocked)挂载,DRAFT 取消必填、留空省略 changeReason 不写变更记录;buildEditBody 按「非 DRAFT 恒携带/DRAFT 填了才携带」;「至少一个实际变化字段」判定剔除元字段后看业务字段。非 DRAFT 继续必填拦截。
|