diff --git a/changelogs-v2/2026-09/29_8515_供应商注册提交未绑定企业微信立即拦截-修改接口-管理后台.md b/changelogs-v2/2026-09/29_8515_供应商注册提交未绑定企业微信立即拦截-修改接口-管理后台.md new file mode 100644 index 00000000..83375f7f --- /dev/null +++ b/changelogs-v2/2026-09/29_8515_供应商注册提交未绑定企业微信立即拦截-修改接口-管理后台.md @@ -0,0 +1,212 @@ +--- +schema: "hl-changelog/v2" +ticket: "8515" +title: "供应商注册提交:未绑定企业微信的管理员立即返回 395020" +consumer: "admin" +author: "lc(GIT)" +change_type: "修改接口" +backend_status: "deployed" +gateway_status: "verified" +frontend_status: "not_required" +frontend_owner: "" +frontend_ref: "" +target_release: "" +verified_at: "" +status_note: "只新增一种失败返回,前端按现有方式展示 message 即可" +updated_at: "2026-09-29" +base: "dev-v3" +--- + +# 供应商: 注册提交未绑定企业微信时立即返回失败 + +> **服务**: hl-resource-service +> **PR**: #8535 +> **Issue**: #8515 +> **日期**: 2026-09-29 +> **影响范围**: 管理端供应商「提交审批」(注册审批) + +--- + +## ⚠️ 关键变化 + +- 以前:未绑定企业微信的管理员提交注册审批,接口先返回成功、供应商转「注册审核中」,随后后台建企业微信审批单失败,审批记录落「建单失败」,自动重提 4 次后才退回草稿。 +- 现在:注册审批走企业微信时,接口当场返回 `395020`「当前账号未绑定企业微信,请先绑定企业微信后再提交」,供应商保持提交前状态,不产生审批记录,也不自动重提。 + +--- + +## 二、变更接口清单 + +| # | 接口 | 方法 | 路径 | 变更类型 | 说明 | +|---|------|------|------|----------|------| +| 1 | 提交供应商注册审批 | POST | `/admin/supplier/items/{supplierId}/submit` | 新增一种失败返回 | 提交人未绑定企业微信时返回 395020 | + +--- + +## 三、接口详情 + +### 1. 提交供应商注册审批 `POST /admin/supplier/items/{supplierId}/submit` + +**VO**: `SupplierSubmitReqVO` → `SupplierApprovalCommandRespVO` + +#### 使用场景 + +管理员把草稿供应商提交注册审批。 + +#### 入参 + +| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 | +|------|------|------|------|------|------| +| supplierId | Path | Long | ✅ | 正整数 | 草稿供应商 ID | +| expectedUpdateTime | Body | String | ✅ | `yyyy-MM-dd HH:mm:ss` | 乐观锁,取详情里的 updateTime | +| 其余注册资料字段 | Body | - | - | 同现有提交接口 | 本次未改 | + +#### 出参 `Result` + +| 字段 | 类型 | 说明 | +|------|------|------| +| approvalLogId | String | 审批记录 ID | +| requestNo | String | 幂等请求号 | +| provider | String | 审批方式,企业微信为 `WECOM` | +| approvalStatus | String | 审批状态,提交后为 `PENDING` | +| approvalStatusName | String | 审批状态中文名 | +| spNo | String | 企业微信审批单号,异步建单完成前为空 | +| syncStatus | String | 同步状态 | +| submittedAt | String | 提交时间 | + +本次出参不变。 + +#### 请求示例 + +```json +{ + "expectedUpdateTime": "2026-09-29 17:30:00", + "fullName": "额尔古纳市室韦镇界河木刻楞民宿有限公司" +} +``` + +#### 响应示例 + +```json +{ + "code": 200, + "message": "成功", + "data": { + "approvalLogId": "2104890000000000001", + "provider": "WECOM", + "approvalStatus": "PENDING", + "approvalStatusName": "审核中", + "syncStatus": "REQUESTING" + }, + "success": true +} +``` + +#### 空数据 / 降级响应 + +本接口没有空数据。用户服务暂不可用、查不到提交人时不拦截,照原流程进入审批,由后台建单时再检查绑定。 + +```json +{ "code": 200, "data": { "provider": "WECOM", "approvalStatus": "PENDING" }, "success": true } +``` + +#### 错误响应 + +```json +{ + "code": 395020, + "message": "当前账号未绑定企业微信,请先绑定企业微信后再提交", + "success": false, + "data": null +} +``` + +#### 业务边界 + +- 校验顺序:登录与写权限 → 企业微信绑定 → 资料校验 → 重名确认 → 进入审批。无写权限仍先返回原有权限错误。 +- 「未绑定」指提交人管理员账号上的企业微信 ID 为空。 +- 只在资源服务启动时按企业微信审批装配(`supplier.approval.provider=WECOM`)时校验;本地自动审批模式不校验。 +- 查不到管理员或用户服务暂不可用时不拦截,照原流程进入审批,由后台建单时再检查绑定。 +- 返回 395020 时零写入:供应商状态、资料、审批记录、变更记录都不变,也不会自动重提。 + +--- + +## 四、契约约束与正确调用方式 + +### ✅ 正确 / ❌ 错误调用对照 + +| 场景 | 结果 | +|------|------| +| ✅ 已绑定企业微信的管理员提交 | 200,进入注册审核中 | +| ❌ 未绑定企业微信的管理员提交 | 395020,供应商保持原状态 | + +请求体不变,没有新增或删除字段。管理员先在账号上绑定企业微信,再重新提交即可。 + +--- + +## 五、数据库行为 + +| 场景 | 供应商状态 | 审批记录 | 变更记录 | +|------|-----------|----------|----------| +| 未绑定,返回 395020 | 不变 | 不新增 | 不新增 | +| 已绑定,提交成功 | 注册审核中 | 新增一条 | 同改前 | + +--- + +## 六、边界行为 + +- 已绑定企业微信的管理员:流程不变,照常进入注册审核中并创建企业微信审批单。 +- 提交后才解绑的:仍由后台建单时的检查拦下(原有「建单失败」逻辑不变)。 + +## 六.6、修改前后对比 + +### 行为级对比 + +| 行为 | 改前 | 改后 | +|------|------|------| +| 未绑定企业微信的管理员提交注册审批 | 返回成功,随后落「建单失败」并自动重提,约 2 分钟后退回草稿 | 当场返回 395020,供应商保持原状态 | +| 已绑定企业微信的管理员提交注册审批 | 进入注册审核中 | 不变 | + +## 六.7、影响评估 + +- **是否破坏向后兼容**: 否(只新增一种失败返回) +- **前端是否必须同步上线**: 否 +- **前端 workaround 清理点**: 无 + +## 七、不影响范围 + +- **仅影响**: 供应商注册「提交审批」接口 +- **零影响**: + - 供应商状态变更审批(暂停、拉黑等)、合作中资料变更审批 + - 用户服务建企业微信审批单的原有检查 + - 395020 在状态变更审批中的原有文案「当前账号未绑定企业微信」 + +--- + +## 八、测试环境已验证 + +TEST 已部署合并提交 `41bc1be10`,经 Gateway 实测: + +``` +管理员未绑定企业微信 → POST /admin/supplier/items/{SUP260106}/submit → 395020「当前账号未绑定企业微信,请先绑定企业微信后再提交」,约 3 秒返回 ✓ +被拦后:供应商仍为草稿、资料未改写、审批记录和变更记录都不新增,130 秒后仍无自动重提 ✓ +管理员已绑定企业微信 → POST /admin/supplier/items/{SUP260103}/submit → 200,provider=WECOM,进入注册审核中并生成企业微信审批单 ✓ +``` + +--- + +## 十、相关文档 + +- 关联 Issue: [wx/HL#8515](https://git.1814.love/wx/HL/issues/8515) +- 关联 PR: [wx/HL#8535](https://git.1814.love/wx/HL/pulls/8535) + +## 关联 / 联系人 + +### 链接 + +- **Issue**: [#8515](https://git.1814.love/wx/HL/issues/8515) +- **PR**: [#8535](https://git.1814.love/wx/HL/pulls/8535) +- **Merge commit**: [41bc1be10](https://git.1814.love/wx/HL/commit/41bc1be10) + +### 联系人 + +- **后端负责人**: @lc