---
schema: "hl-changelog/v2"
ticket: "6273"
title: "供应商审批记录补充供应商编号"
consumer: "admin"
author: "lc(GIT)"
change_type: "修改接口"
backend_status: "deployed"
gateway_status: "verified"
frontend_status: "verified"
frontend_owner: "mmg"
frontend_ref: "a46da334"
target_release: ""
verified_at: "2026-08-24"
status_note: "PR #6274 已合并 dev-v3，合并提交 588573ae4 已随 Resource 双实例滚动部署到 TEST。审批记录分页项新增当前供应商编号 supplierNo；既有目标字段、脱敏字段、权限、分页和闭区间时间筛选保持不变。管理端列展示和自然日边界组装仍待前端交付。"
updated_at: "2026-08-24"
base: "dev-v3"
---

# 供应商审批记录补充供应商编号

供应商详情的审批记录分页项新增当前供应商编号 `supplierNo`，供管理端直接展示。此次是向后兼容的响应扩展，不删除或重命名既有字段，也不改变查询、权限和脱敏语义。

## 变更接口

| 方法 | 路径 | 权限 | 行为变化 |
|---|---|---|---|
| GET | `/admin/supplier/items/{supplierId}/approval-records/page` | `supplier:approval:read` | 每条分页记录新增 `supplierNo` |

请求参数、分页外壳和排序规则均未变化。

## 新增响应字段

| 字段 | 类型 | 空值语义 | 说明 |
|---|---|---|---|
| `supplierNo` | String / null | 尚未生成编号的草稿返回 `null` | 当前供应商编号，直接来自供应商主体档案；不能从供应商 ID、审计 JSON 或展示摘要推导 |

典型分页项如下；示例值仅说明字段结构：

```json
{
  "supplierId": "2091715622923657217",
  "supplierNo": "SUP2091715622923657217",
  "supplierName": "示例供应商",
  "supplierTypes": [],
  "operationType": "UPDATE",
  "targetType": "SUPPLIER",
  "targetId": null,
  "oldValueMasked": "统一社会信用代码：****",
  "newValueMasked": "统一社会信用代码：****",
  "changeReason": "提交注册前保存完整表单",
  "status": "草稿",
  "operatorName": "示例管理员",
  "operatorRole": "超级管理员",
  "createTime": "2026-08-24 10:34:34"
}
```

## 保持兼容的字段与行为

- `targetType` 和 `targetId` 继续返回；管理端可以隐藏“目标类型”列，但不能把前端隐藏等同于删除接口字段。
- `oldValueMasked` 和 `newValueMasked` 继续返回脱敏后的业务摘要。管理端表头可简化为“变更前”“变更后”，但不得改为读取或展示未脱敏数据。
- `page`、`pageSize`、`operationType`、`status`、`from`、`to`、`sortBy` 和 `sortDirection` 的请求约束不变。
- 查询仍使用 `createTime >= from AND createTime <= to` 的闭区间语义；服务端不替客户端推导自然日边界。
- 认证方式、`supplier:approval:read` 权限、管理员数据范围、排序、错误码、Gateway 路由和统一 `Result<T>` 外壳均未变化。
- 不新增数据库 migration，不修改配置、Redis、MQ、审批状态机、审计写入或跨服务契约。

## 管理端待办

1. 在审批记录表格最前面增加“供应商编号”列，绑定 `supplierNo`；空值显示 `—`。
2. 隐藏“目标类型”列，但保留接口兼容字段，不要求后端删除 `targetType`。
3. 将“变更前（脱敏）”“变更后（脱敏）”表头改为“变更前”“变更后”；单元格仍绑定 `oldValueMasked`、`newValueMasked`。
4. 日期查询开始值组装为当天 `00:00:00`，结束值组装为当天 `23:59:59`，并在查询条件变化后重置到第 1 页。

若选择同一天，不能把开始和结束都提交为 `00:00:00`。例如查询 2026-08-24 应提交：

```text
from=2026-08-24 00:00:00
to=2026-08-24 23:59:59
```

## 错误与边界语义

| 场景 | 结果 |
|---|---|
| `from` 晚于 `to` | 参数校验失败，消息为 `from不能晚于to` |
| 只传 `from` 或只传 `to` | 参数校验失败，时间边界必须成对提交 |
| 未认证 | 统一响应 `code=401`、`success=false`；HTTP 状态可能仍为 200 |
| 无读取权限或超出数据范围 | 服务端拒绝查询，不返回审批记录 |
| 筛选结果为空 | 返回空分页，`records=[]`，不返回 `null` |

## 验证证据

- 自动化：供应商审批记录 Controller、投影和查询聚焦测试 16 项零失败；Resource 全量 1954 项零失败，38 项仓库既有条件跳过。
- 部署：TEST 部署任务 `32288c37` 成功、退出码 0；`hl-resource-service` 的 8182、8082 双实例依次启动并健康。部署服务器 HEAD `435ae0a86` 包含目标合并提交 `588573ae4` 和功能提交 `9cf77177c`。
- 真实 Gateway：使用现有有效超级管理员登录态查询 4 条审批记录，每条均返回当前 `supplierNo`；`targetType`、`targetId`、`oldValueMasked` 和 `newValueMasked` 同时保留，脱敏摘要仍包含掩码。
- 分页兼容：请求 `page=1&pageSize=2` 返回 2 条记录、总数 4，新增字段不改变分页外壳。
- 时间边界：同一自然日 `00:00:00` 至 `23:59:59` 返回 4 条；旧前端把结束值提交为 `00:00:00` 时返回 0 条，证明日期问题来自客户端结束边界组装。
- 参数门禁：反向时间范围被拒绝并返回 `from不能晚于to`。
- 认证门禁：不携带 Authorization 经 TEST Gateway 查询，返回 HTTP 200、业务码 `401`、`success=false`；该结果仅作为负向门禁验证，不计作正向验收。
- 清理：本次 TEST 验收只执行只读分页查询，未产生数据库、Redis、MQ、文件或外部业务副作用，无需测试数据清理。

## 撤回

1. 先停止发布或回退依赖 `supplierNo` 的管理端版本，避免后端字段回退后出现空列。
2. 从最新 `dev-v3` 创建回退分支，执行 `git revert -m 1 --no-edit 588573ae4ae016829d90dbb365f5c8ec3df981f0`，经独立 PR 合入。
3. 重新构建并滚动部署 `hl-resource-service`；无需恢复数据库、配置、Redis 或 MQ，没有不可逆数据影响。
4. 回退后接口不再保证返回 `supplierNo`；复测原有分页、权限、数据范围、脱敏字段、目标字段、排序和闭区间时间筛选。
5. 撤回本 Changelog 时，以新的文档提交删除本文件或明确标记撤回，并通知管理端停止消费新增字段；不要重写已发布提交历史。

## 关联 / 联系人

- **Issue**: [#6273](https://git.1814.love:8443/wx/HL/issues/6273)
- **PR**: [#6274](https://git.1814.love:8443/wx/HL/pulls/6274)
- **合并提交**: [588573ae4](https://git.1814.love:8443/wx/HL/commit/588573ae4ae016829d90dbb365f5c8ec3df981f0)
- **后端负责人**: @lc
- **前端负责人**: @mmg