营销活动开发文档

1. 文档概述

1.1 文档目的

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

1.2 适用范围

本文档适用于CRMEB系统开发人员、维护人员及二次开发人员，用于指导营销活动模块的开发、扩展和维护工作。

1.3 术语定义

术语	解释
限时秒杀	在特定时间段内，商品以低于原价的价格销售
商品砍价	用户邀请好友帮忙砍价，以更低价格购买商品
多人拼团	多个用户联合购买商品，享受更低价格
优惠券	可用于抵扣商品价格的电子券
SPU	标准化产品单元，如"iPhone 13"
SKU	库存量单位，如"iPhone 13 128G 白色"
开团	创建拼团活动
参团	加入他人创建的拼团活动
助力	帮助好友砍价

2. 核心功能模块

2.1 限时秒杀

秒杀配置：设置秒杀时间段、参与商品、秒杀价格
秒杀商品管理：添加/编辑/删除参与秒杀的商品
秒杀时间段管理：设置秒杀活动的时间段
秒杀记录：查看用户秒杀记录
秒杀状态管理：开启/关闭秒杀活动

2.2 商品砍价

砍价商品配置：设置砍价商品、初始价格、最低价格、砍价次数
砍价活动管理：添加/编辑/删除砍价活动
砍价记录管理：查看用户砍价记录
砍价助力记录：查看用户砍价助力记录
砍价状态管理：开启/关闭砍价活动

2.3 多人拼团

拼团商品配置：设置拼团商品、拼团价格、成团人数、拼团有效期
拼团活动管理：添加/编辑/删除拼团活动
拼团记录管理：查看拼团记录、成团状态
拼团规则设置：设置拼团规则，如是否允许重复参团
拼团状态管理：开启/关闭拼团活动

2.4 优惠券管理

优惠券模板配置：设置优惠券类型（满减、折扣）、面值、使用条件、有效期
优惠券发放管理：手动发放、自动发放、批量发放优惠券
用户优惠券管理：查看用户领取的优惠券、使用情况
优惠券使用统计：统计优惠券领取量、使用率、优惠金额
优惠券状态管理：开启/关闭优惠券

2.5 积分商城

积分商品配置：设置积分商品、积分价格、库存
积分商品管理：添加/编辑/删除积分商品
积分兑换记录：查看用户积分兑换记录
积分规则设置：设置积分获取、使用规则

2.6 预售活动

预售商品配置：设置预售商品、预售价格、定金、尾款支付时间
预售活动管理：添加/编辑/删除预售活动
预售订单管理：查看预售订单、定金支付情况、尾款支付情况
预售状态管理：开启/关闭预售活动

3. 代码结构与设计

3.1 架构设计

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

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   ActivityModel │     │   ActivityDao   │     │ ActivityServices│
└─────────────────┘     └─────────────────┘     └─────────────────┘
         │                       │                       │
         └───────────────────────┼───────────────────────┘
                                 │
                         ┌─────────────────┐
                         │ ActivityController│
                         └─────────────────┘
                                 │
                         ┌─────────────────┐
                         │     Routes      │
                         └─────────────────┘

3.2 核心文件结构

3.2.1 模型层（Model）

所有营销活动模型均位于 crmeb/app/model/activity/ 目录下，按活动类型分类：

秒杀活动：
- seckill/StoreSeckill.php - 秒杀商品模型
砍价活动：
- bargain/StoreBargain.php - 砍价商品模型
- bargain/StoreBargainUser.php - 砍价用户参与记录模型
- bargain/StoreBargainUserHelp.php - 砍价助力记录模型
拼团活动：
- combination/StoreCombination.php - 拼团商品模型
- combination/StorePink.php - 拼团记录模型
优惠券活动：
- coupon/StoreCoupon.php - 优惠券模板模型
- coupon/StoreCouponIssue.php - 优惠券发放记录模型
- coupon/StoreCouponProduct.php - 优惠券适用商品模型
- coupon/StoreCouponUser.php - 用户优惠券模型

3.2.2 数据访问层（DAO）

所有营销活动DAO均位于 crmeb/app/dao/activity/ 目录下，按活动类型分类：

秒杀活动：
- seckill/StoreSeckillDao.php - 秒杀商品DAO
砍价活动：
- bargain/StoreBargainDao.php - 砍价商品DAO
- bargain/StoreBargainUserDao.php - 砍价用户参与记录DAO
- bargain/StoreBargainUserHelpDao.php - 砍价助力记录DAO
拼团活动：
- combination/StoreCombinationDao.php - 拼团商品DAO
- combination/StorePinkDao.php - 拼团记录DAO
优惠券活动：
- coupon/StoreCouponDao.php - 优惠券模板DAO
- coupon/StoreCouponIssueDao.php - 优惠券发放记录DAO
- coupon/StoreCouponProductDao.php - 优惠券适用商品DAO
- coupon/StoreCouponUserDao.php - 用户优惠券DAO

