---
schema: "hl-changelog/v2"
ticket: "7487"
title: "供应商撤销在途审批失败显式提示"
consumer: "admin"
author: "wx(GIT)"
change_type: "修改接口"
backend_status: "deployed"
gateway_status: "verified"
frontend_status: "not_required"
frontend_owner: ""
frontend_ref: ""
target_release: ""
verified_at: ""
status_note: "PR #7630 已合并 dev-v3，TEST 部署 merge 83626f88f；真实 Gateway 验证 HTTP 200 + 业务码 395029，失败不改本地状态。前端实证 not_required（2026-09-13, mmg）：撤销端点当前零调用，若将来接入则由 request.js 统一透后端 message。#7633 / PR #7634 补充：395029 的 message 现在会带出具体原因；前端若对该码硬编码了文案需同步，否则会覆盖后端可执行指引。TEST 任务分支 9c70e86c6 已验证完整指引。"
updated_at: "2026-09-13"
base: "dev-v3"
---

# 供应商撤销在途审批失败显式提示

供应商管理端撤销在途企微注册审批时，不再把企微未生效误报为成功。#7633 进一步保留 user-service 返回的可执行原因。接口结构、HTTP 状态和 Feign 签名不变；调用方必须读取 `Result.code`，并直接展示后端 `message`。

