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:
1 parent
d3a246a873
commit
6296392e80
27 files changed
+1055
-218
No files matched your search
+7
-6
@@ -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
@@ -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[]`。首页卡片点击详情,`查看更多` 点击案例列表,不再跳转需求页。
|
||||
|
||||
|
||||
Reference in new issue
Block a user