# 资源分页列表 API 文档

> 模块：Form  
> 最后更新：2026-03-19

---

## 本次需求涉及的接口清单

| # | 方法    | 路径                         | 说明               | 类型     |
|---|-------|----------------------------|------------------|--------|
| 1 | `GET` | `/shop/form/resource/page` | 资源分页列表（不含 times） | **新增** |

> 本次需求另包含 WebSocket 推送（非 HTTP 接口），推送消息格式见 `02-API接口文档.md`。

---

## 获取资源分页列表

- **方法**：`GET`
- **路径**：`/shop/form/resource/page`
- **说明**：返回当前店铺下所有资源类表单记录的分页列表，支持按指定 ids 过滤。与 `/shop/schedule/resource/list` 结构类似，但不包含
  times（可用日期）字段，适用于前端收到 WebSocket 推送后按 ids 拉取最新资源数据。

### 鉴权

| Header        | 类型     | 必填 | 说明                           |
|---------------|--------|----|------------------------------|
| Authorization | string | 是  | Bearer \<token\>（shop 端 JWT） |

### 请求

#### Query 参数

| 参数名   | 类型    | 必填 | 说明                                                            |
|-------|-------|----|---------------------------------------------------------------|
| ids[] | int[] | 否  | 指定资源 form_record_id 列表；传入时直接按主键查询（跳过资源类型过滤，性能更优）；不传则返回所有资源类记录 |
| num   | int   | 否  | 每页条数，默认 15，最小 1                                               |
| skip  | int   | 否  | 页码，从 1 开始，默认 1                                                |

#### Body

无

### 响应

#### 成功

| 字段     | 类型      | 说明        |
|--------|---------|-----------|
| status | boolean | 固定 true   |
| data   | object  | 分页数据，结构见下 |

**data 结构**

| 字段名   | 类型    | 说明        |
|-------|-------|-----------|
| list  | array | 当前页资源记录列表 |
| count | int   | 符合条件的总记录数 |
| skip  | int   | 下一页页码     |
| size  | int   | 每页条数      |

**list 列表项字段**

| 字段名               | 类型           | 说明                                                      | 缺失默认值  |
|-------------------|--------------|---------------------------------------------------------|--------|
| id                | int          | 资源记录 ID（form_record.id）                                 | —      |
| form_id           | int          | 所属表单 ID                                                 | —      |
| main_field        | string       | 主字段（资源名称），多段以 ` ## ` 分隔时只取第一段                           | `""`   |
| sort              | int          | 排序值（降序返回）                                               | —      |
| capacity          | int          | 容量                                                      | `0`    |
| combined_resource | object/null  | 组合资源配置，结构 `{"status": 0/1, "resource_ids": int[]}`      | `null` |
| resource_form_id  | int/string   | 关联预约表单 ID（来自 data.partyroom_booking），部分旧数据可能为空字符串 `""`  | `0`    |
| schedule          | int[]/string | 关联日程 ID 列表（schedule_id 数组），部分旧数据可能为空字符串 `""`            | `null` |
| form_code         | string       | 表单 code（如 party_room、therapist、table、sites、resources 等） | `""`   |

> 注：不是每条资源都包含以上所有 data 字段，缺失时按默认值返回。`resource_form_id` 和 `schedule` 存在历史数据为空字符串的情况，前端需兼容处理。

### Demo：请求示例

**获取所有资源（分页）**

```http
GET /shop/form/resource/page?num=10&skip=1 HTTP/1.1
Host: dev.pisellapi.cn
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...
```

**按指定 ids 查询（WebSocket 推送后拉取场景）**

```http
GET /shop/form/resource/page?ids[]=101&ids[]=102&ids[]=103 HTTP/1.1
Host: dev.pisellapi.cn
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGc...
```

### Demo：成功响应（200）

```json
{
  "status": true,
  "code": 200,
  "message": "",
  "data": {
    "list": [
      {
        "id": 46971,
        "form_id": 971,
        "main_field": "test 1",
        "sort": 46971,
        "capacity": 100,
        "combined_resource": {
          "status": 0,
          "resource_ids": []
        },
        "resource_form_id": 967,
        "schedule": [
          1067
        ],
        "form_code": "party_room1"
      },
      {
        "id": 44153,
        "form_id": 207,
        "main_field": "场地4",
        "sort": 44153,
        "capacity": 10,
        "combined_resource": null,
        "resource_form_id": 945,
        "schedule": [
          1060,
          1042
        ],
        "form_code": "sites"
      },
      {
        "id": 43337,
        "form_id": 6,
        "main_field": "",
        "sort": 43337,
        "capacity": 999,
        "combined_resource": {
          "status": 0,
          "resource_ids": []
        },
        "resource_form_id": 950,
        "schedule": "",
        "form_code": "party_room"
      }
    ],
    "count": 80,
    "skip": 2,
    "size": 15
  }
}
```

> Demo 中展示了三种典型场景：有组合资源+单日程、无组合资源+多日程、schedule 为空字符串的历史数据。

### 错误响应示例

```json
{
  "status": false,
  "message": "The ids.0 must be an integer."
}
```

**常见错误码**

| code / message | 说明                        |
|----------------|---------------------------|
| 401            | 未授权（缺少或无效的 Authorization） |
| 422            | 参数校验失败（ids 非数组、num 非正整数等） |

---

## 与现有接口的关系

| 接口                                 | 用途                   | 区别                         |
|------------------------------------|----------------------|----------------------------|
| `GET /shop/schedule/resource/list` | 日程资源列表（含 times 可用日期） | 包含 times 字段，按日期查询          |
| `GET /shop/form/resource/list`     | 混合资源列表               | 无分页                        |
| **`GET /shop/form/resource/page`** | **资源分页列表（本次新增）**     | **有分页，支持 ids 过滤，不含 times** |

---

## 变更记录

- 2026-03-19：新增接口，支持资源分页查询与 ids 过滤
- 2026-03-19：根据实际响应数据修正字段类型（combined_resource 为 object、schedule 为 int[]、resource_form_id 兼容空字符串）