docs(changelogs-v2): #7400 供应商解绑免原因

2026-09-09 21:39:43 +08:00
@@ -0,0 +1,148 @@
+---
+schema: "hl-changelog/v2"
+ticket: "7400"
+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-09"
+status_note: "后端已部署并经 TEST Gateway 验证；前端需移除资源供应商解绑原因弹框，直接提交关系版本字段。"
+updated_at: "2026-09-09"
+base: "dev-v3"
+---
+
+# 资源供应商解绑免原因
+
+## ⚠️ 关键变化
+
+资源管理解绑供应商时，`changeReason` 由必填改为可选；前端无需再弹出原因输入框，也不要补写默认原因。
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|---|---|---|---|---|
+| 1 | 解除资源供应商 | POST | `/admin/supplier/resource-relations/{resourceModule}/{resourceId}/unbind` | 修改接口 | `changeReason` 改为可选 |
+
+## 三、接口详情
+
+### 1. 解除资源供应商 `POST /admin/supplier/resource-relations/{resourceModule}/{resourceId}/unbind`
+
+**VO**: `SupplierResourceUnbindReqVO / Result<Void>`
+
+#### 使用场景
+
+资源管理页面确认解除当前供应商关系时调用。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|---|
+| `resourceModule` | Path | String | 是 | 现有资源模块编码 | 资源模块 |
+| `resourceId` | Path | String | 是 | 正整数 | 资源 ID |
+| `expectedCurrentSupplierId` | Body | String | 是 | 正整数 | 当前关系返回的 `supplierId` |
+| `expectedRelationUpdateTime` | Body | String | 是 | `yyyy-MM-dd HH:mm:ss` | 当前关系返回的 `updateTime` |
+| `changeReason` | Body | String | 否 | 最长 500 字 | 省略、`null`、空串或空白均视为未填写 |
+
+#### 出参 `Result<Void>`
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `code` / `message` / `success` | Integer / String / Boolean | 业务结果 |
+| `data` | null | 成功时固定为空 |
+
+#### 请求示例
+
+```json
+{"expectedCurrentSupplierId":"2000000000000000022","expectedRelationUpdateTime":"2026-09-09 10:01:00"}
+```
+
+#### 响应示例
+
+```json
+{"code":200,"message":"成功","data":null,"success":true}
+```
+
+#### 空数据 / 降级响应
+
+无空成功集合；关系不存在或必要依赖不可用时返回失败结果，不执行解绑。
+
+#### 错误响应
+
+```json
+{"code":395014,"message":"数据已被他人修改，请刷新后重试","data":null,"success":false}
+```
+
+#### 业务边界
+
+- 未登录返回 `401`；缺少任一版本字段或原因超过 500 字返回 `400`；关系不存在返回 `395038`。
+- 权限、数据范围、景区未完成订单门禁、幂等、并发版本与软删除规则不变；失败不改写关系或审计。
+
+## 四、契约约束与正确调用方式
+
+用户确认解绑后，直接提交当前关系的两个版本字段：
+
+| 场景 | payload |
+|---|---|
+| 正确：省略原因 | `{"expectedCurrentSupplierId":"22","expectedRelationUpdateTime":"2026-09-09 10:01:00"}` |
+| 兼容：继续传原因 | `{"expectedCurrentSupplierId":"22","expectedRelationUpdateTime":"2026-09-09 10:01:00","changeReason":"业务调整"}` |
+| 错误：缺版本时间 | `{"expectedCurrentSupplierId":"22"}` → `400` |
+
+关系版本已变化返回 `395014`，应刷新当前关系后再由用户重试。业务失败可能仍为 HTTP 200，须判断响应体 `code` 和 `success`。
+
+## 五、数据库行为
+
+成功解绑仍按原逻辑软删除当前关系并追加供应商变更审计；省略原因时 `supplier_change_log.change_reason` 记录为 `NULL`，非空原因继续原样审计。无表结构或迁移变化。
+
+## 六、边界行为
+
+- `changeReason` 省略、`null`、空串或纯空白均可解绑，且不生成虚构默认值。
+- `changeReason` 最长 500 字；501 字返回 `400` 且零写入。
+- 两个 `expected*` 字段仍必填；陈旧版本返回 `395014` 且零写入。
+- 景区已有未完成订单时继续按既有规则返回 `395059`，不允许解绑。
+
+## 六.6、修改前后对比
+
+| 字段 / 行为 | 改前 | 改后 |
+|---|---|---|
+| `changeReason` | 必填 | 可省略；非空请求继续兼容 |
+| 关系版本、权限与业务门禁 | 必须满足 | 不变 |
+
+## 六.7、影响评估
+
+- **是否破坏向后兼容**: 否。
+- **前端是否必须同步上线**: 是，移除解绑原因弹框及必填校验。
+- **前端 workaround 清理点**: 删除为了满足旧契约而填写或生成解绑原因的逻辑。
+
+## 七、不影响范围
+
+- 仅影响资源供应商解绑请求的 `changeReason` 必填性。
+- 设置与改绑契约、响应字段、错误码数值、数据库结构、Redis、MQ、Feign 和网关路由均不变。
+
+## 八、测试环境已验证
+
+TEST Gateway 已验证省略原因的解绑成功并恢复原关系基线；匿名、缺版本、501 字原因及陈旧版本请求均被拒绝且零写入，原有携带原因的解绑继续成功。
+
+**当前状态：后端已交付，待前端处理。**
+
+## 九、相关历史 PR
+
+| PR | Issue | 说明 | 是否仍有效 |
+|---|---|---|---|
+| #7358 | #7357 | 景区设置及改绑免原因，不覆盖解绑 | 是 |
+| #7401 | #7400 | 全部资源供应商解绑免原因 | 是，最新 |
+
+## 十、相关文档
+
+- 关联工单：[#7400](https://git.1814.love:8443/wx/HL/issues/7400)
+- 后端 PR：[#7401](https://git.1814.love:8443/wx/HL/pulls/7401)
+
+## 关联 / 联系人
+
+- Merge commit：[49a05cfb](https://git.1814.love:8443/wx/HL/commit/49a05cfb83723ae9d72471c1927cf034961a5010)
+- 后端负责人：@lc