diff --git a/changelogs-v2/2026-09/06_7199_供应商分页出参补字段-修改接口-管理后台.md b/changelogs-v2/2026-09/06_7199_供应商分页出参补字段-修改接口-管理后台.md new file mode 100644 index 00000000..c2c4d2e8 --- /dev/null +++ b/changelogs-v2/2026-09/06_7199_供应商分页出参补字段-修改接口-管理后台.md @@ -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`：`{ 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）