diff --git a/changelogs-v2/2026-09/06_7182_供应商账户审批操作-新增接口-管理后台.md b/changelogs-v2/2026-09/06_7182_供应商账户审批操作-新增接口-管理后台.md new file mode 100644 index 00000000..28058157 --- /dev/null +++ b/changelogs-v2/2026-09/06_7182_供应商账户审批操作-新增接口-管理后台.md @@ -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