商品管理开发文档

1. 文档概述

1.1 文档目的

本文档旨在详细说明CRMEB系统中商品管理模块的设计架构、核心功能、代码实现及开发规范，为系统开发人员提供完整的开发参考。

1.2 适用范围

本文档适用于CRMEB系统开发人员、维护人员及二次开发人员，用于指导商品管理模块的开发、扩展和维护工作。

1.3 术语定义

术语	解释
SPU	标准化产品单元，如"iPhone 13"
SKU	库存量单位，如"iPhone 13 128G 白色"
商品属性	商品的特征，如颜色、尺寸等
商品规格	商品属性的具体值，如红色、XL等
商品分类	用于组织商品的树形分类结构
商品标签	用于标记商品特征的关键词

2. 核心功能模块

2.1 商品基础管理

商品列表：展示商品基本信息，支持多条件搜索、分页
商品详情：查看商品完整信息，包括基本信息、规格信息、活动信息等
商品添加：添加新商品，支持SPU生成、规格模板选择
商品编辑：修改商品信息，支持规格调整、活动关联等
商品删除：删除商品，支持物理删除和逻辑删除
商品上下架：控制商品的销售状态
商品批量操作：支持批量上下架、批量删除、批量修改等

2.2 商品规格管理

规格属性管理：定义商品的属性，如颜色、尺寸等
规格值管理：为每个属性定义具体值
SKU生成：根据属性组合自动生成SKU
规格模板：支持保存和使用规格模板，提高商品添加效率

2.3 商品分类管理

分类列表：展示商品分类，支持树形结构
分类添加：添加新分类，支持多级分类
分类编辑：修改分类信息，包括名称、图标、排序等
分类删除：删除分类，支持批量删除
分类排序：调整分类的显示顺序

2.4 商品评论管理

评论列表：展示商品评论，支持多条件筛选
评论审核：审核用户提交的评论
评论回复：回复用户评论
虚拟评论：支持添加虚拟评论
评论删除：删除不适当的评论

2.5 商品标签管理

标签列表：展示商品标签
标签添加：添加新标签，支持标签分类
标签编辑：修改标签信息
标签删除：删除标签
标签关联：将标签关联到商品

2.6 商品参数管理

参数列表：展示商品参数
参数添加：添加自定义参数
参数编辑：修改参数信息
参数删除：删除参数
参数值管理：为商品设置具体参数值

2.7 商品保障管理

保障服务配置：配置商品保障服务，如退换货政策、质保期等
保障服务关联：将保障服务关联到商品

2.8 商品采集功能

淘宝/天猫商品采集：支持从淘宝/天猫复制商品信息
批量导入：支持批量导入商品数据
数据迁移：支持从其他系统迁移商品数据

2.9 商品活动关联

秒杀活动关联：将商品关联到秒杀活动
砍价活动关联：将商品关联到砍价活动
拼团活动关联：将商品关联到拼团活动
优惠券关联：为商品配置优惠券

3. 代码结构与设计

3.1 架构设计

系统采用分层架构设计，严格遵循MVC设计模式：

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   ProductModel  │     │    ProductDao   │     │ ProductServices │
└─────────────────┘     └─────────────────┘     └─────────────────┘
         │                       │                       │
         └───────────────────────┼───────────────────────┘
                                 │
                         ┌─────────────────┐
                         │ ProductController│
                         └─────────────────┘
                                 │
                         ┌─────────────────┐
                         │     Routes      │
                         └─────────────────┘

3.2 核心文件结构

3.2.1 模型层（Model）

商品主模型：crmeb/app/model/product/product/StoreProduct.php

继承自BaseModel，使用ModelTrait
包含商品基本信息字段
定义了与其他模型的关联关系：
- 商品分类（storeCategory）
- 商品规格（attr、attrValue、attrResult）
- 商品描述（storeDescription）
- 商品评论（reply）
- 商品标签（label）
- 商品参数（param）
- 商品保障（protection）
- 商品优惠券（coupon）
- 商品活动（activity）
提供了丰富的搜索器方法

商品规格相关模型：

StoreProductAttr.php - 商品属性模型
StoreProductAttrValue.php - 商品属性值模型
StoreProductAttrResult.php - 商品属性结果模型

商品分类模型：

StoreCategory.php - 商品分类模型

3.2.2 数据访问层（DAO）

商品DAO：crmeb/app/dao/product/product/StoreProductDao.php

继承自BaseDao
提供商品列表查询、统计计数、字段更新等方法
支持分页、条件搜索
包含商品库存、销量等核心数据管理

3.2.3 业务服务层（Services）

商品Services：crmeb/app/services/product/product/StoreProductServices.php

实现商品管理的核心业务逻辑
商品列表、详情、保存、删除、规格管理等核心功能
处理商品与分类、规格、优惠券、活动等关联关系
支持商品SPU生成、规格模板管理
实现商品属性验证和SKU生成
处理商品库存、销量等核心数据管理

3.2.4 控制器层（Controller）

