wx/hl-api-changelog
1
0
派生 0
代码 工单 合并请求 工作流 软件包 项目 发布 百科 活动

交接供应商编辑字段回显契约（#6643）
changelog-filename-gate / validate (push) Successful in 2s
详情

浏览代码
这个提交包含在：
lc
2026-08-29 14:36:10 +08:00
父节点 1f608928b7
当前提交 4621f11e36
共修改 1 个文件，包含 389 行新增和 0 行删除
下载 Patch 文件 下载 Diff 文件 展开所有文件 折叠所有文件
changelogs-v2/2026-08/29_6643_供应商编辑页地址营业执照与备注回显-修改接口-管理后台.md
+389
查看文件
@@ -0,0 +1,389 @@
---
schema: "hl-changelog/v2"
ticket: "6643"
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: "PR #6645 已合并 dev-v3；hl-resource-service 已通过 Deploy Panel 任务 954419f9 部署提交 d206d1d577a3e3f8cec228e73e139fcb36c00fd5。真实 TEST Gateway 已验证 address、licenseImageUrl、remark 原值回显、更新后回读、空地址保留、营业执照顶层字段权威读取、395014 零写入及测试草稿清理。"
updated_at: "2026-08-29"
base: "dev-v3"
---
# 🔧 供应商编辑页地址、营业执照与备注回显
供应商编辑页应直接使用详情根对象的 `address`、`licenseImageUrl`、`remark` 初始化表单。其中 `licenseImageUrl` 是营业执照上传控件的权威字段，不得再从 `qualifications[].imageUrl` 推导或覆盖。
本次没有新增接口路径、请求必填项、权限点或业务错误码。
## 一、关键变化
| 字段 | 修改前 | 修改后 |
|---|---|---|
| `data.address` | 已有详情字段，但编辑和空值保留规则缺少本次回归锁定 | 返回已保存地址；提交非空新值后可回读，更新时留空保持原值 |
| `data.licenseImageUrl` | 详情根对象没有稳定的营业执照权威回显，调用方可能从资质数组取值 | 详情根对象稳定返回营业执照；只读取顶层权威值，不再从资质数组反向派生 |
| `data.remark` | 已有详情字段，但编辑回显和更新规则缺少本次回归锁定 | 返回已保存内部备注；提交非空新值后可回读 |
## 二、变更接口清单
| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
|---:|---|---|---|---|---|
| 1 | 查询供应商基本信息 | GET | `/admin/supplier/items/{supplierId}/basic-info/view` | 响应修改 | 根对象稳定返回 `address`、`licenseImageUrl`、`remark` |
| 2 | 更新供应商资料 | PUT | `/admin/supplier/items/{supplierId}/update` | 行为修改 | 三字段按增量更新和并发版本规则保存；写后重新查询可得到新值 |
## 三、接口详情
### 1. 查询供应商基本信息 `GET /admin/supplier/items/{supplierId}/basic-info/view`
**VO**: `SupplierBasicInfoRespVO`
#### 使用场景
管理端进入供应商详情或编辑页时获取完整表单快照。营业执照上传控件必须绑定根对象 `data.licenseImageUrl`；`qualifications[]` 继续用于独立资质列表，不是该控件的取值来源。
#### 入参
| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---:|---|---|
| `supplierId` | Path | String | 是 | 正整数 ID 字符串 | 目标供应商；不得转为 JavaScript Number |
无 Query 参数，无请求体。
#### 出参 `Result<SupplierBasicInfoRespVO>`
| 字段 | 类型 | 说明 |
|---|---|---|
| `data.address` | String/null | 注册地址或经营地址；未填写时为 `null` |
| `data.licenseImageUrl` | String/null | 营业执照影像权威地址；未填写时为 `null` |
| `data.remark` | String/null | 供应商主体内部备注；不等同于审批意见或变更原因 |
| `data.qualifications[].imageUrl` | String/null | 单项资质影像；与根对象营业执照字段分别读取 |
| `data.updateTime` | String | 主体并发版本，格式 `yyyy-MM-dd HH:mm:ss` |
#### 请求示例
```http
GET /admin/supplier/items/2092800000000000001/basic-info/view
Authorization: Bearer <admin-token>
```
#### 响应示例
```json
{
"code": 200,
"message": "成功",
"success": true,
"data": {
"supplierId": "2092800000000000001",
"supplierNo": "SUP2092800000000000001",
"fullName": "示例旅行服务有限公司",
"shortName": "示例旅行",
"tax_no": "91350211M000100Y46",
"legalRepresentative": "示例法人",
"legalRepresentativeIdNo": "11010519491231002X",
"legalRepresentativeIdNoMask": "11010519491231002X",
"legalRepresentativeIdCardFrontUrl": null,
"legalRepresentativeIdCardBackUrl": null,
"contactPhone": "13800138000",
"contactPhoneMask": "13800138000",
"establishDate": "2020-01-01",
"registeredCapital": "100万元",
"businessScope": "境内旅游服务",
"address": "福建省厦门市示例路 2 号",
"staffScale": "LT50",
"mainCooperation": "酒店与景区资源合作",
"licenseImageUrl": "https://files.example.com/supplier/business-license-new.jpg",
"remark": "地址与营业执照已复核",
"status": "DRAFT",
"creditLevel": "B",
"totalScore": null,
"types": [],
"primaryTypeCode": null,
"primaryTypeName": null,
"contacts": [],
"qualifications": [
{
"qualificationId": "2092800000000000011",
"qualType": "BUSINESS_LICENSE",
"qualTypeName": "营业执照",
"certNo": null,
"certNoMask": null,
"imageUrl": "https://files.example.com/supplier/business-license-new.jpg",
"expiryDate": null,
"permanentValid": true,
"daysUntilExpiry": null,
"validityStatus": "VALID",
"validityStatusName": "有效",
"isRequired": false,
"expired": false,
"updateTime": "2026-08-29 14:40:01"
}
],
"contracts": [],
"updateTime": "2026-08-29 14:40:02"
}
}
```
#### 空数据 / 降级响应
未填写三字段时返回明确的 `null`，前端显示空控件即可，不要用资质数组补写营业执照：
```json
{
"code": 200,
"message": "成功",
"success": true,
"data": {
"supplierId": "2092800000000000001",
"address": null,
"licenseImageUrl": null,
"remark": null,
"qualifications": [],
"updateTime": "2026-08-29 14:40:02"
}
}
```
#### 错误响应
供应商不存在、已删除或超出可见范围：
```json
{
"code": 395001,
"message": "供应商不存在",
"success": false,
"data": null
}
```
#### 业务边界
- 要求可信管理身份、可读角色、`supplier:view` 平台权限和既有数据范围。
- 根对象 `licenseImageUrl` 是编辑页营业执照的唯一权威回显；即使 `qualifications[]` 中同类型影像不同，也不得覆盖根对象值。
- 历史记录没有可用营业执照时返回 `null`，不猜测默认图片。
- 本接口只读，不推进版本、不触发审批或其他业务副作用。
### 2. 更新供应商资料 `PUT /admin/supplier/items/{supplierId}/update`
**VO**: `SupplierUpdateReqVO / SupplierWriteRespVO`
#### 使用场景
管理端保存供应商编辑表单。请求只发送实际修改字段，并携带详情中的最新 `updateTime` 和本次 `changeReason`。
#### 入参
| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|---|---|---|---:|---|---|
| `supplierId` | Path | String | 是 | 正整数 ID 字符串 | 目标供应商 |
| `address` | Body | String | 否 | 最长 500 字符 | 非空时更新；省略、`null`、空串或纯空格时保留原值 |
| `licenseImageUrl` | Body | String | 否 | 最长 500 字符 | 省略时保留；传非空值时更新权威营业执照；传空串时清空 |
| `remark` | Body | String | 否 | - | 非空时更新；省略、`null`、空串或纯空格时保留原值 |
| `changeReason` | Body | String | 是 | 去空白后非空，最长 500 字符 | 本次资料变更原因 |
| `expectedUpdateTime` | Body | String | 是 | `yyyy-MM-dd HH:mm:ss` | 详情最新主体并发版本 |
其他既有可选字段和集合快照规则保持不变。
#### 出参 `Result<SupplierWriteRespVO>`
| 字段 | 类型 | 说明 |
|---|---|---|
| `data.supplierId` | String | 供应商 ID |
| `data.supplierNo` | String | 供应商业务编号 |
| `data.status` | String | 当前生命周期状态 |
| `data.onboardingStage` | String | 当前注册阶段 |
| `data.initialAccounts` | Array | 初始收款账户摘要 |
| `data.updateTime` | String | 写入后的新主体并发版本 |
#### 请求示例
```http
PUT /admin/supplier/items/2092800000000000001/update
Authorization: Bearer <admin-token>
Content-Type: application/json
{
"address": "福建省厦门市示例路 2 号",
"licenseImageUrl": "https://files.example.com/supplier/business-license-new.jpg",
"remark": "地址与营业执照已复核",
"changeReason": "更新供应商编辑资料",
"expectedUpdateTime": "2026-08-29 14:40:00"
}
```
#### 响应示例
```json
{
"code": 200,
"message": "成功",
"success": true,
"data": {
"supplierId": "2092800000000000001",
"supplierNo": "SUP2092800000000000001",
"status": "DRAFT",
"onboardingStage": "PROFILE_DRAFT",
"initialAccounts": [],
"updateTime": "2026-08-29 14:40:02"
}
}
```
写响应不重复返回 `address`、`licenseImageUrl`、`remark`。前端需要完整表单时，应使用新 `updateTime` 重新查询详情。
#### 空数据 / 降级响应
成功更新时 `data` 恒为写入结果对象，不返回 `null`。当前请求没有实际变化时不会伪造成功或推进版本，而是返回业务失败：
```json
{
"code": 400,
"message": "未检测到实际变化",
"success": false,
"data": null
}
```
#### 错误响应
```json
{
"code": 395014,
"message": "数据已被他人修改，请刷新后重试",
"success": false,
"data": null
}
```
收到 `395014` 后先重新获取详情，由用户确认后再提交；不得用旧表单自动覆盖。
#### 业务边界
- 要求可信管理身份、`FINANCE` 或 `SUPER_ADMIN` 写角色及 `supplier:update` 平台权限。
- 成功写入后推进主体 `updateTime`；权限、参数、状态或并发失败时三字段及版本均不变化。
- 顶层 `licenseImageUrl` 更新时会继续兼容同步营业执照资质影像；反向只修改 `qualifications[].imageUrl` 不会改写顶层权威字段。
- `remark` 是主体内部备注；`changeReason` 是本次变更审计原因，两者不得互相替代。
- 统一响应可能以 HTTP 200 承载业务失败，调用方必须同时判断 `code`、`success`、`message` 和 `data`。
## 四、契约约束与正确调用方式
### 编辑页初始化
```text
地址输入框 ← data.address
营业执照上传控件 ← data.licenseImageUrl
内部备注输入框 ← data.remark
并发版本 ← data.updateTime
```
不得把 `qualifications.find(item => item.qualType === "BUSINESS_LICENSE").imageUrl` 作为营业执照上传控件的回显值或顶层字段兜底。
### 更新规则对照
| 场景 | 请求 | 结果 |
|---|---|---|
| 更新三个字段 | 发送三个非空新值 + 原因 + 最新版本 | 更新成功；重新查询返回三个新值 |
| 地址留空，修改备注 | `address: " "`，`remark` 为新值 | 地址保持原值，备注更新 |
| 省略营业执照 | 不发送 `licenseImageUrl` | 顶层营业执照保持原值 |
| 清空营业执照 | `licenseImageUrl: ""` | 顶层营业执照清空，兼容影像同步清空 |
| 只改资质数组影像 | 发送 `qualifications[]`，不发送顶层字段 | 资质影像独立变化，顶层营业执照保持原值 |
| 使用旧版本 | 发送过期 `expectedUpdateTime` | 返回 `395014`，零写入 |
## 五、数据库行为
本节只描述接口可观察结果，不要求前端感知存储结构：
- 三字段更新成功后，再次查询详情返回新值，且主体 `updateTime` 推进。
- `address` 或 `remark` 留空时保存其他字段，重新查询仍返回原地址或原备注。
- 顶层 `licenseImageUrl` 更新成功后，详情根对象与兼容营业执照资质影像均返回新值。
- 只更新资质数组影像时，详情根对象 `licenseImageUrl` 保持原值。
- 权限、参数、状态或 `395014` 并发失败时，三字段和主体版本均不变化。
- 部署时已对可识别的历史营业执照影像完成一次性兼容初始化；之后详情根对象不再从资质数组动态派生。
## 六、边界行为
- 未登录或 Token 无效由 Gateway 拒绝，不产生业务写入。
- 无 `supplier:view` 时详情读取失败；无 `supplier:update` 或不属于允许写角色时更新返回 `395002`，零写入。
- 供应商不存在、已删除或不可见时返回 `395001`。
- `address` 或 `licenseImageUrl` 超过各自长度上限时返回 `400`，零写入。
- 缺少 `changeReason`、缺少 `expectedUpdateTime` 或没有实际变化时返回 `400`，零写入。
- 版本过期返回 `395014`；客户端必须刷新详情，不能自动覆盖。
- `ARCHIVED` 等不可修改状态继续由既有状态门禁拒绝。
- 业务失败可能仍使用 HTTP 200，客户端必须检查统一响应体。
## 六.6、修改前后对比
### 字段级对比
| 字段 | 改前 | 改后 |
|---|---|---|
| `data.address` | 字段已存在，但本次编辑回归未锁定 | 原值、更新值及留空保留规则均已锁定 |
| `data.licenseImageUrl` | 根对象没有稳定权威回显 | 根对象返回可空权威值，不从 `qualifications[]` 反向派生 |
| `data.remark` | 字段已存在，但本次编辑回归未锁定 | 原值和更新值均可稳定回读 |
### 行为级对比
| 行为 | 改前 | 改后 |
|---|---|---|
| 编辑页初始化营业执照 | 可能从资质数组搜索影像 | 固定读取根对象 `licenseImageUrl` |
| 更新营业执照 | 根对象回读来源不稳定 | 提交顶层字段后，写后查询返回同一新值 |
| 单独修改资质影像 | 可能被误当成主体营业执照 | 不改变根对象营业执照权威值 |
## 六.7、影响评估
- **是否破坏向后兼容**：否。详情根对象增加可空字段并固定既有字段行为；旧客户端可忽略未知字段。
- **前端是否必须同步上线**：需要。营业执照上传控件必须改为读取并提交顶层 `licenseImageUrl`；地址和备注继续直接绑定根对象字段。
- **前端 workaround 清理点**：删除从 `qualifications[]` 搜索营业执照影像并覆盖表单值的逻辑。
- **QA 重点**：已有值回显、三字段更新后刷新、地址留空保留、资质影像与顶层营业执照相互独立、旧版本失败零写入。
## 七、不影响范围
- **仅影响**：管理后台供应商详情与编辑表单的地址、营业执照和内部备注。
- **零影响**：
- 接口路径、Gateway 路由和认证级别。
- 供应商既有角色、平台权限和数据范围。
- 生命周期状态机、审批、合同、收款账户和资源关系。
- 既有业务错误码、Redis、MQ、Feign 和其他服务。
- 小程序、C 端、Web、H5 和桌面端接口。
## 八、测试环境已验证
- 本地：供应商定向 62 项通过；`hl-resource-service` Reactor 全量 2,186 项通过，0 失败、0 错误，38 项既有条件跳过。
- 合并：后端 PR [#6645](https://git.1814.love:8443/wx/HL/pulls/6645) 已合并，合并提交为 `d206d1d577a3e3f8cec228e73e139fcb36c00fd5`。
- 部署：Deploy Panel API 任务 `954419f9` 成功，TEST 目标与实际提交均为上述合并提交；任务期 6 个采样均至少保持 2 个进程与 2 个健康启用实例匹配，0 个不可用采样。
- 真实 Gateway：唯一测试草稿依次验证原值回显、资质影像独立变化时顶层营业执照不变、三字段更新后回读、空地址保留、旧版本 `395014` 零写入及未认证拒绝。
- 清理：测试草稿已通过业务删除接口软删除并确认详情不可查询；仅保留系统规定的脱敏业务审计事实。
## 九、撤回
如后端撤回本次契约，前端在回退部署前停止依赖顶层 `licenseImageUrl`，并以同步发布的撤回 Changelog 为准；不得自行恢复未冻结的资质数组反向覆盖逻辑。地址与备注仍按既有 #6476 契约处理。
## 十、相关文档
- 关联 Issue：[#6643](https://git.1814.love:8443/wx/HL/issues/6643)
- 关联 PR：[#6645](https://git.1814.love:8443/wx/HL/pulls/6645)
- 既有地址与备注契约：[#6476](./27_6476_供应商详情补齐地址备注并统一表单校验-修改接口-管理后台.md)
- 当前前端状态：待前端处理；请按根对象字段完成映射后回写本文件的消费状态。
## 关联 / 联系人
### 链接
- **Issue**: [#6643](https://git.1814.love:8443/wx/HL/issues/6643)
- **PR**: [#6645](https://git.1814.love:8443/wx/HL/pulls/6645)
- **Merge commit**: [`d206d1d5`](https://git.1814.love:8443/wx/HL/commit/d206d1d577a3e3f8cec228e73e139fcb36c00fd5)
- **既有地址/备注契约**: [#6476](./27_6476_供应商详情补齐地址备注并统一表单校验-修改接口-管理后台.md)
### 联系人
- **后端负责人**: @lc
- **管理端负责人**: 待认领（`frontend_status: pending`）