供应商合作中资料变更接入企微审批（#7101）

2026-09-05 09:17:56 +08:00
@@ -0,0 +1,299 @@
+---
+schema: "hl-changelog/v2"
+ticket: "7101"
+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-05"
+status_note: "后端已部署并通过 TEST；前端需将合作中资料保存结果按企微异步审批处理，并展示审核中。"
+updated_at: "2026-09-05"
+base: "dev-v3"
+---
+
+# 供应商模块：合作中资料变更接入企微审批
+
+> **服务**: `hl-resource-service`、`hl-user-service`
+> **Issue**: #7101
+> **PR**: #7125、#7128
+> **日期**: 2026-09-05
+> **影响范围**: 管理后台供应商资料保存与新增收款账户结果展示
+
+## ⚠️ 关键变化
+
+合作中（`ACTIVE`）供应商保存资料不再直接更新正式资料：接口先返回企微审批受理结果，待审批时统一显示“审核中”；驳回不更新，通过后才应用本次申请。新增账户仍独立审批，本次补充中文审批状态字段。
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|---|---|---|---|---|
+| 1 | 更新供应商 | PUT | `/admin/supplier/items/{supplierId}/update` | 行为与响应修改 | `ACTIVE` 改为企微审批后生效，响应新增 `approval` |
+| 2 | 批量新增收款账户 | POST | `/admin/supplier/items/{supplierId}/bank-accounts/add` | 响应字段扩展 | 每项新增 `approvalStatusName` |
+
+## 三、接口详情
+
+### 1. 更新供应商 `PUT /admin/supplier/items/{supplierId}/update`
+
+**VO**: `SupplierUpdateReqVO → SupplierWriteRespVO`
+
+#### 使用场景
+
+保存合作中供应商的主体资料、联系人或资质；草稿保存语义不变。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|---|
+| `supplierId` | Path | String | 是 | 正整数 | 供应商 ID |
+| `expectedUpdateTime` | Body | String | 是 | `yyyy-MM-dd HH:mm:ss` | 当前供应商版本 |
+| `changeReason` | Body | String | `ACTIVE` 必填 | 最长 500 | 变更原因 |
+| 资料字段 | Body | 原类型 | 否 | 沿用原契约 | 至少产生一项实际变化 |
+| `contacts` | Body | Array | 否 | 完整快照 | 已有联系人带 `contactId`、`expectedUpdateTime`；新增联系人省略 `contactId` |
+
+#### 出参 `Result<SupplierWriteRespVO>`
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `data.status` | String | 审批期间仍为 `ACTIVE` |
+| `data.statusName` | String | 待审批时为“审核中” |
+| `data.approval.approvalLogId` | String | 资料变更审批记录 ID |
+| `data.approval.approvalStatus` | String | 初次受理为 `PENDING` |
+| `data.approval.approvalStatusName` | String | 初次受理为“审核中” |
+| `data.approval.spNo` | String | 企业微信审批单号 |
+| `data.approval.syncStatus` | String | 审批同步状态 |
+| `data.updateTime` | String | 审核中仍返回正式资料当前版本 |
+
+#### 请求示例
+
+```json
+{
+  "remark": "更新合作备注",
+  "changeReason": "业务资料更新",
+  "expectedUpdateTime": "2026-09-05 09:00:00"
+}
+```
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "success": true,
+  "data": {
+    "supplierId": "2095000000000000001",
+    "status": "ACTIVE",
+    "statusName": "审核中",
+    "approval": {
+      "approvalLogId": "2095000000000000002",
+      "provider": "WECOM",
+      "approvalStatus": "PENDING",
+      "approvalStatusName": "审核中",
+      "spNo": "202609050001",
+      "syncStatus": "REQUESTING"
+    },
+    "updateTime": "2026-09-05 09:00:00"
+  }
+}
+```
+
+#### 空数据 / 降级响应
+
+成功受理时 `data.approval` 不为空；企微结果不确定时保留审批事实，前端不得自动重复提交。草稿直接保存时 `data.approval=null`。
+
+#### 错误响应
+
+```json
+{
+  "code": 395014,
+  "message": "数据已被他人修改，请刷新后重试",
+  "success": false,
+  "data": null
+}
+```
+
+`400` 表示字段、联系人快照或变更原因不合法；`395005` 表示当前状态不允许；`395019`～`395022` 表示企微未配置、账号未绑定、提交失败或状态待对账。未新增错误码。
+
+#### 业务边界
+
+- 审核中正式资料保持原值；驳回不更新，通过后一次性应用申请中的冻结值。
+- 新增联系人必须省略 `contactId`，不得发送 `contactId:null`；只修正内部审批快照兼容，不放宽外部显式空 ID 校验。
+- 企微表单的变更明细只列实际差异，身份证号和个人电话完整展示；相关附件和当前正式资料为选填。
+
+### 2. 批量新增收款账户 `POST /admin/supplier/items/{supplierId}/bank-accounts/add`
+
+**VO**: `SupplierBankAccountBatchCreateReqVO → List<BankAccountSubmitResultRespVO>`
+
+#### 使用场景
+
+为合作中供应商新增一至五十个收款账户，每个账户独立提交企微审批。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|---|
+| `supplierId` | Path | String | 是 | 正整数 | 合作中供应商 ID |
+| `accounts` | Body | Array | 是 | 1～50 项 | 账户列表，原请求结构不变 |
+
+#### 出参 `Result<List<BankAccountSubmitResultRespVO>>`
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `data[].approvalStatus` | String | `PENDING` / `APPROVED` / `REJECTED` |
+| `data[].approvalStatusName` | String | “审核中” / “已通过” / “已驳回” |
+| `data[].accountStatus` | String | 审核中为 `PENDING`，通过为 `ACTIVE`，驳回为 `REJECTED` |
+| `data[].spNo` | String | 企业微信审批单号 |
+
+#### 请求示例
+
+```json
+{
+  "accounts": [{
+    "accountType": "PERSONAL",
+    "bankName": "示例银行",
+    "bankBranch": "示例支行",
+    "accountNo": "6222000012345678",
+    "proofFileUrls": [],
+    "settleMode": "SINGLE",
+    "invoiceType": "NONE"
+  }]
+}
+```
+
+#### 响应示例
+
+```json
+{
+  "code": 200,
+  "message": "成功",
+  "success": true,
+  "data": [{
+    "accountId": "2095000000000000003",
+    "approvalLogId": "2095000000000000004",
+    "provider": "WECOM",
+    "approvalStatus": "PENDING",
+    "approvalStatusName": "审核中",
+    "spNo": "202609050002",
+    "syncStatus": "REQUESTING",
+    "accountStatus": "PENDING",
+    "isDefault": "NO"
+  }]
+}
+```
+
+#### 空数据 / 降级响应
+
+写接口不返回空成功列表；结果不确定时账户保持不可用，前端不得自动重提。
+
+#### 错误响应
+
+```json
+{
+  "code": 395011,
+  "message": "该账户正在审批中，请勿重复提交",
+  "success": false,
+  "data": null
+}
+```
+
+`400` 表示账户字段或组合规则不合法；`395010` 表示供应商尚未生效；其他企微错误沿用现有 `395019`～`395022`。
+
+#### 业务边界
+
+- 每个账户独立审批；审核中保持 `PENDING` 且不可收款、不可设为默认。
+- 企微驳回后为 `REJECTED`，通过后为 `ACTIVE`；前端只把 `ACTIVE` 当作生效账户。
+
+## 四、契约约束与正确调用方式
+
+1. 更新接口返回成功后，若 `data.approval.approvalStatus=PENDING`，展示“审核中”并保留正式资料页面值，不做本地乐观覆盖。
+2. 通过详情、审批记录或账户列表刷新终态；审批只能在企业微信处理，管理端不发送通过或驳回命令。
+3. 联系人数组是完整快照；新增项省略 `contactId`，已有项同时传 `contactId` 与 `expectedUpdateTime`。
+4. 所有接口同时检查 HTTP 状态和响应体 `code/success`。
+
+## 五、数据库行为
+
+- 本次无数据库结构或迁移变化。
+- 资料审批中不写正式资料；通过后应用冻结申请，驳回后正式版本和值均不变。
+- 新账户审批中为 `PENDING`，通过后为 `ACTIVE`，驳回后为 `REJECTED`。
+
+## 六、边界行为
+
+- 模板审批节点由企业微信配置决定，后端不校验“恰好一级”。
+- 表单固定使用已配置的八个 `Text` 控件；相关附件与当前正式资料允许为空。
+- 企微回调或轮询完成前，前端只展示受理状态，不推断最终结果。
+
+## 六.5、枚举 / 数据字典
+
+| 字段 | 值 | 中文 | 说明 |
+|---|---|---|---|
+| `approvalStatus` | `PENDING` | 审核中 | 尚未终结 |
+| `approvalStatus` | `APPROVED` | 已通过 | 业务变更已应用 |
+| `approvalStatus` | `REJECTED` | 已驳回 | 业务变更未应用 |
+| `accountStatus` | `PENDING` | 待审批 | 账户不可用 |
+| `accountStatus` | `ACTIVE` | 生效中 | 账户可用 |
+| `accountStatus` | `REJECTED` | 已驳回 | 账户不可用 |
+
+## 六.6、修改前后对比
+
+| 行为 | 修改前 | 修改后 |
+|---|---|---|
+| `ACTIVE` 供应商保存资料 | 直接更新正式资料 | 返回企微审批；通过后更新，驳回不更新 |
+| 资料保存响应 | 无独立资料审批结果 | 返回 `data.approval` 与“审核中”状态 |
+| 新增账户响应 | 仅英文审批状态 | 增加 `approvalStatusName` 中文状态 |
+
+## 六.7、影响评估
+
+- **是否破坏向后兼容**: 是；合作中资料保存由同步生效改为异步审批。
+- **前端是否必须同步上线**: 是。
+- **前端 workaround 清理点**: 删除保存成功后立即以请求值覆盖正式资料的逻辑，改为展示“审核中”并刷新终态。
+
+## 七、不影响范围
+
+- 草稿供应商直接保存、注册审批、主体状态审批、合同、默认账户和停用流程不变。
+- 新增账户的请求路径、请求字段和独立审批语义不变。
+- 未新增数据库、配置、Redis、MQ 或错误码。
+
+## 八、测试环境已验证
+
+```text
+PUT  /admin/supplier/items/{supplierId}/update                    → PENDING / 审核中，正式资料保持原值 ✓
+企微通过资料变更                                                  → 正式资料更新，身份证号与电话完整值可见 ✓
+企微驳回资料变更                                                  → 正式资料和值版本均不变 ✓
+POST /admin/supplier/items/{supplierId}/bank-accounts/add         → PENDING / 审核中 ✓
+企微通过新增账户                                                  → ACTIVE ✓
+企微驳回新增账户                                                  → REJECTED，未激活 ✓
+```
+
+资料审批使用模板 `3WNhaxns4i6kfVs74gz4qZQhFxy4iJY4anxMuvYw`；八个 `Text` 控件、实际差异格式、完整身份证号/电话和两个选填项已逐项验证。部署提交为 `6bc1c1262e5e4902a893f30fac875d35a65f8a76`。
+
+## 十、相关文档
+
+- [Issue #7101](https://git.1814.love:8443/wx/HL/issues/7101)
+- [主 PR #7125](https://git.1814.love:8443/wx/HL/pulls/7125)
+- [补充 Issue #7127](https://git.1814.love:8443/wx/HL/issues/7127)
+- [补充 PR #7128](https://git.1814.love:8443/wx/HL/pulls/7128)
+
+## 前端动作与当前状态
+
+- 合作中资料保存成功后读取 `data.approval`，展示“审核中”，刷新终态后再更新正式资料。
+- 新增账户直接展示 `approvalStatusName`，并按 `accountStatus` 判断是否可用。
+- 新增联系人省略 `contactId`，已有联系人继续携带 ID 与版本。
+- **当前状态：待前端处理。**
+
+## 关联 / 联系人
+
+### 链接
+
+- **Issue**: [#7101](https://git.1814.love:8443/wx/HL/issues/7101)
+- **PR**: [#7125](https://git.1814.love:8443/wx/HL/pulls/7125)
+- **Merge commit**: [91a965f0b0f403a0f8c9d3990587f09ea780c9dd](https://git.1814.love:8443/wx/HL/commit/91a965f0b0f403a0f8c9d3990587f09ea780c9dd)
+
+### 联系人
+
+- **后端负责人**: @lc