---
schema: "hl-changelog/v2"
ticket: "6316"
title: "供应商详情新增资源信息分页"
consumer: "admin"
author: "lc(GIT)"
change_type: "新增接口"
backend_status: "deployed"
gateway_status: "verified"
frontend_status: "verified"
frontend_owner: "mmg"
frontend_ref: "de665364"
target_release: ""
verified_at: "2026-08-25"
status_note: "PR #6330 已合并 dev-v3，合并提交 4f032cd6f 已由任务 cc1fe248、2697d374 精确发布 Resource/Fleet 至 TEST 并经真实 Gateway 只读验收；验收后任务 45e843e5、c05eda6e 已回切包含该提交的 dev-v3，两个服务均保持双实例健康。"
updated_at: "2026-08-25"
base: "dev-v3"
---

# 供应商详情新增资源信息分页

供应商详情新增只读“资源信息”分页接口。数据以本系统 `supplier_resource_rel` 当前有效关系为入口，展示 Resource 本地九类资源及 Fleet 车辆的当前权威信息；供应商关系已保留但资源已删除时返回缺失占位，避免详情悄然丢行。

## 变更接口

| 方法 | 路径 | 用途 |
|---|---|---|
| GET | `/admin/supplier/items/{supplierId}/resource-info/page` | 分页查询供应商当前有效关系对应的资源信息 |

查询参数：

| 参数 | 类型 | 必填 | 默认/约束 | 说明 |
|---|---|---:|---|---|
| `supplierId` | string | 是 | 正整数 | 路径参数，Snowflake ID 按字符串处理 |
| `page` | integer | 否 | 默认 `1`，最小 `1` | 页码；兼容公共分页参数 `pageNo` |
| `pageSize` | integer | 否 | 默认 `20`，范围 `1..100` | 每页条数 |
| `resourceModule` | string | 否 | 十选一 | 按关系冻结的资源模块精确筛选 |

支持模块：`SCENIC`、`RESTAURANT`、`SUPPLIES`、`SUPPLIES_COMBO`、`ACTIVITY`、`HOTEL`、`SERVICE`、`COST_ITEM`、`STAFF`、`VEHICLE`。

## 返回字段

分页 `data` 使用统一 `PageResult`：`records`、`total`、`page`、`pageSize`。`records[]` 字段如下：

| 字段 | JSON 类型 | 语义 |
|---|---|---|
| `relationId` | string | 供应商资源关系 ID |
| `resourceModule` | string | 冻结模块编码 |
| `moduleName` | string | 模块中文名 |
| `resourceId` | string | 资源 ID；资源缺失时仍保留关系原值 |
| `resourceName` | string/null | 当前资源名称 |
| `coverUrl` | string/null | 当前有效封面 URL |
| `city` | string/null | 城市展示值 |
| `isCharged` | boolean/null | 是否收费 |
| `isChargedName` | string/null | 是否收费中文名 |
| `settleTypeCode` | string/null | 结算方式编码 |
| `settleTypeName` | string/null | 结算方式中文名 |
| `tags` | array | 标签数组，永不返回 `null` |
| `seasons` | array | 标准季节数组，永不返回 `null` |
| `statusCode` | string/null | 资源当前权威状态编码 |
| `statusName` | string/null | 归一化状态中文名 |
| `enabled` | boolean/null | 归一化启用状态 |
| `resourceAvailable` | boolean | 资源当前是否存在；`false` 为关系保留、资源缺失 |
| `updateTime` | string/null | 资源本身更新时间，格式 `yyyy-MM-dd HH:mm:ss` |

`tags[]` 返回 `tagId`、`tagName`、`tagColor`；`seasons[]` 返回 `seasonCode`、`seasonName`。标量不适用或未知时返回 `null`，集合无数据时返回 `[]`。结果按关系 `update_time DESC, rel_id DESC` 排序，展示的 `updateTime` 则来自资源主数据。

响应示例：

```json
{
  "code": 200,
  "message": "success",
  "success": true,
  "data": {
    "records": [
      {
        "relationId": "2091715622923657218",
        "resourceModule": "SCENIC",
        "moduleName": "景区管理",
        "resourceId": "2091715622923657001",
        "resourceName": "示例景区",
        "coverUrl": null,
        "city": "海拉尔",
        "isCharged": true,
        "isChargedName": "是",
        "settleTypeCode": "CASH",
        "settleTypeName": "现付",
        "tags": [
          { "tagId": "2084636804090089473", "tagName": "自然风光", "tagColor": "#52C41A" }
        ],
        "seasons": [
          { "seasonCode": "spring", "seasonName": "春" }
        ],
        "statusCode": "ENABLED",
        "statusName": "启用",
        "enabled": true,
        "resourceAvailable": true,
        "updateTime": "2026-08-25 10:00:00"
      }
    ],
    "total": 1,
    "page": 1,
    "pageSize": 20
  }
}
```

## 权限、依赖与错误码

- Gateway 强制认证；服务端仅允许 `ADMIN`、`FINANCE`、`SUPER_ADMIN`，并同时要求 `supplier:view` 与 `supplier:resource:view`。
- 任意供应商生命周期状态均可查询；接口没有写入、缓存、MQ 或操作审计副作用。
- 本地九类资源批量查询 Resource 数据；`VEHICLE` 通过内部 Token 调用 Fleet 批量接口，管理端不得直接调用内部接口。
- Resource、Fleet 或必要字典依赖异常时失败关闭，不返回半真半假的成功数据。

