From 97ca1fd45d5705487313c756064782c0296d949e Mon Sep 17 00:00:00 2001 From: lc Date: Mon, 24 Aug 2026 15:35:34 +0800 Subject: [PATCH] =?UTF-8?q?docs(changelog):=20=E8=AE=B0=E5=BD=95=E4=BE=9B?= =?UTF-8?q?=E5=BA=94=E5=95=86=E8=B5=84=E8=B4=A8=E6=A0=A1=E9=AA=8C=E5=8F=98?= =?UTF-8?q?=E6=9B=B4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Refs wx/HL#6241 --- ...字典化及证件编号公司级校验-修改接口-管理后台.md | 92 +++++++++++++++++++ 1 file changed, 92 insertions(+) create mode 100644 changelogs-v2/2026-08/24_6241_供应商资质类型字典化及证件编号公司级校验-修改接口-管理后台.md diff --git a/changelogs-v2/2026-08/24_6241_供应商资质类型字典化及证件编号公司级校验-修改接口-管理后台.md b/changelogs-v2/2026-08/24_6241_供应商资质类型字典化及证件编号公司级校验-修改接口-管理后台.md new file mode 100644 index 00000000..e22279b0 --- /dev/null +++ b/changelogs-v2/2026-08/24_6241_供应商资质类型字典化及证件编号公司级校验-修改接口-管理后台.md @@ -0,0 +1,92 @@ +--- +schema: "hl-changelog/v2" +ticket: "6241" +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: "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