hl-api-changelog/changelogs-v2/2026-08/24_6266_供应商审批记录业务展示字段调整-修改接口-管理后台.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	6266	供应商审批记录业务展示字段调整	admin	lc(GIT)	修改接口	deployed	verified	verified	mmg	cd7fd4c4			PR #6270 已合并 dev-v3，合并提交 f14544fe0 已随 Resource 双实例滚动部署到 TEST。审批记录新增供应商名称、供应商类型、操作人姓名和审批角色，隐藏四个技术字段，并把变更前后值、状态和历史原因转换为中文脱敏业务展示。管理端需同步调整表格列和字段绑定。	2026-08-24	dev-v3

供应商审批记录业务展示字段调整

⚠️ 破坏性变更

供应商详情的审批记录响应改为面向业务展示：新增供应商名称、供应商类型、操作人姓名和审批角色；不再返回变更记录 ID、字段名、审批日志 ID 和操作人 ID。管理端必须按本契约调整表格列，不能继续依赖已移除字段。

变更接口

方法	路径	权限	行为变化
GET	/admin/supplier/items/{supplierId}/approval-records/page	supplier:approval:read	调整分页记录的响应字段和展示语义；请求参数、分页结构及权限不变

请求

GET /admin/supplier/items/2091715622923657217/approval-records/page?page=1&pageSize=10 HTTP/1.1
Host: api.test.1814.love:9443
Authorization: Bearer <adminToken>

GET 请求无请求体。

路径参数

参数	类型	必填	说明
supplierId	String	是	供应商 ID

查询参数

参数	类型	必填	默认值	说明
page	Integer	否	1	页码，最小为 1；兼容别名 pageNo
pageSize	Integer	否	20	每页条数，范围 1–100
approvalLogId	String	否	—	按关联审批日志 ID 精确筛选；仅为请求筛选条件，响应不再回传该字段
operationType	String	否	—	CREATE、UPDATE、ENABLE、DISABLE、DELETE
targetType	String	否	—	当前仅支持 SUPPLIER
fieldName	String	否	—	按历史变更字段精确筛选；仅为请求筛选条件，响应不再回传该字段
status	String	否	—	以生命周期编码筛选：DRAFT、VETTING、ACTIVE、SUSPENDED、FROZEN、BLACKLIST、ARCHIVED
from	String	否	—	开始时间，格式 yyyy-MM-dd HH:mm:ss；必须与 to 同时传入
to	String	否	—	结束时间，格式 yyyy-MM-dd HH:mm:ss；不得早于 from
sortBy	String	否	createTime	createTime 或 changeLogId
sortDirection	String	否	DESC	ASC 或 DESC，大小写均可

响应字段变化

新增字段

字段	类型	空值语义	说明
supplierName	String	供应商存在时非空	当前供应商法定全称
supplierTypes	Array	无类型时 []	当前供应商全部类型，主类型优先；typeCode 为字典值，typeName 为运行时中文名称
operatorName	String	不返回 null	优先返回操作人的企微姓名，其次为用户名；系统记录显示 系统，人员信息暂不可用时显示 管理员#<ID>
operatorRole	String	不返回 null	审计发生时的角色快照中文名；空角色显示 系统，未知历史角色显示 其他角色（<CODE>）

supplierTypes[] 元素结构：

字段	类型	说明
typeCode	String	供应商类型字典值
typeName	String	供应商类型中文名称

移除字段

原字段	前端处理
changeLogId	删除“变更 ID”列及所有字段读取
fieldName	删除“字段”列及所有字段读取；变更内容已经合并到中文摘要
approvalLogId	删除“审批日志 ID”列及所有字段读取
operatorId	改为展示 operatorName，不要再直接展示管理员 ID

上述字段仅从响应记录中移除；approvalLogId、fieldName 和 sortBy=changeLogId 作为既有查询能力继续兼容。

保留字段与新语义

字段	类型	新语义
supplierId	String	供应商 ID
operationType	String	操作类型编码保持不变
targetType	String	当前固定为 SUPPLIER
targetId	String / null	主体变更记录为 null
oldValueMasked	String	变更前的中文脱敏业务摘要，不再直接返回生命周期等原始编码
newValueMasked	String	变更后的中文脱敏业务摘要，不再直接返回生命周期等原始编码
changeReason	String	业务原因；已识别的历史注册记录同步校正为正确原因
status	String / null	变更后生命周期中文名，不再返回原始状态编码
createTime	String	yyyy-MM-dd HH:mm:ss

生命周期展示值如下：

原编码	响应中文值
DRAFT	草稿
VETTING	注册审核中
ACTIVE	合作中
SUSPENDED	暂停合作
FROZEN	已冻结
BLACKLIST	黑名单
ARCHIVED	已归档

审批角色常用展示值如下：

角色快照	operatorRole
SUPER_ADMIN	超级管理员
ADMIN	管理员
FINANCE	财务
OPERATOR	运营人员
CUSTOMIZER	定制师
HOUSEKEEPING_ADMIN	房务管理员
LOGISTICS_ADMIN	车务管理员
VEHICLE_MANAGER	车辆管理员

历史注册链路中可明确识别的原因统一为：

场景	changeReason
创建供应商草稿	创建供应商注册草稿
草稿提交注册审核	提交供应商注册审批
注册审批通过并启用	供应商注册审批通过并启用合作

典型成功响应

