diff --git a/changelogs-v2/2026-09/04_7069_供应商企微在途状态统一审核中-修改接口-管理后台.md b/changelogs-v2/2026-09/04_7069_供应商企微在途状态统一审核中-修改接口-管理后台.md new file mode 100644 index 00000000..8b549a6e --- /dev/null +++ b/changelogs-v2/2026-09/04_7069_供应商企微在途状态统一审核中-修改接口-管理后台.md @@ -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` + +#### 使用场景 + +供应商管理分页展示及按生命周期状态筛选。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|---|---|---|---|---|---| +| page / pageSize | Query | Integer | 否 | `page>=1`,`1<=pageSize<=100` | 默认 1 / 20 | +| status | Query | String | 否 | 生命周期枚举 | 仍按原 `status` 筛选 | +| keyword / typeCode / creditLevel / creatorId | Query | String | 否 | 沿用原约束 | 其他筛选条件不变 | + +#### 出参 `Result>` + +| 字段 | 类型 | 说明 | +|---|---|---| +| 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` + +#### 使用场景 + +下拉选择及有界供应商列表展示。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|---|---|---|---|---|---| +| limit | Query | Integer | 否 | 1~200 | 默认 50 | +| status | Query | String | 否 | 生命周期枚举 | 仍按原 `status` 筛选 | +| keyword / typeCode / resourceModule / resourceId | Query | String | 否 | 沿用原约束 | 其他筛选条件不变 | + +#### 出参 `Result>` + +| 字段 | 类型 | 说明 | +|---|---|---| +| 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` + +| 字段 | 类型 | 说明 | +|---|---|---| +| 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` + +| 字段 | 类型 | 说明 | +|---|---|---| +| 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` + +| 字段 | 类型 | 说明 | +|---|---|---| +| 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` + +| 字段 | 类型 | 说明 | +|---|---|---| +| 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` + +| 字段 | 类型 | 说明 | +|---|---|---| +| 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` + +| 字段 | 类型 | 说明 | +|---|---|---| +| 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