d3a246a873
更新所有业务API文档，明确持久化资源的正式ID必须为服务端生成的稳定UUID，本地调试或接口失败时可使用语义ID作为fallback。新增数据库迁移脚本0022_opaque_ids，用于将历史语义ID转换为稳定UUID，并同步外键关联、详情记录的key字段以及审计日志的实体ID引用。新增该迁移的单元测试用例，验证ID替换与关联数据同步的逻辑正确性。调整MiniAPP前端代码，优化导航工具函数的格式，移除废弃函数并修改首页跳转逻辑，使用接口返回的UUID作为详情跳转参数。
160 lines
4.7 KiB
Markdown
160 lines
4.7 KiB
Markdown
# 客片案例 API 契约
|
||
|
||
> 适用端：`WonderQ-Admin`、`WonderQ-Admin-UI`、`WonderQ-MiniAPP`。
|
||
>
|
||
> 目标：维护“极境视界”首页卡片，并提供客片案例更多列表和案例详情页面。
|
||
|
||
所有 JSON 响应遵循 [三端统一 API 响应契约](./api-response-contract.md)，成功业务对象位于 `data`，失败时 `data` 为 `null`。
|
||
|
||
客片案例记录的正式 `id` 为服务端生成的稳定 UUID 字符串；列表、详情和删除使用同一 ID。本地 fallback 的语义 ID 仅用于接口失败时定位模拟内容。
|
||
|
||
## 领域边界
|
||
|
||
客片案例是首页内容领域的一类展示内容，不属于商品、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)。
|