Files

duanshuwen e082bd2d98 feat(api): 实现三端统一的JSON API响应契约

- 新增`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文档，调整文档分类顺序将响应契约置于首位

2026-08-19 22:02:20 +08:00

4.6 KiB

Raw Blame History

客片案例 API 契约

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

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

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

领域边界

客片案例是首页内容领域的一类展示内容，不属于商品、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.6 KiB Raw Blame History Unescape Escape