商品Controller：crmeb/app/adminapi/controller/v1/product/StoreProduct.php

处理商品管理的HTTP请求
支持商品的增删改查、上架下架、批量操作
提供商品规格生成、活动检测、卡密导入功能
支持商品数据缓存
实现商品批量设置、迁移导入导出功能

3.2.5 路由配置

商品路由：crmeb/app/adminapi/route/product.php

包含商品管理相关的所有API路由
模块化设计：商品分类、商品管理、商品评论、商品采集、商品标签、商品参数、商品保障
每个模块包含完整的CRUD操作路由
支持权限控制和日志记录

4. 数据库设计

4.1 商品主表（store_product）

字段名	数据类型	描述
id	int(10) unsigned	商品ID（主键）
cid	int(10)	分类ID
merchant_id	int(10)	商户ID
store_name	varchar(100)	商品名称
store_info	text	商品简介
keywords	varchar(255)	关键词
image	varchar(255)	商品主图
slider_image	text	轮播图
video_link	varchar(255)	视频链接
price	decimal(10,2)	商品价格
ot_price	decimal(10,2)	原价
unit_name	varchar(10)	单位名称
stock	int(10)	库存
sales	int(10)	销量
sales_actual	int(10)	实际销量
give_integral	int(10)	赠送积分
cost	decimal(10,2)	成本价
is_show	tinyint(1)	是否显示
is_hot	tinyint(1)	是否热门
is_new	tinyint(1)	是否新品
is_recommend	tinyint(1)	是否推荐
is_postage	tinyint(1)	是否包邮
postage	decimal(10,2)	邮费
unit_id	int(10)	计量单位ID
sort	int(10)	排序
add_time	int(10)	添加时间
is_deleted	tinyint(1)	是否删除
store_content	longtext	商品详情
virtual_sales	int(10)	虚拟销量
browse	int(10)	浏览量
code_path	varchar(255)	商品码路径
temp_id	int(10)	商品模板ID
goods_id	int(10)	商品SPU ID
specs_type	tinyint(1)	规格类型

4.2 商品规格相关表

商品属性表（store_product_attr）

字段名	数据类型	描述
id	int(10) unsigned	属性ID
product_id	int(10)	商品ID
attr_name	varchar(50)	属性名称
attr_values	text	属性值
sort	int(10)	排序
add_time	int(10)	添加时间

商品属性值表（store_product_attr_value）

字段名	数据类型	描述
id	int(10) unsigned	属性值ID
product_id	int(10)	商品ID
attr_id	int(10)	属性ID
attr_value	varchar(50)	属性值
image	varchar(255)	属性图片
sort	int(10)	排序
add_time	int(10)	添加时间

商品属性结果表（store_product_attr_result）

字段名	数据类型	描述
id	int(10) unsigned	结果ID
product_id	int(10)	商品ID
attr_result	varchar(255)	属性结果（JSON格式）
stock	int(10)	库存
price	decimal(10,2)	价格
cost	decimal(10,2)	成本价
code	varchar(30)	商品编码
bar_code	varchar(30)	条形码
weight	decimal(10,2)	重量
volume	decimal(10,2)	体积
sales	int(10)	销量
sales_actual	int(10)	实际销量
image	varchar(255)	商品图片
is_show	tinyint(1)	是否显示
sort	int(10)	排序
unique	varchar(255)	唯一值

4.3 商品分类表（store_category）

字段名	数据类型	描述
id	int(10) unsigned	分类ID
pid	int(10)	父分类ID
cate_name	varchar(50)	分类名称
icon	varchar(255)	分类图标
sort	int(10)	排序
is_show	tinyint(1)	是否显示
add_time	int(10)	添加时间

5. API接口说明

5.1 商品基础管理接口

5.1.1 商品列表

请求URL：/adminapi/v1/product/list
请求方法：GET
权限要求：product/product/list
请求参数：
- page：页码
- limit：每页数量
- keyword：搜索关键词
- cid：分类ID
- price_min：最低价格
- price_max：最高价格
- is_show：是否显示
- is_hot：是否热门
- is_new：是否新品
- is_recommend：是否推荐
返回结果：商品列表数据

5.1.2 商品详情

请求URL：/adminapi/v1/product/detail/{id}
请求方法：GET
权限要求：product/product/detail
返回结果：商品详细信息

5.1.3 添加商品

请求URL：/adminapi/v1/product/create
请求方法：POST
权限要求：product/product/create
请求参数：商品基本信息、规格信息等
返回结果：操作结果

5.1.4 编辑商品

请求URL：/adminapi/v1/product/update/{id}
请求方法：PUT
权限要求：product/product/update
请求参数：商品基本信息、规格信息等
返回结果：操作结果

5.1.5 删除商品

请求URL：/adminapi/v1/product/delete/{id}
请求方法：DELETE
权限要求：product/product/delete
返回结果：操作结果

5.1.6 商品上下架

请求URL：/adminapi/v1/product/status/{id}
请求方法：PUT
权限要求：product/product/status
请求参数：
- is_show：是否显示（1-显示，0-隐藏）
返回结果：操作结果

