# 商城首页接口缺字段补充建议

## 背景

当前首页已经按原来的页面结构保留：

- 顶部搜索区
- 左侧分类导航
- 中间 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`

## 结论

当前首页已经可以只用现有接口字段跑起来，但如果要真正做到：

- 样式不变
- 内容不写死
- 页面表达完整
- 运营可配置

上面这些字段建议尽快补到文档和接口定义里。