简介
本文件面向电商应用开发者，提供“商品管理模块”的API参考。覆盖商品列表查询、详情获取、分类浏览、属性管理与价格计算等能力；并给出搜索与排序、筛选参数、分页规范、错误处理与最佳实践建议。当前仓库已实现的商品相关API包括：
- 商品列表（支持分类、品牌、归档时间、排序）
- 商品详情（含图片、品牌、收藏状态、Markdown内容渲染）
- 商品属性列表（规格属性、自定义属性及选中值的价格联动）
注意：仓库未包含独立的“关键词搜索”“库存/价格/促销写操作”等接口，文档将基于现有代码进行准确描述，并对缺失能力给出扩展建议。
项目结构
商品API位于 api 模块下，路由通过声明式方式注册，控制器调用前台服务层完成数据组装与业务逻辑。
graph TB
A["客户端"] --> B["API路由: product.php"]
B --> C["API控制器: ProductController"]
C --> D["前台服务: ProductService"]
D --> E["模型/ORM: FrontProductModel"]
D --> F["定价服务: PricingService"]
D --> G["附件服务: attachment()"]
D --> H["属性服务: AttributeService"]核心组件
- API路由与控制器：负责接收请求、解析参数、调用服务、返回统一响应。
- 前台服务层：封装商品列表构建、详情构建、属性与价格计算、附件与品牌信息聚合。
- 属性服务：按模块、分类、商品维度加载属性与属性值，支持选中值对价格的联动。
- 定价服务：根据用户身份、活动规则计算实际售价。
架构总览
商品API采用“控制器-服务-模型/外部服务”的分层架构。列表与详情由同一服务方法统一处理，保证数据一致性；属性与价格通过独立服务解耦。
sequenceDiagram
participant C as "客户端"
participant R as "API路由"
participant PC as "ProductController"
participant PS as "ProductService"
participant PR as "PricingService"
participant AT as "Attachment/附件"
participant AS as "AttributeService"
C->>R : GET /api/?route=product
R->>PC : index()
PC->>PS : buildProductListData(...)
PS->>PR : salePrice(...)
PS->>AT : galleryFirstMap(...)
PS-->>PC : 列表+分页+排序选项
PC-->>C : 成功响应
C->>R : GET /api/?route=product/{id}
R->>PC : show()
PC->>PS : buildProductShowData(...)
PS->>PR : salePrice(...)
PS->>AT : gallery(...)
PS-->>PC : 详情数据
PC-->>C : 成功响应
C->>R : GET /api/?route=product/attribute_list
R->>PC : attributeList()
PC->>AS : getAttributeList(...)
AS-->>PC : 属性与值
PC-->>C : 成功响应详细接口说明
通用约定
- 入口形式：/api/?route=product[...子路径]
- 认证：部分接口会读取当前登录用户ID（如收藏状态、会员价），需携带平台约定的鉴权头或会话。
- 分页：列表接口默认每页条数由控制器决定；详情页不分页。
- 统一响应：成功返回 data 包裹的数据体；失败返回标准错误结构。
1) 商品列表
- 方法：GET
- 路径：/api/?route=product
- 功能：按分类、品牌、归档时间、排序条件分页获取商品列表。
- 关键参数
- id：分类ID；传 0 表示全部分类（小程序场景）。
- category_slug：分类别名（与 id 二选一）。
- brand_id：品牌ID过滤。
- by：排序字段，支持 sales、price、created_at、sort。
- sort：排序方向，通常配合 by 使用。
- page：页码。
- year/month：归档时间（年/月），与分类互斥。
- 返回要点
- product_list：商品数组，包含标题、缩略图、主图、其他图、价格、销量、库存、销售占比等。
- pager：分页信息。
- sort_list：可用排序项。
- brand：品牌信息（若启用品牌功能）。
- title/category_id/product_category：分类信息与树。
- 行为说明
- 列表页在API模式下会额外返回 stock、sales、sales_percentage。
- 当未传分类且非全部分类时，回退到第一个分类。
- 归档模式与分类模式互斥。
flowchart TD
Start(["进入列表接口"]) --> Parse["解析参数<br/>id/category_slug/brand_id/by/sort/page/year/month"]
Parse --> CatCheck{"是否归档?"}
CatCheck --> |是| UseArchive["使用归档过滤"]
CatCheck --> |否| UseCat["使用分类过滤"]
UseArchive --> BuildSort["构建排序选项"]
UseCat --> BuildSort
BuildSort --> Query["查询商品(发布态)+品牌过滤+排序+分页"]
Query --> Enrich["补充附件/收藏/品牌/价格"]
Enrich --> Return["返回 product_list/pager/sort_list/brand/title/category"]2) 商品详情
- 方法：GET
- 路径：/api/?route=product/{id}
- 功能：获取商品详情，包含标题、内容（Markdown转HTML）、图片、品牌、收藏状态、价格与优惠价等。
- 关键参数
- id：商品ID；也支持 category_slug/slug 作为路由识别。
- 返回要点
- product：商品主体数据（包含 defined、content、image、thumb、gallery_list、brand、favorites、sale_price 等）。
- open：功能开关（如订单功能）。
- coupon_list：优惠券列表（若启用优惠券模块）。
- 行为说明
- 详情页在API模式下会返回 price_format 格式化后的价格。
- 内容通过 Markdown 渲染为 HTML。
- 图片集合通过附件服务获取。
sequenceDiagram
participant C as "客户端"
participant PC as "ProductController"
participant PS as "ProductService"
participant PR as "PricingService"
participant AT as "Attachment"
C->>PC : GET /api/?route=product/{id}
PC->>PS : buildProductShowData(id, userId)
PS->>PR : salePrice(...)
PS->>AT : gallery(...)
PS-->>PC : 商品详情
PC-->>C : 成功响应3) 商品属性列表（规格/自定义属性）
- 方法：GET
- 路径：/api/?route=product/attribute_list
- 功能：根据商品ID与分类，返回该商品可用的属性与属性值，支持选中值对价格的影响。
- 关键参数
- id：商品ID；也支持 category_slug/slug。
- attribute_data：JSON字符串，表示已选中的属性值映射（键为属性ID，值为属性值ID）。
- 返回要点
- attribute_list：属性列表，每个属性包含名称、类型、值列表、选中值ID、选中值价格变动。
- box：基础价格、折后价、积分等汇总信息。
- 行为说明
- 若属性模块未启用或未安装，返回空列表。
- 选中属性的价格变动会累加到基础价格与折后价中。
sequenceDiagram
participant C as "客户端"
participant PC as "ProductController"
participant AS as "AttributeService"
participant PS as "ProductService"
C->>PC : GET /api/?route=product/attribute_list?id=...&attribute_data=...
PC->>AS : getAttributeList(module='product', catId, itemId, 'common')
AS-->>PC : 属性与值
PC->>PS : buildApiAttributeData(...)
PS-->>PC : 属性列表+价格盒
PC-->>C : 成功响应4) 商品搜索与筛选
- 当前实现
- 支持按分类、品牌、归档时间（年/月）筛选。
- 支持排序字段：sales、price、created_at、sort。
- 未实现能力
- 关键词全文搜索：未在商品API中发现关键词搜索参数与实现。
- 多条件组合筛选：仅支持品牌与分类/归档的组合。
- 建议扩展
- 新增 keyword 参数并在服务层增加模糊匹配范围（标题、关键词、描述）。
- 新增价格区间、上架状态、标签等多维筛选。
- 引入缓存与索引优化高频查询。
5) 商品图片处理
- 当前实现
- 列表与详情均通过附件服务获取图片URL与缩略图。
- 详情返回 gallery_list 完整图集；列表返回 image_other 首图。
- 未实现能力
- 图片上传、缩略图生成、图片优化等写操作接口在当前仓库中未发现。
- 建议扩展
- 新增图片上传接口，支持多图、压缩、水印、缩略图生成。
- 提供图片删除与替换接口。
- 结合对象存储与CDN提升访问性能。
6) 库存、价格与促销管理
- 当前实现
- 列表返回 stock、sales、sales_percentage。
- 价格通过定价服务计算，支持属性值价格变动叠加。
- 详情返回 sale_price（可能为空，表示无活动价）。
- 未实现能力
- 库存增减、批量调价、促销活动创建/更新等写操作接口在当前仓库中未发现。
- 建议扩展
- 新增库存扣减与回滚接口，确保并发安全。
- 新增价格模板与促销规则引擎，支持限时折扣、满减、会员价等。
- 提供价格历史与审计日志。
依赖关系分析
- 控制器依赖服务：ProductController 依赖 ProductService 与 AttributeService。
- 服务依赖外部能力：定价服务、附件服务、品牌模型、Markdown渲染器、排序构建器。
- 路由与控制器映射：通过声明式路由将 /api/?route=product 映射到对应方法。
classDiagram
class ProductController {
+index(request)
+show(request)
+attributeList(request)
}
class ProductService {
+buildProductListData(...)
+buildProductShowData(...)
+buildApiAttributeData(...)
}
class AttributeService {
+getAttributeList(...)
+getValueList(...)
}
class PricingService {
+salePrice(...)
}
ProductController --> ProductService : "调用"
ProductController --> AttributeService : "间接调用"
ProductService --> PricingService : "调用"性能与扩展建议
- 列表查询
- 合理使用 by/sort 避免全表扫描；必要时为常用排序字段建立索引。
- 归档与分类互斥，减少不必要的数据集合并。
- 图片与附件
- 使用缩略图与CDN加速；大图按需懒加载。
- 属性与价格
- 属性值价格变动较小，适合前端增量计算；服务端保持幂等。
- 扩展点
- 关键词搜索：建议在服务层增加关键词过滤与分词检索。
- 高级筛选：引入结构化查询构建器，支持多条件组合。
- 缓存：对热门分类与详情结果做短期缓存。
故障排查指南
- 页面错误
- 当分类或商品不存在时，控制器抛出领域异常，返回“页面错误”。
- 参数校验
- 属性接口对 module 与 item_id 进行校验，非法参数返回无效参数错误。
- 常见问题
- 列表为空：检查分类/品牌/归档参数是否正确；确认商品是否已发布。
- 价格显示讨论：当商品价格为0时，列表与详情会显示“面议”提示。
- 属性为空：确认属性模块是否启用；确认商品所属分类是否配置了属性。
结论
当前商品API提供了稳定的列表、详情与属性能力，满足电商前端展示与交互的核心需求。对于关键词搜索、图片上传、库存与促销管理等高级能力，可在现有服务层基础上进行扩展，遵循统一的控制器-服务分层与响应格式，确保可维护性与可扩展性。
附录：请求响应示例与错误码
- 请求示例
- 商品列表：GET /api/?route=product&id=1&brand_id=2&by=price&sort=ASC&page=1
- 商品详情：GET /api/?route=product&id=123
- 属性列表：GET /api/?route=product/attribute_list&id=123&attribute_data={"1":"5","2":"8"}
- 响应结构
- 成功：{ code: 200, message: "success", data: {...} }
- 失败：{ code: 400/422/500, message: "错误描述", data: {} }
- 常见错误
- 无效参数：module/item_id 校验失败。
- 页面错误：分类或商品不存在。
- 权限不足：需要登录但未登录（视平台鉴权策略而定）。