diff --git a/changelogs-v2/2026-09/05_7101_供应商合作中资料变更接入企微审批-修改接口-管理后台.md b/changelogs-v2/2026-09/05_7101_供应商合作中资料变更接入企微审批-修改接口-管理后台.md new file mode 100644 index 00000000..063d18e7 --- /dev/null +++ b/changelogs-v2/2026-09/05_7101_供应商合作中资料变更接入企微审批-修改接口-管理后台.md @@ -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` + +| 字段 | 类型 | 说明 | +|---|---|---| +| `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` + +#### 使用场景 + +为合作中供应商新增一至五十个收款账户,每个账户独立提交企微审批。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|---|---|---|---|---|---| +| `supplierId` | Path | String | 是 | 正整数 | 合作中供应商 ID | +| `accounts` | Body | Array | 是 | 1~50 项 | 账户列表,原请求结构不变 | + +#### 出参 `Result>` + +| 字段 | 类型 | 说明 | +|---|---|---| +| `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