hl-api-changelog/changelogs-v2/2026-09/02_6938_供应商注册提交可选主表字段缺席保留-修改接口-管理后台.md

schema, ticket, title, consumer, author, change_type, backend_status, gateway_status, frontend_status, frontend_owner, frontend_ref, target_release, verified_at, status_note, updated_at, base

schema	ticket	title	consumer	author	change_type	backend_status	gateway_status	frontend_status	frontend_owner	frontend_ref	target_release	verified_at	status_note	updated_at	base
hl-changelog/v2	6938	供应商注册提交可选主表字段缺席保留	admin	lc(GIT)	修改接口	deployed	verified	pending				2026-09-02	PR #6941（含补充 #6945/#6946）已合并 dev-v3，合并链终态提交 697ae6f57 已滚动部署 TEST 双实例。注册提交接口可选主表字段语义由缺席清空改为缺席保留；TEST 真实网关验收 32 项断言通过。	2026-09-02	dev-v3

供应商模块: 注册提交可选主表字段缺席保留

存放目录: 二期(v3) → changelogs-v2/2026-09/

服务: hl-resource-service (端口 8082) PR: #6941 Issue: #6938 日期: 2026-09-02 影响范围: 管理端供应商注册提交表单

---

⚠️ 关键变化（非必须,本版与上版行为不同 / 纠错 / 撤销时必写）

• 本次变化：注册提交保存完整表单时，缺席或空白的可选主表字段保留草稿现值，不再清空。
• 前端以前以为的：提交表单未回显的字段（如公司联系电话）提交后仍在。
• 实际旧行为：提交瞬间被静默置空（本单修复前的缺陷）；新行为：缺席=保留，与增量更新接口语义对齐。

---

一、背景（选填）

工单 #6938：供应商提交注册时全量表单静默清空未回传字段（公司联系电话丢失）。根因是提交链路按"完整表单权威覆盖"语义把缺席/空白字段写成 NULL 并留下清空审计。修复后提交与增量更新共用"空白=保留"语义。

---

二、变更接口清单

#	接口	方法	路径	变更类型	说明
1	提交供应商注册审批	POST	/admin/supplier/items/{supplierId}/submit	字段缺席语义变更	可选主表字段缺席/空白由"清空"改为"保留现值"

---

三、接口详情

1. 提交供应商注册审批 POST /admin/supplier/items/{supplierId}/submit

VO: SupplierSubmitReqVO

使用场景

管理端供应商编辑页点击"提交注册"时调用；提交前应用 GET /admin/supplier/items/{supplierId}/basic-info/view 回显完整表单。

入参

字段	位置	类型	必填	约束	说明
fullName	Body	String	✅	-	全称，请求权威提供
taxNo	Body	String	✅	GB32100 校验位	税号，请求权威提供
mainCooperation	Body	String	✅	-	主要合作内容
balance	Body	BigDecimal	✅	≥0	余额
paymentType	Body	String	✅	-	支付类型
licenseImageUrl	Body	String	✅（提交时）	-	执照影像，维持请求侧必填门禁，缺席拒绝
expectedUpdateTime	Body	LocalDateTime	✅	yyyy-MM-dd HH:mm:ss	乐观锁，取视图 updateTime
shortName / contactPhone / address / countyId / establishDate / registeredCapital / businessScope / staffScale / remark	Body	-	❌	-	缺席或空白 = 保留草稿现值（本次变更）
legalRepresentative / legalRepresentativeIdNo / legalRepresentativeIdCardFrontUrl / legalRepresentativeIdCardBackUrl	Body	-	❌	格式校验	法人四件套，同上缺席保留
types / contacts / qualifications / initialAccounts	Body	List	❌	-	子项快照；contacts/initialAccounts 缺席 = 保留历史

出参 Result<SupplierApprovalCommandRespVO>

字段	类型	说明
approvalStatus	String	受理后 PENDING
spNo	String	审批单号（TEST 现为真实企微单号）

请求示例

{
  "fullName": "HL6938-TEST-20260902",
  "taxNo": "91150100HL6938T01W",
  "mainCooperation": "车队合作",
  "balance": "0.00",
  "paymentType": "1",
  "licenseImageUrl": "https://example.com/hl6938-license.png",
  "expectedUpdateTime": "2026-09-02 11:05:52",
  "types": [{"typeCode": "FLEET", "isPrimary": 1}],
  "qualifications": [{"qualType": "GZZRX_LICENSE", "certNo": "GZZRX2026HL6938A", "permanentValid": true}]
}

响应示例

{
  "code": 200,
  "message": "成功",
  "data": { "approvalStatus": "PENDING", "spNo": "202609020001" },
  "success": true
}

空数据 / 降级响应

写接口无空数据场景；提交受理即返回审批单号，无降级分支。

{ "code": 200, "data": { "approvalStatus": "PENDING" }, "success": true }

错误响应

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

业务边界

