@@ -0,0 +1,175 @@
|
||||
---
|
||||
schema: "hl-changelog/v2"
|
||||
ticket: "7274"
|
||||
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: "后端已部署并通过 TEST Gateway 验证；景区首次设置可省略原因。当前状态：待前端移除“设置供应商”原因弹框并在确定选择后直接提交。"
|
||||
updated_at: "2026-09-07"
|
||||
base: "dev-v3"
|
||||
---
|
||||
|
||||
# 景区管理：首次设置供应商免变更原因
|
||||
|
||||
## 一、关键变化
|
||||
|
||||
景区尚未绑定供应商时，用户选择供应商并点击“确定选择”后应直接调用设置接口；不再打开“设置供应商”变更原因弹框，也不需要提交 `changeReason`。
|
||||
|
||||
## 二、变更接口清单
|
||||
|
||||
| # | 接口 | 方法 | 路径 | 变更类型 | 说明 |
|
||||
|---|---|---|---|---|---|
|
||||
| 1 | 设置或改绑资源供应商 | PUT | `/admin/supplier/resource-relations/{resourceModule}/{resourceId}/update` | 请求必填性调整 | 仅 `SCENIC` 首次设置允许省略 `changeReason` |
|
||||
|
||||
## 三、接口详情
|
||||
|
||||
### 1. 设置或改绑资源供应商 `PUT /admin/supplier/resource-relations/{resourceModule}/{resourceId}/update`
|
||||
|
||||
**VO**: `SupplierResourceReassignReqVO / SupplierResourceRelationRespVO`
|
||||
|
||||
#### 使用场景
|
||||
|
||||
景区管理选择候选供应商后，首次设置直接提交；同一路径继续兼容原有改绑流程。
|
||||
|
||||
#### 入参
|
||||
|
||||
| 字段 | 位置 | 类型 | 必填 | 约束 | 说明 |
|
||||
|---|---|---|---|---|---|
|
||||
| `resourceModule` | Path | String | 是 | 景区固定为 `SCENIC` | 当前资源模块 |
|
||||
| `resourceId` | Path | String | 是 | 正整数 | 景区 ID |
|
||||
| `supplierId` | Body | String | 是 | 正整数 | 选中的供应商 ID |
|
||||
| `changeReason` | Body | String | 条件必填 | 最长 500 字 | `SCENIC` 首次设置可省略；景区改绑及其他资源设置/改绑仍必填 |
|
||||
| `expectedCurrentSupplierId` | Body | String | 改绑必填 | 与版本时间同传 | 当前关系供应商 ID |
|
||||
| `expectedRelationUpdateTime` | Body | String | 改绑必填 | `yyyy-MM-dd HH:mm:ss` | 当前关系的 `updateTime` |
|
||||
| `requiredTypeCode` | Body | String | 否 | 最长 64 字 | 景区沿用既有规则，可省略 |
|
||||
| `remark` | Body | String | 否 | 最长 500 字 | 关系备注 |
|
||||
|
||||
#### 出参
|
||||
|
||||
| 字段 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| `data.relationId` | String | 当前关系 ID |
|
||||
| `data.supplierId` / `supplierName` | String | 生效供应商 ID / 全称 |
|
||||
| `data.resourceModule` / `resourceId` | String | 资源模块 / 资源 ID |
|
||||
| `data.requiredTypeCode` | String | 景区为 `SCENIC` |
|
||||
| `data.available` / `unavailableReasons` | Boolean / Array | 当前可用性及原因 |
|
||||
| `data.updateTime` | String | 后续改绑或解绑使用的关系版本 |
|
||||
| 其他既有字段 | - | 响应字段和语义均未变化 |
|
||||
|
||||
#### 请求示例
|
||||
|
||||
```http
|
||||
PUT /admin/supplier/resource-relations/SCENIC/3001000000000000015/update
|
||||
Authorization: Bearer <当前有效凭证>
|
||||
Content-Type: application/json
|
||||
|
||||
{"supplierId":"2094247871271350274"}
|
||||
```
|
||||
|
||||
#### 响应示例
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 200,
|
||||
"message": "成功",
|
||||
"data": {
|
||||
"relationId": "2096882924480589826",
|
||||
"supplierId": "2094247871271350274",
|
||||
"supplierNo": "SUP2094247871271350274",
|
||||
"supplierName": "示例景区供应商",
|
||||
"resourceModule": "SCENIC",
|
||||
"moduleName": "景区管理",
|
||||
"resourceId": "3001000000000000015",
|
||||
"resourceName": "示例景区",
|
||||
"requiredTypeCode": "SCENIC",
|
||||
"requiredTypeName": "景区管理",
|
||||
"remark": null,
|
||||
"available": true,
|
||||
"unavailableReasons": [],
|
||||
"createTime": "2026-09-07 16:47:02",
|
||||
"updateTime": "2026-09-07 16:47:02"
|
||||
},
|
||||
"success": true
|
||||
}
|
||||
```
|
||||
|
||||
#### 空数据 / 降级响应
|
||||
|
||||
没有空成功数据；校验或依赖失败时返回业务错误和 `data: null`，不会降级为成功，也不会创建或改写关系。
|
||||
|
||||
#### 错误响应
|
||||
|
||||
```json
|
||||
{"code":400,"message":"changeReason不能为空","data":null,"success":false}
|
||||
```
|
||||
|
||||
#### 业务边界
|
||||
|
||||
- 只有 `SCENIC` 且当前无供应商关系的首次设置可省略 `changeReason`。
|
||||
- 景区改绑仍须提交两个并发版本字段和非空原因；其他资源设置/改绑与所有解绑行为不变。
|
||||
- 权限、资源数据范围、供应商状态与资格门禁不变。
|
||||
|
||||
## 四、契约约束与正确调用方式
|
||||
|
||||
- 当前资源模块为 `SCENIC` 且没有现有关系时，供应商选择器点击“确定选择”后立即提交上述 PUT，请求体不要补默认原因或空原因。
|
||||
- 提交成功后结束设置流程，不再打开 `SupplierRelationModal` 中的“设置供应商”原因弹框。
|
||||
- 景区已有关系时仍按改绑流程提交两个并发版本字段和非空 `changeReason`。
|
||||
- 非景区资源的首次设置、改绑，以及所有资源的解绑流程均保持原原因校验和弹框行为。
|
||||
|
||||
## 五、数据库行为
|
||||
|
||||
首次设置成功后可立即查询到当前关系，并追加一条原因为空的关系变更审计；后端不会生成默认或伪造原因。校验失败时关系与审计均不变化。本次没有表结构或存量数据迁移。
|
||||
|
||||
## 六、边界行为
|
||||
|
||||
- 景区显式改绑省略 `changeReason`：`code=400`、`success=false`，消息为 `changeReason不能为空`。
|
||||
- 未登录：应用响应 `code=401`、`success=false`。
|
||||
- 业务错误可能仍使用 HTTP 200，调用方必须同时判断响应体 `code` 和 `success`。
|
||||
- 无新增响应字段、错误码、枚举或接口路径。
|
||||
|
||||
## 六.6、修改前后对比
|
||||
|
||||
| 场景 | 修改前 | 修改后 |
|
||||
|---|---|---|
|
||||
| `SCENIC` 首次设置 | 原因必填，确定选择后打开原因弹框 | 原因可省略，确定选择后直接完成设置 |
|
||||
| `SCENIC` 改绑 | 原因与并发版本必填 | 不变 |
|
||||
| 其他资源设置/改绑、解绑 | 原因必填 | 不变 |
|
||||
|
||||
## 六.7、影响评估
|
||||
|
||||
- **是否破坏向后兼容**: 否；原有携带原因的请求仍可用。
|
||||
- **前端是否必须同步上线**: 是；后端无法移除前端主动打开的弹框。
|
||||
- **前端 workaround 清理点**: 景区无现有关系时，删除“确定选择后打开原因弹框”的步骤并直接提交。
|
||||
|
||||
## 七、不影响范围
|
||||
|
||||
- **仅影响**: 管理后台景区首次设置供应商。
|
||||
- **零影响**: 景区改绑、其他资源设置/改绑、所有解绑、响应字段、错误码和小程序接口。
|
||||
|
||||
## 八、测试环境已验证
|
||||
|
||||
- 首次设置请求完全省略 `changeReason`，返回 `code=200`，关系查询与空原因审计一致。
|
||||
- 匿名设置返回 `401`；景区显式改绑省略原因返回 `400`，失败路径零写入。
|
||||
- 测试关系已解绑并回读恢复为未绑定状态。
|
||||
|
||||
**当前状态：后端已部署并验证；待前端处理。**
|
||||
|
||||
## 十、相关文档
|
||||
|
||||
- [Issue #7274](https://git.1814.love:8443/wx/HL/issues/7274)
|
||||
- [PR #7282](https://git.1814.love:8443/wx/HL/pulls/7282)
|
||||
|
||||
## 关联 / 联系人
|
||||
|
||||
- **Issue**: [#7274](https://git.1814.love:8443/wx/HL/issues/7274)
|
||||
- **PR**: [#7282](https://git.1814.love:8443/wx/HL/pulls/7282)
|
||||
- **Merge commit**: [86286f5fdfac0b5e097bf36ab0ac4be757aeaac0](https://git.1814.love:8443/wx/HL/commit/86286f5fdfac0b5e097bf36ab0ac4be757aeaac0)
|
||||
- **后端负责人**: @lc
|
||||
在新工单中引用
屏蔽一个用户