> **服务**: `hl-resource-service`、`hl-user-service`
> **PR**: [#7630](https://git.1814.love:8443/wx/HL/pulls/7630)
> **Issue**: [#7487](https://git.1814.love:8443/wx/HL/issues/7487)
> **Merge commit**: [`83626f88f`](https://git.1814.love:8443/wx/HL/commit/83626f88f18cd3bfce21f462d9aaaad5b375d32f)
> **Follow-up**: [Issue #7633](https://git.1814.love:8443/wx/HL/issues/7633) / [PR #7634](https://git.1814.love:8443/wx/HL/pulls/7634)

## ⚠️ 关键变化

- 企微未生效时，管理端撤销返回业务码 `395029`；#7633 起 `message` 会带出具体原因，例如「企业微信撤销下发失败：企业微信暂不支持接口撤销审批，请申请人在企业微信中撤销该审批单，撤销后系统会自动将供应商退回草稿」。
- user-service 不再请求不存在的 `/oa/approval/revoke`，改为返回明确失败和申请人操作指引。
- `AUTO-*`、空单号与企微未配置路径保持原行为。
- 企业微信没有服务端撤销 API；申请人需在企微客户端撤销，既有回调/轮询收到 `spStatus=4` 后自动退回 `DRAFT`。

## 二、变更接口清单

| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
|---|------|------|------|----------|------|
| 1 | 管理端撤销供应商注册审批 | POST | `/admin/supplier/items/{supplierId}/approval/revoke` | 返回语义修改 | 撤销未生效时返回业务错误 `395029`，不写本地成功态 |

统一响应仍为 `Result<T>`。HTTP 仍为 200；前端与 Feign 消费方必须判断业务字段 `code` / `success`。

## 三、接口详情

### 1. 管理端撤销供应商注册审批 `POST /admin/supplier/items/{supplierId}/approval/revoke`

**VO**: `无请求 VO → Result<Void>`

#### 使用场景

管理端供应商详情在供应商处于 `VETTING`、且存在企微在途注册审批时调用，用于请求撤销该审批。企业微信不支持服务端撤销时，本接口明确返回失败，前端引导申请人在企微客户端操作。

#### 入参

| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|------|------|------|------|------|------|
| `supplierId` | Path | Long | 是 | 正整数；供应商必须存在 | 待撤销审批的供应商 ID |
| 请求体 | Body | Object | 否 | 无业务字段 | 可发送空对象 `{}` |

#### 出参 `Result<Void>`

| 字段 | 类型 | 说明 |
|------|------|------|
| `code` | Integer | `200` 表示下发成功；`395029` 表示企微撤销未生效 |
| `message` | String | 成功文案；或「企业微信撤销下发失败」加具体原因。传输异常固定为「企业微信撤销下发失败，请稍后重试」 |
| `data` | Void | 固定为 `null` |
| `success` | Boolean | 仅 `code=200` 时为 `true` |

#### 请求示例

```json
{}
```

#### 响应示例

下发成功时：

```json
{
  "code": 200,
  "message": "成功",
  "data": null,
  "success": true
}
```

#### 空数据 / 降级响应

本接口没有列表或空对象降级语义。user-service 返回空 `Result`、业务非 200 或 Feign 传输异常时，统一升级为 `395029`；不得降级成成功。

```json
{ "code": 395029, "message": "企业微信撤销下发失败，请稍后重试", "data": null, "success": false }
```

#### 错误响应

```json
{
  "code": 395029,
  "message": "企业微信撤销下发失败：企业微信暂不支持接口撤销审批，请申请人在企业微信中撤销该审批单，撤销后系统会自动将供应商退回草稿",
  "data": null,
  "traceId": null,
  "success": false
}
```

#### 业务边界

- 需要已登录管理端身份和供应商更新/提交权限；未登录由 Gateway 返回 401。
- 仅 `VETTING` 且存在 `PROFILE_CREATE + WECOM + PENDING` 在途记录可调用；供应商不存在、状态不符或无在途记录时返回既有业务错误。
- 本次调用不直接把供应商改为 `DRAFT`；真实撤销终态仅由企微 `spStatus=4` 回调/轮询统一收口。
- 企微撤销未生效、空响应或传输异常均返回 `395029`，并保证 `supplier_main` 与 `supplier_approval_log` 零写入。
- HTTP 仍为 200，调用方必须判断 `Result.code` / `success`；重复失败重试不会伪造本地成功态。

## 四、契约约束与正确调用方式

调用方必须同时判断 HTTP 状态与 `Result.code` / `success`；本接口的业务失败仍使用 HTTP 200。

### 错误码与前端处理

| code | message | 触发条件 | 管理端处理 |
|---|---|---|---|
| `395029` | `企业微信撤销下发失败：<具体原因>`；传输异常为 `企业微信撤销下发失败，请稍后重试` | resource 调用 user 得到非 200、空响应或传输异常 | 直接展示后端 `message`；不得硬编码覆盖具体原因，不得提示撤销成功 |

管理端建议同时展示在途审批单号；客户端撤销后等待回调/轮询自动退回草稿。

### 契约与兼容性

- Controller mapping、HTTP method、path 参数、`Result<Void>`、Feign 方法签名均未变化。
- 无 DTO / VO 字段增删，无共享 `hl-common` 契约修改。
- 这是内部 Feign 的行为语义变更；producer 与 resource consumer 定向测试均已执行。
- Swagger 2 未配置 `oasdiff`，本单没有 OpenAPI 结构变化。
- 未配置 Spring Cloud Contract；以 producer/consumer 源码审查、定向测试、全量测试和 TEST 实请求作为回退证据。
- `hl-product-service-v2` 现有调用仍忽略 `Result<Void>` 并可能记录「审批已撤销」；按 #7487 范围只记录风险、不修改，由 `wx` 决定是否另立工单。

## 五、数据库行为

- 撤销下发失败时禁止修改 `supplier_main` 和 `supplier_approval_log`。
- TEST 隔离夹具实测：调用前后供应商保持 `VETTING`，审批保持 `PENDING/NOT_APPLIED`，时间戳未变。
- 本单无 DDL、无生产数据操作；TEST 临时夹具按批准 manifest 精确清理为 0 残留。

## 六、边界行为

- 空 `spNo` 仍返回 400；`AUTO-*` 仍成功且不调用企微；企微未配置仍返回原 500。
- 仅真实企微单撤销未生效路径由静默成功改为明确失败。
- 用户在企微客户端撤销后的 `spStatus=4` 回调/轮询收口不变。

## 六.6、修改前后对比

| 行为 | 修改前 | 修改后 |
|---|---|---|
| user-service 实际企微撤销失败 | `Result.code=200` | `Result.code=500` + 申请人操作指引 |
| resource-service 收到非 200 / 空响应 / 传输异常 | 非 200 仅日志、异常误用 395021 | 统一抛业务码 `395029`；非空安全原因透传，空响应/传输异常使用固定重试文案 |
| 本地状态 | 不应修改 | 仍不修改，并有 DB 前后证据 |

## 六.7、影响评估

- 管理端 supplier revoke → resource-service → user-service 的失败结果及可执行原因均不再丢失。
- 撤销失败不会修改本地供应商或审批状态。
- 新码不进入 `SUPPLIER_WECOM_SUBMIT_FAILED(395021)` 的恢复逻辑；其余提交路径和文案未改。
- 前端需要按业务码处理 `395029`，不可只看 HTTP 200；`message` 现在会带出具体原因，若对该码硬编码了文案需同步。

## 七、不影响范围

- 不修改 `hl-common/**`、`hl-product-service-v2`、order-v3、house、groupbatch 或 `GroupVehicle*`。
- 不修改企微回调/轮询和 `spStatus=4` 的既有退回草稿收口。
- 不修改空 `spNo`、`AUTO-*`、企微未配置或真实成功路径。
- 不涉及生产部署或生产数据库。

## 八、测试环境已验证

- user producer/client：77 tests；resource consumer：6 tests；product-v2 回归：35 tests；全部 0 failures/errors。
- `mvn -o -pl hl-user-service -am test`：3990 tests，0 failures/errors。
- `mvn -o -pl hl-resource-service -am test`：2902 tests，0 failures/errors。
- TEST：resource/user 均为 `dev-v3@83626f88f`、`BEHIND=0`、`STATE=ok`。
- Gateway：HTTP 200 + `code=395029`；前后 SELECT 证明状态未变。
- 隔离夹具按 `hl-data-cleanup/v1` manifest 创建并精确清理，最终 0 残留。
- Gateway jar mtime 后 `git log origin/dev-v3 -- hl-gateway` 无提交，无需重部署。

### #7633 跟进验证

- resource 定向 6 tests、user 撤销两组定向 16 tests；resource 全量 2902 tests、user 全量 4004 tests，全部 0 failures/errors。
- TEST 取证前人工确认 resource/user 均为 `fix/7633-supplier-revoke-guidance@9c70e86c6`、`BEHIND` 右侧 `N`、`STATE=ok`；`hl-gateway` 行也为右侧 `N`、`STATE=ok`。
- Gateway 真实响应：HTTP 200、`code=395029`、`message=企业微信撤销下发失败：企业微信暂不支持接口撤销审批，请申请人在企业微信中撤销该审批单，撤销后系统会自动将供应商退回草稿`。
- 失败后隔离 fixture 仍为 `VETTING / PENDING / NOT_APPLIED`；已按批准 manifest 精确清理为 0 残留。

### 前端验收建议

1. `VETTING` 且有在途企微单时点击撤销。
2. 收到 HTTP 200、`code=395029` 时展示错误，不得 toast 撤销成功。
3. 提示申请人到企微客户端撤销，并说明回调/轮询会自动退回草稿。
4. `AUTO-*` 仍按成功处理。

## 十、相关文档

- Issue [#7487](https://git.1814.love:8443/wx/HL/issues/7487)
- PR [#7630](https://git.1814.love:8443/wx/HL/pulls/7630)
- Follow-up Issue [#7633](https://git.1814.love:8443/wx/HL/issues/7633)
- Follow-up PR [#7634](https://git.1814.love:8443/wx/HL/pulls/7634)

## 关联 / 联系人

- 后端负责人：@wx
- 前端负责人：@mmg