docs(changelog): 发布7182供应商账户审批接口

2026-09-06 19:57:03 +08:00
@@ -0,0 +1,292 @@
+---
+schema: "hl-changelog/v2"
+ticket: "7182"
+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-06"
+status_note: "后端已部署并通过 TEST；前端待接入四类账户审批操作及状态刷新"
+updated_at: "2026-09-06"
+base: "dev-v3"
+---
+
+# 供应商：账户删除、启用与新记录式修改审批
+
+## 关键变化
+
+`#7029` 中“无删除/停用入口”已过时。后端现提供删除、停用、启用和修改四类审批操作；提交成功只表示待审，企微通过后才应用账户变更。
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|---|---|---|---|---|
+| 1 | 申请停用账户 | POST | `/admin/supplier/bank-accounts/{accountId}/disable` | 权限与链路延用 | 保留现有入口，待审期间仍启用 |
+| 2 | 申请启用账户 | POST | `/admin/supplier/bank-accounts/{accountId}/enable` | 新增接口 | 待审期间仍停用 |
+| 3 | 申请删除账户 | POST | `/admin/supplier/bank-accounts/{accountId}/delete` | 新增接口 | 通过后软删除 |
+| 4 | 申请修改账户 | PUT | `/admin/supplier/bank-accounts/{accountId}/update` | 新增接口 | 新建 PENDING 记录，原账户待审期间继续生效 |
+
+## 三、接口详情
+
+### 1. 申请停用 `POST /admin/supplier/bank-accounts/{accountId}/disable`
+
+**VO**: `SupplierAccountDisableReqVO / BankAccountSubmitResultRespVO`
+
+#### 使用场景
+
+对非默认 `ACTIVE` 账户申请停用。`FINANCE` 与 `SUPER_ADMIN` 均可在具备账户维护和审批提交权限时操作。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|---|
+| accountId | Path | String | 是 | 正整数 | 目标账户 ID |
+| expectedUpdateTime | Body | String | 是 | `yyyy-MM-dd HH:mm:ss` | 最新账户详情版本 |
+
+#### 出参
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| accountId / approvalLogId | String | 账户 / 审批记录 ID |
+| requestNo / provider / spNo | String | 幂等号 / 审批提供方 / 企微单号 |
+| approvalStatus / approvalStatusName | String | 审批状态 / 中文名 |
+| syncStatus / accountStatus / isDefault | String | 同步状态 / 账户现态 / 默认标记 |
+| submittedAt / finishedAt | String/null | 提交 / 终态时间 |
+
+#### 请求示例
+
+```json
+{"expectedUpdateTime":"2026-09-06 12:00:00"}
+```
+
+#### 响应示例
+
+```json
+{"code":200,"message":"成功","success":true,"data":{"accountId":"7182001","approvalLogId":"7182002","approvalStatus":"PENDING","approvalStatusName":"审核中","spNo":"202609060001","syncStatus":"REQUESTING","accountStatus":"ACTIVE","isDefault":"NO"}}
+```
+
+#### 空数据 / 降级响应
+
+无空成功数据；账户不存在返回 `395001`。企微提交或对账异常按 `syncStatus` 返回原审批事实，不直接停用账户。
+
+#### 错误响应
+
+```json
+{"code":395005,"message":"当前状态不允许执行该操作","success":false,"data":null}
+```
+
+#### 业务边界
+
+- 仅非默认 `ACTIVE` 账户可提交；待审期间仍 `ACTIVE`，通过后才 `DISABLED`。
+- 供应商必须 `ACTIVE`，主体与账户均不能有在途审批；失败零写入。
+
+### 2. 申请启用 `POST /admin/supplier/bank-accounts/{accountId}/enable`
+
+**VO**: `SupplierAccountActionReqVO / BankAccountSubmitResultRespVO`
+
+#### 使用场景
+
+对 `DISABLED` 账户申请恢复启用。`FINANCE` 与 `SUPER_ADMIN` 均可在具备账户维护和审批提交权限时操作。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|---|
+| accountId | Path | String | 是 | 正整数 | 目标账户 ID |
+| expectedUpdateTime | Body | String | 是 | `yyyy-MM-dd HH:mm:ss` | 最新账户详情版本 |
+
+#### 出参
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| accountId / approvalLogId | String | 账户 / 审批记录 ID |
+| requestNo / provider / spNo | String | 幂等号 / 审批提供方 / 企微单号 |
+| approvalStatus / approvalStatusName | String | 审批状态 / 中文名 |
+| syncStatus / accountStatus / isDefault | String | 同步状态 / 账户现态 / 默认标记 |
+| submittedAt / finishedAt | String/null | 提交 / 终态时间 |
+
+#### 请求示例
+
+```json
+{"expectedUpdateTime":"2026-09-06 12:00:00"}
+```
+
+#### 响应示例
+
+```json
+{"code":200,"message":"成功","success":true,"data":{"accountId":"7182001","approvalLogId":"7182003","approvalStatus":"PENDING","approvalStatusName":"审核中","spNo":"202609060002","syncStatus":"REQUESTING","accountStatus":"DISABLED","isDefault":"NO"}}
+```
+
+#### 空数据 / 降级响应
+
+无空成功数据；账户不存在返回 `395001`。企微异常不会提前启用账户，调用方须按 `syncStatus` 展示待同步/待对账。
+
+#### 错误响应
+
+```json
+{"code":395011,"message":"该账户正在审批中，请勿重复提交","success":false,"data":null}
+```
+
+#### 业务边界
+
+- 仅 `DISABLED` 账户可提交；待审期间仍 `DISABLED`，通过后才 `ACTIVE`。
+- 供应商必须 `ACTIVE`，主体与账户均不能有在途审批；失败零写入。
+
+### 3. 申请删除 `POST /admin/supplier/bank-accounts/{accountId}/delete`
+
+**VO**: `SupplierAccountActionReqVO / BankAccountSubmitResultRespVO`
+
+#### 使用场景
+
+对非默认 `ACTIVE` 或 `DISABLED` 账户申请删除。`FINANCE` 与 `SUPER_ADMIN` 均可在具备账户维护和审批提交权限时操作。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|---|
+| accountId | Path | String | 是 | 正整数 | 目标账户 ID |
+| expectedUpdateTime | Body | String | 是 | `yyyy-MM-dd HH:mm:ss` | 最新账户详情版本 |
+
+#### 出参
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| accountId / approvalLogId | String | 账户 / 审批记录 ID |
+| requestNo / provider / spNo | String | 幂等号 / 审批提供方 / 企微单号 |
+| approvalStatus / approvalStatusName | String | 审批状态 / 中文名 |
+| syncStatus / accountStatus / isDefault | String | 同步状态 / 账户现态 / 默认标记 |
+| submittedAt / finishedAt | String/null | 提交 / 终态时间 |
+
+#### 请求示例
+
+```json
+{"expectedUpdateTime":"2026-09-06 12:00:00"}
+```
+
+#### 响应示例
+
+```json
+{"code":200,"message":"成功","success":true,"data":{"accountId":"7182001","approvalLogId":"7182004","approvalStatus":"PENDING","approvalStatusName":"审核中","spNo":"202609060003","syncStatus":"REQUESTING","accountStatus":"ACTIVE","isDefault":"NO"}}
+```
+
+#### 空数据 / 降级响应
+
+无空成功数据；已软删除或不存在返回 `395001`。企微异常时保留原账户，不把提交成功当作删除成功。
+
+#### 错误响应
+
+```json
+{"code":395005,"message":"当前状态不允许执行该操作","success":false,"data":null}
+```
+
+#### 业务边界
+
+- 仅非默认 `ACTIVE` 或 `DISABLED` 账户可提交；待审期间保留原状态，通过后才软删除。
+- 供应商必须 `ACTIVE`，主体与账户均不能有在途审批；失败零写入。
+
+### 4. 申请修改 `PUT /admin/supplier/bank-accounts/{accountId}/update`
+
+**VO**: `SupplierAccountUpdateReqVO / BankAccountSubmitResultRespVO`
+
+#### 使用场景
+
+对 `ACTIVE` 账户提交完整新资料。后端新建待审账户，不覆盖原记录。`FINANCE` 与 `SUPER_ADMIN` 均可在具备账户维护和审批提交权限时操作。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|---|
+| accountId | Path | String | 是 | 正整数 | 原账户 ID |
+| accountType / bankName / accountNo | Body | String | 是 | 沿用账户校验 | 新账户核心资料 |
+| bankBranch / proofFileUrls | Body | String/List | 否 | 附件最多 20 个 | 开户支行 / 证明材料 |
+| settleMode / accountPeriod | Body | String | 否 | 月结时账期必填 | 结算方式 / 账期 |
+| invoiceType / taxRate | Body | String | 否 | 开票时税率必填 | 发票类型 / 税率 |
+| expectedUpdateTime | Body | String | 是 | `yyyy-MM-dd HH:mm:ss` | 原账户最新版本 |
+
+#### 出参
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| accountId / approvalLogId | String | 新建待审账户 / 审批记录 ID |
+| requestNo / provider / spNo | String | 幂等号 / 审批提供方 / 企微单号 |
+| approvalStatus / approvalStatusName | String | 审批状态 / 中文名 |
+| syncStatus / accountStatus / isDefault | String | 同步状态 / 新账户现态 / 默认标记 |
+| submittedAt / finishedAt | String/null | 提交 / 终态时间 |
+
+#### 请求示例
+
+```json
+{"accountType":"CORPORATE","bankName":"示例银行","bankBranch":"示例支行","accountNo":"718200000002","proofFileUrls":[],"settleMode":"PREPAY","invoiceType":"NONE","expectedUpdateTime":"2026-09-06 12:00:00"}
+```
+
+#### 响应示例
+
+```json
+{"code":200,"message":"成功","success":true,"data":{"accountId":"7182010","approvalLogId":"7182011","approvalStatus":"PENDING","approvalStatusName":"审核中","spNo":"202609060004","syncStatus":"REQUESTING","accountStatus":"PENDING","isDefault":"NO"}}
+```
+
+#### 空数据 / 降级响应
+
+无空成功数据；原账户不存在返回 `395001`。企微异常时原账户保持 `ACTIVE`，已创建的新记录按同步状态对账，不覆盖原账户。
+
+#### 错误响应
+
+```json
+{"code":395027,"message":"该收款账号已被占用，请联系财务核实","success":false,"data":null}
+```
+
+#### 业务边界
+
+- 仅 `ACTIVE` 原账户可提交，新 `accountNo` 必须全局未占用；返回的 `accountId` 是新记录。
+- 待审期间原账户 `ACTIVE`、新记录 `PENDING`；通过后原账户 `DISABLED`、新记录 `ACTIVE` 并承接默认标记。
+- 驳回或撤销后原账户不变、新记录 `DISABLED`；所有门禁失败零写入。
+
+## 四、契约约束与正确调用方式
+
+1. 先读取账户详情，将最新 `updateTime` 原样传为 `expectedUpdateTime`。
+2. 提交后根据 `approvalStatus`、`syncStatus`、`accountStatus` 展示待审态，不要把 `code=200` 解释为已应用。
+3. 同账户有在途审批时禁用其他变更按钮；回调或轮询进入终态后刷新账户列表和详情。
+4. 修改成功返回的 `accountId` 指向新记录；驳回/撤销后不要用新记录覆盖原账户。
+5. 前端需移除“无删除/停用入口”的过时提示，接入四类操作的按钮、版本参数、待审展示和终态刷新。
+
+## 五、数据库行为
+
+无 DDL。四类操作复用现有账户审批表和企微回调/轮询链路；修改新建账户行，删除仅在审批通过后软删除目标行。
+
+## 六、边界行为
+
+- `401`：未登录；`400`：缺参或字段校验失败。
+- `395001`：账户/供应商不存在；`395002`：角色或权限不允许。
+- `395005`：供应商主审批中、账户状态或默认标记不允许；`395010`：供应商非 `ACTIVE`（如暂停合作）。
+- `395011` / `395028`：账户已有在途审批/变更；`395014`：版本过期；`395027`：新账号已占用。
+- `395019`–`395022`：企微配置、绑定、提交失败或结果待对账；按 `syncStatus` 处理，不要无限新建申请。
+
+## 六.5、枚举 / 数据字典
+
+- `approvalStatus`：`PENDING` 审核中，`APPROVED` 已通过，`REJECTED` 已驳回，`CANCELED` 已撤销。
+- `accountStatus`：`PENDING`、`ACTIVE`、`DISABLED`、`DELETED`；历史 `REJECTED` 仅兼容读取。
+- `syncStatus`：`REQUESTING`、`APPLIED`、`APPLY_FAILED`、`RESULT_UNCERTAIN`。
+
+## 七、不影响范围
+
+仅影响管理后台供应商账户维护。已有账户新增、查询、设为默认的路径与响应结构不变；无数据迁移、Redis、MQ 或前端源码变更。
+
+## 八、测试环境已验证
+
+TEST Gateway 已验证真实企微通过后的修改、停用、启用与删除：修改待审期间原账户继续生效，通过后新旧记录正确迁移；停用/启用待审期间保持原状态；`ACTIVE` 与 `DISABLED` 删除通过后均软删除。同版本重试复用原审批，在途变更、主体审批中、暂停合作和未登录请求均被拒绝且零写入。合成账户已清理，有效账户数回到基线 0；前端待接入。
+
+## 十、相关文档
+
+- **Issue**：[#7182](https://git.1814.love:8443/wx/HL/issues/7182)
+- **PR**：[#7192](https://git.1814.love:8443/wx/HL/pulls/7192)
+- **Merge commit**：[`06e682ae417defddcfb391d2afc4e928fc702627`](https://git.1814.love:8443/wx/HL/commit/06e682ae417defddcfb391d2afc4e928fc702627)
+
+## 关联 / 联系人
+
+- **后端负责人**：@lc