e082bd2d98
- 新增`api_response.py`统一响应封装工具类，提供标准成功/错误响应构造方法 - 重构WonderQ-Admin全局异常处理器，将所有异常转换为标准响应格式 - 修改所有公共和管理端接口的返回逻辑，统一使用`code`（与HTTP状态码一致）、`msg`和`data`的三层结构 - 新增`api-response-contract.md`文档，定义完整的三端统一JSON响应规范 - 更新所有领域API文档，明确业务数据需位于`data`字段内，补充响应格式说明 - 为WonderQ-MiniAPP和WonderQ-Admin-UI新增响应解析逻辑和类型定义，自动完成协议校验和错误处理 - 更新所有测试用例，适配新的响应结构确保接口符合契约要求 - 新增`module-config-api.md`模块配置API文档，补充站点模块配置的接口约定 - 更新项目README文档，调整文档分类顺序将响应契约置于首位
158 lines
4.6 KiB
Markdown
158 lines
4.6 KiB
Markdown
# 客片案例 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)。
|