供应商企微在途状态统一审核中（#7069）

2026-09-04 12:55:57 +08:00
@@ -0,0 +1,514 @@
+---
+schema: "hl-changelog/v2"
+ticket: "7069"
+title: "供应商企微在途状态统一审核中"
+consumer: "admin"
+author: "lc(GIT)"
+change_type: "修改接口"
+backend_status: "deployed"
+gateway_status: "verified"
+frontend_status: "pending"
+frontend_owner: ""
+frontend_ref: ""
+target_release: ""
+verified_at: "2026-09-04"
+status_note: "后端已部署并通过 TEST；前端需统一展示 statusName。"
+updated_at: "2026-09-04"
+base: "dev-v3"
+---
+
+# 供应商模块：企微在途状态统一显示“审核中”
+
+> **服务**: `hl-resource-service`
+> **Issue**: #7069
+> **PR**: #7072
+> **影响范围**: 管理后台供应商列表、详情和状态动作结果
+
+## ⚠️ 关键变化
+
+前端统一展示新增的 `statusName`：已提交企业微信且仍在审批中的供应商显示“审核中”，不再把来源生命周期状态作为展示文案；原 `status` 字段继续用于筛选和业务判断。
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|---|---|---|---|---|
+| 1 | 供应商分页 | GET | `/admin/supplier/items/page` | 响应新增字段 | 每行新增 `statusName` |
+| 2 | 供应商有界列表 | GET | `/admin/supplier/items/list` | 响应新增字段 | 每行新增 `statusName` |
+| 3 | 供应商基本信息 | GET | `/admin/supplier/items/{supplierId}/basic-info/view` | 响应新增字段 | 详情新增 `statusName` |
+| 4 | 暂停合作 | POST | `/admin/supplier/items/{supplierId}/suspend` | 响应新增字段 | 返回 `statusName=暂停合作` |
+| 5 | 列入黑名单 | POST | `/admin/supplier/items/{supplierId}/blacklist` | 响应新增字段 | 企微在途返回 `statusName=审核中` |
+| 6 | 恢复合作 | POST | `/admin/supplier/items/{supplierId}/resume` | 响应新增字段 | 返回 `statusName=合作中` |
+| 7 | 解除黑名单 | POST | `/admin/supplier/items/{supplierId}/unblacklist` | 响应新增字段 | 企微在途返回 `statusName=审核中` |
+| 8 | 清账归档 | POST | `/admin/supplier/items/{supplierId}/archive` | 响应新增字段 | 两类企微归档在途均返回“审核中” |
+
+## 三、接口详情
+
+### 1. 供应商分页 `GET /admin/supplier/items/page`
+
+**VO**: `SupplierPageReqVO` → `PageResult<SupplierListItemRespVO>`
+
+#### 使用场景
+
+供应商管理分页展示及按生命周期状态筛选。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|---|
+| page / pageSize | Query | Integer | 否 | `page>=1`，`1<=pageSize<=100` | 默认 1 / 20 |
+| status | Query | String | 否 | 生命周期枚举 | 仍按原 `status` 筛选 |
+| keyword / typeCode / creditLevel / creatorId | Query | String | 否 | 沿用原约束 | 其他筛选条件不变 |
+
+#### 出参 `Result<PageResult<SupplierListItemRespVO>>`
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| data.records[].status | String | 原生命周期状态码，保持不变 |
+| data.records[].statusName | String | 对外展示文案；企微审批在途为“审核中” |
+
+#### 请求示例
+
+```http
+GET /admin/supplier/items/page?page=1&pageSize=20
+```
+
+#### 响应示例
+
+```json
+{"code":200,"message":"成功","data":{"records":[{"supplierId":"2095701432631017473","status":"VETTING","statusName":"审核中"}],"total":1,"page":1,"pageSize":20},"success":true}
+```
+
+#### 空数据 / 降级响应
+
+无匹配供应商时 `data.records` 为空数组，分页元数据仍正常返回。
+
+#### 错误响应
+
+```json
+{"code":401,"message":"未登录或登录已过期","data":null,"success":false}
+```
+
+#### 业务边界
+
+- `status` 仍只接受既有生命周期状态码；“审核中”是展示文案，不作为筛选值。
+
+### 2. 供应商有界列表 `GET /admin/supplier/items/list`
+
+**VO**: `SupplierListReqVO` → `List<SupplierListItemRespVO>`
+
+#### 使用场景
+
+下拉选择及有界供应商列表展示。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|---|
+| limit | Query | Integer | 否 | 1～200 | 默认 50 |
+| status | Query | String | 否 | 生命周期枚举 | 仍按原 `status` 筛选 |
+| keyword / typeCode / resourceModule / resourceId | Query | String | 否 | 沿用原约束 | 其他筛选条件不变 |
+
+#### 出参 `Result<List<SupplierListItemRespVO>>`
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| data[].status | String | 原生命周期状态码，保持不变 |
+| data[].statusName | String | 对外展示文案；企微审批在途为“审核中” |
+
+#### 请求示例
+
+```http
+GET /admin/supplier/items/list?limit=50
+```
+
+#### 响应示例
+
+```json
+{"code":200,"message":"成功","data":[{"supplierId":"2095701432631017473","status":"VETTING","statusName":"审核中"}],"success":true}
+```
+
+#### 空数据 / 降级响应
+
+无匹配供应商时返回 `data=[]`。
+
+#### 错误响应
+
+```json
+{"code":401,"message":"未登录或登录已过期","data":null,"success":false}
+```
+
+#### 业务边界
+
+- 返回条数仍受 `limit` 限制；前端展示 `statusName`，业务判断继续使用 `status`。
+
+### 3. 供应商基本信息 `GET /admin/supplier/items/{supplierId}/basic-info/view`
+
+**VO**: `Void` → `SupplierBasicInfoRespVO`
+
+#### 使用场景
+
+供应商详情页展示当前对外状态。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|---|
+| supplierId | Path | String | 是 | 正整数 | 供应商 ID |
+
+#### 出参 `Result<SupplierBasicInfoRespVO>`
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| data.status | String | 原生命周期状态码，保持不变 |
+| data.statusName | String | 对外展示文案；企微审批在途为“审核中” |
+
+#### 请求示例
+
+```http
+GET /admin/supplier/items/2095701432631017473/basic-info/view
+```
+
+#### 响应示例
+
+```json
+{"code":200,"message":"成功","data":{"supplierId":"2095701432631017473","status":"VETTING","statusName":"审核中"},"success":true}
+```
+
+#### 空数据 / 降级响应
+
+供应商不存在时返回业务失败，不返回空成功详情。
+
+#### 错误响应
+
+```json
+{"code":395001,"message":"供应商不存在","data":null,"success":false}
+```
+
+#### 业务边界
+
+- 企微审批结束后刷新本接口，即可获得对应终态展示文案。
+
+### 4. 暂停合作 `POST /admin/supplier/items/{supplierId}/suspend`
+
+**VO**: `SupplierStatusChangeReqVO` → `SupplierStatusChangeRespVO`
+
+#### 使用场景
+
+将合作中供应商暂停合作。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|---|
+| supplierId | Path | String | 是 | 正整数 | 供应商 ID |
+| reason | Body | String | 是 | 1～500 字符 | 状态变更原因 |
+| expectedUpdateTime | Body | String | 是 | `yyyy-MM-dd HH:mm:ss` | 页面读取到的并发版本 |
+
+#### 出参 `Result<SupplierStatusChangeRespVO>`
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| data.status | String | `SUSPENDED` |
+| data.statusName | String | “暂停合作” |
+
+#### 请求示例
+
+```json
+{"reason":"暂停合作","expectedUpdateTime":"2026-09-04 10:00:00"}
+```
+
+#### 响应示例
+
+```json
+{"code":200,"message":"成功","data":{"supplierId":"2095000000000000001","status":"SUSPENDED","statusName":"暂停合作"},"success":true}
+```
+
+#### 空数据 / 降级响应
+
+写接口不返回空成功数据；执行失败时状态不变。
+
+#### 错误响应
+
+```json
+{"code":395014,"message":"数据已被他人修改，请刷新后重试","data":null,"success":false}
+```
+
+#### 业务边界
+
+- 权限、允许状态、并发版本及幂等规则均保持不变。
+
+### 5. 列入黑名单 `POST /admin/supplier/items/{supplierId}/blacklist`
+
+**VO**: `SupplierStatusChangeReqVO` → `SupplierStatusChangeRespVO`
+
+#### 使用场景
+
+对暂停合作供应商发起列入黑名单企微审批。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|---|
+| supplierId | Path | String | 是 | 正整数 | 供应商 ID |
+| reason | Body | String | 是 | 1～500 字符 | 列入黑名单原因 |
+| expectedUpdateTime | Body | String | 是 | `yyyy-MM-dd HH:mm:ss` | 页面读取到的并发版本 |
+
+#### 出参 `Result<SupplierStatusChangeRespVO>`
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| data.status | String | 审批中仍为 `SUSPENDED` |
+| data.statusName | String | 审批中为“审核中” |
+| data.approval.approvalStatus | String | 审批中为 `PENDING` |
+
+#### 请求示例
+
+```json
+{"reason":"严重违约","expectedUpdateTime":"2026-09-04 10:00:00"}
+```
+
+#### 响应示例
+
+```json
+{"code":200,"message":"成功","data":{"supplierId":"2095000000000000002","status":"SUSPENDED","statusName":"审核中","approval":{"provider":"WECOM","approvalStatus":"PENDING","spNo":"202609040001"}},"success":true}
+```
+
+#### 空数据 / 降级响应
+
+写接口不返回空成功数据；企微提交失败时保持暂停合作。
+
+#### 错误响应
+
+```json
+{"code":395005,"message":"当前状态不允许执行该操作","data":null,"success":false}
+```
+
+#### 业务边界
+
+- 审批通过后刷新查询接口显示“黑名单”，驳回后显示“暂停合作”。
+
+### 6. 恢复合作 `POST /admin/supplier/items/{supplierId}/resume`
+
+**VO**: `SupplierStatusChangeReqVO` → `SupplierStatusChangeRespVO`
+
+#### 使用场景
+
+将暂停合作供应商恢复合作。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|---|
+| supplierId | Path | String | 是 | 正整数 | 供应商 ID |
+| reason | Body | String | 是 | 1～500 字符 | 状态变更原因 |
+| expectedUpdateTime | Body | String | 是 | `yyyy-MM-dd HH:mm:ss` | 页面读取到的并发版本 |
+
+#### 出参 `Result<SupplierStatusChangeRespVO>`
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| data.status | String | `ACTIVE` |
+| data.statusName | String | “合作中” |
+
+#### 请求示例
+
+```json
+{"reason":"恢复合作","expectedUpdateTime":"2026-09-04 10:00:00"}
+```
+
+#### 响应示例
+
+```json
+{"code":200,"message":"成功","data":{"supplierId":"2095000000000000003","status":"ACTIVE","statusName":"合作中"},"success":true}
+```
+
+#### 空数据 / 降级响应
+
+写接口不返回空成功数据；执行失败时状态不变。
+
+#### 错误响应
+
+```json
+{"code":395014,"message":"数据已被他人修改，请刷新后重试","data":null,"success":false}
+```
+
+#### 业务边界
+
+- 权限、允许状态、并发版本及幂等规则均保持不变。
+
+### 7. 解除黑名单 `POST /admin/supplier/items/{supplierId}/unblacklist`
+
+**VO**: `SupplierStatusChangeReqVO` → `SupplierStatusChangeRespVO`
+
+#### 使用场景
+
+对黑名单供应商发起解除黑名单企微审批。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|---|
+| supplierId | Path | String | 是 | 正整数 | 供应商 ID |
+| reason | Body | String | 是 | 1～500 字符 | 解除原因 |
+| expectedUpdateTime | Body | String | 是 | `yyyy-MM-dd HH:mm:ss` | 页面读取到的并发版本 |
+
+#### 出参 `Result<SupplierStatusChangeRespVO>`
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| data.status | String | 审批中仍为 `BLACKLIST` |
+| data.statusName | String | 审批中为“审核中” |
+| data.approval.approvalStatus | String | 审批中为 `PENDING` |
+
+#### 请求示例
+
+```json
+{"reason":"整改完成","expectedUpdateTime":"2026-09-04 10:00:00"}
+```
+
+#### 响应示例
+
+```json
+{"code":200,"message":"成功","data":{"supplierId":"2095000000000000004","status":"BLACKLIST","statusName":"审核中","approval":{"provider":"WECOM","approvalStatus":"PENDING","spNo":"202609040002"}},"success":true}
+```
+
+#### 空数据 / 降级响应
+
+写接口不返回空成功数据；企微提交失败时保持黑名单。
+
+#### 错误响应
+
+```json
+{"code":395005,"message":"当前状态不允许执行该操作","data":null,"success":false}
+```
+
+#### 业务边界
+
+- 审批通过后刷新查询接口显示“暂停合作”，驳回后显示“黑名单”。
+
+### 8. 清账归档 `POST /admin/supplier/items/{supplierId}/archive`
+
+**VO**: `Void` → `SupplierArchiveRespVO`
+
+#### 使用场景
+
+暂停合作供应商发起“终止且账清”，或黑名单供应商发起“拉黑且账清”企微审批。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|---|
+| supplierId | Path | String | 是 | 正整数 | 供应商 ID |
+
+#### 出参 `Result<SupplierArchiveRespVO>`
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| data.status | String | 审批中保持 `SUSPENDED` 或 `BLACKLIST` |
+| data.statusName | String | 两类审批在途均为“审核中” |
+| data.approval.approvalStatus | String | 审批中为 `PENDING` |
+
+#### 请求示例
+
+```http
+POST /admin/supplier/items/2095000000000000005/archive
+```
+
+#### 响应示例
+
+```json
+{"code":200,"message":"成功","data":{"supplierId":"2095000000000000005","status":"SUSPENDED","statusName":"审核中","approval":{"provider":"WECOM","approvalStatus":"PENDING","spNo":"202609040003"}},"success":true}
+```
+
+#### 空数据 / 降级响应
+
+写接口不返回空成功数据；企微提交失败时保持来源状态。
+
+#### 错误响应
+
+```json
+{"code":395021,"message":"企业微信申请提交失败，请稍后重试","data":null,"success":false}
+```
+
+#### 业务边界
+
+- 两类审批通过后刷新查询接口均显示“已归档”；驳回后分别显示“暂停合作”或“黑名单”。
+
+## 四、契约约束与正确调用方式
+
+- 请求参数、鉴权、权限、幂等和错误码均不变。
+- `status` 是生命周期状态码，继续用于筛选、按钮门禁和业务判断；`statusName` 是中文展示值。
+- 状态动作成功后先使用响应中的 `statusName`，后续刷新分页、列表或详情获取审批终态。
+
+## 五、数据库行为
+
+本次不修改数据结构和状态迁移规则；写接口原有业务写入、失败零写入及并发规则不变，仅在响应中增加展示字段。
+
+## 六、边界行为
+
+- 注册审批中：`status=VETTING`，`statusName=审核中`。
+- 企业微信状态审批仅在 `provider=WECOM`、`approvalStatus=PENDING` 且已有审批单号时覆盖展示为“审核中”。
+- 审批结束后按当前生命周期状态展示，不继续显示“审核中”。
+- 未登录时统一返回业务码 `401`；其他错误码保持不变。
+
+## 六.5、枚举 / 数据字典
+
+| 原状态或审批条件 | `statusName` |
+|---|---|
+| 注册审批中 `VETTING` | 审核中 |
+| 企微状态审批在途 | 审核中 |
+| `DRAFT` | 草稿 |
+| `ACTIVE` | 合作中 |
+| `SUSPENDED` 且无在途审批 | 暂停合作 |
+| `BLACKLIST` 且无在途审批 | 黑名单 |
+| `ARCHIVED` | 已归档 |
+
+## 六.6、修改前后对比
+
+### 字段级对比
+
+| 字段 | 改前 | 改后 |
+|---|---|---|
+| `statusName` | 不返回 | 列表、详情及五个状态动作响应返回中文展示值 |
+| `status` | 生命周期状态码 | 保持不变 |
+
+### 行为级对比
+
+| 行为 | 改前 | 改后 |
+|---|---|---|
+| 企微审批在途展示 | 可能继续显示来源状态 | 统一显示“审核中” |
+| 审批完成展示 | 读取生命周期状态 | 保持按最终生命周期状态展示 |
+
+## 六.7、影响评估
+
+- **是否破坏向后兼容**: 否，响应仅新增字段，原 `status` 保留。
+- **前端是否必须同步上线**: 是，需改为展示 `statusName`。
+- **前端 workaround 清理点**: 删除前端自行翻译 `status` 作为展示文案的逻辑。
+
+## 七、不影响范围
+
+- **仅影响**: 管理后台供应商状态文案展示。
+- **零影响**: 生命周期状态机、审批通过或驳回迁移、请求参数、权限、数据库结构、配置、Redis 和 MQ。
+
+## 八、测试环境已验证
+
+- 分页、列表和详情均返回 `statusName`；注册审批中返回“审核中”，稳定态分别返回草稿、合作中、暂停合作、黑名单和已归档。
+- 四类企微状态审批的完成态与来源状态一致；未登录请求返回业务码 `401`。
+
+## 十、相关文档
+
+- [Issue #7069](https://git.1814.love:8443/wx/HL/issues/7069)
+- [PR #7072](https://git.1814.love:8443/wx/HL/pulls/7072)
+
+## 前端动作与当前状态
+
+- 列表、详情和动作结果统一展示 `statusName`；保留 `status` 做筛选和按钮门禁。
+- 状态动作后刷新列表或详情，以最新 `statusName` 展示审批终态。
+- **当前状态：待前端适配。**
+
+## 关联 / 联系人
+
+- **Issue**: [#7069](https://git.1814.love:8443/wx/HL/issues/7069)
+- **PR**: [#7072](https://git.1814.love:8443/wx/HL/pulls/7072)
+- **Merge commit**: [c95f1de495d4bcdd8579ccd1f0c895deca29e14a](https://git.1814.love:8443/wx/HL/commit/c95f1de495d4bcdd8579ccd1f0c895deca29e14a)
+- **后端负责人**: @lc