---
schema: "hl-changelog/v2"
ticket: "6241"
title: "供应商资质类型字典化及证件编号公司级校验"
consumer: "admin"
author: "lc(GIT)"
change_type: "修改接口"
backend_status: "deployed"
gateway_status: "verified"
frontend_status: "verified"
frontend_owner: "mmg"
frontend_ref: "a3ef713b"
target_release: ""
verified_at: "2026-08-24"
status_note: "PR #6254 已合并 dev-v3，合并提交 b17ace883 已随 Resource 双实例滚动部署到 TEST。供应商新增、编辑和提交统一校验 company_qualification_type 生效字典值及证件编号通用安全格式；权威/国家核验按确认口径降级为公司级校验。"
updated_at: "2026-08-24"
base: "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](https://git.1814.love:8443/wx/HL/issues/6241)
- **PR**: [#6254](https://git.1814.love:8443/wx/HL/pulls/6254)
- **合并提交**: [b17ace883](https://git.1814.love:8443/wx/HL/commit/b17ace88399269710ea515e9b19e63a159b888c9)
- **后端负责人**: @lc