3.2.3 业务服务层（Services）

所有营销活动Services均位于 crmeb/app/services/activity/ 目录下，按活动类型分类：

秒杀活动：
- seckill/StoreSeckillServices.php - 秒杀商品Services
砍价活动：
- bargain/StoreBargainServices.php - 砍价商品Services
- bargain/StoreBargainUserServices.php - 砍价用户参与记录Services
- bargain/StoreBargainUserHelpServices.php - 砍价助力记录Services
拼团活动：
- combination/StoreCombinationServices.php - 拼团商品Services
- combination/StorePinkServices.php - 拼团记录Services
优惠券活动：
- coupon/StoreCouponServices.php - 优惠券模板Services
- coupon/StoreCouponIssueServices.php - 优惠券发放记录Services
- coupon/StoreCouponUserServices.php - 用户优惠券Services

3.2.4 控制器层（Controller）

管理员API控制器位于 crmeb/app/adminapi/controller/v1/marketing/ 目录下：

StoreSeckill.php - 秒杀活动控制器
StoreBargain.php - 砍价活动控制器
StoreCombination.php - 拼团活动控制器
StoreCoupon.php - 优惠券控制器

移动端API控制器位于 crmeb/app/api/controller/v1/activity/ 目录下，提供移动端调用的活动接口。

3.2.5 路由配置

营销活动路由配置位于 crmeb/app/adminapi/route/marketing.php 文件中，包含了各种活动的增删改查、状态管理、统计等路由。

移动端路由配置位于 crmeb/app/api/route/ 目录下，根据API版本分类。

4. 数据库设计

4.1 秒杀活动相关表

秒杀商品表（store_seckill）

字段名	数据类型	描述
id	int(10) unsigned	秒杀商品ID
product_id	int(10)	关联商品ID
title	varchar(100)	秒杀活动标题
image	varchar(255)	秒杀商品图片
unit_name	varchar(10)	单位名称
sec_price	decimal(10,2)	秒杀价格
price	decimal(10,2)	原价
cost	decimal(10,2)	成本价
description	varchar(255)	秒杀活动描述
start_time	int(10)	开始时间
end_time	int(10)	结束时间
status	tinyint(1)	状态（0-关闭，1-开启）
sales	int(10)	销量
stock	int(10)	库存
give_integral	int(10)	赠送积分
sort	int(10)	排序
is_delete	tinyint(1)	是否删除
add_time	int(10)	添加时间

4.2 砍价活动相关表

砍价商品表（store_bargain）

字段名	数据类型	描述
id	int(10) unsigned	砍价商品ID
product_id	int(10)	关联商品ID
title	varchar(100)	砍价活动标题
image	varchar(255)	砍价商品图片
unit_name	varchar(10)	单位名称
min_price	decimal(10,2)	最低价格
price	decimal(10,2)	原价
cost	decimal(10,2)	成本价
description	varchar(255)	砍价活动描述
start_time	int(10)	开始时间
end_time	int(10)	结束时间
status	tinyint(1)	状态（0-关闭，1-开启）
sales	int(10)	销量
stock	int(10)	库存
people_num	int(10)	每人可发起砍价次数
bargain_num	int(10)	每次砍价可邀请人数
sort	int(10)	排序
is_delete	tinyint(1)	是否删除
add_time	int(10)	添加时间

砍价用户参与记录表（store_bargain_user）

字段名	数据类型	描述
id	int(10) unsigned	记录ID
uid	int(10)	用户ID
bargain_id	int(10)	砍价商品ID
price	decimal(10,2)	最终砍价价格
status	tinyint(1)	状态（0-进行中，1-成功，2-失败）
add_time	int(10)	开始时间
stop_time	int(10)	结束时间

砍价助力记录表（store_bargain_user_help）

字段名	数据类型	描述
id	int(10) unsigned	记录ID
bargain_user_id	int(10)	砍价用户记录ID
uid	int(10)	助力用户ID
price	decimal(10,2)	砍掉的价格
add_time	int(10)	助力时间

4.3 拼团活动相关表

拼团商品表（store_combination）

字段名	数据类型	描述
id	int(10) unsigned	拼团商品ID
product_id	int(10)	关联商品ID
title	varchar(100)	拼团活动标题
image	varchar(255)	拼团商品图片
unit_name	varchar(10)	单位名称
pink_price	decimal(10,2)	拼团价格
price	decimal(10,2)	原价
cost	decimal(10,2)	成本价
description	varchar(255)	拼团活动描述
start_time	int(10)	开始时间
end_time	int(10)	结束时间
status	tinyint(1)	状态（0-关闭，1-开启）
sales	int(10)	销量
stock	int(10)	库存
people	int(10)	成团人数
sort	int(10)	排序
is_delete	tinyint(1)	是否删除
add_time	int(10)	添加时间

