9.6 KiB
9.6 KiB
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 | 7199 | 供应商分页/列表出参补字段（联系电话） | admin | yst | 修改接口 | deployed | verified | not_required | mmg | not_required 2026-09-10 mmg：净变化仅 SupplierListItemRespVO 新增 contactPhone(balance 已被 #7291 移除勿消费)。changelog 自答非必须同步上线、需要电话时才接入;grep 实证 SupplierPickerModal 选择器列(fullName/supplierNo/types/creditLevel)未读 contactPhone,供应商列表页/财务域供应商选择弹窗均无该字段消费点。纯新增可选出参、旧前端不读不受影响。将来财务大批(应付款/业务外/往来账选供应商)需电话列时在对应模块接入,不属本条。 | 2026-09-10 | 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 典型成功（分页）
GET /admin/supplier/items/page?pageNo=1&pageSize=10&status=ACTIVE
{
"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 边界（有界列表 + 电话为空）
GET /admin/supplier/items/list?limit=50
{
"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 业务失败（未认证）
GET /admin/supplier/items/page?pageNo=1&pageSize=10 # 不带 JWT
{"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 端或日志。