供应商详情展示字段交付（#6317）

2026-08-25 12:12:53 +08:00
@@ -0,0 +1,103 @@
+---
+schema: "hl-changelog/v2"
+ticket: "6317"
+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-25"
+status_note: "PR #6323 已合并 dev-v3，合并提交 e9e523733 已由部署任务 318eb344 精确发布到 TEST 并经真实 Gateway 验证；验收后任务 faa1df6e 已将 Resource 恢复到包含该提交的最新 dev-v3。供应商详情新增联系人角色、资质类型中文名，以及永久使用和有效状态字段；isRequired 保持原必备规则并集语义，仅为兼容保留，详情业务不展示。"
+updated_at: "2026-08-25"
+base: "dev-v3"
+---
+
+# 供应商详情补充中文名称与资质有效状态
+
+供应商基本信息详情补充面向管理端展示的中文名称和资质有效性字段。联系人角色与资质类型继续保留原始字典值，同时返回中文标签；资质有效性由有效期截止日按上海自然日动态推导。
+
+## 变更接口
+
+| 方法 | 路径 | 行为变化 |
+|---|---|---|
+| GET | `/admin/supplier/items/{supplierId}/basic-info/view` | `contacts[]` 新增 `contactRoleName`；`qualifications[]` 新增 `qualTypeName`、`permanentValid`、`validityStatus` 和 `validityStatusName` |
+
+原字段 `contactRole`、`qualType`、`expiryDate`、`isRequired` 和 `expired` 均继续返回，字段名与 JSON 类型不变。
+
+响应片段示例：
+
+```json
+{
+  "contacts": [
+    {
+      "contactRole": "contentBus",
+      "contactRoleName": "业务人员"
+    }
+  ],
+  "qualifications": [
+    {
+      "qualType": "BUSINESS_LICENSE",
+      "qualTypeName": "营业执照",
+      "expiryDate": "2027-08-25",
+      "permanentValid": false,
+      "validityStatus": "VALID",
+      "validityStatusName": "有效",
+      "isRequired": true,
+      "expired": false
+    }
+  ]
+}
+```
+
+## 字段与状态语义
+
+- `contactRoleName` 来自 `sup_content_role` 生效字典项的中文标签；`qualTypeName` 来自 `company_qualification_type` 生效字典项的中文标签。
+- 历史值、自由文本值或已停用值未命中当前生效字典时，中文名称字段回退为原始值，避免详情空白。
+- 字典依赖异常时详情查询失败关闭，不伪造硬编码中文标签。
+- `expiryDate=null` 表示永久使用，返回 `permanentValid=true`、`validityStatus=VALID`、`validityStatusName=有效`。
+- `expiryDate` 早于上海时区当天时返回 `INVALID`、`无效`；等于当天或晚于当天时返回 `VALID`、`有效`。
+- `isRequired` 继续按供应商全部类型对应必备资质规则的并集计算，不改义为“是否永久”，也不参与有效状态推导。该字段仅为历史调用方兼容保留，供应商详情业务不展示。
+- 既有 `expired` 字段继续与“截止日早于上海当天”保持一致；调用方可迁移到新的状态字段，但无需立即停止兼容读取。
+
+## 管理端接入事项
+
+1. 联系人角色展示使用 `contactRoleName`，提交和稳定判断仍使用 `contactRole`。
+2. 资质类型展示使用 `qualTypeName`，提交和稳定判断仍使用 `qualType`。
+3. 资质区域展示固定为“有效期至”“永久使用”“状态”；“永久使用”按 `permanentValid` 显示“是/否”，“状态”按 `validityStatusName` 显示“有效/无效”。
+4. 详情页隐藏 `isRequired`，不要将其当作永久标识；`expiryDate` 为空时可显示占位符，永久语义以 `permanentValid=true` 为准。
+
+## 兼容性与未变化范围
+
+- 本次是既有 GET 响应的向后兼容扩展，不新增接口、请求参数、业务错误码、Gateway 路由或权限点。
+- 不修改供应商联系人、资质、类型规则等数据库数据，不新增 migration，也不回填历史值。
+- 不改变联系人电话和证件编号脱敏、软删除、数据范围、`supplier:view` 权限或统一响应结构。
+- 不修改配置、Redis、MQ、审批、状态机或跨服务写契约。
+- 本工单只交付后端；管理端源码未在后端仓库修改，前端状态保持 `pending`，直至完成上述展示适配并提供验证提交。
+
+## 验证证据
+
+- 自动化：新增详情展示 4 项测试，联合供应商字典 11 项定向测试共 15 项零失败；Resource 全量 2022 项零失败，38 项仓库既有条件跳过。
+- 合并后独立审计：在合并提交 `e9e523733` 上重新执行 15 项定向测试，零失败；同时核对 Gateway 强制认证、`supplier:view` 权限、脱敏、软删除和 `isRequired` 并集逻辑均未被绕过。
+- TEST 部署：任务 `318eb344` 将合并提交 `e9e523733` 精确发布，12:07:42 至 12:08:23、退出码 0；`hl-resource-service` 的 8182、8082 依次恢复健康，部署服务器 HEAD 与合并提交一致，Nacos `test` 命名空间实例数为 2。
+- 真实 Gateway：使用现有 `SUPER_ADMIN` 会话只读查询三条有效供应商；详情实际返回 `contactRoleName=业务人员`、`qualTypeName=营业执照`、`permanentValid=true`、`validityStatus=VALID` 和 `validityStatusName=有效`；同一资质的 `isRequired=false`，证明该字段未被改义为永久标识。未认证请求返回 HTTP 200、业务码 `401`、`success=false`。
+- 环境恢复：验收后任务 `faa1df6e` 将 Resource 恢复到包含 `e9e523733` 的最新 `dev-v3`，退出码 0，8082/8182 与 Nacos 两实例保持健康；临时精确提交部署分支已删除。
+- 清理：本次验收只读查询，不创建或修改供应商、文件、数据库、Redis、MQ 或配置数据，无测试数据需要清理。
+
+## 撤回
+
+1. 从最新 `dev-v3` 创建回退分支，执行 `git revert -m 1 --no-edit e9e523733c51dda3e5d5cd9a69cc20972cd8b741`，经独立 PR 合入。
+2. 重新构建并滚动部署 `hl-resource-service`；本次无数据库、配置、Redis 或 MQ 变更，无需执行 DDL、DML 或数据恢复。
+3. 回退后详情不再返回本次新增的四类展示字段；历史字段和数据保持兼容，管理端应同步停止读取 `contactRoleName`、`qualTypeName`、`permanentValid`、`validityStatus` 和 `validityStatusName`。
+4. 经 Gateway 复测详情成功、未认证、无权限、历史字典值回退和资质永久/过期/今日到期/未来到期边界，并确认电话与证件号仍脱敏。
+
+## 关联 / 联系人
+
+- **Issue**: [#6317](https://git.1814.love:8443/wx/HL/issues/6317)
+- **PR**: [#6323](https://git.1814.love:8443/wx/HL/pulls/6323)
+- **合并提交**: [e9e523733](https://git.1814.love:8443/wx/HL/commit/e9e523733c51dda3e5d5cd9a69cc20972cd8b741)
+- **后端负责人**: @lc