diff --git a/changelogs-v2/2026-09/06_7148_供应商账户停用审批-新增接口-管理后台.md b/changelogs-v2/2026-09/06_7148_供应商账户停用审批-新增接口-管理后台.md new file mode 100644 index 00000000..3cc1a469 --- /dev/null +++ b/changelogs-v2/2026-09/06_7148_供应商账户停用审批-新增接口-管理后台.md @@ -0,0 +1,133 @@ +--- +schema: "hl-changelog/v2" +ticket: "7148" +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: "" +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` + +| 字段 | 类型 | 说明 | +|---|---|---| +| 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