--- schema: "hl-changelog/v2" ticket: "7199" title: "供应商分页/列表出参补字段（联系电话）" consumer: "admin" author: "yst" change_type: "修改接口" backend_status: "deployed" gateway_status: "verified" frontend_status: "not_required" frontend_owner: "mmg" frontend_ref: "" target_release: "" verified_at: "" status_note: "not_required 2026-09-10 mmg：净变化仅 SupplierListItemRespVO 新增 contactPhone(balance 已被 #7291 移除勿消费)。changelog 自答非必须同步上线、需要电话时才接入;grep 实证 SupplierPickerModal 选择器列(fullName/supplierNo/types/creditLevel)未读 contactPhone,供应商列表页/财务域供应商选择弹窗均无该字段消费点。纯新增可选出参、旧前端不读不受影响。将来财务大批(应付款/业务外/往来账选供应商)需电话列时在对应模块接入,不属本条。" 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`：`{ records: [], total, page, pageSize }` - `/list` 返回 `List`（数组） `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）