docs(changelog): #7029 供应商账户企微审批

2026-09-03 15:51:47 +08:00
@@ -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<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 | 完成时间，审批中为空 |
+
+#### 请求示例
+
+```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