# 客片案例 API 契约

> 适用端：`WonderQ-Admin`、`WonderQ-Admin-UI`、`WonderQ-MiniAPP`。
>
> 目标：维护“极境视界”首页卡片，并提供客片案例更多列表和案例详情页面。

所有 JSON 响应遵循 [三端统一 API 响应契约](./api-response-contract.md)，成功业务对象位于 `data`，失败时 `data` 为 `null`。

## 领域边界

客片案例是首页内容领域的一类展示内容，不属于商品、Product、ProductImage、订单或预订领域。

- `image` 是首页卡片封面。
- `images` 是详情页纵向展示的图片 URL 列表。
- `demandKeyword` 仅为兼容已有需求入口的普通文案，本次案例卡片和详情不跳转需求页。
- 图片只保存 URL，不保存 base64，不建立商品图片关联。

## 数据类型

```ts
type WildArchiveRecord = {
  id: string;
  title: string;
  image: string;
  images: string[];
  demandKeyword: string;
  isActive: boolean;
  sortOrder: number;
  createdAt: string;
  updatedAt: string;
};

type PublicWildArchiveSummary = {
  id: string;
  title: string;
  image: string;
  demandKeyword: string;
  photoCount: number;
};

type PublicWildArchiveDetail = PublicWildArchiveSummary & {
  images: string[];
};

type WildArchiveCreate = {
  title: string;
  image: string;
  images?: string[];
  demandKeyword: string;
  isActive?: boolean;
  sortOrder?: number;
};

type WildArchivePatch = Partial<WildArchiveCreate>;
```

`images` 未传时服务端兼容为 `[image]`；传入后至少包含一张合法 `http` 或 `https` 图片 URL，最多 30 张。`photoCount` 始终由服务端根据详情图片列表返回。

## Admin API

所有 Admin API 需要 `Authorization: Bearer <admin-jwt>`。

| 方法 | 路径 | 用途 |
| --- | --- | --- |
| `GET` | `/api/admin/home/wild-archives` | 获取全部案例，包含启用和停用记录及详情图片 |
| `POST` | `/api/admin/home/wild-archives` | 新增案例 |
| `PATCH` | `/api/admin/home/wild-archives/{archiveId}` | 修改标题、封面、详情图片、需求关键词、启用状态或排序 |
| `DELETE` | `/api/admin/home/wild-archives/{archiveId}` | 删除案例 |
| `PATCH` | `/api/admin/home/wild-archives/reorder` | 按完整 ID 列表调整顺序 |

新增示例：

```json
{
  "title": "石龙洞——客片案例",
  "image": "https://example.test/cover.jpg",
  "images": [
    "https://example.test/cover.jpg",
    "https://example.test/cave-1.jpg"
  ],
  "demandKeyword": "地心探险",
  "isActive": true
}
```

Admin UI 的“极境视界”表单必须同时维护封面和详情图片，详情图片使用一行一个 URL；删除需要二次确认，排序提交完整 `itemIds`。

## Public API

### 获取更多列表

```http
GET /api/public/home/wild-archives
```

无需鉴权。只返回 `isActive === true` 的记录，按 `sortOrder` 升序：

```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "items": [
      {
        "id": "shilong-cave",
        "title": "石龙洞——客片案例",
        "image": "https://example.test/cover.jpg",
        "demandKeyword": "地心探险",
        "photoCount": 5
      }
    ]
  }
}
```

### 获取案例详情

```http
GET /api/public/home/wild-archives/{archiveId}
```

无需鉴权。停用或不存在的案例返回 `404`，成功返回：

```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "id": "shilong-cave",
    "title": "石龙洞——客片案例",
    "image": "https://example.test/cover.jpg",
    "demandKeyword": "地心探险",
    "photoCount": 5,
    "images": [
      "https://example.test/cover.jpg",
      "https://example.test/cave-1.jpg"
    ]
  }
}
```

## MiniAPP 页面约定

- `pages/wild-archives/index`：客片案例更多列表。
- `pages/wild-archives/detail?id={archiveId}`：客片案例详情。
- 首页“极境视界”卡片调用详情页；“查看更多”调用列表页。
- 页面数据层优先调用 Public API；接口失败时列表和详情允许使用 `homeWildArchivesData.ts` 中的网络图片 mock 数据。
- 详情页按 `images` 顺序纵向展示，保留图片原始比例；空列表时展示空态，不渲染破损图片。

## 迁移与验证

- 数据模型：`HomeWildArchive.images` 使用 JSONB 保存 URL 数组。
- 迁移：`WonderQ-Admin/alembic/versions/0019_home_wild_archive_images.py`。
- 迁移会将历史 `image` 自动转为第一张详情图片，保证旧数据可打开详情页。
- 三端联调顺序：执行迁移 → 启动 Admin API → 配置 Admin UI 案例 → 访问 MiniAPP 列表和详情。

相关契约：[首页内容 API](./home-api.md)、[Public API](./public-api.md)。