1
This commit is contained in:
魔方熊成祥
381
docs/home-interface-missing-fields.md
Normal file
381
docs/home-interface-missing-fields.md
Normal file
@@ -0,0 +1,381 @@
|
||||
# 商城首页接口缺字段补充建议
|
||||
|
||||
## 背景
|
||||
|
||||
当前首页已经按原来的页面结构保留：
|
||||
|
||||
- 顶部搜索区
|
||||
- 左侧分类导航
|
||||
- 中间 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`
|
||||
|
||||
## 结论
|
||||
|
||||
当前首页已经可以只用现有接口字段跑起来，但如果要真正做到：
|
||||
|
||||
- 样式不变
|
||||
- 内容不写死
|
||||
- 页面表达完整
|
||||
- 运营可配置
|
||||
|
||||
上面这些字段建议尽快补到文档和接口定义里。
|
||||
Reference in New Issue
Block a user