| 业务码 | 场景 |
|---:|---|
| `401` | 未认证或登录态失效 |
| `400` | 路径/分页参数不合法 |
| `395001` | 供应商不存在 |
| `395034` | 不支持的 `resourceModule` |
| `395039` | Fleet、字典或资源必要依赖不可用/响应不完整 |

## 管理端接入事项

1. 在供应商详情“账号信息”页签后新增“资源信息”页签，进入页签后按需请求本接口。
2. 建议列为资源名称（含封面）、模块/类型、城市、是否收费、结算方式、标签、季节、状态、更新时间；字段与用户提供的资源列表示意保持一致，但以本接口实际数据为准。
3. ID 全程按字符串传递和比较，禁止转为 JavaScript `number`。
4. 展示名称优先使用 `moduleName`、`isChargedName`、`settleTypeName`、`statusName`；未知值显示占位符，不自行推导业务码。
5. `tags`、`seasons` 直接按数组渲染；`resourceAvailable=false` 时保留该行并展示“资源已删除/不可用”，不要过滤。
6. 分页筛选变化时回到第 1 页；页容量不得超过 100。管理端不提供资源关系的新增、编辑、删除或状态切换操作。

## 兼容性与未变化范围

- 新增只读 GET，不修改既有供应商详情、账号、审批、资源管理写接口及响应字段。
- 不新增或修改数据库 migration；沿用既有 `supplier_resource_rel`、Resource 主表与 Fleet 车辆数据。
- 不变更 Gateway 顶级路由、Nacos 配置、Redis、MQ、状态机、审批、数据范围或软删除语义。
- 后端仓库未修改任何管理端源码；管理端接入状态保持 `pending`。

## 验证证据

- 自动化：供应商相关测试 282 项零失败（1 项条件跳过）；Fleet 车辆包 228 项零失败；Resource 全量 2043 项零失败（38 项条件跳过）；Fleet 可运行全量 3853 项零失败（7 项条件跳过）；Gateway 路由审计 3 项零失败。
- 独立审计：在合并提交 `4f032cd6f` 的 detached worktree 重新核对权限、错误码、软删除、缺失资源占位、Fleet 批量与失败关闭；供应商审计套件和 Fleet 审计套件 249 项均零失败。
- TEST 精确部署：Resource 任务 `cc1fe248`（13:02:08–13:02:42）和 Fleet 任务 `2697d374`（13:03:42–13:04:18）均退出码 0；部署端 HEAD 为 `4f032cd6f`，Resource 8082/8182、Fleet 8087/8187 滚动恢复健康，Nacos `test` 中各有 2 个实例。
- 真实 Gateway：使用现有有效管理端会话只读查询全部 3 个 TEST 供应商，实际取得 1 条 `SCENIC` 资源关系；18 个字段齐全，Snowflake ID 为字符串，`tags`/`seasons` 为数组，时间格式及模块筛选通过。不存在供应商、未知模块、`page=0`、`pageSize=101` 分别返回 `395001`、`395034`、`400`、`400`；未认证请求为 HTTP 200、业务码 `401`、`success=false`。
- TEST 当前没有 `VEHICLE` 供应商关系样本，因此未伪造数据；跨服务车辆路径由真实双服务部署健康、内部 Token 控制器契约、批量查询、重复/缺失/额外响应拒绝及 tombstone 测试覆盖。
- 环境恢复：验收后任务 `45e843e5`（Resource）与 `c05eda6e`（Fleet）依次回切包含本次合并的 `dev-v3`，退出码均为 0；8082/8182、8087/8187 及 Nacos 各 2 个实例保持健康，临时精确部署分支已删除。
- 清理：验收全程只读，无供应商、资源、数据库、Redis、MQ 或配置数据需要清理。

## 撤回

1. 从最新 `dev-v3` 创建回退分支，执行 `git revert -m 1 --no-edit 4f032cd6f6698607a2f1524437533d595975fc9a`，经独立 PR 合入。
2. 依次重新构建并滚动部署 `hl-resource-service`、`hl-fleet-service`；回退期间两个服务分别维持双实例滚动策略。
3. 本次无数据库、Redis、MQ、Nacos 或其他配置变更，不需要 DDL、DML、缓存清理、消息补偿或配置恢复；不存在不可逆数据影响。
4. 回退后管理端停止调用新增 GET 和读取本次字段；既有供应商详情、账号及资源管理接口继续兼容。
5. 经 Gateway 复测新增路径不可用/已撤回、既有供应商详情正常、两个服务双实例与 Nacos 健康，并核对数据库、缓存和 MQ 无副作用。

## 关联 / 联系人

- **Issue**: [#6316](https://git.1814.love:8443/wx/HL/issues/6316)
- **PR**: [#6330](https://git.1814.love:8443/wx/HL/pulls/6330)
- **合并提交**: [4f032cd6f](https://git.1814.love:8443/wx/HL/commit/4f032cd6f6698607a2f1524437533d595975fc9a)
- **后端负责人**: @lc