7ba92f3c5d
- 新增客片案例全流程功能，包含前台页面、管理端配置、后端API、数据库迁移与文档 - 新增团队共创详情页面与对应接口 - 重构玩法模块：将静态playData替换为动态API获取，拆分类型定义到playTypes.ts - 优化vite构建配置与环境变量处理，调整详情页操作栏文案 - 更新全量相关文档与配图，新增客片案例、团队共创API文档 - 新增测试用例，完善数据归一化逻辑 - 调整路由配置与环境变量示例文件
148 lines
4.3 KiB
Markdown
148 lines
4.3 KiB
Markdown
# 客片案例 API 契约
|
||
|
||
> 适用端：`WonderQ-Admin`、`WonderQ-Admin-UI`、`WonderQ-MiniAPP`。
|
||
>
|
||
> 目标：维护“极境视界”首页卡片，并提供客片案例更多列表和案例详情页面。
|
||
|
||
## 领域边界
|
||
|
||
客片案例是首页内容领域的一类展示内容，不属于商品、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
|
||
{
|
||
"items": [
|
||
{
|
||
"id": "shilong-cave",
|
||
"title": "石龙洞——客片案例",
|
||
"image": "https://example.test/cover.jpg",
|
||
"demandKeyword": "地心探险",
|
||
"photoCount": 5
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
### 获取案例详情
|
||
|
||
```http
|
||
GET /api/public/home/wild-archives/{archiveId}
|
||
```
|
||
|
||
无需鉴权。停用或不存在的案例返回 `404`，成功返回：
|
||
|
||
```json
|
||
{
|
||
"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)。
|