hl-api-changelog/changelogs-v2/2026-09/03_7029_供应商新增账户接入企微审批-修改接口-管理后台.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	7029	供应商新增账户接入企微审批	admin	lc(GIT)	修改接口	deployed	verified	verified	mmg	908e691f		2026-09-03	后端已改为企微异步审批；前端需切换账户新增路径、展示待审批状态并移除本地人工审批入口。	2026-09-03	dev-v3

供应商模块：新增账户接入企微审批

服务: hl-resource-service（8082）、hl-user-service（8081） Issue: #7029 PR: #7031 影响范围: 管理后台供应商列表的账户管理

⚠️ 关键变化

已审核通过的供应商新增账户后不再立即生效，也不再由管理端调用人工审批接口；后端会在企微“账户”模板发起审批，账户先返回 PENDING，企微通过并同步后才变为 ACTIVE。

二、变更接口清单

#	接口	方法	路径	变更类型	说明
1	批量新增并提交收款账户	POST	/admin/supplier/items/{supplierId}/bank-accounts/add	行为修改	每个账户独立发起企微审批并返回审批状态

三、接口详情

1. 批量新增并提交收款账户 POST /admin/supplier/items/{supplierId}/bank-accounts/add

VO: SupplierBankAccountBatchCreateReqVO → List<BankAccountSubmitResultRespVO>

使用场景

供应商状态为 ACTIVE 后，在账户管理中新增一至五十个收款账户。

入参

字段	位置	类型	必填	约束	说明
supplierId	Path	String	是	正整数雪花 ID	已生效供应商
accounts	Body	Array	是	1～50 项	收款账户列表
accounts[].accountType	Body	String	是	CORPORATE / PERSONAL	账户类型
accounts[].bankName	Body	String	是	最长 500	开户行
accounts[].bankBranch	Body	String	否	最长 500	开户支行
accounts[].accountNo	Body	String	是	8～128 位，仅数字、空格、-	账号
accounts[].proofFileUrls	Body	Array	否	最多 20 项	证明附件
accounts[].settleMode	Body	String	否	PREPAY / MONTHLY / SINGLE	结算方式
accounts[].accountPeriod	Body	String	条件必填	MONTHLY 时必填，其他方式必须为空	账期
accounts[].invoiceType	Body	String	否	SPECIAL / NORMAL / NONE	发票类型
accounts[].taxRate	Body	String	条件必填	可开票时必填，NONE 时必须为空	0%～100%，最多两位小数

出参 Result<List<BankAccountSubmitResultRespVO>>

字段	类型	说明
accountId	String	新账户 ID
approvalLogId	String	账户审批记录 ID
requestNo	String	同一请求重放使用的稳定请求号
provider	String	新申请固定为 WECOM
approvalStatus	String	新申请为 PENDING，通过后为 APPROVED
spNo	String	企微审批单号
spStatus	String / null	企微原始状态，完成同步前可为空
syncStatus	String	正常建单为 REQUESTING，完成应用为 APPLIED；异常可能为 APPLY_FAILED / RESULT_UNCERTAIN
accountStatus	String	通过前 PENDING，通过后 ACTIVE
isDefault	String	新增账户固定为 NO
submittedAt	String / null	提交时间
finishedAt	String / null	完成时间，审批中为空

请求示例

{
  "accounts": [
    {
      "accountType": "PERSONAL",
      "bankName": "示例银行",
      "bankBranch": "示例支行",
      "accountNo": "6222 0000 1234 5678",
      "proofFileUrls": [],
      "settleMode": "SINGLE",
      "accountPeriod": null,
      "invoiceType": "NONE",
      "taxRate": null
    }
  ]
}

响应示例

{
  "code": 200,
  "message": "成功",
  "data": [
    {
      "accountId": "353807302408683520",
      "approvalLogId": "353807302408683521",
      "requestNo": "SUP-ACC-REQ-example",
      "provider": "WECOM",
      "approvalStatus": "PENDING",
      "spNo": "202609030009",
      "spStatus": null,
      "syncStatus": "REQUESTING",
      "accountStatus": "PENDING",
      "isDefault": "NO",
      "submittedAt": "2026-09-03 15:45:00",
      "finishedAt": null
    }
  ],
  "success": true
}

