refactor(home-api): 统一首页API响应格式并迁移配套代码

完成首页数据模型的统一重构,具体变更如下:
1.  重构公共首页API接口,移除`playRecommendations`字段,将玩法推荐数据统一放入`experiences`字段
2.  更新前后端类型定义、序列化逻辑与前端页面组件,适配新的API响应结构
3.  为微信登录相关接口添加`trust_env=True`配置,支持企业代理环境并新增`socksio`依赖
4.  新增图片画廊上传组件,重构SingleImageUploader组件支持自定义宽高比
5.  重构Toast与Select组件的实现与样式,统一后台UI设计系统
6.  移除个人中心页面不必要的返回事件与顶部标题组件,优化详情卡片布局
7.  新增微信接口单元测试,更新官方文档与测试用例适配变更
8.  删除过期的文档图片资源
This commit is contained in:
duanshuwen committed 2026-08-20 21:18:27 +08:00
1 parent d3a246a873
commit 6296392e80
27 files changed
+1055 -218

No files matched your search

+7 -6
View File
@@ -23,7 +23,7 @@
首页正式接口返回的所有资源 `id` 都是稳定 UUID 字符串。不要把下方 fallback 文件中的语义 ID 当作服务端 ID,也不要在接口序列化时重新生成 ID;首页卡片跳转详情、排序和删除必须复用接口返回的同一 ID。
当前首页通过 `GET /api/public/home` 消费四类内容;三个卡片 mock 数组仍作为接口失败、空响应或字段缺失时的前台 fallback,玩法推荐无本地模拟数据时保持空态。Admin UI 通过本文件列出的 Admin API 维护正式数据。
当前首页通过 `GET /api/public/home` 消费三类内容;团队共创和极境视界 mock 数组仍作为接口失败、空响应或字段缺失时的前台 fallback,`experiences` 中的玩法推荐无本地模拟数据时保持空态。Admin UI 仍通过本文件列出的 Admin API 分别维护体验推荐和玩法推荐关联。
本文件所有 JSON 示例的业务对象均位于统一响应的 `data` 字段内,完整包裹格式见 [api-response-contract.md](./api-response-contract.md)。
@@ -289,14 +289,13 @@ Content-Type: application/json
GET /api/public/home
```
无需鉴权。接口只返回 `isActive === true` 的记录,首页卡片和玩法推荐分别按 `sortOrder` 升序返回,并移除管理端状态、排序和审计时间字段:
无需鉴权。接口只返回 `isActive === true` 的记录,并移除管理端状态、排序和审计时间字段。为统一三端首页消费模型,玩法推荐数据放入 `experiences` 字段,响应中不再返回 `playRecommendations`:
```ts
type PublicHomeResponse = {
experiences: HomeExperience[];
experiences: HomeWanfaRecommendation[];
teamBuildings: HomeTeamBuilding[];
wildArchives: HomeWildArchive[];
playRecommendations: HomeWanfaRecommendation[];
};
type HomeWanfaRecommendation = {
@@ -316,7 +315,9 @@ type WanfaRoute = {
};
```
四组列表始终返回数组;没有可用内容时返回空数组。玩法推荐只返回启用的关联记录,并展开关联分类当前的路线。MiniAPP 应在数据层归一化字段并保留对应 mock fallback,不在页面组件内直接请求接口。
注意:`/api/admin/home/experiences` 仍是后台体验推荐 CRUD 资源;Public `/api/public/home` 的 `experiences` 字段已统一承载玩法推荐数据,不能按后台体验推荐字段解读。
三组列表始终返回数组;没有可用内容时返回空数组。`experiences` 只返回启用的玩法推荐关联记录,并展开关联分类当前的路线。MiniAPP 应在数据层将 `experiences` 归一化为玩法推荐,不再读取或维护 `playRecommendations` 字段。
首页玩法推荐点击行为:当 `routes` 存在第一条路线时,MiniAPP 使用该路线的 `id` 调用 `goWanfaRouteDetail`,进入 `/pages/detail/index?routeId={route.id}`;没有关联路线时才使用 `demandKeyword` 或分类名称进入需求页。路线详情字段和 Public 详情接口以 [详情展示契约](./detail-api.md) 为准。
@@ -434,7 +435,7 @@ reorderHomeWanfaRecommendations(itemIds: string[]);
- Admin API 返回启用和停用的完整记录,供管理端维护。
- 未来 Public API 只返回已发布且启用的首页内容;Public API 的响应字段应与本契约的渲染字段兼容,但不应暴露 `createdAt`、`updatedAt` 等管理元数据。
- MiniAPP 已在 `src/lib/api.ts`、`src/lib/types.ts` 和 `src/lib/store.ts` 接入 Public API;首页组件通过共享状态消费归一化后的四类内容,玩法推荐按关联分类展示。
- MiniAPP 已在 `src/lib/api.ts`、`src/lib/types.ts` 和 `src/lib/store.ts` 接入 Public API;首页组件通过共享状态消费归一化后的三类内容,`experiences` 按关联分类展示玩法推荐。
- 后端不得把 `demandKeyword` 解析成 Product 或订单关联;如需线路、详情或预订能力,应另立领域契约。
## 团队共创详情
Binary file not shown.

Before

Width:  |  Height:  |  Size: 2.0 MiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 274 KiB

Binary file not shown.

Before

Width:  |  Height:  |  Size: 15 KiB

+3 -14
View File
@@ -145,14 +145,13 @@ type PublicConciergeResponse = {
### `GET /api/public/home`
无需鉴权。接口只返回后台启用的首页体验推荐、团队共创和极境视界内容,按后台排序返回,不暴露管理元数据。
无需鉴权。接口只返回后台启用的首页玩法推荐、团队共创和极境视界内容,按后台排序返回,不暴露管理元数据。为统一前台消费模型,玩法推荐列表放在 `experiences` 字段,响应中不再返回 `playRecommendations`。
```ts
type PublicHomeResponse = {
experiences: HomeExperience[];
experiences: HomeWanfaRecommendation[];
teamBuildings: HomeTeamBuilding[];
wildArchives: HomeWildArchive[];
playRecommendations: HomeWanfaRecommendation[];
};
type HomeWanfaRecommendation = {
@@ -171,16 +170,6 @@ type WanfaRoute = {
demandKeyword: string;
};
type HomeExperience = {
id: string;
badge: string;
category: string;
title: string;
englishTitle: string;
image: string;
demandKeyword: string;
};
type HomeTeamBuilding = {
id: string;
tag: string;
@@ -204,7 +193,7 @@ type HomeWildArchive = {
};
```
无可用内容时,`experiences`、`teamBuildings`、`wildArchives` 和 `playRecommendations` 均返回空数组。玩法推荐由首页内容域关联玩法分类后生成,接口只返回启用的关联及分类当前路线;MiniAPP 接口失败或字段不完整时使用首页对应 fallback,玩法推荐缺省为空态。
无可用内容时,`experiences`、`teamBuildings` 和 `wildArchives` 均返回空数组。`experiences` 实际承载首页玩法推荐,由首页内容域关联玩法分类后生成,接口只返回启用的关联及分类当前路线;MiniAPP 接口失败或字段不完整时使用对应空态,不再读取 `playRecommendations`。
客片案例更多列表使用 `GET /api/public/home/wild-archives`,返回同样的摘要字段;详情使用 `GET /api/public/home/wild-archives/{archiveId}`,在摘要字段基础上增加 `images: string[]`。首页卡片点击详情,`查看更多` 点击案例列表,不再跳转需求页。