hl-api-changelog/changelogs-v2/2026-09/06_7182_供应商账户审批操作-新增接口-管理后台.md

schema, ticket, title, consumer, author, change_type, backend_status, gateway_status, frontend_status, frontend_owner, frontend_ref, target_release, verified_at, status_note, updated_at, base

schema	ticket	title	consumer	author	change_type	backend_status	gateway_status	frontend_status	frontend_owner	frontend_ref	target_release	verified_at	status_note	updated_at	base
hl-changelog/v2	7182	供应商账户删除、启用与新记录式修改审批	admin	lc(GIT)	新增接口	deployed	verified	verified	mmg	326a1523		2026-09-07	前端已交付 ref 326a1523(+sync-log 20eb2a19):accounts.js 新增 enable/delete/update 三 API(disable 已有);SupplierAccountsManageModal 操作列扩启用/修改/删除(显隐 status×isDefault、在途审批本地禁用+后端 395011/395028 兜底);新建 SupplierAccountEditModal 新记录式修改(条件必填月结账期/开票税率、proofFileUrls 按权限省略);移除「无删除/停用入口」过时提示。supplier 域 175+全量 vitest 2171 绿,生产构建过。	2026-09-06	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	提交 / 终态时间

请求示例

{"expectedUpdateTime":"2026-09-06 12:00:00"}

响应示例

{"code":200,"message":"成功","success":true,"data":{"accountId":"7182001","approvalLogId":"7182002","approvalStatus":"PENDING","approvalStatusName":"审核中","spNo":"202609060001","syncStatus":"REQUESTING","accountStatus":"ACTIVE","isDefault":"NO"}}

空数据 / 降级响应

无空成功数据；账户不存在返回 395001。企微提交或对账异常按 syncStatus 返回原审批事实，不直接停用账户。

错误响应

{"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	提交 / 终态时间

请求示例

{"expectedUpdateTime":"2026-09-06 12:00:00"}

响应示例

{"code":200,"message":"成功","success":true,"data":{"accountId":"7182001","approvalLogId":"7182003","approvalStatus":"PENDING","approvalStatusName":"审核中","spNo":"202609060002","syncStatus":"REQUESTING","accountStatus":"DISABLED","isDefault":"NO"}}

空数据 / 降级响应

无空成功数据；账户不存在返回 395001。企微异常不会提前启用账户，调用方须按 syncStatus 展示待同步/待对账。

错误响应

{"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	提交 / 终态时间

请求示例

{"expectedUpdateTime":"2026-09-06 12:00:00"}

响应示例

{"code":200,"message":"成功","success":true,"data":{"accountId":"7182001","approvalLogId":"7182004","approvalStatus":"PENDING","approvalStatusName":"审核中","spNo":"202609060003","syncStatus":"REQUESTING","accountStatus":"ACTIVE","isDefault":"NO"}}

空数据 / 降级响应

无空成功数据；已软删除或不存在返回 395001。企微异常时保留原账户，不把提交成功当作删除成功。

错误响应

{"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	提交 / 终态时间

请求示例

{"accountType":"CORPORATE","bankName":"示例银行","bankBranch":"示例支行","accountNo":"718200000002","proofFileUrls":[],"settleMode":"PREPAY","invoiceType":"NONE","expectedUpdateTime":"2026-09-06 12:00:00"}

响应示例

{"code":200,"message":"成功","success":true,"data":{"accountId":"7182010","approvalLogId":"7182011","approvalStatus":"PENDING","approvalStatusName":"审核中","spNo":"202609060004","syncStatus":"REQUESTING","accountStatus":"PENDING","isDefault":"NO"}}

空数据 / 降级响应

无空成功数据；原账户不存在返回 395001。企微异常时原账户保持 ACTIVE，已创建的新记录按同步状态对账，不覆盖原账户。

错误响应

{"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
• PR：#7192
• Merge commit：06e682ae417defddcfb391d2afc4e928fc702627

关联 / 联系人

• 后端负责人：@lc