docs: 景区改绑供应商免原因交接（#7274 #7357）

2026-09-09 09:47:07 +08:00
@@ -0,0 +1,144 @@
+---
+schema: "hl-changelog/v2"
+ticket: "7357"
+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: ""
+status_note: "后端已部署并验证；待前端移除景区改绑原因弹框。"
+updated_at: "2026-09-09"
+base: "dev-v3"
+---
+
+# 景区改绑供应商免变更原因
+
+## 一、关键变化
+
+景区改绑也可省略 `changeReason`。选择新供应商后直接提交，去掉“改绑供应商—变更原因”弹框；首次添加已完成的免原因行为继续保留。
+
+## 二、变更接口清单
+
+| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
+|---|---|---|---|---|---|
+| 1 | 设置或改绑供应商 | PUT | `/admin/supplier/resource-relations/{resourceModule}/{resourceId}/update` | 修改接口 | 景区改绑原因改为可选 |
+
+## 三、接口详情
+
+### 1. 设置或改绑供应商 `PUT /admin/supplier/resource-relations/{resourceModule}/{resourceId}/update`
+
+**VO**: `SupplierResourceReassignReqVO / SupplierResourceRelationRespVO`
+
+#### 使用场景
+
+景区管理选择目标供应商后提交添加或改绑。
+
+#### 入参
+
+| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
+|---|---|---|---|---|---|
+| `resourceModule` | Path | String | 是 | 景区为 `SCENIC` | 本次放宽仅适用于景区 |
+| `resourceId` | Path | String | 是 | 正整数 | 景区 ID |
+| `supplierId` | Body | String | 是 | 正整数 | 新供应商 ID |
+| `expectedCurrentSupplierId` | Body | String | 改绑必填 | 与版本时间成对提交 | 当前关系的供应商 ID |
+| `expectedRelationUpdateTime` | Body | String | 改绑必填 | `yyyy-MM-dd HH:mm:ss` | 当前关系的 `updateTime` |
+| `changeReason` | Body | String | 景区可省略 | 最长 500 字 | 省略、null、空串、空白均视为未填；无需补默认原因 |
+| `requiredTypeCode` | Body | String | 否 | 最长 64 字 | 景区可省略，由后端确定为 `SCENIC` |
+| `remark` | Body | String | 否 | 最长 500 字 | 关系备注，继续按原表单组装 |
+
+#### 出参
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `code` / `message` / `success` | Integer / String / Boolean | 业务结果 |
+| `data.relationId` / `supplierId` / `supplierNo` / `supplierName` | String | 生效关系及供应商标识、全称 |
+| `data.resourceModule` / `moduleName` / `resourceId` / `resourceName` | String | 资源模块及资源信息 |
+| `data.requiredTypeCode` / `requiredTypeName` | String | 要求的供应商类型 |
+| `data.remark` | String 或 null | 关系备注 |
+| `data.available` / `unavailableReasons` | Boolean / Array | 关系可用性及原因 |
+| `data.createTime` / `updateTime` | String | 关系时间；后续改绑使用最新 `updateTime` |
+
+#### 请求示例
+
+以下 ID 为示例，版本时间必须取当前关系返回值。
+
+```http
+PUT /admin/supplier/resource-relations/SCENIC/3001000000000000015/update
+Content-Type: application/json
+
+{"supplierId":"2000000000000000022","expectedCurrentSupplierId":"2000000000000000011","expectedRelationUpdateTime":"2026-09-09 10:00:00"}
+```
+
+#### 响应示例
+
+```json
+{"code":200,"message":"成功","success":true,"data":{"relationId":"2000000000000000031","supplierId":"2000000000000000022","supplierNo":"SUP2000000000000000022","supplierName":"示例新供应商","resourceModule":"SCENIC","moduleName":"景区管理","resourceId":"3001000000000000015","resourceName":"示例景区","requiredTypeCode":"SCENIC","requiredTypeName":"景区管理","remark":null,"available":true,"unavailableReasons":[],"createTime":"2026-09-09 10:01:00","updateTime":"2026-09-09 10:01:00"}}
+```
+
+#### 空数据 / 降级响应
+
+无空成功结果；校验失败返回 `data: null`、`success: false`。
+
+#### 错误响应
+
+```json
+{"code":395014,"message":"数据已被他人修改，请刷新后重试","data":null,"success":false}
+```
+
+#### 业务边界
+
+- 使用现有登录凭证及关系维护权限；目标供应商仍须符合既有状态、类型和资格要求。
+- 改绑须携带完整且最新的两个版本字段；过期返回 `395014`，不覆盖当前关系。原来携带原因的请求继续兼容。
+
+## 四、契约约束与正确调用方式
+
+改绑提交 `supplierId` 和两个 `expected*` 字段，可完全不传 `changeReason`。两个版本字段仅传一个会返回 `400`；已有关系却完全省略版本字段仍按原规则拒绝。
+
+## 五、数据库行为
+
+成功后切换当前供应商并保留新旧关系变更记录；未填原因记录为空，失败不改写关系。相同业务请求重放不产生重复变更。
+
+## 六、边界行为
+
+未登录返回 `401`；缺少目标供应商或原因超过 500 字返回 `400`。业务失败可能使用 HTTP 200，应同时判断响应体 `code` 和 `success`。
+
+## 六.6、修改前后对比
+
+| 场景 | 原来 | 现在 |
+|---|---|---|
+| 景区改绑 `changeReason` | 必填 | 可省略 |
+| 改绑关系版本 | 两字段必填 | 保持原规则 |
+
+## 六.7、影响评估
+
+- 向后兼容：是，原请求仍可使用。
+- 前端动作：移除景区改绑的原因弹框及必填校验，确定选择后直接调用接口；保留两个关系版本字段。
+
+## 七、不影响范围
+
+非景区添加/改绑、全部解绑的原因要求及现有响应字段保持原契约。
+
+## 八、测试环境已验证
+
+景区添加与改绑均完全省略 `changeReason` 成功，当前关系回读一致；原有携带原因的改绑请求成功。缺参、超长原因及旧关系版本均拒绝且零写入。
+
+**当前状态：后端已部署并验证；待前端处理。**
+
+## 九、相关历史 PR
+
+[#7282](https://git.1814.love:8443/wx/HL/pulls/7282) 的首次添加免原因仍有效；其中“景区改绑仍必填”的旧口径由本次补充替代。
+
+## 十、相关文档
+
+主工单 [#7274](https://git.1814.love:8443/wx/HL/issues/7274)，补充工单 [#7357](https://git.1814.love:8443/wx/HL/issues/7357)。
+
+## 关联 / 联系人
+
+- PR：[#7358](https://git.1814.love:8443/wx/HL/pulls/7358)
+- 后端负责人：@lc