交付供应商审核中资料冻结联调说明（#7078）

2026-09-04 15:56:31 +08:00
@@ -0,0 +1,370 @@
 ---
 schema: "hl-changelog/v2"
 ticket: "7078"
 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-04"
 status_note: '后端已部署并通过 TEST；前端需在 statusName="审核中" 时制灰供应商、账户、合同及冲突状态写操作。'
 updated_at: "2026-09-04"
 base: "dev-v3"
 ---
 # 供应商模块：企微审核中冻结资料修改
 > **服务**: `hl-resource-service`
 > **Issue**: [#7078](https://git.1814.love:8443/wx/HL/issues/7078)
 > **PR**: [#7086](https://git.1814.love:8443/wx/HL/pulls/7086)
 > **日期**: 2026-09-04
 > **影响范围**: 管理后台供应商详情、账户、合同和状态操作
 ## ⚠️ 关键变化
 `statusName="审核中"` 时，前端统一制灰供应商资料、账户、合同及冲突状态写入口；详情和审批记录仍可查看，注册审批撤销等合法审批退出路径保持可用。`statusName` 是 #7069 已交付字段，本次未新增请求字段、响应字段或错误码。
 ## 二、变更接口清单
 | # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
 |---|---|---|---|---|---|
 | 1 | 更新供应商 | PUT | `/admin/supplier/items/{supplierId}/update` | 行为修改 | 企微主体审批中返回 `395005` |
 | 2 | 新增合同 | POST | `/admin/supplier/items/{supplierId}/contracts/add` | 行为修改 | 企微主体审批中返回 `395005` |
 | 3 | 更新合同 | PUT | `/admin/supplier/items/{supplierId}/contracts/{contractId}/update` | 行为修改 | 企微主体审批中返回 `395005` |
 | 4 | 删除合同 | DELETE | `/admin/supplier/items/{supplierId}/contracts/{contractId}/del` | 行为修改 | 企微主体审批中返回 `395005` |
 | 5 | 恢复合作 | POST | `/admin/supplier/items/{supplierId}/resume` | 行为修改 | 状态审批中不得绕过审批恢复合作 |
 ## 三、接口详情
 ### 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 | 条件必填 | 最长 500 | 非草稿修改必填 |
 | 资料字段 | Body | 原类型 | 否 | 沿用原契约 | 至少提交一个可变更字段 |
 #### 出参
 | 字段 | 类型 | 说明 |
 |---|---|---|
 | `data` | `SupplierWriteRespVO` | 成功响应结构不变 |
 #### 请求示例
 ```json
 {"remark":"更新备注","changeReason":"资料修正","expectedUpdateTime":"2026-09-04 10:00:00"}
 ```
 #### 响应示例
 ```json
 {"code":200,"message":"成功","data":{"supplierId":"2095000000000000001","status":"ACTIVE","updateTime":"2026-09-04 10:01:00"},"success":true}
 ```
 #### 空数据 / 降级响应
 写接口无空成功结果，也不提供降级成功。
 #### 错误响应
 ```json
 {"code":395005,"message":"当前状态不允许执行该操作","data":null,"success":false}
 ```
 #### 业务边界
 - 企微注册或主体状态审批为 `PENDING` 时拒绝，供应商主档及聚合子项均保持不变。
 - 其他权限、字段校验、并发和审计规则不变。
 ### 2. 新增合同 `POST /admin/supplier/items/{supplierId}/contracts/add`
 **VO**: `SupplierContractCreateReqVO → SupplierContractRespVO`
 #### 使用场景
 为供应商独立登记一份线下合同。
 #### 入参
 | 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
 |---|---|---|---|---|---|
 | `supplierId` | Path | String | 是 | 正整数 | 供应商 ID |
 | `changeReason` | Body | String | 是 | 最长 500 | 登记原因 |
 | 合同资料字段 | Body | 原类型 | 否 | 沿用原契约 | 名称、编号、日期、金额等字段不变 |
 #### 出参
 | 字段 | 类型 | 说明 |
 |---|---|---|
 | `data` | `SupplierContractRespVO` | 成功响应结构不变 |
 #### 请求示例
 ```json
 {"contractName":"年度框架合同","changeReason":"线下签署后登记"}
 ```
 #### 响应示例
 ```json
 {"code":200,"message":"成功","data":{"contractId":"2095000000000000002","contractName":"年度框架合同","updateTime":"2026-09-04 10:02:00"},"success":true}
 ```
 #### 空数据 / 降级响应
 除 `changeReason` 外的合同业务字段可空；成功仍返回合同对象，不提供降级成功。
 #### 错误响应
 ```json
 {"code":395005,"message":"当前状态不允许执行该操作","data":null,"success":false}
 ```
 #### 业务边界
 - 企微注册或主体状态审批为 `PENDING` 时不新增合同或审计记录。
 - 合同字段、权限、锁和幂等规则不变。
 ### 3. 更新合同 `PUT /admin/supplier/items/{supplierId}/contracts/{contractId}/update`
 **VO**: `SupplierContractUpdateReqVO → SupplierContractRespVO`
 #### 使用场景
 完整替换一份已有合同的业务资料。
 #### 入参
 | 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
 |---|---|---|---|---|---|
 | `supplierId` / `contractId` | Path | String | 是 | 正整数 | 供应商和合同 ID |
 | `changeReason` | Body | String | 是 | 最长 500 | 修改原因 |
 | `expectedUpdateTime` | Body | String | 否 | `yyyy-MM-dd HH:mm:ss` | 合同并发版本 |
 | 合同资料字段 | Body | 原类型 | 否 | 沿用原契约 | 完整替换语义不变 |
 #### 出参
 | 字段 | 类型 | 说明 |
 |---|---|---|
 | `data` | `SupplierContractRespVO` | 成功响应结构不变 |
 #### 请求示例
 ```json
 {"contractName":"年度框架合同（修订）","changeReason":"合同修订","expectedUpdateTime":"2026-09-04 10:02:00"}
 ```
 #### 响应示例
 ```json
 {"code":200,"message":"成功","data":{"contractId":"2095000000000000002","contractName":"年度框架合同（修订）","updateTime":"2026-09-04 10:03:00"},"success":true}
 ```
 #### 空数据 / 降级响应
 合同业务字段保持既有可空和完整替换语义；写接口不提供降级成功。
 #### 错误响应
 ```json
 {"code":395005,"message":"当前状态不允许执行该操作","data":null,"success":false}
 ```
 #### 业务边界
 - 企微注册或主体状态审批为 `PENDING` 时，先于合同查询拒绝，不修改合同或审计记录。
 - 合同归属、可选版本及无变化校验不变。
 ### 4. 删除合同 `DELETE /admin/supplier/items/{supplierId}/contracts/{contractId}/del`
 **VO**: `SupplierContractDeleteReqVO → Void`
 #### 使用场景
 软删除一份已有合同。
 #### 入参
 | 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
 |---|---|---|---|---|---|
 | `supplierId` / `contractId` | Path | String | 是 | 正整数 | 供应商和合同 ID |
 | `changeReason` | Body | String | 是 | 最长 500 | 删除原因 |
 | `expectedUpdateTime` | Body | String | 否 | `yyyy-MM-dd HH:mm:ss` | 合同并发版本 |
 #### 出参
 | 字段 | 类型 | 说明 |
 |---|---|---|
 | `data` | null | 成功时为空 |
 #### 请求示例
 ```json
 {"changeReason":"合同登记作废","expectedUpdateTime":"2026-09-04 10:03:00"}
 ```
 #### 响应示例
 ```json
 {"code":200,"message":"成功","data":null,"success":true}
 ```
 #### 空数据 / 降级响应
 成功时 `data=null`；请求体不能省略，也不提供降级成功。
 #### 错误响应
 ```json
 {"code":395005,"message":"当前状态不允许执行该操作","data":null,"success":false}
 ```
 #### 业务边界
 - 企微注册或主体状态审批为 `PENDING` 时，先于合同查询拒绝，不删除合同或新增审计记录。
 - 合同归属、可选版本、软删除及幂等规则不变。
 ### 5. 恢复合作 `POST /admin/supplier/items/{supplierId}/resume`
 **VO**: `SupplierStatusChangeReqVO → SupplierStatusChangeRespVO`
 #### 使用场景
 将没有在途主体审批的暂停合作供应商恢复合作。
 #### 入参
 | 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
 |---|---|---|---|---|---|
 | `supplierId` | Path | String | 是 | 正整数 | 供应商 ID |
 | `reason` | Body | String | 是 | 1～500 字符 | 恢复原因 |
 | `expectedUpdateTime` | Body | String | 是 | `yyyy-MM-dd HH:mm:ss` | 当前供应商版本 |
 #### 出参
 | 字段 | 类型 | 说明 |
 |---|---|---|
 | `data.status` / `data.statusName` | String | 成功后为 `ACTIVE` / “合作中” |
 | `data.updateTime` | String | 新并发版本 |
 #### 请求示例
 ```json
 {"reason":"恢复合作","expectedUpdateTime":"2026-09-04 10:00:00"}
 ```
 #### 响应示例
 ```json
 {"code":200,"message":"成功","data":{"supplierId":"2095000000000000003","status":"ACTIVE","statusName":"合作中","updateTime":"2026-09-04 10:04:00"},"success":true}
 ```
 #### 空数据 / 降级响应
 写接口无空成功结果，也不提供降级成功。
 #### 错误响应
 ```json
 {"code":395005,"message":"当前状态不允许执行该操作","data":null,"success":false}
 ```
 #### 业务边界
 - 暂停合作供应商已有企微主体状态审批时不得恢复合作，来源状态保持不变。
 - 原有权限、来源状态、并发、审计和幂等规则不变。
 ## 四、契约约束与正确调用方式
 - 后端以企微注册或主体状态审批 `PENDING` 为权威门禁；页面即使状态滞后，写请求仍可能返回 `395005`。
 - 前端展示和制灰统一读取列表或详情的 `statusName`；`status` 继续用于筛选和生命周期判断。
 - 账户新增和设默认接口的后端契约未变：注册审批中的 `VETTING`、状态审批来源的 `SUSPENDED` / `BLACKLIST` 均不满足账户写入所需的 `ACTIVE` 状态，仍返回既有 `395010`。
 - 详情、账户详情、审批记录和变更记录等读取入口保持可用；注册审批撤销 `POST /admin/supplier/items/{supplierId}/approval/revoke` 保持可用。
 ## 五、数据库行为
 - 本次没有数据库结构、初始化数据或迁移变化。
 - 审核中被拒绝的请求不修改供应商、账户、合同、状态或审计数据。
 ## 六、边界行为
 - 五类展示场景：注册、列入黑名单、解除黑名单、“终止且账清”和“拉黑且账清”在企微审核中均返回 `statusName="审核中"`。
 - 审批结束后刷新列表或详情，再按最终生命周期状态恢复原有可用操作。
 - 请求参数、成功响应、认证、权限、配置、Redis 和 MQ 契约均未改变。
 ## 六.6、修改前后对比
 | 行为 | 修改前 | 修改后 |
 |---|---|---|
 | 企微主体审批中修改供应商资料 | 部分入口可能继续写入 | 返回 `395005`，业务数据不变 |
 | 企微主体审批中新增、更新或删除合同 | 部分入口可能继续写入 | 返回 `395005`，业务数据不变 |
 | 状态审批中恢复合作 | 可能绕过审批候选来源状态 | 返回 `395005`，来源状态不变 |
 | 账户写入 | 既有规则要求供应商为 `ACTIVE` | 规则不变；前端在“审核中”时提前制灰 |
 | 详情与合法审批退出 | 可用 | 保持可用 |
 ## 六.7、影响评估
 - **是否破坏向后兼容**: 是；审批中的资料和合同写请求由可能成功调整为业务拒绝。
 - **前端是否必须同步上线**: 是。
 - **前端 workaround 清理点**: 不再仅按 `status` 放开写按钮，增加 `statusName="审核中"` 的统一制灰条件。
 ## 七、不影响范围
 - **仅影响**: 企微注册或主体状态审批中的供应商资料、账户、合同和冲突状态操作。
 - **零影响**: 详情及审批记录读取、注册审批撤销、企微回调与轮询、审批结束后的原有业务规则。
 - **无变化**: 请求/响应字段、错误码定义、数据库、配置、Redis、MQ；后端仓库未修改前端代码。
 ## 八、测试环境已验证
 部署提交：`6462397526ad61acfbcf503486d8507c9c1c7293`。
 ```text
 GET  /admin/supplier/items/list?limit=200                                      → 200；注册审批返回 VETTING / 审核中 ✓
 GET  /admin/supplier/items/{supplierId}/basic-info/view                        → 200；详情同为 VETTING / 审核中 ✓
 PUT  /admin/supplier/items/{supplierId}/update                                 → 395005 ✓
 POST /admin/supplier/items/{supplierId}/contracts/add                          → 395005 ✓
 PUT  /admin/supplier/items/{supplierId}/contracts/{contractId}/update           → 395005 ✓
 DELETE /admin/supplier/items/{supplierId}/contracts/{contractId}/del            → 395005 ✓
 POST /admin/supplier/items/{supplierId}/bank-accounts/add                       → 395010 ✓
 ```
 上述拒绝请求前后，供应商版本、账户、合同、审批和审计的只读数据库快照哈希一致。TEST 当前没有四类状态审批的在途样本，因此没有发起企微审批造数；对应子类型、来源状态、“审核中”投影及全部写入口由合并提交中的精确自动化测试覆盖。
 ## 十、相关文档
 - [Issue #7078](https://git.1814.love:8443/wx/HL/issues/7078)
 - [PR #7086](https://git.1814.love:8443/wx/HL/pulls/7086)
 - [前置展示契约 #7069](https://git.1814.love:8443/wx/HL/issues/7069)
 ## 前端动作与当前状态
 - `statusName="审核中"` 时，统一制灰供应商资料编辑/保存、账户新增/设默认、合同新增/编辑/删除，以及暂停、恢复、拉黑、解除拉黑和归档等冲突写入口。
 - 保留详情、审批记录、审批进度刷新和合法审批退出。
 - **当前状态：待前端处理。**
 ## 关联 / 联系人
 ### 链接
 - **Issue**: [#7078](https://git.1814.love:8443/wx/HL/issues/7078)
 - **PR**: [#7086](https://git.1814.love:8443/wx/HL/pulls/7086)
 - **Merge commit**: [6462397526ad61acfbcf503486d8507c9c1c7293](https://git.1814.love:8443/wx/HL/commit/6462397526ad61acfbcf503486d8507c9c1c7293)
 ### 联系人
 - **后端负责人**: @lc