Files

duanshuwen d3a246a873 docs: 统一业务资源ID为服务端生成的稳定UUID

更新所有业务API文档，明确持久化资源的正式ID必须为服务端生成的稳定UUID，本地调试或接口失败时可使用语义ID作为fallback。新增数据库迁移脚本0022_opaque_ids，用于将历史语义ID转换为稳定UUID，并同步外键关联、详情记录的key字段以及审计日志的实体ID引用。新增该迁移的单元测试用例，验证ID替换与关联数据同步的逻辑正确性。调整MiniAPP前端代码，优化导航工具函数的格式，移除废弃函数并修改首页跳转逻辑，使用接口返回的UUID作为详情跳转参数。

2026-08-19 22:28:13 +08:00

4.7 KiB

Raw Blame History

客片案例 API 契约

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

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

所有 JSON 响应遵循三端统一 API 响应契约，成功业务对象位于 data，失败时 data 为 null。

客片案例记录的正式 id 为服务端生成的稳定 UUID 字符串；列表、详情和删除使用同一 ID。本地 fallback 的语义 ID 仅用于接口失败时定位模拟内容。

领域边界

客片案例是首页内容领域的一类展示内容，不属于商品、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 升序：

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

获取案例详情

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

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

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

4.7 KiB Raw Blame History Unescape Escape