142 行
5.7 KiB
Markdown
142 行
5.7 KiB
Markdown
---
|
||
schema: "hl-changelog/v2"
|
||
ticket: "6710"
|
||
title: "供应商联系人快照版本字段兼容"
|
||
consumer: "admin"
|
||
author: "lc(GIT)"
|
||
change_type: "修改接口"
|
||
backend_status: "deployed"
|
||
gateway_status: "verified"
|
||
frontend_status: "verified"
|
||
frontend_owner: "mmg"
|
||
frontend_ref: "95e1f917"
|
||
target_release: "v2.1"
|
||
verified_at: "2026-08-30"
|
||
status_note: "PR #6712 已合并 dev-v3，合并提交 7f3f944bf361b7ae41424c43b29262fb634fe791 已精确部署 TEST。后端后改判「当前前端已回传 updateTime 无需修改代码」，但前端实证：修复前 cleanContactRow 对已有联系人仅发 contactId 不带任何版本，必触发 400「联系人快照项不合法」；本次前端补回传条目级版本（commit 95e1f917），修复后方可正常保存。前端按实际修复记 verified。"
|
||
updated_at: "2026-08-30"
|
||
base: "dev-v3"
|
||
---
|
||
|
||
# 供应商联系人快照版本字段兼容
|
||
|
||
后端现已兼容详情联系人字段 `contacts[].updateTime`。当前前端已经回传该字段，无需修改代码；本记录仅保留历史审计，不构成前端任务。
|
||
|
||
## 二、变更接口清单
|
||
|
||
| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
|
||
|---:|---|---|---|---|---|
|
||
| 1 | 编辑供应商 | PUT | `/admin/supplier/items/{supplierId}/update` | 请求兼容 | 已有联系人可用 `updateTime` 作为条目级并发版本 |
|
||
|
||
## 三、接口详情
|
||
|
||
### 1. 编辑供应商 `PUT /admin/supplier/items/{supplierId}/update`
|
||
|
||
**VO**: `SupplierUpdateReqVO / SupplierContactMergeReqVO / SupplierWriteRespVO`
|
||
|
||
#### 使用场景
|
||
|
||
保留已有联系人并在一次编辑中新增多个联系人。
|
||
|
||
#### 入参
|
||
|
||
| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|
||
|---|---|---|---:|---|---|
|
||
| `expectedUpdateTime` | Body | String | 是 | `yyyy-MM-dd HH:mm:ss` | 主体并发版本 |
|
||
| `contacts` | Body | Array | 否 | 最多 100 项 | 联系人完整快照 |
|
||
| `contacts[].contactId` | Body | String | 已有项是 | 正整数 | 为空表示新增 |
|
||
| `contacts[].expectedUpdateTime` / `updateTime` | Body | String | 已有项二选一 | 时间格式同上 | 条目级并发版本 |
|
||
|
||
姓名和联系电话允许与已有联系人或同批新增联系人重复。新增项仍按既有规则提供姓名、电话和角色，不传 ID 与版本。
|
||
|
||
#### 出参 `Result<SupplierWriteRespVO>`
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| `data.updateTime` | String | 保存后的主体并发版本 |
|
||
|
||
#### 请求示例
|
||
|
||
```json
|
||
{"expectedUpdateTime":"2026-08-30 10:04:18","contacts":[{"contactId":"2093000000000000001","contactName":"张三","contactPhone":"18501941408","contactRole":"contentBus","updateTime":"2026-08-30 10:04:19"},{"contactName":"张三","contactPhone":"18501941408","contactRole":"contentMoney"}]}
|
||
```
|
||
|
||
#### 响应示例
|
||
|
||
```json
|
||
{"code":200,"message":"成功","success":true,"data":{"updateTime":"2026-08-30 10:04:29"}}
|
||
```
|
||
|
||
#### 空数据 / 降级响应
|
||
|
||
- 省略 `contacts` 或传 `null`：联系人不变。
|
||
- 依赖异常：沿用既有失败关闭语义，不产生部分写入。
|
||
|
||
#### 错误响应
|
||
|
||
版本过期时：
|
||
|
||
```json
|
||
{"code":395014,"message":"数据已被他人修改，请刷新后重试","success":false,"data":null}
|
||
```
|
||
|
||
已有联系人未携带任一版本字段时，仍返回 `400`、`联系人快照项不合法`。
|
||
|
||
#### 业务边界
|
||
|
||
- 已有联系人仍须提供 `contactId` 和有效版本；本次没有取消并发校验。
|
||
- 姓名或联系电话重复本身不是错误条件。
|
||
- 权限、状态、默认联系人及角色字典规则均不变。
|
||
|
||
## 四、契约约束与正确调用方式
|
||
|
||
1. 主体详情 `updateTime` 放入请求顶层 `expectedUpdateTime`。
|
||
2. 已有联系人的 `updateTime` 可原样回传；新增联系人不传 ID 和版本。
|
||
3. 保存后重新读取详情，使用最新版本继续编辑。
|
||
|
||
## 五、数据库行为
|
||
|
||
- 不新增数据库结构或姓名、电话唯一约束。
|
||
- 校验失败时联系人和主体均不写入。
|
||
|
||
## 六、边界行为
|
||
|
||
- 未登录、无权限、供应商不存在或版本过期时沿用既有错误。
|
||
- `contacts=[]` 沿用既有清空语义。
|
||
- 业务失败可能仍为 HTTP 200，调用方同时判断 `code` 和 `success`。
|
||
|
||
## 六.6、修改前后对比
|
||
|
||
| 项目 | 修改前 | 修改后 |
|
||
|---|---|---|
|
||
| 联系人版本字段 | 仅识别 `expectedUpdateTime` | 同时识别 `expectedUpdateTime`、`updateTime` |
|
||
| 姓名、电话重复 | 允许 | 继续允许 |
|
||
|
||
## 六.7、影响评估
|
||
|
||
- **是否破坏向后兼容**：否。
|
||
- **前端是否必须同步上线**：否，当前前端已回传 `updateTime`。
|
||
- **前端 workaround 清理点**：无。
|
||
- **响应与错误码影响**：无。
|
||
|
||
## 七、不影响范围
|
||
|
||
- 不修改其他供应商接口、权限或状态机。
|
||
- 不修改数据库结构、配置、Redis 或 MQ。
|
||
- 不修改任何前端代码。
|
||
|
||
## 八、测试环境已验证
|
||
|
||
- 详情 `updateTime` 原样回传后，可保留已有联系人并新增多个联系人。
|
||
- 多个联系人姓名、电话重复时保存成功。
|
||
- 过期版本返回 `395014` 且零写入；验收草稿已清理。
|
||
|
||
## 十、相关文档
|
||
|
||
- [Issue #6710](https://git.1814.love:8443/wx/HL/issues/6710)
|
||
- [PR #6712](https://git.1814.love:8443/wx/HL/pulls/6712)
|
||
|
||
## 关联 / 联系人
|
||
|
||
- **后端负责人**：@lc
|
||
- **当前状态**：已消费（`frontend_status: verified`)。SupplierEditModal fillForm 回填详情联系人条目级 updateTime、createContactRow 新增行置 null;cleanContactRow 已有项(contactId 存在)加发 expectedUpdateTime=row.updateTime 原样回传,新增行仍不发版本;快照比对两侧同经 cleanContactRow,未改动不误携带。spec +3 例累计 71 例绿,commit 95e1f917 已推 v2.1。注:后端后改判「无需前端处理」系基于修复后前端,修复前旧前端仅发 contactId 必 400,本修复为必要。
|