{
  "code": 200,
  "message": "成功",
  "traceId": "6266-success-example",
  "success": true,
  "data": {
    "records": [
      {
        "supplierId": "2091715622923657217",
        "supplierName": "内蒙古示例景区有限公司",
        "supplierTypes": [
          {
            "typeCode": "SCENIC",
            "typeName": "景区管理"
          }
        ],
        "operationType": "ENABLE",
        "targetType": "SUPPLIER",
        "targetId": null,
        "oldValueMasked": "供应商状态：注册审核中；供应商编号：无",
        "newValueMasked": "供应商状态：合作中；供应商编号：SUP2091715622923657217",
        "changeReason": "供应商注册审批通过并启用合作",
        "status": "合作中",
        "operatorName": "示例管理员",
        "operatorRole": "超级管理员",
        "createTime": "2026-08-24 10:34:34"
      }
    ],
    "total": 1,
    "page": 1,
    "pageSize": 10
  }
}

前端不能从示例中的名称、类型或状态推导固定值；供应商名称和类型取当前档案，状态、角色和变更内容由服务端提供中文展示。

边界响应

供应商存在但筛选条件下没有审批记录时返回空分页，不返回 null：

{
  "code": 200,
  "message": "成功",
  "traceId": "6266-empty-example",
  "success": true,
  "data": {
    "records": [],
    "total": 0,
    "page": 1,
    "pageSize": 10
  }
}

错误语义

场景	HTTP	业务码	说明
缺少或无效认证	可能为 200	401	success=false；不能只判断 HTTP 状态
无可信管理员身份、角色或 supplier:approval:read 权限	403	403	拒绝查询，不返回审批记录
供应商不存在或已删除	200	395001	供应商不存在
查询枚举、分页或时间范围非法	200	400	返回对应参数校验消息

未认证示例：

{
  "code": 401,
  "message": "缺少有效的 Authorization 头",
  "data": null,
  "traceId": "6266-auth-example",
  "success": false
}

脱敏与兼容约束

• 税号、联系电话、证件号和银行账号等敏感内容始终按字段语义重新脱敏；历史摘要也不会因旧数据格式而返回完整敏感值。
• 集合型资料只返回有界中文摘要；未知历史资料显示为安全的“其他资料：已变更”，客户端不要解析摘要反推结构化表单。
• 无变更值统一显示 —；前端直接展示服务端摘要，不再对 oldValueMasked、newValueMasked 或 status 做生命周期编码翻译。
• supplierName 和 supplierTypes 是当前供应商档案信息，不是每次审批发生时的历史快照。
• 本次不修改请求参数、分页外壳、认证方式、权限码、Gateway 路由或操作类型编码。

管理端改造清单

1. 隐藏“变更 ID”“字段”“审批日志 ID”列。
2. 新增“供应商名称”“供应商类型”“操作人”“审批角色”列，分别绑定 supplierName、supplierTypes、operatorName、operatorRole。
3. “变更前（脱敏）”“变更后（脱敏）”直接展示 oldValueMasked、newValueMasked，不再显示原始状态编码。
4. “状态快照”直接展示中文 status；操作类型筛选仍提交既有英文编码。
5. 删除对 changeLogId、fieldName、approvalLogId、operatorId 的响应依赖。

验证证据

• 自动化：审批记录投影与契约定向测试 22 项零失败；Supplier 聚焦回归 196 项零失败（1 项条件跳过）；Resource 全量 1953 项零失败（38 项仓库既有条件跳过）。
• 部署：TEST 部署任务 73bfe0aa 成功、退出码 0；hl-resource-service 的 8182、8082 双实例依次启动并健康。部署服务器 HEAD 4de8e1703 包含目标合并提交 f14544fe0 和功能提交 bdcb48d78。
• 真实 Gateway：管理端开发代理明确指向 https://api.test.1814.love:9443；有效超级管理员查询得到 code=200、success=true 和 4 条真实审批记录。
• 响应断言：四个新增字段在每条记录中均存在，四个移除字段均不存在；变更前后摘要和状态未出现 DRAFT、VETTING、ACTIVE 等原始生命周期编码；操作人返回姓名、审批角色返回中文。
• 原因断言：同一供应商的创建、提交、审批通过记录分别返回正确中文业务原因。
• 认证门禁：直接经 TEST Gateway 不携带 Authorization 查询，返回 HTTP 200、业务码 401、success=false。
• 清理：本次 TEST 验收仅执行只读查询，未创建、修改或删除业务数据，无需数据清理。

撤回

1. 从最新 dev-v3 创建回退分支，执行 git revert -m 1 --no-edit f14544fe0430ccafb7b74bca1ef43c080eabf491，经独立 PR 合入。
2. 重新构建并滚动部署 hl-resource-service；无需恢复数据库、配置、Redis 或 MQ，也没有不可逆数据影响。
3. 回退后审批记录会恢复旧响应字段和旧展示语义；管理端若已接入新字段，必须同步回退字段绑定，避免空列。
4. 经 Gateway 复测成功分页、空分页、未认证、无权限、中文/旧编码展示、敏感字段脱敏和历史原因。
5. 撤回本 Changelog 时，以新的文档提交删除本文件并通知管理端停止消费新契约；不要重写已发布提交历史。

关联 / 联系人

• Issue: #6266
• PR: #6270
• 合并提交: f14544fe0
• 后端负责人: @lc