From 95d178979377be70ed820fd0f51067345ea38860 Mon Sep 17 00:00:00 2001
From: lc <liuchang@1814.love>
Date: Thu, 10 Sep 2026 22:17:51 +0800
Subject: [PATCH] =?UTF-8?q?docs:=20=E4=BA=A4=E6=8E=A5=E9=A4=90=E5=8E=85?=
 =?UTF-8?q?=E4=BE=9B=E5=BA=94=E5=95=86=E5=85=B3=E7=B3=BB=E5=A5=91=E7=BA=A6?=
 =?UTF-8?q?=EF=BC=88#7387=EF=BC=89?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 ...Œ‰æ™¯åŒºå�£å¾„接入供应商关系-修改接å�£-管ç�†å�Žå�°.md | 463 ++++++++++++++++++
 1 file changed, 463 insertions(+)
 create mode 100644 changelogs-v2/2026-09/10_7387_�厅按景区�径接入供应商关系-修改接�-管���.md

diff --git a/changelogs-v2/2026-09/10_7387_�厅按景区�径接入供应商关系-修改接�-管���.md b/changelogs-v2/2026-09/10_7387_�厅按景区�径接入供应商关系-修改接�-管���.md
new file mode 100644
index 00000000..2a077678
--- /dev/null
+++ b/changelogs-v2/2026-09/10_7387_�厅按景区�径接入供应商关系-修改接�-管���.md
@@ -0,0 +1,463 @@
+---
+schema: "hl-changelog/v2"
+ticket: "7387"
+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: "�端已部署并� Gateway 验�；待�端展示�厅列表供应商全称并接入�厅供应商关系�作。"
+updated_at: "2026-09-10"
+base: "dev-v3"
+---
+
+# �厅管�：按景区�径接入供应商关系
+
+> **�务**: hl-resource-service（8082）
+> **PR**: #7493
+> **Issue**: #7387
+> **日期**: 2026-09-10
+> **影�范围**: 管�端�厅列表和�厅供应商查询�设置�改绑�解绑
+
+## ⚠� 关键�化
+
+- �厅列表��记录固定返回 `supplierFullName`；无当�供应商时为 `null`。
+- �厅使用通用资�供应商关系接�，路径�数固定传 `resourceModule=RESTAURANT`。
+- �厅首次绑定�改绑和解绑都�以�略 `changeReason`；真正改绑或解绑�会检查 V2�V3 订�，存在未结�订�时返回 `395060`。
+
+## 一�背景
+
+�厅管�此�无法从列表直接�得当�供应商全称，�端也未按�厅模�接入通用供应商关系�作。本次冻结�厅所需的展示字段�调用�数�原因规则和订�状�边界。
+
+## 二��更接�清�
+
+| # | 接� | 方法 | 路径 | �更类型 | 说明 |
+|---|---|---|---|---|---|
+| 1 | �厅列表 | GET | `/admin/restaurant/items` | �应字段新增 | ��记录固定返回 `supplierFullName` |
+| 2 | 查询�厅当�供应商 | GET | `/admin/supplier/resource-relations/{resourceModule}/{resourceId}/view` | 调用契约补充 | �厅传 `resourceModule=RESTAURANT` |
+| 3 | 设置或改绑�厅供应商 | PUT | `/admin/supplier/resource-relations/{resourceModule}/{resourceId}/update` | 请求与行为修改 | �厅��略原因；真正改绑增加未结�订�门� |
+| 4 | 解绑�厅供应商 | POST | `/admin/supplier/resource-relations/{resourceModule}/{resourceId}/unbind` | 行为修改 | �厅��略原因；增加未结�订�门� |
+
+## 三�接�详情
+
+### 1. �厅列表 `GET /admin/restaurant/items`
+
+**VO**: `RestaurantQueryRequest / PageResult<RestaurantAdminListVO>`
+
+#### 使用场景
+
+�厅管�列表�始化�翻页�筛选或刷新时调用；列表列直接读� `supplierFullName`。
+
+#### 入�
+
+| 字段 | �置 | 类型 | 必填 | 约� | 说明 |
+|---|---|---|---|---|---|
+| `keyword` | Query | String | � | 最长 100 字 | 按�称或副标题模糊查询 |
+| `categoryCode` | Query | String | � | 现有字典值 | �厅分类 |
+| `cuisineType` | Query | String | � | 现有字典值 | �系类型 |
+| `province` / `cityName` / `city` | Query | String | � | 现有规则 | 地区筛选 |
+| `status` | Query | Integer | � | `0` 下架，`1` 上架 | 状�筛选 |
+| `recommended` | Query | Integer | � | `0` �，`1` 是 | 推�筛选 |
+| `tagId` / `tagIds` | Query | String | � | `tagIds` 用逗�分隔 | 标签筛选 |
+| `sortBy` | Query | String | � | 最长 50 字 | 现有排�字段 |
+| `sortDir` | Query | String | � | `asc` 或 `desc` | 排�方� |
+| `page` | Query | Integer | � | 最� 1，默认 1 | 页� |
+| `pageSize` | Query | Integer | � | 1～100，默认 20 | �页�数 |
+
+#### 出� `Result<PageResult<RestaurantAdminListVO>>`
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `code` / `message` / `success` | Integer / String / Boolean | 业务结果 |
+| `data.total` / `page` / `pageSize` | Long / Integer / Integer | 分页信� |
+| `data.records[].restaurantId` | String | �厅 ID |
+| `data.records[].name` | String | �厅�称 |
+| `data.records[].supplierFullName` | String 或 null | 当�有效供应商的法定全称；未关�或供应商已删除时为 `null`，字段始终存在 |
+| `data.records[]` 其他字段 | Object | 原�厅列表字段���� |
+
+#### 请求示例
+
+```http
+GET /admin/restaurant/items?page=1&pageSize=20&sortDir=desc HTTP/1.1
+```
+
+#### �应示例
+
+```json
+{
+  "code": 200,
+  "message": "�功",
+  "success": true,
+  "data": {
+    "total": 2,
+    "page": 1,
+    "pageSize": 20,
+    "records": [
+      {
+        "restaurantId": "2023382100664676353",
+        "name": "示例�厅 A",
+        "status": 1,
+        "supplierFullName": "示例�饮供应商有�公�"
+      },
+      {
+        "restaurantId": "2023382106075328513",
+        "name": "示例�厅 B",
+        "status": 1,
+        "supplierFullName": null
+      }
+    ]
+  }
+}
+```
+
+#### 空数� / �级�应
+
+```json
+{"code":200,"message":"�功","success":true,"data":{"total":0,"page":1,"pageSize":20,"records":[]}}
+```
+
+#### 错误�应
+
+```json
+{"code":401,"message":"缺少有效的 Authorization 头","success":false,"data":null}
+```
+
+#### 业务边界
+
+- 本次�新增筛选�排�或分页规则；`supplierFullName` �用于展示，�是供应商�称快照。
+- 供应商改��返回当�全称；无当�有效关系时必须按 `null` 处�，��根�字段是�存在分支。
+
+### 2. 查询�厅当�供应商 `GET /admin/supplier/resource-relations/{resourceModule}/{resourceId}/view`
+
+**VO**: `SupplierResourceRelationRespVO`
+
+#### 使用场景
+
+打开�厅供应商弹窗或在写�作�刷新当�关系时调用。
+
+#### 入�
+
+| 字段 | �置 | 类型 | 必填 | 约� | 说明 |
+|---|---|---|---|---|---|
+| `resourceModule` | Path | String | 是 | �厅固定为 `RESTAURANT` | 资�模� |
+| `resourceId` | Path | String | 是 | 正整数 | �厅 ID |
+
+#### 出� `Result<SupplierResourceRelationRespVO>`
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `code` / `message` / `success` | Integer / String / Boolean | 业务结果 |
+| `data.relationId` | String | 当�关系 ID |
+| `data.supplierId` / `supplierNo` / `supplierName` | String | 当�供应商 ID�编�和全称 |
+| `data.resourceModule` / `moduleName` | String | `RESTAURANT` / �厅管� |
+| `data.resourceId` / `resourceName` | String | �厅 ID 和�称 |
+| `data.requiredTypeCode` / `requiredTypeName` | String | `RESTAURANT` / �厅管� |
+| `data.remark` | String 或 null | 关系备注 |
+| `data.available` / `unavailableReasons` | Boolean / Array | 当�关系是���用���用原因 |
+| `data.createTime` / `updateTime` | String | `yyyy-MM-dd HH:mm:ss`；写�作使用最新 `updateTime` |
+
+#### 请求示例
+
+```http
+GET /admin/supplier/resource-relations/RESTAURANT/2023382100664676353/view HTTP/1.1
+```
+
+#### �应示例
+
+```json
+{
+  "code": 200,
+  "message": "�功",
+  "success": true,
+  "data": {
+    "relationId": "2098015198429298690",
+    "supplierId": "2097899397319684098",
+    "supplierNo": "SUP2097899397319684098",
+    "supplierName": "示例�饮供应商有�公�",
+    "resourceModule": "RESTAURANT",
+    "moduleName": "�厅管�",
+    "resourceId": "2023382100664676353",
+    "resourceName": "示例�厅 A",
+    "requiredTypeCode": "RESTAURANT",
+    "requiredTypeName": "�厅管�",
+    "remark": null,
+    "available": true,
+    "unavailableReasons": [],
+    "createTime": "2026-09-10 20:00:00",
+    "updateTime": "2026-09-10 20:00:00"
+  }
+}
+```
+
+#### 空数� / �级�应
+
+当�没有有效关系时�是空�功，返回 `395038`。
+
+#### 错误�应
+
+```json
+{"code":395038,"message":"供应商资�关��存在","success":false,"data":null}
+```
+
+#### 业务边界
+
+- 使用现有登录凭�� `supplier:resource:view` �务端��；�端按钮��性�能替代�端判�。
+- 未关�时按 `395038` 展示“未设置供应商�；��把它当�系统异常。
+
+### 3. 设置或改绑�厅供应商 `PUT /admin/supplier/resource-relations/{resourceModule}/{resourceId}/update`
+
+**VO**: `SupplierResourceReassignReqVO / SupplierResourceRelationRespVO`
+
+#### 使用场景
+
+�厅当�无关系时首次设置供应商，或选择�一供应商�改绑。
+
+#### 入�
+
+| 字段 | �置 | 类型 | 必填 | 约� | 说明 |
+|---|---|---|---|---|---|
+| `resourceModule` | Path | String | 是 | �厅固定为 `RESTAURANT` | 资�模� |
+| `resourceId` | Path | String | 是 | 正整数 | �厅 ID |
+| `supplierId` | Body | String | 是 | 正整数 | 目标供应商 ID |
+| `requiredTypeCode` | Body | String | � | �厅��略；传值�能为 `RESTAURANT` | 关系�求的供应商类型 |
+| `remark` | Body | String | � | 最长 500 字 | 关系备注 |
+| `expectedCurrentSupplierId` | Body | String | 改绑时是 | 与版本时间�时传或�时�略 | 当�关系的 `supplierId` |
+| `expectedRelationUpdateTime` | Body | String | 改绑时是 | `yyyy-MM-dd HH:mm:ss` | 当�关系的 `updateTime` |
+| `changeReason` | Body | String | � | 最长 500 字 | �厅首次设置和改绑���略；��补默认原因 |
+
+#### 出� `Result<SupplierResourceRelationRespVO>`
+
+| 字段 | 类型 | 说明 |
+|---|---|---|
+| `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 | 当�关系时间与�续�作版本 |
+
+#### 请求示例
+
+首次绑定时��传两个 `expected*` 字段：
+
+```json
+{"supplierId":"2097899397319684098"}
+```
+
+改绑时两个版本字段必须�自最新关系回读；�以�传 `changeReason`：
+
+```json
+{"supplierId":"2097849575707475969","expectedCurrentSupplierId":"2097899397319684098","expectedRelationUpdateTime":"2026-09-10 20:00:00"}
+```
+
+#### �应示例
+
+```json
+{
+  "code": 200,
+  "message": "�功",
+  "success": true,
+  "data": {
+    "relationId": "2098100000000000001",
+    "supplierId": "2097849575707475969",
+    "supplierNo": "SUP2097849575707475969",
+    "supplierName": "示例新�饮供应商有�公�",
+    "resourceModule": "RESTAURANT",
+    "moduleName": "�厅管�",
+    "resourceId": "2023382100664676353",
+    "resourceName": "示例�厅 A",
+    "requiredTypeCode": "RESTAURANT",
+    "requiredTypeName": "�厅管�",
+    "remark": null,
+    "available": true,
+    "unavailableReasons": [],
+    "createTime": "2026-09-10 20:01:00",
+    "updateTime": "2026-09-10 20:01:00"
+  }
+}
+```
+
+#### 空数� / �级�应
+
+无空�功结果；订��务���或字典等必��赖无法明确核验时返回失败且�改�关系。
+
+#### 错误�应
+
+```json
+{"code":395060,"message":"�厅已关�订�，�能更�供应商","success":false,"data":null}
+```
+
+#### 业务边界
+
+- 当�无关系时是首次绑定：�传版本对；�使�厅已有订�也�许绑定。
+- 当�有关系且目标供应商���是真正改绑：必须传完整�最新版本对；仅关� `COMPLETED`�`CANCELLED` 订�（包括两者混�）时�许，存在其他状�时返回 `395060`，原关系��。
+- 目标与当�供应商相�且其他业务字段未�时沿用无�化返回；目标供应商�须满足�作状���厅类型和资格�求。
+- 版本过期返回 `395014`；必��赖无法明确判断返回 `395039`；失败�改�关系或审计。
+
+### 4. 解绑�厅供应商 `POST /admin/supplier/resource-relations/{resourceModule}/{resourceId}/unbind`
+
+**VO**: `SupplierResourceUnbindReqVO / Result<Void>`
+
+#### 使用场景
+
+用户确认清除�厅当�供应商关系时调用。
+
+#### 入�
+
+| 字段 | �置 | 类型 | 必填 | 约� | 说明 |
+|---|---|---|---|---|---|
+| `resourceModule` | Path | String | 是 | �厅固定为 `RESTAURANT` | 资�模� |
+| `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 | �功时固定为 `null` |
+
+#### 请求示例
+
+```json
+{"expectedCurrentSupplierId":"2097849575707475969","expectedRelationUpdateTime":"2026-09-10 20:01:00"}
+```
+
+#### �应示例
+
+```json
+{"code":200,"message":"�功","success":true,"data":null}
+```
+
+#### 空数� / �级�应
+
+当�无关系时返回 `395038`；必��赖无法明确核验时返回 `395039`，��执行解绑。
+
+#### 错误�应
+
+```json
+{"code":395060,"message":"�厅已关�订�，�能更�供应商","success":false,"data":null}
+```
+
+#### 业务边界
+
+- 解绑必须使用当�关系最新版本对；版本过期返回 `395014`，原关系��。
+- 仅关� `COMPLETED`�`CANCELLED` 订�（包括两者混�）时�许解绑；存在其他状�时返回 `395060`。
+- 登录�`supplier:resource:manage` �务端���数�范围�幂等��和审计规则����；失败零写入。
+
+## 四�契约约�与正确调用方�
+
+| 场景 | 正确 payload | 调用结果 |
+|---|---|---|
+| 查询当�关系 | 无请求体，`resourceModule=RESTAURANT` | 返回关系；无关系为 `395038` |
+| 首次绑定 | `{"supplierId":"22"}` | �传版本对，��略 `changeReason` |
+| 改绑 | `{"supplierId":"33","expectedCurrentSupplierId":"22","expectedRelationUpdateTime":"2026-09-10 20:00:00"}` | 两个版本字段必须�对且�最新关系值 |
+| 解绑 | `{"expectedCurrentSupplierId":"33","expectedRelationUpdateTime":"2026-09-10 20:01:00"}` | ��略 `changeReason` |
+| 错误：版本字段�传一个 | `{"supplierId":"33","expectedCurrentSupplierId":"22"}` | 返回 `400`，�写入 |
+
+�次改绑或解绑�先回读当�关系，�功��新刷新关系和�厅列表。业务失败�能�为 HTTP 200，必须�时判断�应体 `code` 与 `success`。
+
+## 五�数�库行为
+
+| �端�作 | 外部�观察结果 |
+|---|---|
+| 首次绑定 | 生�一个当�有效关系；未填原因时�虚构默认原因 |
+| 改绑 | 旧关系转为历�，新供应商�为唯一当�关系，并�留正常�更审计 |
+| 解绑 | 当�关系消失并�留正常解绑审计；�厅列表返回 `supplierFullName: null` |
+| 订��版本���或资格校验失败 | 当�关系和审计���化 |
+
+本次��移或回填任何数�，�修改订�业务�订�数�或订�供应商快照。
+
+## 六�边界行为
+
+- 未登录返回 `401`；关系查询�求查看��，设置�改绑�解绑�求维护���对应数�范围。
+- �厅未绑定供应商时，列表返回 `supplierFullName: null`，关系查询返回 `395038`。
+- `changeReason` 最长 500 字；�略�`null`�空串或纯空白�按未填写处�。
+- 未结�订�包�除 `COMPLETED`�`CANCELLED` 以外的状�以�未知状�；V2 或 V3 任一�务确认存在�返回 `395060`。
+- 无法从任一订��务得到明确结果时返回 `395039`，�把�赖异常当�无订�。
+
+## 六.5�枚举 / 数�字典
+
+### `resourceModule` / `requiredTypeCode`（�厅供应商关系）
+
+**所属字段**: Path `resourceModule`�Body/Response `requiredTypeCode` | **类型**: `String`
+
+| 值 | 中文 | 说明 |
+|---|---|---|
+| `RESTAURANT` | �厅管� | �厅关系固定值；`requiredTypeCode` ��略并由�端确定 |
+
+## 六.6�修改��对比
+
+### 字段级对比
+
+| 字段 | 改� | 改� |
+|---|---|---|
+| `GET /admin/restaurant/items` 的 `records[].supplierFullName` | �返回 | ��固定返回 `String` 或 `null` |
+| �厅设置/改绑的 `changeReason` | 必填 | ��略；原有�空值继续兼容 |
+| �厅解绑的 `changeReason` | 已��略 | ����略 |
+
+### 行为级对比
+
+| 行为 | 改� | 改� |
+|---|---|---|
+| �厅列表展示供应商 | 需�外�关系且列表无�称字段 | 直接读� `supplierFullName` |
+| �厅真正改绑�解绑 | �检查�厅订� | 仅完�/�消订�放行；其他状�返回 `395060` |
+| 尚未绑定供应商的�厅 | �首次绑定 | ���首次绑定，�使已有订� |
+
+## 六.7�影�评估
+
+- **是�破���兼容**: �；仅新增�空�应字段�放宽�选入�并增加业务�护。
+- **�端是�必须�步上线**: 是。
+- **�端 workaround 清�点**: �厅列表直接展示 `supplierFullName`；�用供应商关系弹窗并传 `RESTAURANT`；删除�厅设置�改绑�解绑的原因弹框和必填校验；收到 `395060` 时�示原文并��当�关系。
+
+## 七��影�范围
+
+- **仅影�**: 管�端�厅列表��厅供应商关系�作。
+- **零影�**: 订�创建�状��转�结算�支付�退款�订�数�和订�供应商快照。
+- 景区�其他资�模�的字段�原因规则和订�门���原契约；数�库结构��置�Redis�MQ 和 Gateway 路由无�化。
+
+## 八�测试环境已验�
+
+- `GET /admin/restaurant/items`：HTTP 200�业务� 200；当�页��记录�� `supplierFullName`，�时实测�空全称与 `null`。
+- `GET /admin/supplier/resource-relations/RESTAURANT/{resourceId}/view`：已绑定关系返回 200；未绑定关系返回 `395038`；匿�请求返回业务� 401。
+- `PUT .../update` 与 `POST .../unbind`：完全�略 `changeReason` 的改绑�解绑和�次首次绑定��功，列表与关系回读�步；验收�原供应商�类型和备注已��。
+- 两版订��行程� V3 产�快照在验收��的�读摘�一致；完���消�混�放行�未结��入� `395060` 零写入�已有订�首次绑定由隔离 MySQL/资�门�测试覆盖。
+
+**当�状�：�端已部署并验�；待�端处�。**
+
+## ��相关历� PR
+
+| PR | Issue | 说明 | 是��有效 |
+|---|---|---|---|
+| #6315 | #6313 | 景区列表增加 `supplierFullName` | 是，�厅沿用相�字段语义 |
+| #7282 | #7274 | 景区首次设置供应商�原因 | 是 |
+| #7358 | #7357 | 景区改绑供应商�原因 | 是 |
+| #7401 | #7400 | 全部资�供应商解绑�原因 | 是 |
+| **#7493** | **#7387** | �厅列表�原因规则与订�门� | **是，�厅最新契约** |
+
+## ��相关文档
+
+- 关� Issue：[#7387](https://git.1814.love:8443/wx/HL/issues/7387)
+- �端 PR：[#7493](https://git.1814.love:8443/wx/HL/pulls/7493)
+- �并�交：[33b994d](https://git.1814.love:8443/wx/HL/commit/33b994deb2345cdda614144d03f9f1e2d3958c76)
+
+## 关� / �系人
+
+### 链接
+
+- **Issue**: [#7387](https://git.1814.love:8443/wx/HL/issues/7387)
+- **PR**: [#7493](https://git.1814.love:8443/wx/HL/pulls/7493)
+- **Merge commit**: [33b994d](https://git.1814.love:8443/wx/HL/commit/33b994deb2345cdda614144d03f9f1e2d3958c76)
+
+### �系人
+
+- **�端负责人**: @lc