拼团记录表（store_pink）

字段名	数据类型	描述
id	int(10) unsigned	记录ID
cid	int(10)	拼团商品ID
uid	int(10)	开团用户ID
order_id	int(10)	开团订单ID
people	int(10)	成团人数
price	decimal(10,2)	拼团价格
status	tinyint(1)	状态（0-拼团中，1-成团，2-失败）
add_time	int(10)	开团时间
stop_time	int(10)	结束时间

4.4 优惠券相关表

优惠券模板表（store_coupon）

字段名	数据类型	描述
id	int(10) unsigned	优惠券ID
type	tinyint(1)	优惠券类型（0-满减，1-折扣）
title	varchar(100)	优惠券名称
money	decimal(10,2)	优惠券金额
min_price	decimal(10,2)	最低使用金额
discount	decimal(10,2)	折扣（如9.5折）
use_type	tinyint(1)	使用类型（0-全场通用，1-指定商品，2-指定分类）
start_time	int(10)	开始时间
end_time	int(10)	结束时间
status	tinyint(1)	状态（0-关闭，1-开启）
total_count	int(10)	总发行量
give_count	int(10)	已发放数量
use_count	int(10)	已使用数量
get_type	tinyint(1)	获取方式（0-手动领取，1-自动发放）
is_perpetual	tinyint(1)	是否永久有效
effective_days	int(10)	有效天数
sort	int(10)	排序
add_time	int(10)	添加时间

用户优惠券表（store_coupon_user）

字段名	数据类型	描述
id	int(10) unsigned	记录ID
cid	int(10)	优惠券ID
uid	int(10)	用户ID
status	tinyint(1)	状态（0-未使用，1-已使用，2-已过期）
get_time	int(10)	领取时间
use_time	int(10)	使用时间
order_id	int(10)	使用订单ID
end_time	int(10)	过期时间

5. API接口说明

5.1 秒杀活动接口

5.1.1 秒杀商品列表

请求URL：/adminapi/v1/marketing/seckill/list
请求方法：GET
权限要求：marketing/seckill/list
请求参数：
- page：页码
- limit：每页数量
- keyword：搜索关键词
- status：状态（0-关闭，1-开启）
返回结果：秒杀商品列表数据

5.1.2 添加秒杀商品

请求URL：/adminapi/v1/marketing/seckill/create
请求方法：POST
权限要求：marketing/seckill/create
请求参数：秒杀商品信息
返回结果：操作结果

5.1.3 编辑秒杀商品

请求URL：/adminapi/v1/marketing/seckill/update/{id}
请求方法：PUT
权限要求：marketing/seckill/update
请求参数：秒杀商品信息
返回结果：操作结果

5.1.4 删除秒杀商品

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

5.2 砍价活动接口

5.2.1 砍价商品列表

请求URL：/adminapi/v1/marketing/bargain/list
请求方法：GET
权限要求：marketing/bargain/list
请求参数：
- page：页码
- limit：每页数量
- keyword：搜索关键词
- status：状态（0-关闭，1-开启）
返回结果：砍价商品列表数据

5.2.2 添加砍价商品

请求URL：/adminapi/v1/marketing/bargain/create
请求方法：POST
权限要求：marketing/bargain/create
请求参数：砍价商品信息
返回结果：操作结果

5.3 拼团活动接口

5.3.1 拼团商品列表

请求URL：/adminapi/v1/marketing/combination/list
请求方法：GET
权限要求：marketing/combination/list
请求参数：
- page：页码
- limit：每页数量
- keyword：搜索关键词
- status：状态（0-关闭，1-开启）
返回结果：拼团商品列表数据

5.3.2 添加拼团商品

请求URL：/adminapi/v1/marketing/combination/create
请求方法：POST
权限要求：marketing/combination/create
请求参数：拼团商品信息
返回结果：操作结果

5.4 优惠券接口

5.4.1 优惠券列表

请求URL：/adminapi/v1/marketing/coupon/list
请求方法：GET
权限要求：marketing/coupon/list
请求参数：
- page：页码
- limit：每页数量
- keyword：搜索关键词
- status：状态（0-关闭，1-开启）
返回结果：优惠券列表数据

5.4.2 添加优惠券

请求URL：/adminapi/v1/marketing/coupon/create
请求方法：POST
权限要求：marketing/coupon/create
请求参数：优惠券信息
返回结果：操作结果

5. 开发规范与流程

5.1 代码规范

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

5.2 开发流程

