hl-api-changelog/changelogs-v2/2026-08/24_6241_供应商资质类型字典化及证件编号公司级校验-修改接口-管理后台.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	6241	供应商资质类型字典化及证件编号公司级校验	admin	lc(GIT)	修改接口	deployed	verified	verified	mmg	a3ef713b		2026-08-24	PR #6254 已合并 dev-v3，合并提交 b17ace883 已随 Resource 双实例滚动部署到 TEST。供应商新增、编辑和提交统一校验 company_qualification_type 生效字典值及证件编号通用安全格式；权威/国家核验按确认口径降级为公司级校验。	2026-08-24	dev-v3

供应商资质类型字典化及证件编号公司级校验

供应商资质写入不再接受任意资质类型。新增、编辑和提交均以 User 服务的 company_qualification_type 生效项为准，并通过公共校验组件统一处理证件编号。

本次“核验”仅表示输入符合公司系统的格式和安全约束，不代表证照真实存在，也不声明已通过国家平台或第三方权威核验。

变更接口

方法	路径	行为变化
POST	/admin/supplier/items/add	显式资质类型必须是生效字典值；草稿证件编号可空，非空时校验通用格式
PUT	/admin/supplier/items/{supplierId}/update	新增或显式修改的资质类型、证件编号执行同一规则；未传类型的历史资质保持兼容
POST	/admin/supplier/items/{supplierId}/submit	提交时每项资质必须有合法证件编号；营业执照快捷影像也受字典门禁约束

请求和响应字段结构未变化。qualType 仍提交字符串，但其值必须来自：

GET /admin/dict/data/company_qualification_type

当前 TEST 已启用以下五项：

字典值	标签
BUSINESS_LICENSE	营业执照
INDUSTRY_LICENSE	行业经营许可证
FOOD_OPERATION_LICENSE	食品经营许可证
PUBLIC_HEALTH_LICENSE	公共场所卫生许可证
FIRE_SAFETY_CERTIFICATE	消防安全证明

证件编号规则

• 自动去除首尾空白，最大为 128 个 UTF-8 字节。
• 允许 Unicode 字母、数字及常见中英文证照分隔符。
• 排除空白、控制字符及可组成 HTML 标签的半角尖括号。
• 草稿允许为空；提交审批时每项资质必须填写。
• 读取仍只返回脱敏证件号，不返回明文。

新增业务错误码

错误码	含义	前端处理建议
395040	资质类型不合法或已停用	刷新 company_qualification_type 字典并要求用户重新选择
395041	证件编号格式不合法	保留表单，提示用户修正编号；提交场景同时检查是否为空

业务失败可能仍使用 HTTP 200，客户端必须同时判断统一响应的 code、success 和 data。

兼容性与前端事项

• 不新增数据库 migration、配置、Redis、MQ 或跨服务写入。
• 既有历史自由文本资质可以读取；编辑既有项且不传 qualType 时不会被强制改写。
• 前端应将资质类型自由输入改为 company_qualification_type 字典选择，并只提交 dictValue。
• 前端无需修改字段名、JSON 类型或接口路径。

验证证据

• 自动化：Resource 全量 1925 项零失败（38 项仓库既有条件跳过）；#6241 定向 35 项零失败；独立审计 48 项零失败。
• 部署：TEST 部署任务退出码 0，hl-resource-service 的 8182、8082 双实例依次健康；服务器部署 HEAD 04a6dba66 明确包含合并提交 b17ace883 和功能提交 bc899930e。
• 真实 Gateway：非法资质类型返回“资质类型不合法或已停用”，非法证件编号返回“证件编号格式不合法”，两次失败后列表仍为原 3 条。
• 真实 Gateway：使用五个生效字典值和多种常见编号格式成功创建草稿；详情页五个证件号均为脱敏值。
• 清理：TEST 草稿删除成功，供应商列表恢复原 3 条，未留下测试数据。

撤回

1. 从最新 dev-v3 创建回退分支，revert #6254 合并提交 b17ace88399269710ea515e9b19e63a159b888c9，经独立 PR 合入。
2. 重新构建并滚动部署 hl-resource-service；无需恢复数据库、User 字典、配置、Redis 或 MQ。
3. 回退后既有资质数据保持可读，不做数据回写；写接口会恢复为旧的自由文本行为。
4. 经 Gateway 重跑新增、编辑、提交、非法类型、非法编号和读取脱敏用例，并核对失败零写入。

关联 / 联系人

• Issue: #6241
• PR: #6254
• 合并提交: b17ace883
• 后端负责人: @lc