diff --git a/changelogs-v2/2026-09/03_7029_供应商新增账户接入企微审批-修改接口-管理后台.md b/changelogs-v2/2026-09/03_7029_供应商新增账户接入企微审批-修改接口-管理后台.md new file mode 100644 index 00000000..a37383f1 --- /dev/null +++ b/changelogs-v2/2026-09/03_7029_供应商新增账户接入企微审批-修改接口-管理后台.md @@ -0,0 +1,223 @@ +--- +schema: "hl-changelog/v2" +ticket: "7029" +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-03" +status_note: "后端已改为企微异步审批;前端需切换账户新增路径、展示待审批状态并移除本地人工审批入口。" +updated_at: "2026-09-03" +base: "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` + +#### 使用场景 + +供应商状态为 `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>` + +| 字段 | 类型 | 说明 | +|---|---|---| +| 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 | 完成时间,审批中为空 | + +#### 请求示例 + +```json +{ + "accounts": [ + { + "accountType": "PERSONAL", + "bankName": "示例银行", + "bankBranch": "示例支行", + "accountNo": "6222 0000 1234 5678", + "proofFileUrls": [], + "settleMode": "SINGLE", + "accountPeriod": null, + "invoiceType": "NONE", + "taxRate": null + } + ] +} +``` + +#### 响应示例 + +```json +{ + "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`,前端不得自动重提。 + +#### 错误响应 + +```json +{ + "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](https://git.1814.love:8443/wx/HL/issues/7029) +- [PR #7031](https://git.1814.love:8443/wx/HL/pulls/7031) + +## 前端动作与当前状态 + +- 将账户新增改为批量接口及 `accounts` 请求结构。 +- 新增后展示 `PENDING`,轮询或刷新账户列表,直到后端返回 `ACTIVE`。 +- 移除管理端账户审批按钮和旧人工审批请求。 +- **当前状态:待前端处理。** + +## 关联 / 联系人 + +- **Issue**: [#7029](https://git.1814.love:8443/wx/HL/issues/7029) +- **PR**: [#7031](https://git.1814.love:8443/wx/HL/pulls/7031) +- **Merge commit**: [f5dfa7771a61948bb4d59e35fbedb67d61fcb3f3](https://git.1814.love:8443/wx/HL/commit/f5dfa7771a61948bb4d59e35fbedb67d61fcb3f3) +- **后端负责人**: @lc