5.2 商品分类管理接口

5.2.1 分类列表

请求URL：/adminapi/v1/product/category/list
请求方法：GET
权限要求：product/category/list
返回结果：分类列表数据

5.2.2 添加分类

请求URL：/adminapi/v1/product/category/create
请求方法：POST
权限要求：product/category/create
请求参数：分类信息
返回结果：操作结果

5.2.3 编辑分类

请求URL：/adminapi/v1/product/category/update/{id}
请求方法：PUT
权限要求：product/category/update
请求参数：分类信息
返回结果：操作结果

5.2.4 删除分类

请求URL：/adminapi/v1/product/category/delete/{id}
请求方法：DELETE
权限要求：product/category/delete
返回结果：操作结果

6. 开发规范与流程

6.1 代码规范

命名规范：
- 类名采用大驼峰命名法
- 方法名采用小驼峰命名法
- 变量名采用小驼峰命名法
- 常量名采用全大写，下划线分隔
代码结构：
- 严格遵循分层架构，禁止跨层调用
- 每个方法职责单一，代码行数控制在50行以内
- 适当添加注释，说明方法功能、参数含义和返回值
数据库操作：
- 所有数据库操作必须通过Dao层进行
- 使用ORM提供的查询构建器，避免直接编写SQL
- 批量操作使用事务处理

6.2 开发流程

需求分析：明确功能需求和业务逻辑
设计阶段：设计数据结构、API接口和业务流程
编码实现：按照分层架构编写代码
单元测试：编写单元测试，确保功能正确性
集成测试：进行模块集成测试
代码审查：提交代码审查，确保代码质量
部署上线：部署到生产环境

7. 常见问题与解决方案

7.1 SKU生成问题

问题：商品规格属性过多时，SKU生成数量过大，导致页面卡顿 解决方案：

限制单个商品的属性数量和每个属性的取值数量
使用异步加载方式生成SKU
优化SKU生成算法，提高生成效率

7.2 商品库存管理

问题：高并发场景下，商品库存出现超卖问题 解决方案：

使用数据库事务和乐观锁机制
实现库存预扣和释放机制
考虑使用Redis等缓存技术，提高库存操作效率

7.3 商品数据同步

问题：商品数据在多个终端间同步不及时 解决方案：

使用消息队列实现数据同步
实现数据缓存机制，减少数据库查询压力
采用事件驱动架构，确保数据变更及时通知

7.4 商品搜索性能

问题：商品数量过多时，搜索速度变慢 解决方案：

优化数据库索引设计
考虑使用搜索引擎，如Elasticsearch
实现搜索结果缓存

8. 扩展与定制

8.1 功能扩展

系统设计具有良好的扩展性，可通过以下方式扩展功能：

添加新模型：继承BaseModel，定义新的数据结构
添加新服务：继承BaseServices，实现新的业务逻辑
添加新控制器：继承BaseController，处理新的API请求
添加新路由：在路由文件中定义新的路由规则

8.2 事件扩展

系统在关键业务节点触发事件，可通过监听事件进行功能扩展：

商品添加事件：ProductAddEvent
商品编辑事件：ProductUpdateEvent
商品删除事件：ProductDeleteEvent
商品上下架事件：ProductStatusEvent
商品库存变动事件：ProductStockChangeEvent

8.3 钩子扩展

系统提供了多个钩子点，可通过钩子函数进行功能扩展：

商品添加前钩子：product_add_before
商品添加后钩子：product_add_after
商品编辑前钩子：product_edit_before
商品编辑后钩子：product_edit_after
商品删除前钩子：product_delete_before
商品删除后钩子：product_delete_after

9. 文档更新记录

版本	更新日期	更新内容	更新人
1.0	2026-01-19	初始版本，包含商品管理核心功能	AI Assistant

10. 附录

10.1 核心类关系图

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   ProductModel  │     │    ProductDao   │     │ ProductServices │
└─────────────────┘     └─────────────────┘     └─────────────────┘
         │                       │                       │
         └───────────────────────┼───────────────────────┘
                                 │
                         ┌─────────────────┐
                         │ ProductController│
                         └─────────────────┘
                                 │
                         ┌─────────────────┐
                         │     Routes      │
                         └─────────────────┘

10.2 商品添加流程图

商品添加流程：
1. 接收商品基本信息
2. 验证商品信息合法性
3. 处理商品分类关联
4. 生成商品SPU（如果需要）
5. 处理商品规格属性
6. 生成SKU列表
7. 保存商品主信息
8. 保存商品规格信息
9. 保存商品描述
10. 关联商品标签、参数、保障等
11. 返回操作结果

10.3 商品上下架流程图

商品上下架流程：
1. 接收商品ID和状态
2. 验证商品是否存在
3. 更新商品状态
4. 清除商品缓存（如果需要）
5. 触发商品状态变更事件
6. 返回操作结果

提示：该文档由AI生成，仅供参考。

商品管理开发文档.md 18 KB History Raw