docs(changelog): 供应商分页/列表出参补 contactPhone（#7199 / PR #7202）

出参 SupplierListItemRespVO 新增 contactPhone（联系电话完整原值，管理后台授权场景）。注：同 PR 曾新增 balance，已被 #7291 移除，changelog 内已显式标注勿消费。
2026-09-10 00:20:54 +08:00
@@ -0,0 +1,236 @@
+---
+schema: "hl-changelog/v2"
+ticket: "7199"
+title: "供应商分页/列表出参补字段（联系电话）"
+consumer: "admin"
+author: "yst"
+change_type: "修改接口"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "pending"
+frontend_owner: "hl-admin"
+frontend_ref: ""
+target_release: ""
+verified_at: ""
+status_note: "后端已合 dev-v3（PR #7202）。注意：本 PR 同时新增的 balance 字段已于 2026-09-07 被 PR #7291 移除（见同目录 07_7291 变更说明），当前线上有效新增仅 contactPhone，请勿消费 balance。"
+updated_at: "2026-09-10"
+base: "dev-v3"
+---
+
+# 供应商分页/列表出参补字段
+
+## 1. 接口背景
+
+财务域弹窗选供应商（应付款 / 业务外收支 / 往来账 / 收票四个场景）需要在选择器里直接看到供应商的联系电话。复用现有供应商分页 / 有界列表接口（弹窗分页搜索形态，供应商数量多不适用下拉全量加载），出参 `SupplierListItemRespVO` 补字段。
+
+> **重要时序说明**：本 PR（#7202，2026-09-06 合并）当时新增了 `balance` + `contactPhone` 两个字段；次日 PR #7291（2026-09-07 合并）做供应商历史字段清理，又把 `balance` 从出参移除（详见同目录 `07_7291_供应商与结算信息移除历史字段-修改接口-管理后台.md`，前端已配合清理完毕）。**因此当前线上相对旧版的净变化只有 `contactPhone` 一个新增字段，请勿消费 `balance`。**
+
+## 2. 变更清单
+
+| 类型 | 接口 | 说明 |
+|---|---|---|
+| 修改 | GET `/admin/supplier/items/page` | 出参 `records[]` 新增 `contactPhone` |
+| 修改 | GET `/admin/supplier/items/list` | 出参数组项新增 `contactPhone` |
+
+两接口共用同一出参装配逻辑，同时生效。入参与其他出参字段不变，仅新增字段，向后兼容。
+
+## 3. 接口详情
+
+| 项 | 说明 |
+|---|---|
+| 使用场景 | 管理后台供应商列表页；财务域弹窗选供应商（应付款 / 业务外收支 / 往来账 / 收票） |
+| 认证 | 管理后台 JWT（`/admin/*` 网关鉴权），Service 层校验可信角色和列表权限 |
+| 幂等性 | 只读查询，天然幂等 |
+| 限流 | 无特殊限流 |
+
+## 4. 接口入参
+
+### 4.1 GET /admin/supplier/items/page（Query，SupplierPageReqVO）
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| pageNo | Integer | 是 | 页码（沿用现有分页规则） |
+| pageSize | Integer | 是 | 每页条数 |
+| keyword | String | 否 | 模糊匹配业务编码 / 全称 / 简称；明文税号优先等值匹配，最长 500 |
+| status | String | 否 | 状态筛选：`DRAFT` / `VETTING` / `ACTIVE` / `SUSPENDED` / `BLACKLIST` / `ARCHIVED` |
+| typeCode | String | 否 | 生效供应商类型字典值，最长 64 |
+| creditLevel | String | 否 | 信用等级：`A` / `B` / `C` / `D` |
+| creatorId | Long | 否 | 创建管理员 ID |
+
+### 4.2 GET /admin/supplier/items/list（Query，SupplierListReqVO）
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| keyword | String | 否 | 同 4.1 |
+| status | String | 否 | 同 4.1 |
+| typeCode | String | 否 | 同 4.1 |
+| resourceModule | String | 否 | 设置供应商场景的资源模块；必须与 `resourceId` 同时提供 |
+| resourceId | Long | 否 | 设置供应商场景的资源 ID；必须与 `resourceModule` 同时提供 |
+| limit | Integer | 否 | 最大返回条数，默认 50，最大 200 |
+
+**本次入参无任何变化**，以上仅为完整契约内联。
+
+## 5. 出参字段
+
+- `/page` 返回 `PageResult<SupplierListItemRespVO>`：`{ records: [], total, page, pageSize }`
+- `/list` 返回 `List<SupplierListItemRespVO>`（数组）
+
+`SupplierListItemRespVO` 行字段：
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| supplierId | Long(String) | 供应商 ID（雪花 ID，JSON 序列化为字符串） |
+| supplierNo | String | 供应商业务编码，创建草稿时按 `SUP{supplierId}` 生成且全生命周期不变 |
+| fullName | String | 供应商法定全称 |
+| shortName | String | 供应商业务简称 |
+| types | Array | 供应商类型列表：`{ typeCode, typeName, isPrimary }` |
+| status | String | 当前生命周期状态（枚举值见 §6） |
+| statusName | String | 当前对外展示状态；企微审批在途时统一为「审核中」 |
+| creditLevel | String | 当前信用等级 |
+| totalScore | BigDecimal | 当前综合评分 |
+| activeAccountCount | Integer | 未删除且状态为 ACTIVE 的收款账户数量 |
+| **contactPhone** | **String** | **本次新增：公司联系电话完整原值（不脱敏），仅供管理后台授权场景展示；明文优先取值，无明文时回退历史密文解密值，可为 null** |
+| createTime | LocalDateTime | 供应商创建时间 |
+| updateTime | LocalDateTime | 供应商当前并发版本（乐观锁用） |
+
+> `balance` 曾随本 PR 短暂加入，已被 #7291 移除，**当前响应不含 `balance`**。
+
+## 6. 枚举 / 数据字典
+
+`status`（供应商生命周期状态）：
+
+| 值 | 含义 |
+|---|---|
+| DRAFT | 草稿 |
+| VETTING | 审核中 |
+| ACTIVE | 正常合作 |
+| SUSPENDED | 暂停合作 |
+| BLACKLIST | 黑名单 |
+| ARCHIVED | 已归档 |
+
+`creditLevel`：`A` / `B` / `C` / `D`。`typeCode` 走供应商类型数据字典。
+
+## 7. 错误码
+
+无新增错误码。沿用现有通用错误：
+
+| 码 | 含义 | 触发场景 |
+|---|---|---|
+| 401 | 未登录或登录已过期 | 未携带 / 过期 JWT |
+| 400 | 参数校验失败 | 如 `供应商状态不合法`、`搜索关键字长度不能超过500`、`limit最大为200` 等 |
+
+## 8. 示例
+
+### 8.1 典型成功（分页）
+
+```http
+GET /admin/supplier/items/page?pageNo=1&pageSize=10&status=ACTIVE
+```
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": {
+    "records": [
+      {
+        "supplierId": "2084636804090089473",
+        "supplierNo": "SUP2084636804090089473",
+        "fullName": "示例供应商有限公司",
+        "shortName": "示例供应商",
+        "types": [{"typeCode": "SCENIC", "typeName": "景区", "isPrimary": true}],
+        "status": "ACTIVE",
+        "statusName": "正常合作",
+        "creditLevel": "A",
+        "totalScore": 92.50,
+        "activeAccountCount": 1,
+        "contactPhone": "0471-1234567",
+        "createTime": "2026-08-01 10:00:00",
+        "updateTime": "2026-09-06 18:00:00"
+      }
+    ],
+    "total": 1,
+    "page": 1,
+    "pageSize": 10
+  },
+  "success": true
+}
+```
+
+### 8.2 边界（有界列表 + 电话为空）
+
+```http
+GET /admin/supplier/items/list?limit=50
+```
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "data": [
+    {
+      "supplierId": "2084636804090089473",
+      "supplierNo": "SUP2084636804090089473",
+      "fullName": "示例供应商有限公司",
+      "shortName": null,
+      "types": [],
+      "status": "DRAFT",
+      "statusName": "草稿",
+      "creditLevel": null,
+      "totalScore": null,
+      "activeAccountCount": 0,
+      "contactPhone": null,
+      "createTime": "2026-09-06 17:00:00",
+      "updateTime": "2026-09-06 17:00:00"
+    }
+  ],
+  "success": true
+}
+```
+
+供应商未填写公司联系电话时 `contactPhone` 为 `null`，前端选择器按空值兜底展示。
+
+### 8.3 业务失败（未认证）
+
+```http
+GET /admin/supplier/items/page?pageNo=1&pageSize=10   # 不带 JWT
+```
+
+```json
+{"code": 401, "message": "未登录或登录已过期", "data": null, "success": false}
+```
+
+## 9. 业务边界
+
+- 适用：管理后台供应商列表页、财务域弹窗选供应商（应付款 / 业务外收支 / 往来账 / 收票）。
+- 不适用：小程序端（`/mp/*` 无此接口）；对外展示场景禁止直接透出 `contactPhone` 原值。
+- `contactPhone` 是公司联系电话（非联系人手机号），完整原值不脱敏，仅限管理后台授权角色可见；Service 层已做角色与列表权限校验。
+- 弹窗选供应商推荐用 `/page`（分页搜索形态）；`/list` 最多返回 200 条，适合小数据集选择器。
+
+## 10. 修改前后对比
+
+| 项 | 修改前 | 修改后（当前线上，含 #7291 后续清理） |
+|---|---|---|
+| 出参字段 | 无 `contactPhone`、无 `balance` | 新增 `contactPhone`（`balance` 已于 #7291 移除，不含） |
+| 入参 | — | 不变 |
+| 行为 | 财务弹窗选供应商看不到联系电话 | 可直接展示联系电话，无需再调详情接口 |
+
+## 11. 影响评估 / 回滚
+
+- **是否破坏向后兼容**：否。仅新增字段，旧前端不读 `contactPhone` 不受影响。
+- **前端是否必须同步上线**：否。财务域弹窗需要联系电话时才接入。
+- **回滚方案**：后端回退 PR #7202 对应提交即恢复无 `contactPhone` 的旧响应；前端已接入时同步摘除列展示即可。
+
+## 12. 注意事项
+
+- **不要消费 `balance`**：本 PR 曾短暂引入，已由 #7291（2026-09-07）移除，以同目录 `07_7291_供应商与结算信息移除历史字段-修改接口-管理后台.md` 为准。
+- `supplierId` 为雪花 ID，JSON 中是字符串，前端按字符串处理避免精度丢失。
+- `contactPhone` 明文原值属于敏感信息，仅限管理后台授权场景展示，禁止外传到 C 端或日志。
+
+## 13. 关联 / 联系人
+
+- Issue：https://git.1814.love:8443/wx/HL/issues/7199
+- PR：https://git.1814.love:8443/wx/HL/pulls/7202
+- Commit：https://git.1814.love:8443/wx/HL/commit/8ff8a2462801c81400a25d0c8046cd401ac75ff6
+- 后续移除 balance 的 PR：https://git.1814.love:8443/wx/HL/pulls/7291
+- 后端负责人：腰苏图（yst）