mall/docs/home-interface-missing-fields.md

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

背景

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

• 顶部搜索区
• 左侧分类导航
• 中间 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，因为首页首屏进入时就需要这组数据。

建议定义

interface HomeCategoryNav {
  categoryId: number
  categoryName: string
  goodsCount: number
  sort: number
}

建议追加到：

interface AppHomeResponse {
  banners: BannerInfo[]
  recommendGoods: GoodsSummary[]
  recommendStores: RecommendStoreInfo[]
  categoryNavs: HomeCategoryNav[]
}

示例

{
  "categoryId": 101,
  "categoryName": "手机配件",
  "goodsCount": 286,
  "sort": 10
}

2. Banner 缺少副文案和按钮文案字段

当前问题

BannerInfo 目前只有：

• title
• imageUrl
• linkType
• linkValue

这足够渲染图片和标题，但首屏 Banner 按当前页面样式还需要：

• 副标题
• 描述文案
• 主按钮文案

不补的话，这些内容只能前端写死。

为什么需要

Banner 是首页视觉中心。如果副文案和按钮文案不能由接口控制：

• 运营无法灵活调整首屏内容
• 前端只能用固定文案
• 不同 Banner 的表达层级无法统一

建议定义

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
}

示例

{
  "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

右侧“档口排行榜”区域如果要保持现有样式和业务含义，还需要：

• 推荐理由
• 主营类目
• 排行分值或展示指标

不补的话，只能展示店铺公告，排行榜会显得信息不完整。

为什么需要

当前右侧区域不是普通店铺列表，而是“推荐 / 排行”型模块。用户需要知道：

• 为什么推荐这家店
• 它主要卖什么
• 排行依据是什么

建议定义

interface RecommendStoreInfo {
  id: number
  merchantId: number
  storeName: string
  storeLogo: string
  storeNotice: string
  storeStatus: "enabled" | "disabled"
  mainCategoryName: string
  recommendReason: string
  rankScore: number
}

示例

{
  "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 不够。

建议定义

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 里抽。

为什么需要

热词一般是运营位，不应该完全依赖推荐商品标题：

• 热词和推荐商品不是一个概念
• 热词排序和内容应该可单独控制
• 需要支持临时活动词、营销词

建议定义

interface AppHomeResponse {
  banners: BannerInfo[]
  recommendGoods: GoodsSummary[]
  recommendStores: RecommendStoreInfo[]
  categoryNavs: HomeCategoryNav[]
  searchKeywords: string[]
}

示例

[
  "磁吸手机壳",
  "直播补光灯",
  "蓝牙耳机",
  "快充套装",
  "智能手表表带"
]

6. 平台专区 / 频道卡片缺少独立数据源

当前问题

原首页样式里有一块“平台专区 / 场景卡片”区域。当前接口没有对应字段，所以如果要保留这块业务含义，前端只能拿别的数据硬凑。

为什么需要

这类区域通常代表固定业务入口，例如：

• 平台铺货
• 一件代发
• 活动专区
• 类目专题

它不适合和 Banner 或推荐商品混用。

建议定义

interface HomeChannelCard {
  id: number
  title: string
  subTitle: string
  iconUrl: string
  linkType: string
  linkValue: string
  sort: number
  status: "enabled" | "disabled"
}

建议追加到：

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

结论

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

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

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