主题
03 商品搜索
版本：v3.0
所属端：前台商城
文档状态：已交付
1. 概述
1.1 背景与目标
搜索是用户查找目标商品最直接的途径。当用户有明确的购买意向时，通过关键词搜索可以快速定位到目标商品，是转化路径最短的入口。
本模块的设计目标：
- 提供关键词搜索能力，帮助用户快速找到目标商品
- 支持多维度排序，满足不同用户的浏览偏好
- 支持按商品分类浏览，覆盖"逛"的场景
- 搜索结果仅展示有效商品（已上架、未删除）
1.2 目标用户
| 角色 | 使用场景 |
|---|---|
| 游客 | 搜索商品、浏览分类商品、查看搜索结果 |
| 会员 | 同游客，搜索结果可直接加购 |
搜索功能无需登录即可使用。
1.3 功能范围
| 功能模块 | 说明 | 优先级 |
|---|---|---|
| 关键词搜索 | 输入关键词匹配商品名称 | P0 |
| 排序 | 综合/价格升序/价格降序/最新上架 | P0 |
| 分页浏览 | 搜索结果分页展示 | P0 |
| 分类商品列表 | 按分类浏览商品 | P0 |
| 搜索历史 | 记录用户近期搜索关键词 | 待启动 |
| 热门搜索 | 展示平台热门搜索词 | 待启动 |
| 全文检索升级 | 支持分词、高亮、多字段匹配 | 待启动 |
| 属性筛选面板 | 按品牌、价格区间、规格属性筛选 | 待启动 |
2. 功能详细设计
2.1 关键词搜索
页面结构
页面顶部为搜索框（含输入框、搜索按钮、清空按钮）。搜索后进入结果页，顶部为排序栏，下方为商品卡片网格，底部为分页组件。
商品卡片展示内容：商品主图、商品名称（最多两行）、销售价格（促销价优先展示）、原价（划线）、销量。
业务规则
| 编号 | 规则描述 |
|---|---|
| BR-SRCH-01 | 搜索范围为商品名称的模糊匹配 |
| BR-SRCH-02 | 仅搜索已上架且未删除的商品 |
| BR-SRCH-03 | 关键词为空或纯空格时，不执行搜索，提示用户输入 |
| BR-SRCH-04 | 关键词去除前后空格后执行搜索 |
| BR-SRCH-05 | 关键词过长（超过100字符）时截断处理 |
| BR-SRCH-06 | 搜索结果顶部展示"共找到 X 件商品" |
| BR-SRCH-07 | 价格展示规则：有促销价时优先展示促销价，原价以划线形式展示 |
排序规则
| 排序方式 | 说明 |
|---|---|
| 综合（默认） | 按系统默认排序 |
| 价格从低到高 | 按销售价格升序 |
| 价格从高到低 | 按销售价格降序 |
| 最新上架 | 按商品创建时间倒序 |
交互说明
| 用户操作 | 系统反馈 |
|---|---|
| 输入关键词后点击搜索或按回车 | 展示搜索结果，页码重置为第1页 |
| 切换排序方式 | 重新加载列表，页码重置为第1页，滚动到顶部 |
| 点击分页 | 保留当前关键词和排序，加载对应页数据 |
| 点击商品卡片 | 跳转商品详情页 |
| 点击清空按钮 | 清空搜索框内容 |
边界与异常
| 场景 | 处理方式 |
|---|---|
| 无搜索结果 | 展示空态页面，提示"换个关键词试试" |
| 搜索中 | 展示骨架屏加载状态 |
| 关键词为空 | 提示"请输入搜索关键词" |
| 图片加载失败 | 展示默认占位图 |
| 网络异常 | 提示"网络异常，请稍后重试" |
| 分页参数超出范围 | 返回空列表 |
2.2 分类商品列表
页面结构
从首页分类导航或分类页进入。顶部为面包屑导航（首页 > 一级分类 > 二级分类），下方为同级分类切换Tab、排序栏、商品卡片列表、分页组件。
业务规则
| 编号 | 规则描述 |
|---|---|
| BR-SRCH-10 | 点击一级分类时，展示该分类下所有子分类的商品聚合 |
| BR-SRCH-11 | 点击二级分类时，仅展示该分类下的商品 |
| BR-SRCH-12 | 仅展示已上架且未删除的商品 |
| BR-SRCH-13 | 排序规则与关键词搜索一致 |
| BR-SRCH-14 | 面包屑根据分类层级自动生成 |
交互说明
| 用户操作 | 系统反馈 |
|---|---|
| 点击同级分类Tab | 切换分类，重新加载商品列表 |
| 点击面包屑中的分类 | 跳转至对应分类层级 |
| 切换排序/翻页 | 与搜索页行为一致 |
边界与异常
| 场景 | 处理方式 |
|---|---|
| 分类下无商品 | 展示空态页面 |
| 分类不存在 | 提示"分类不存在"并引导回首页 |
2.3 搜索历史（待启动）
预期设计
搜索框获得焦点时，下方展示搜索历史（最近10条）和热门搜索词。点击历史关键词可直接发起搜索。支持一键清除历史记录。
2.4 全文检索升级（待启动）
预期设计
将搜索能力从简单的名称匹配升级为全文检索，支持：
- 多字段匹配（商品名称、副标题、品牌名、关键词）
- 中文分词，提升召回率
- 搜索关键词高亮显示
- 搜索联想（输入时实时提示候选词）
2.5 属性筛选面板（待启动）
预期设计
搜索结果页增加筛选面板，支持按以下维度缩小结果范围：
- 商品分类（树形选择）
- 品牌（仅展示当前分类下有商品的品牌）
- 价格区间（预设区间 + 自定义范围）
- 规格属性（根据分类动态展示，如：网络制式、操作系统等）
多条件可组合使用，选择分类后品牌和属性列表联动更新。
3. 接口能力
| 能力名称 | 说明 | 是否需登录 |
|---|---|---|
| 关键词搜索 | 按关键词搜索商品，支持排序和分页 | 否 |
| 分类商品列表 | 按分类ID浏览商品，支持排序和分页 | 否 |
关键词搜索
- 输入：搜索关键词、页码、每页条数、排序方式
- 输出：商品列表（名称、主图、价格、促销价、销量、品牌、分类、是否有库存）+ 分页信息
分类商品列表
- 输入：分类ID、页码、每页条数、排序方式
- 输出：同关键词搜索
4. 核心数据实体
| 实体 | 业务含义 | 与搜索的关系 |
|---|---|---|
| 商品 | 平台售卖的商品主体 | 搜索的目标对象，匹配名称字段 |
| 商品分类 | 商品的品类归属 | 分类浏览的筛选维度 |
| 品牌 | 商品所属品牌 | 搜索结果中展示品牌名，待启动阶段作为筛选维度 |
5. 验收标准
| 编号 | 验收条件 |
|---|---|
| AC-SRCH-01 | 输入关键词搜索，返回名称匹配的商品列表 |
| AC-SRCH-02 | 搜索结果仅包含已上架商品 |
| AC-SRCH-03 | 四种排序方式均正确生效 |
| AC-SRCH-04 | 分页功能正常，翻页后数据正确 |
| AC-SRCH-05 | 分类商品列表正确展示对应分类下的商品 |
| AC-SRCH-06 | 一级分类展示所有子分类商品，二级分类仅展示本级商品 |
| AC-SRCH-07 | 无搜索结果时展示空态页面 |
| AC-SRCH-08 | 关键词为空时给予提示，不发起无效请求 |
| AC-SRCH-09 | 有促销价的商品优先展示促销价，原价划线 |
| AC-SRCH-10 | 切换排序后页码重置，列表刷新 |