69 lines
3.9 KiB
Markdown
69 lines
3.9 KiB
Markdown
# TicketHome 首页接口接入设计
|
|
|
|
## 目标
|
|
|
|
在 `src/pages-service/tickets/index.vue` 中调用 `scenicProductHome`，使用固定参数：
|
|
|
|
```js
|
|
{ scenicId: 20260811 }
|
|
```
|
|
|
|
以接口返回的数据替换票务首页现有的 `SCENIC_SPOT`、`GROUPS` 和 `ticketStore.products` 静态数据。本次只接入首页接口，不修改商品详情、预订、订单等后续页面的数据来源。
|
|
|
|
## 数据流与组件边界
|
|
|
|
- `index.vue` 负责请求、保存首页数据以及加载和失败状态。
|
|
- 请求成功且 `code === 0`、`data` 为对象时，将 `data` 原样保存，不创建字段映射或首页 DTO 适配器。
|
|
- `TicketHome.vue` 直接使用接口字段，不再依赖静态数据字段名：
|
|
- 景区：`scenicId`、`scenicName`、`subtitle`、`levelText`、`address`、`phone`、`longitude`、`latitude`、`coverImage`、`mediaList`
|
|
- 分类：`categories` 中的 `categoryId`、`categoryName`、`title`、`subtitle`、`defaultFlag`
|
|
- 商品：`products.records` 中的 `commodityId`、`categoryId`、`saleTargetKey`、`title`、`image`、`tags`、`displayPrice`、`salesText`、`detailRouteType`、`bookingFeatureFlags`
|
|
- 默认分类：`selectedCategoryId`
|
|
- `index.vue` 通过单个 `homeData` prop 将接口 `data` 传给 `TicketHome.vue`，避免将接口结果拆分或转换成旧的 `scenicSpot/groups/products` props。
|
|
- `TicketHome.vue` 按商品的 `categoryId` 过滤每个分类下的首屏商品，并以 `commodityId` 作为商品点击事件参数。
|
|
|
|
## 展示规则
|
|
|
|
- 景区头图使用 `coverImage`，景区名称使用 `scenicName`。
|
|
- 等级和副标题使用 `levelText` 与 `subtitle`；任一字段为空时不渲染多余分隔符。
|
|
- 分类导航和分组标题使用 `categoryName`，分类说明使用分类 `subtitle`；分类 `title` 作为辅助标签，仅在非空时展示。
|
|
- 商品卡展示 `image`、`title`、`tags`、`displayPrice` 和 `salesText`。
|
|
- 接口中的字段为空时使用空态或隐藏对应可选内容，不回填旧静态文案或图片。
|
|
- 电话和导航继续使用现有交互；经纬度为空或非法时沿用“暂无导航坐标”提示。
|
|
- 左右分类滚动联动保持不变。初始高亮优先使用 `selectedCategoryId`，无有效匹配时使用第一个分类。
|
|
|
|
## 加载、失败与空数据
|
|
|
|
- 页面首次加载时请求一次 `scenicProductHome`。
|
|
- 加载期间显示明确的加载状态，不渲染静态首页。
|
|
- 请求失败、业务 `code !== 0` 或 `data` 无效时显示错误状态和重试入口，并使用接口 `msg` 或通用错误文案说明失败原因。
|
|
- 请求成功但分类或商品为空时，仍渲染景区信息，由 `TicketHome.vue` 展示对应空状态。
|
|
- 重试只重新请求首页接口，不重复导航或重置其他票务 store 状态。
|
|
|
|
## 测试与验证
|
|
|
|
- 先扩展 `view-contract.test.mjs`，验证：
|
|
- `index.vue` 调用 `scenicProductHome({ scenicId: 20260811 })`。
|
|
- 首页不再导入或传入 `SCENIC_SPOT`、`GROUPS`、`ticketStore.products`。
|
|
- `TicketHome.vue` 使用接口原始字段及 `products.records`。
|
|
- 分类商品通过 `categoryId` 关联，商品事件使用 `commodityId`。
|
|
- 页面包含加载、失败和重试状态。
|
|
- 确认新增测试先因功能未实现而失败，再实施最小代码使其通过。
|
|
- 实现后运行：
|
|
|
|
```bash
|
|
node --test src/pages-service/tickets/view-contract.test.mjs
|
|
node --test src/pages-service/tickets/model.test.mjs
|
|
git diff --check
|
|
```
|
|
|
|
本次变更不涉及依赖、配置或微信小程序编译能力，因此不默认运行生产构建。
|
|
|
|
## 非目标
|
|
|
|
- 不调用 `scenicCategoryProductsList` 或 `scenicProductCardContext`。
|
|
- 不把首页卡片数据写入现有 Pinia 票务 store。
|
|
- 不把首页简略商品数据转换为详情页所需的旧商品模型。
|
|
- 不调整商品详情、预订、订单、退款和凭证页的数据结构。
|
|
- 不修改接口文件或当前客户配置。
|