• 鉴权：写权限 FINANCE/SUPER_ADMIN；未登录 → 业务码 401。
• 乐观锁：expectedUpdateTime 与现值不符 → 业务码 395014，零写入。
• 非草稿状态重复提交 → 状态机拒绝，零写入。
• 表单与草稿一致时不产生"提交注册前保存完整表单"变更记录。

---

四、契约约束与正确调用方式（接口类必写）

本节只写后端接受/拒绝 payload 的规则,不写 UI 渲染建议。

✅ 正确 / ❌ 错误 payload 对照

场景	payload
✅ 回显全量已填字段提交	视图字段全部带回，行为与旧版一致
✅ 可选字段缺席	contactPhone 等缺省 → 保留草稿现值，不再清空
✅ 显式修改可选字段	contactPhone: "04712227654" → 覆盖并双向审计留痕
❌ 缺席 licenseImageUrl	提交必填门禁拒绝（业务码 3950xx 资质必填）
❌ 缺席 expectedUpdateTime	400，expectedUpdateTime不能为空

• 缺席保留意味着可选字段不再支持以空白清空；确需清空请联系后端评估独立入口。
• expectedUpdateTime 必须取最近一次 basic-info/view 返回的 updateTime。

---

五、数据库行为（涉及写操作时必写）

前端提交	contact_phone 等可选列
字段缺席或空白	保留数据库现值（不再 SET NULL）
字段显式提供新值	覆盖为新值，supplier_change_log 记录旧→新

• 无 migration、DDL 或 DML；历史已被清空的旧数据不回写。

---

六、边界行为

• 未登录 → 业务码 401（网关包装 HTTP 200）。
• 乐观锁冲突 → 业务码 395014，不阻断页面，重新取视图重试即可。
• 旧客户端继续全量回显提交 → 行为不变。
• 历史已清空数据 → 保持 NULL，不异常、不回写。

---

六.6、修改前后对比（修改/删除类接口必写，新增跳过）

字段级对比

字段	改前	改后
12 个可选文本字段（contactPhone 等）缺席/空白	清空为 NULL 并记清空审计	保留草稿现值，无审计
countyId/establishDate 缺席	清空为 NULL	保留草稿现值

行为级对比

行为	改前	改后
提交表单未回显可选字段	字段被静默清空	字段保留
提交审计 delta	出现非用户主动的清空留痕	只记录真实变化；一致时不落审计行

六.7、影响评估（修改/删除类必写）

• 是否破坏向后兼容: 否。请求/响应结构不变；仅缺席字段行为由清空变保留，无合理调用方依赖清空语义。
• 前端是否必须同步上线: 否。建议跟进修复提交表单回显（工单验收②的前端分支），后端缺席保留已兜底。
• 前端 workaround 清理点: 无。

---

七、不影响范围（显式声明, 帮前端/QA 缩小排查面）

• 仅影响: 管理后台供应商注册提交接口的可选主表字段缺席行为。
• 零影响:
  • 供应商新增 /add、增量更新 /update（其 licenseImageUrl 既有空白清空分支保持原样，不在本单）
  • 必填字段（全称/税号/合作内容/余额/支付类型/执照影像）的请求权威语义
  • 供应商状态机、审批流、企微 Provider 交互、审批候选快照结构
  • C 端接口与历史存量数据

---

八、测试环境已验证

真实 Gateway（api.test.1814.love）+ TEST 数据库实证，带 ✓ 标记：

POST /admin/supplier/items/add                       → 200 草稿含全量可选字段 ✓
POST /admin/supplier/items/{id}/submit（缺席可选字段） → 200 PENDING + 真实单号 ✓
GET  /admin/supplier/items/{id}/basic-info/view      → 九个可选字段全部保留 ✓
     （contactPhone=04711234567 座机形态保留，验收①②）
DB   supplier_change_log 提交审计 changedFields       → 恰为 [contacts,qualifications]，
     九字段均不在列，无 "contactPhone":null 清空形态 ✓（验收③）
POST submit（显式改 contactPhone）                    → 新值生效，审计 before/after
     双向留痕 13847110001→04712227654 ✓（兼容性）

验证夹具: HL6938-TEST-20260902(supplierId=2094985119537217538) / HL6938B-TEST-20260902(supplierId=2094987591035101186)；验收产生的真实企微在途单已发起撤销。 自动化: SupplierAggregateWriterTest 定向零失败；hl-resource-service 全量 2293 项零失败。部署: TEST 任务 dcdfb70a，部署提交 697ae6f57 与预期一致，双实例滚动健康。

---

九、相关历史 PR（纠错 / 功能演进时必写）

PR	Issue	说明	是否仍有效
#6930	#6927	注册提交接企微四级串行审批	✅ 有效
本 PR #6941	#6938	可选主表字段缺席保留（补充 #6945/#6946）	✅ 最新

---

十、相关文档

• 关联 Issue: wx/HL#6938
• 关联 PR: wx/HL#6941

关联 / 联系人

链接

• Issue: #6938
• PR: #6941（补充 #6945、#6946）
• Merge commit: 697ae6f57

联系人

• 后端负责人: @lc