382 lines
8.0 KiB
Markdown
382 lines
8.0 KiB
Markdown
# 商城首页接口缺字段补充建议
|
|
|
|
## 背景
|
|
|
|
当前首页已经按原来的页面结构保留：
|
|
|
|
- 顶部搜索区
|
|
- 左侧分类导航
|
|
- 中间 Banner 主视觉
|
|
- 右侧档口排行榜
|
|
- 中下方 Banner 卡片区
|
|
- 商品列表区
|
|
- 店铺推荐区
|
|
|
|
同时页面展示已经改成“优先按接口字段渲染”，不再使用本地 mock 数据补业务内容。
|
|
|
|
当前直接使用的接口是：
|
|
|
|
- `AppHome`
|
|
- `AppGoodsPage`
|
|
|
|
现状是页面能跑通，但为了完全摆脱前端硬编码、数字占位和临时推导，首页还有几组字段缺口需要后端补齐。
|
|
|
|
## 当前接口已能直接支撑的内容
|
|
|
|
### `AppHome`
|
|
|
|
当前已足够支撑：
|
|
|
|
- Banner 图片：`banners[].imageUrl`
|
|
- Banner 主标题：`banners[].title`
|
|
- Banner 跳转信息：`banners[].linkType`、`banners[].linkValue`
|
|
- 推荐商品：`recommendGoods[]`
|
|
- 推荐店铺：`recommendStores[]`
|
|
|
|
### `AppGoodsPage`
|
|
|
|
当前已足够支撑：
|
|
|
|
- 商品分页列表：`list[]`
|
|
- 商品基础卡片：`spuName`、`subTitle`、`coverUrl`
|
|
- 价格：`minPrice`、`maxPrice`
|
|
- 销量：`salesVolume`、`virtualSales`
|
|
- 库存：`totalStock`
|
|
- 排序：`sortType`
|
|
- 类目筛选请求值：`categoryId`
|
|
|
|
## 缺字段清单
|
|
|
|
### 1. 首页分类导航缺少类目展示字段
|
|
|
|
#### 当前问题
|
|
|
|
当前前端只能拿到 `GoodsSummary.categoryId`，但左侧分类导航如果要保持现有样式，需要：
|
|
|
|
- 类目名称
|
|
- 类目排序
|
|
- 商品数量
|
|
|
|
现在如果只靠 `categoryId`，前端只能显示成 `类目 12` 这种数字占位，不够可用，也不适合正式页面。
|
|
|
|
#### 为什么需要
|
|
|
|
左侧分类导航不仅是筛选入口，也是首页首屏的重要信息模块。如果没有类目名称：
|
|
|
|
- 用户看不懂类目内容
|
|
- 前端无法稳定排序
|
|
- 无法避免写死类目文案或临时用数字占位
|
|
|
|
#### 建议补充方式
|
|
|
|
优先建议直接补到 `AppHomeResponse`，因为首页首屏进入时就需要这组数据。
|
|
|
|
#### 建议定义
|
|
|
|
```ts
|
|
interface HomeCategoryNav {
|
|
categoryId: number
|
|
categoryName: string
|
|
goodsCount: number
|
|
sort: number
|
|
}
|
|
```
|
|
|
|
建议追加到：
|
|
|
|
```ts
|
|
interface AppHomeResponse {
|
|
banners: BannerInfo[]
|
|
recommendGoods: GoodsSummary[]
|
|
recommendStores: RecommendStoreInfo[]
|
|
categoryNavs: HomeCategoryNav[]
|
|
}
|
|
```
|
|
|
|
#### 示例
|
|
|
|
```json
|
|
{
|
|
"categoryId": 101,
|
|
"categoryName": "手机配件",
|
|
"goodsCount": 286,
|
|
"sort": 10
|
|
}
|
|
```
|
|
|
|
### 2. Banner 缺少副文案和按钮文案字段
|
|
|
|
#### 当前问题
|
|
|
|
`BannerInfo` 目前只有：
|
|
|
|
- `title`
|
|
- `imageUrl`
|
|
- `linkType`
|
|
- `linkValue`
|
|
|
|
这足够渲染图片和标题，但首屏 Banner 按当前页面样式还需要：
|
|
|
|
- 副标题
|
|
- 描述文案
|
|
- 主按钮文案
|
|
|
|
不补的话，这些内容只能前端写死。
|
|
|
|
#### 为什么需要
|
|
|
|
Banner 是首页视觉中心。如果副文案和按钮文案不能由接口控制：
|
|
|
|
- 运营无法灵活调整首屏内容
|
|
- 前端只能用固定文案
|
|
- 不同 Banner 的表达层级无法统一
|
|
|
|
#### 建议定义
|
|
|
|
```ts
|
|
interface BannerInfo {
|
|
id: number
|
|
title: string
|
|
subTitle: string
|
|
description: string
|
|
buttonText: string
|
|
positionCode: string
|
|
imageUrl: string
|
|
linkType: string
|
|
linkValue: string
|
|
sort: number
|
|
status: "enabled" | "disabled"
|
|
startTime: number
|
|
endTime: number
|
|
}
|
|
```
|
|
|
|
#### 示例
|
|
|
|
```json
|
|
{
|
|
"id": 1,
|
|
"title": "春季上新",
|
|
"subTitle": "精选档口同步上新",
|
|
"description": "聚合热卖新品与高频补货商品",
|
|
"buttonText": "立即搜款",
|
|
"positionCode": "home_top",
|
|
"imageUrl": "https://cdn.example.com/banner/1.png",
|
|
"linkType": "goods",
|
|
"linkValue": "10001",
|
|
"sort": 1,
|
|
"status": "enabled",
|
|
"startTime": 1710000000,
|
|
"endTime": 1730000000
|
|
}
|
|
```
|
|
|
|
### 3. 推荐店铺缺少推荐理由和排行依据
|
|
|
|
#### 当前问题
|
|
|
|
`RecommendStoreInfo` 现在只有：
|
|
|
|
- `storeName`
|
|
- `storeLogo`
|
|
- `storeNotice`
|
|
- `storeStatus`
|
|
|
|
右侧“档口排行榜”区域如果要保持现有样式和业务含义，还需要：
|
|
|
|
- 推荐理由
|
|
- 主营类目
|
|
- 排行分值或展示指标
|
|
|
|
不补的话，只能展示店铺公告，排行榜会显得信息不完整。
|
|
|
|
#### 为什么需要
|
|
|
|
当前右侧区域不是普通店铺列表，而是“推荐 / 排行”型模块。用户需要知道：
|
|
|
|
- 为什么推荐这家店
|
|
- 它主要卖什么
|
|
- 排行依据是什么
|
|
|
|
#### 建议定义
|
|
|
|
```ts
|
|
interface RecommendStoreInfo {
|
|
id: number
|
|
merchantId: number
|
|
storeName: string
|
|
storeLogo: string
|
|
storeNotice: string
|
|
storeStatus: "enabled" | "disabled"
|
|
mainCategoryName: string
|
|
recommendReason: string
|
|
rankScore: number
|
|
}
|
|
```
|
|
|
|
#### 示例
|
|
|
|
```json
|
|
{
|
|
"id": 9001,
|
|
"merchantId": 5001,
|
|
"storeName": "星驰数码档口",
|
|
"storeLogo": "https://cdn.example.com/store/logo-1.png",
|
|
"storeNotice": "手机配件热销档口",
|
|
"storeStatus": "enabled",
|
|
"mainCategoryName": "手机配件",
|
|
"recommendReason": "近 7 天出单稳定，适合做日常补货",
|
|
"rankScore": 98.6
|
|
}
|
|
```
|
|
|
|
### 4. 商品摘要缺少类目名称
|
|
|
|
#### 当前问题
|
|
|
|
`GoodsSummary` 里有 `categoryId`，但没有 `categoryName`。
|
|
|
|
这会导致：
|
|
|
|
- 商品卡片无法展示人类可读的类目名
|
|
- 分类筛选区无法直接使用列表结果做回显
|
|
- 前端必须再维护一套 `categoryId -> 名称` 映射
|
|
|
|
#### 为什么需要
|
|
|
|
商品列表卡片、推荐商品卡片、筛选回显，都需要类目中文名。只靠 `categoryId` 不够。
|
|
|
|
#### 建议定义
|
|
|
|
```ts
|
|
interface GoodsSummary {
|
|
id: number
|
|
merchantId: number
|
|
storeId: number
|
|
categoryId: number
|
|
categoryName: string
|
|
spuNo: string
|
|
spuName: string
|
|
subTitle: string
|
|
coverUrl: string
|
|
status: "enabled" | "disabled"
|
|
auditStatus: "pending" | "approved" | "rejected"
|
|
saleStatus: "off" | "on"
|
|
sort: number
|
|
salesVolume: number
|
|
virtualSales: number
|
|
viewCount: number
|
|
minPrice: string
|
|
maxPrice: string
|
|
totalStock: number
|
|
lockedStock: number
|
|
createdAt: number
|
|
updatedAt: number
|
|
}
|
|
```
|
|
|
|
### 5. 搜索热词缺少接口字段
|
|
|
|
#### 当前问题
|
|
|
|
搜索框下方原样式里有热词区。当前文档没有专门的热词字段，所以前端只能临时从 `recommendGoods[].spuName` 里抽。
|
|
|
|
#### 为什么需要
|
|
|
|
热词一般是运营位，不应该完全依赖推荐商品标题：
|
|
|
|
- 热词和推荐商品不是一个概念
|
|
- 热词排序和内容应该可单独控制
|
|
- 需要支持临时活动词、营销词
|
|
|
|
#### 建议定义
|
|
|
|
```ts
|
|
interface AppHomeResponse {
|
|
banners: BannerInfo[]
|
|
recommendGoods: GoodsSummary[]
|
|
recommendStores: RecommendStoreInfo[]
|
|
categoryNavs: HomeCategoryNav[]
|
|
searchKeywords: string[]
|
|
}
|
|
```
|
|
|
|
#### 示例
|
|
|
|
```json
|
|
[
|
|
"磁吸手机壳",
|
|
"直播补光灯",
|
|
"蓝牙耳机",
|
|
"快充套装",
|
|
"智能手表表带"
|
|
]
|
|
```
|
|
|
|
### 6. 平台专区 / 频道卡片缺少独立数据源
|
|
|
|
#### 当前问题
|
|
|
|
原首页样式里有一块“平台专区 / 场景卡片”区域。当前接口没有对应字段，所以如果要保留这块业务含义，前端只能拿别的数据硬凑。
|
|
|
|
#### 为什么需要
|
|
|
|
这类区域通常代表固定业务入口，例如：
|
|
|
|
- 平台铺货
|
|
- 一件代发
|
|
- 活动专区
|
|
- 类目专题
|
|
|
|
它不适合和 Banner 或推荐商品混用。
|
|
|
|
#### 建议定义
|
|
|
|
```ts
|
|
interface HomeChannelCard {
|
|
id: number
|
|
title: string
|
|
subTitle: string
|
|
iconUrl: string
|
|
linkType: string
|
|
linkValue: string
|
|
sort: number
|
|
status: "enabled" | "disabled"
|
|
}
|
|
```
|
|
|
|
建议追加到：
|
|
|
|
```ts
|
|
interface AppHomeResponse {
|
|
banners: BannerInfo[]
|
|
recommendGoods: GoodsSummary[]
|
|
recommendStores: RecommendStoreInfo[]
|
|
categoryNavs: HomeCategoryNav[]
|
|
searchKeywords: string[]
|
|
channels: HomeChannelCard[]
|
|
}
|
|
```
|
|
|
|
## 建议优先级
|
|
|
|
如果按“先把当前首页做完整”来排，建议优先级如下：
|
|
|
|
1. `categoryNavs`
|
|
2. `BannerInfo.subTitle / description / buttonText`
|
|
3. `GoodsSummary.categoryName`
|
|
4. `RecommendStoreInfo.mainCategoryName / recommendReason / rankScore`
|
|
5. `searchKeywords`
|
|
6. `channels`
|
|
|
|
## 结论
|
|
|
|
当前首页已经可以只用现有接口字段跑起来，但如果要真正做到：
|
|
|
|
- 样式不变
|
|
- 内容不写死
|
|
- 页面表达完整
|
|
- 运营可配置
|
|
|
|
上面这些字段建议尽快补到文档和接口定义里。
|