134 行
5.6 KiB
Markdown
134 行
5.6 KiB
Markdown
---
|
||
schema: "hl-changelog/v2"
|
||
ticket: "7148"
|
||
title: "供应商账户停用审批及审批结果状态调整"
|
||
consumer: "admin"
|
||
author: "lc(GIT)"
|
||
change_type: "新增接口"
|
||
backend_status: "deployed"
|
||
gateway_status: "verified"
|
||
frontend_status: "verified"
|
||
frontend_owner: "mmg"
|
||
frontend_ref: "7245780a"
|
||
target_release: ""
|
||
verified_at: "2026-09-06"
|
||
status_note: "后端已部署并通过 TEST；前端待接入停用审批入口与状态刷新"
|
||
updated_at: "2026-09-06"
|
||
base: "dev-v3"
|
||
---
|
||
|
||
# 供应商：账户停用审批及审批结果状态调整
|
||
|
||
## 关键变化
|
||
|
||
停用审批通过后账户停用、驳回后启用；原账户新增审批通过后启用、驳回后改为停用。审批状态与账户状态分别展示。
|
||
|
||
## 二、变更接口清单
|
||
|
||
| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
|
||
|---|---|---|---|---|---|
|
||
| 1 | 申请账户停用 | POST | `/admin/supplier/bank-accounts/{accountId}/disable` | 新增接口 | 复用现有账户审批模板与表单 |
|
||
|
||
## 三、接口详情
|
||
|
||
### 1. 申请账户停用 `POST /admin/supplier/bank-accounts/{accountId}/disable`
|
||
|
||
**VO**: `SupplierAccountDisableReqVO / BankAccountSubmitResultRespVO`
|
||
|
||
#### 使用场景
|
||
|
||
供应商账户页面对非默认启用账户提交停用申请。
|
||
|
||
#### 入参
|
||
|
||
| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|
||
|---|---|---|---|---|---|
|
||
| accountId | Path | String | 是 | 正整数 | 目标账户 ID |
|
||
| expectedUpdateTime | Body | String | 是 | `yyyy-MM-dd HH:mm:ss` | 账户详情返回的 updateTime |
|
||
|
||
#### 出参 `Result<BankAccountSubmitResultVO>`
|
||
|
||
| 字段 | 类型 | 说明 |
|
||
|---|---|---|
|
||
| accountId / approvalLogId | String | 账户 / 本次审批记录 ID |
|
||
| requestNo | String | 同次申请重试时不变 |
|
||
| provider | String | 新停用申请为 WECOM |
|
||
| approvalStatus / approvalStatusName | String | 审批状态 / 中文名称 |
|
||
| spNo / spStatus | String 或 null | 企微单号 / 企微原始状态，尚未取得时为 null |
|
||
| syncStatus | String | REQUESTING 待同步、APPLIED 已应用、APPLY_FAILED 应用失败、RESULT_UNCERTAIN 待对账 |
|
||
| accountStatus | String | 当前账户状态 |
|
||
| isDefault | String | NO 非默认；历史申请重试返回当前默认标记 |
|
||
| submittedAt / finishedAt | String 或 null | 提交 / 审批完成时间，尚未发生时为 null |
|
||
|
||
#### 请求示例
|
||
|
||
`POST /admin/supplier/bank-accounts/7148001/disable`，携带正常管理端登录认证。
|
||
|
||
```json
|
||
{"expectedUpdateTime":"2026-09-06 12:00:00"}
|
||
```
|
||
|
||
#### 响应示例
|
||
|
||
```json
|
||
{"code":200,"message":"成功","success":true,"data":{"accountId":"7148001","approvalLogId":"7148002","requestNo":"SUP-ACC-DISABLE-example","provider":"WECOM","approvalStatus":"PENDING","approvalStatusName":"审核中","spNo":"202609060001","spStatus":null,"syncStatus":"REQUESTING","accountStatus":"ACTIVE","isDefault":"NO","submittedAt":"2026-09-06 12:01:00","finishedAt":null}}
|
||
```
|
||
|
||
#### 错误响应
|
||
|
||
```json
|
||
{"code":395014,"message":"数据已被他人修改，请刷新后重试","success":false,"data":null}
|
||
```
|
||
|
||
#### 空数据 / 降级响应
|
||
|
||
不存在返回 395001；外部提交失败时可能返回已保留的审批与 `APPLY_FAILED` 或 `RESULT_UNCERTAIN`，不会把账户直接停用。
|
||
|
||
#### 业务边界
|
||
|
||
- 仅 SUPER_ADMIN 且具备 `supplier:account:manage`、`supplier:approval:submit` 可提交。主体须启用、账户须启用且非默认，主体与账户均不能有在途审批。门禁失败不新建申请；企微失败可能保留申请，须同时检查 `syncStatus`，不能把 `code=200` 当作已停用。
|
||
|
||
## 四、契约约束与正确调用方式
|
||
|
||
从最新账户详情取版本；同次失败重试复用原版本。已结束申请后重新申请须刷新版本。`RESULT_UNCERTAIN` 停止自动重提并等待对账；`APPLY_FAILED` 沿用原申请重试。默认账户须先切换默认。前端新增停用动作并在提交后刷新账户和审批状态。
|
||
|
||
## 五、数据库行为
|
||
|
||
审批中账户保持启用；只有停用审批通过才转为停用。驳回或撤销保留启用，重复请求不重复应用结果。
|
||
|
||
## 六、边界行为
|
||
|
||
未登录由网关拒绝；400 参数无效；395001 账户不存在；395004 无权限；395005 账户状态或默认标记不允许；395010 主体未启用；395011 账户已有在途审批；395014 版本过期。主体审批冻结返回 395005。
|
||
|
||
## 六.5、枚举 / 数据字典
|
||
|
||
### accountStatus（账户状态）
|
||
|
||
| 值 | 中文 | 说明 |
|
||
|---|---|---|
|
||
| ACTIVE | 启用 | 停用待审或驳回后保持可用 |
|
||
| DISABLED | 停用 | 停用通过或新账户审批驳回 |
|
||
| PENDING | 待审批 | 原新账户审批未结束 |
|
||
| REJECTED | 驳回 | 仅兼容历史账户记录 |
|
||
|
||
### approvalStatus（审批状态）
|
||
|
||
PENDING 审核中；APPROVED 已通过；REJECTED 已驳回；CANCELED 已撤销。终态重试返回账户当前状态，不据旧审批推导账户状态。
|
||
|
||
## 七、不影响范围
|
||
|
||
本单涉及供应商账户停用入口和审批结果状态；已有账户请求、查询返回结构保持兼容。
|
||
|
||
## 八、测试环境已验证
|
||
|
||
真实企微审批已验证：新增账户通过后为 `ACTIVE`、驳回后为 `DISABLED`；停用审批待审期间保持 `ACTIVE`，驳回后仍为 `ACTIVE`，通过后为 `DISABLED`。同版本重试复用原审批单；未登录、缺参、非法账户 ID、旧版本、在途审批和状态不允许均按契约拒绝，失败请求未新增审批或改写账户。测试账户最终均为非默认 `DISABLED`，原默认账户未变化。
|
||
|
||
## 十、相关文档
|
||
|
||
- **Issue**：[#7148](https://git.1814.love:8443/wx/HL/issues/7148)
|
||
- **PR**：[#7161](https://git.1814.love:8443/wx/HL/pulls/7161)
|
||
|
||
## 关联 / 联系人
|
||
|
||
- **后端负责人**：@lc
|