Files

duanshuwen 7ba92f3c5d feat: 新增客片案例与团队共创模块，重构玩法与配置

- 新增客片案例全流程功能，包含前台页面、管理端配置、后端API、数据库迁移与文档
- 新增团队共创详情页面与对应接口
- 重构玩法模块：将静态playData替换为动态API获取，拆分类型定义到playTypes.ts
- 优化vite构建配置与环境变量处理，调整详情页操作栏文案
- 更新全量相关文档与配图，新增客片案例、团队共创API文档
- 新增测试用例，完善数据归一化逻辑
- 调整路由配置与环境变量示例文件

2026-08-19 20:23:04 +08:00

4.3 KiB

Raw Blame History

客片案例 API 契约

适用端：WonderQ-Admin、WonderQ-Admin-UI、WonderQ-MiniAPP。

目标：维护“极境视界”首页卡片，并提供客片案例更多列表和案例详情页面。

领域边界

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

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

数据类型

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 列表调整顺序

新增示例：

{
  "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

获取更多列表

GET /api/public/home/wild-archives

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

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

获取案例详情

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

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

{
  "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、Public API。

4.3 KiB Raw Blame History Unescape Escape