空数据 / 降级响应

写接口不返回空成功列表。企微结果不确定时仍保留账户和审批事实为 PENDING，对应项返回 syncStatus=RESULT_UNCERTAIN，前端不得自动重提。

错误响应

{
  "code": 395010,
  "message": "请先完成供应商注册",
  "data": null,
  "success": false
}

业务边界

code	场景	前端处理
400	账户字段、枚举或组合规则不合法	保留表单并展示后端提示
395001	供应商不存在	关闭弹窗并刷新列表
395002	无账户管理或提交权限	禁止操作
395010	供应商不是 ACTIVE	先完成供应商注册审批
395011	同一账号已有在途审批	不重复提交，刷新账户列表
395027	账号已被占用	联系财务核实

• 每个账户生成独立审批；顶层 success=true 后仍须检查每项 syncStatus 和 accountStatus。
• 企微模板固定展示供应商、账户类型、开户行和账号，审批人由企微模板配置决定，前端不传审批人。

四、契约约束与正确调用方式

1. 新增账户只调用 POST /admin/supplier/items/{supplierId}/bank-accounts/add，请求体必须使用 accounts 数组。
2. 成功建单后展示“待审批”，不得把 PENDING 当作可用账户，也不得调用旧的 /supplier/{supplierId}/accounts/{accountId}/approve。
3. 通过 GET /admin/supplier/items/{supplierId}/account-info/list 刷新状态；只有 status=ACTIVE 才展示为生效中。
4. 必须同时判断顶层 success/code 与每项 syncStatus/accountStatus；RESULT_UNCERTAIN 只提示对账，不自动重试。

五、数据库行为

提交成功后先持久化 PENDING、非默认账户及对应审批记录；企微审批通过后异步更新为 ACTIVE，并追加审批关联的账户启用审计。外部提交失败或结果不确定时不会把账户标记为生效。

六、边界行为

• 供应商创建时携带的初始账户仍随供应商注册审批，通过前为 PENDING，通过后为 ACTIVE。
• 后续新增账户与供应商创建时是否携带初始账户无关，只要求供应商当前为 ACTIVE。
• 企微驳回或撤销不会激活账户；终态由后端回调或轮询同步。
• 接口使用统一 Result；业务错误可能仍为 HTTP 200，必须读取响应体 code/success。

六.5、枚举 / 数据字典

accountStatus / 账户列表 status

值	中文	说明
PENDING	待审批	不可作为生效账户使用
ACTIVE	生效中	企微审批通过且后端已完成应用
DISABLED	已停用	本工单未修改停用流程

六.6、修改前后对比

行为	修改前	修改后
新增账户	本地自动通过并立即 ACTIVE	企微建单后先 PENDING，通过后才 ACTIVE
审批动作	管理端存在本地人工审批调用	仅在企微处理，管理端只刷新状态
新增路径	旧页面调用 /supplier/{supplierId}/accounts	调用 /admin/supplier/items/{supplierId}/bank-accounts/add

六.7、影响评估

• 是否破坏向后兼容: 是；新增账户由同步生效改为异步审批。
• 前端是否必须同步上线: 是。
• 前端 workaround 清理点: 删除账户本地审批按钮及 /supplier/{supplierId}/accounts/{accountId}/approve 调用。

七、不影响范围

• 仅影响: 管理后台供应商账户新增及状态展示。
• 零影响: 账户详情读取、默认账户切换、停用流程、合同、资源绑定和小程序接口。

八、测试环境已验证

TEST Gateway 已验证：初始账户随注册审批由 PENDING 转为 ACTIVE；后续账户使用指定企微模板建单并在通过后由 PENDING 转为 ACTIVE，审批记录和启用审计均可查询；非法账户类型返回业务失败且零写入。

十、相关文档

• Issue #7029
• PR #7031

前端动作与当前状态

• 将账户新增改为批量接口及 accounts 请求结构。
• 新增后展示 PENDING，轮询或刷新账户列表，直到后端返回 ACTIVE。
• 移除管理端账户审批按钮和旧人工审批请求。
• 当前状态：待前端处理。

关联 / 联系人

• Issue: #7029
• PR: #7031
• Merge commit: f5dfa7771a61948bb4d59e35fbedb67d61fcb3f3
• 后端负责人: @lc