需求分析：明确营销活动的功能需求和业务逻辑
设计阶段：设计数据结构、API接口和业务流程
编码实现：按照分层架构编写代码
单元测试：编写单元测试，确保功能正确性
集成测试：进行模块集成测试，测试活动与商品、订单等模块的交互
性能测试：对高并发场景进行性能测试，如秒杀活动
代码审查：提交代码审查，确保代码质量
部署上线：部署到生产环境

6. 常见问题与解决方案

6.1 高并发处理

问题：秒杀、拼团等活动在高并发场景下可能出现超卖、数据不一致等问题 解决方案：

使用数据库事务和乐观锁机制
实现库存预扣和释放机制
使用Redis等缓存技术，提高库存操作效率
采用分布式锁，确保数据一致性
实现流量削峰，如使用队列、限流等技术

6.2 活动时间管理

问题：活动开始和结束时间的精确控制 解决方案：

使用定时器任务，定期检查活动状态
在关键操作（如用户参与活动）时，再次验证活动时间
使用Redis的过期时间功能，自动更新活动状态

6.3 活动数据统计

问题：实时统计活动参与人数、销售额等数据 解决方案：

使用Redis缓存实时数据，定期同步到数据库
采用异步处理方式，避免影响主业务流程
实现数据报表功能，支持多维度查询

6.4 活动冲突处理

问题：同一商品参与多个活动时的冲突 解决方案：

设计活动优先级机制，明确活动执行顺序
在用户参与活动时，验证商品是否可以同时参与多个活动
提供活动冲突检测功能，在创建活动时提示冲突

7. 扩展与定制

7.1 功能扩展

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

添加新活动类型：
- 在 model/activity/ 目录下创建新的活动模型
- 在 dao/activity/ 目录下创建对应的DAO
- 在 services/activity/ 目录下创建对应的Services
- 在 controller/ 目录下创建对应的控制器
- 在路由文件中添加新的路由
扩展现有活动功能：
- 在现有模型中添加新字段
- 在现有Services中添加新方法
- 在现有控制器中添加新接口

7.2 事件扩展

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

活动开始事件：ActivityStartEvent
活动结束事件：ActivityEndEvent
用户参与活动事件：UserJoinActivityEvent
活动订单创建事件：ActivityOrderCreateEvent
活动订单支付事件：ActivityOrderPayEvent

7.3 钩子扩展

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

活动创建前钩子：activity_create_before
活动创建后钩子：activity_create_after
活动编辑前钩子：activity_edit_before
活动编辑后钩子：activity_edit_after
活动删除前钩子：activity_delete_before
活动删除后钩子：activity_delete_after
用户参与活动前钩子：user_join_activity_before
用户参与活动后钩子：user_join_activity_after

8. 文档更新记录

版本	更新日期	更新内容	更新人
1.0	2026-01-19	初始版本，包含秒杀、砍价、拼团、优惠券等核心营销活动	AI Assistant

9. 附录

9.1 核心类关系图

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│   ActivityModel │     │   ActivityDao   │     │ ActivityServices│
└─────────────────┘     └─────────────────┘     └─────────────────┘
         │                       │                       │
         └───────────────────────┼───────────────────────┘
                                 │
                         ┌─────────────────┐
                         │ ActivityController│
                         └─────────────────┘
                                 │
                         ┌─────────────────┐
                         │     Routes      │
                         └─────────────────┘

9.2 秒杀活动流程图

秒杀活动流程：
1. 用户进入秒杀活动页面
2. 系统验证活动是否开始
3. 用户点击秒杀按钮
4. 系统验证商品库存
5. 系统预扣商品库存
6. 用户创建订单
7. 用户支付订单
8. 系统确认订单，扣减库存
9. 活动结束，释放未支付订单的库存

9.3 拼团活动流程图

拼团活动流程：
1. 用户进入拼团活动页面
2. 选择商品和拼团规格
3. 选择开团或参团
   a. 开团：创建新的拼团记录
   b. 参团：加入已有拼团记录
4. 系统预扣商品库存
5. 用户创建订单
6. 用户支付订单
7. 系统检查是否达到成团人数
   a. 达到：拼团成功
   b. 未达到：等待其他用户参团
8. 拼团时间结束
   a. 成团：订单生效
   b. 未成团：退款给用户，释放库存

9.4 砍价活动流程图

砍价活动流程：
1. 用户进入砍价活动页面
2. 选择商品，点击开始砍价
3. 系统创建砍价记录
4. 用户邀请好友帮忙砍价
5. 好友点击助力，系统随机砍掉一定金额
6. 用户达到最低价格或砍价时间结束
7. 用户以砍价价格购买商品
8. 系统创建订单，扣减库存

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

营销活动开发文档.md 22 KB History Raw