github/CRMEB
1
0
Fork 0
mirror of https://github.com/crmeb/CRMEB.git synced 2026-10-29 14:01:07 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: 添加多个文档文件包括业务流程说明、API接口文档等

Browse Source 
新增多个文档文件，涵盖业务流程说明、API接口文档、开发规范说明、AI代码理解指南、配置参数说明、数据库结构设计、分销系统说明文档、uniapp目录结构、uniapp前端架构说明、uniapp目录结构详细说明、系统错误码说明、订单模块说明、项目目录文档、docker安装说明文档、移动端前端架构说明、移动端前端目录结构详细说明、系统队列任务开发文档等，为项目提供全面的文档支持
This commit is contained in:
sugar1569 2026-01-23 19:54:43 +08:00
parent d3dba751ca
commit 8dda1e97ef
43 changed files with 16033 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

677
.comate/specs/order_development_flow/doc.md Normal file
View File

@ -0,0 +1,677 @@
# CRMEB 订单开发流程文档
## 📋 需求背景
为了规范CRMEB系统的订单功能开发，提供完整的订单业务流程、技术实现规范和开发指导，确保开发团队能够高效、标准化地进行订单相关功能的开发与维护。
## 🏗️ 订单系统架构概览
### 整体架构模式
- **框架**: ThinkPHP 6.0 + 多应用模式
- **架构模式**: MVC + 三层架构（Controller → Service → DAO/Model）
- **请求流程**: 路由分发 → 中间件 → 控制器 → 服务层 → DAO层 → 数据库
### 核心模块结构
```
订单模块/
├── Controller层/
│ ├── 前端API: api/controller/v1/order/StoreOrderController.php
│ ├── 管理端API: api/controller/v1/admin/StoreOrderController.php
│ └── PC端API: api/controller/pc/OrderController.php
├── Service层/
│ ├── StoreOrderServices.php (核心订单服务)
│ ├── StoreOrderCreateServices.php (订单创建服务)
│ ├── StoreOrderComputedServices.php (订单计算服务)
│ ├── StoreOrderDeliveryServices.php (订单配送服务)
│ ├── StoreOrderRefundServices.php (订单退款服务)
│ ├── StoreOrderStatusServices.php (订单状态服务)
│ └── StoreOrderSuccessServices.php (订单成功服务)
├── DAO层/
│ └── StoreOrderDao.php (订单数据访问)
└── Model层/
└── StoreOrder.php (订单模型)
```
## 🔄 订单业务流程详解
### 1. 订单创建流程
```
用户下单 → 购物车确认 → 订单计算 → 订单创建 → 库存扣减 → 支付处理
```
#### 1.1 订单确认页面 (`/order/confirm`)
**Controller**: `StoreOrderController::confirm()`
**Service**: `StoreOrderServices::getOrderConfirmData()`
**数据流转**:
```php
// 接收参数
$cartId, $new, $addressId, $shipping_type, $is_gift
// 业务处理
1. 验证购物车商品有效性
2. 计算商品价格、运费、优惠
3. 检查用户地址信息
4. 获取可用优惠券
5. 返回确认页面数据
```
#### 1.2 订单金额计算 (`/order/computed/:key`)
**Controller**: `StoreOrderController::computedOrder()`
**Service**: `StoreOrderComputedServices`
**核心计算逻辑**:
```php
// 计算参数
$addressId, $couponId, $payType, $useIntegral, $mark, $shipping_type
// 计算流程
1. 商品总价计算
2. 运费计算 (ShippingTemplatesServices)
3. 优惠券抵扣计算
4. 积分抵扣计算
5. 会员折扣计算
6. 最终支付金额确认
```
#### 1.3 订单创建 (`/order/create/:key`)
**Controller**: `StoreOrderController::create()`
**Service**: `StoreOrderCreateServices::createOrder()`
**关键步骤**:
```php
// 订单生成流程
1. 生成唯一订单ID (雪花算法)
2. 订单基本信息入库
3. 订单商品信息入库 (StoreOrderCartInfoServices)
4. 库存扣减 (StoreProductServices)
5. 优惠券使用记录
6. 积分扣减记录
7. 订单状态记录 (StoreOrderStatusServices)
8. 返回订单信息
```
### 2. 订单支付流程
```
选择支付方式 → 支付参数生成 → 第三方支付 → 支付回调 → 订单状态更新
```
#### 2.1 支付处理 (`/order/pay`)
**Service**: `OrderPayServices`
**支持支付方式**:
- 微信支付 (WechatPayServices)
- 支付宝支付 (AlipayPayServices)
- 余额支付 (YuePayServices)
- 线下支付 (OrderOfflineServices)
#### 2.2 支付回调处理
```php
// 支付成功后处理流程
1. 验证回调签名
2. 更新订单支付状态 (paid=1, pay_time)
3. 扣减商品库存
4. 生成用户账单记录
5. 触发相关营销活动
6. 发送支付成功通知
```
### 3. 订单状态流转
```
待支付 → 已支付 → 待发货 → 待收货 → 已完成 → 已评价
↓
已取消 → 已删除
↓
退款中 → 已退款
```
#### 3.1 状态定义
```php
// StoreOrderServices 订单状态常量
const STATUS_UNPAID = 0; // 待支付
const STATUS_PAID = 1; // 已支付/待发货
const STATUS_SHIPPED = 2; // 待收货
const STATUS_RECEIVED = 3; // 已完成
const STATUS_EVALUATE = 4; // 已评价
const STATUS_PART_SHIPPED = 5; // 部分发货
```
#### 3.2 状态变更服务
- `StoreOrderStatusServices`: 订单状态变更记录
- `StoreOrderSuccessServices`: 订单成功处理
- `StoreOrderTakeServices`: 订单收货处理
### 4. 订单退款流程
```
申请退款 → 审核处理 → 退款处理 → 状态更新 → 库存恢复
```
#### 4.1 退款申请
**Controller**: `StoreOrderController::refund_verify()`
**Service**: `StoreOrderRefundServices`
#### 4.2 退款处理类型
- 部分退款 (部分商品退款)
- 整单退款 (整个订单退款)
- 仅退款 (不退货)
- 退货退款 (需要退货)
### 5. 订单发货流程
```
订单发货 → 物流信息录入 → 状态更新 → 用户通知 → 物流跟踪
```
#### 5.1 发货类型
```php
// StoreOrderServices 发货类型
public $deliveryType = [
'send' => '商家配送', // 同城配送
'express' => '快递配送', // 快递发货
'fictitious' => '虚拟发货', // 虚拟商品
'delivery_part_split' => '拆分部分发货', // 部分发货
'delivery_split' => '拆分发货完成' // 完成发货
];
```
#### 5.2 发货服务
- `StoreOrderDeliveryServices`: 发货处理
- `ExpressServices`: 物流信息查询
## 🗄️ 数据库设计
### 核心表结构
#### 订单主表 (eb_store_order)
```sql
CREATE TABLE `eb_store_order` (
`id` int(11) NOT NULL AUTO_INCREMENT COMMENT '订单ID',
`order_id` varchar(32) NOT NULL COMMENT '订单号',
`uid` int(11) NOT NULL COMMENT '用户ID',
`real_name` varchar(32) DEFAULT NULL COMMENT '收货人姓名',
`user_phone` varchar(16) DEFAULT NULL COMMENT '收货人电话',
`user_address` varchar(255) DEFAULT NULL COMMENT '收货地址',
`cart_id` varchar(255) DEFAULT NULL COMMENT '购物车ID',
`total_num` int(11) DEFAULT '0' COMMENT '订单商品总数',
`total_price` decimal(10,2) DEFAULT '0.00' COMMENT '订单总价',
`total_postage` decimal(10,2) DEFAULT '0.00' COMMENT '邮费',
`pay_price` decimal(10,2) DEFAULT '0.00' COMMENT '实际支付金额',
`pay_postage` decimal(10,2) DEFAULT '0.00' COMMENT '支付邮费',
`deduction_price` decimal(10,2) DEFAULT '0.00' COMMENT '抵扣金额',
`coupon_id` int(11) DEFAULT '0' COMMENT '优惠券ID',
`coupon_price` decimal(10,2) DEFAULT '0.00' COMMENT '优惠券金额',
`paid` tinyint(1) DEFAULT '0' COMMENT '支付状态',
`pay_time` timestamp NULL DEFAULT NULL COMMENT '支付时间',
`pay_type` varchar(20) DEFAULT NULL COMMENT '支付方式',
`status` tinyint(1) DEFAULT '0' COMMENT '订单状态',
`refund_status` tinyint(1) DEFAULT '0' COMMENT '退款状态',
`refund_reason` varchar(255) DEFAULT NULL COMMENT '退款理由',
`refund_reason_wap_img` varchar(255) DEFAULT NULL COMMENT '退款图片',
`refund_reason_wap_explain` varchar(255) DEFAULT NULL COMMENT '退款用户说明',
`refund_price` decimal(10,2) DEFAULT '0.00' COMMENT '退款金额',
`refund_price_time` timestamp NULL DEFAULT NULL COMMENT '退款时间',
`delivery_name` varchar(64) DEFAULT NULL COMMENT '快递公司',
`delivery_id` varchar(100) DEFAULT NULL COMMENT '快递单号',
`delivery_type` varchar(32) DEFAULT NULL COMMENT '发货方式',
`delivery_uid` int(11) DEFAULT '0' COMMENT '配送员ID',
`delivery_code` varchar(50) DEFAULT NULL COMMENT '快递公司编码',
`store_id` int(11) DEFAULT '0' COMMENT '门店ID',
`shipping_type` tinyint(1) DEFAULT '1' COMMENT '配送方式 1=快递 2=自提',
`pick_up_code` varchar(50) DEFAULT NULL COMMENT '核销码',
`mark` varchar(512) DEFAULT NULL COMMENT '备注',
`unique` varchar(32) DEFAULT NULL COMMENT '唯一key(md5加密)用于查询',
`remark` varchar(512) DEFAULT NULL COMMENT '管理员备注',
`mer_id` int(11) DEFAULT '0' COMMENT '商户ID',
`is_del` tinyint(1) DEFAULT '0' COMMENT '是否删除',
`is_system_del` tinyint(1) DEFAULT '0' COMMENT '是否系统删除',
`combination_id` int(11) DEFAULT '0' COMMENT '拼团产品ID',
`pink_id` int(11) DEFAULT '0' COMMENT '拼团ID',
`seckill_id` int(11) DEFAULT '0' COMMENT '秒杀产品ID',
`bargain_id` int(11) DEFAULT '0' COMMENT '砍价产品ID',
`order_type` varchar(32) DEFAULT '' COMMENT '订单类型',
`activity_type` varchar(32) DEFAULT '' COMMENT '活动类型',
`channel_type` tinyint(1) DEFAULT '0' COMMENT '渠道类型',
`extension_type` varchar(32) DEFAULT '' COMMENT '扩展类型',
`staff_id` int(11) DEFAULT '0' COMMENT '客服ID',
`vip_price` decimal(10,2) DEFAULT '0.00' COMMENT '会员价格',
`finance_status` tinyint(1) DEFAULT '0' COMMENT '财务状态',
`create_time` timestamp NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
`update_time` timestamp NULL DEFAULT NULL COMMENT '更新时间',
PRIMARY KEY (`id`),
UNIQUE KEY `order_id` (`order_id`),
KEY `uid` (`uid`),
KEY `paid` (`paid`),
KEY `status` (`status`),
KEY `is_del` (`is_del`),
KEY `unique` (`unique`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='订单表';
```
#### 订单商品表 (eb_store_order_cart_info)
```sql
CREATE TABLE `eb_store_order_cart_info` (
`id` int(11) NOT NULL AUTO_INCREMENT,
`oid` int(11) NOT NULL COMMENT '订单ID',
`cart_id` int(11) DEFAULT NULL COMMENT '购物车ID',
`product_id` int(11) NOT NULL COMMENT '产品ID',
`cart_num` int(11) NOT NULL COMMENT '购买数量',
`unique` varchar(50) NOT NULL COMMENT '唯一ID',
`product_name` varchar(255) NOT NULL COMMENT '产品名称',
`image` varchar(255) DEFAULT NULL COMMENT '产品图片',
`unit_name` varchar(32) DEFAULT NULL COMMENT '单位名',
`price` decimal(10,2) DEFAULT '0.00' COMMENT '产品价格',
`cost` decimal(10,2) DEFAULT '0.00' COMMENT '产品成本',
`vip_price` decimal(10,2) DEFAULT '0.00' COMMENT '会员价格',
`pay_price` decimal(10,2) DEFAULT '0.00' COMMENT '实际支付价格',
`pay_postage` decimal(10,2) DEFAULT '0.00' COMMENT '实际支付邮费',
`is_gift` tinyint(1) DEFAULT '0' COMMENT '是否是赠品',
`cart_info` text COMMENT '购物车信息',
`refund_num` int(11) DEFAULT '0' COMMENT '退款数量',
`is_refund` tinyint(1) DEFAULT '0' COMMENT '是否退款',
`refund_price` decimal(10,2) DEFAULT '0.00' COMMENT '退款金额',
`create_time` timestamp NULL DEFAULT CURRENT_TIMESTAMP,
`update_time` timestamp NULL DEFAULT NULL,
PRIMARY KEY (`id`),
KEY `oid` (`oid`),
KEY `product_id` (`product_id`),
KEY `unique` (`unique`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='订单商品表';
```
## 🔧 开发规范与最佳实践
### 1. Service层开发规范
#### 1.1 基础服务结构
```php
class StoreOrderServices extends BaseServices
{
/**
* 构造函数
* @param StoreOrderDao $dao
*/
public function __construct(StoreOrderDao $dao)
{
$this->dao = $dao;
}
/**
* 业务方法示例
* @param int $orderId 订单ID
* @param array $data 请求数据
* @return array
* @throws ApiException
*/
public function businessMethod(int $orderId, array $data): array
{
// 1. 参数验证
if (!$orderId) {
throw new ApiException('参数错误');
}
// 2. 数据查询
$order = $this->dao->get($orderId);
if (!$order) {
throw new ApiException('订单不存在');
}
// 3. 业务逻辑处理
// ...业务处理代码
// 4. 数据更新
$this->dao->update($orderId, $updateData);
// 5. 返回结果
return $result;
}
}
```
#### 1.2 异常处理规范
```php
// 使用项目特定异常类
throw new ApiException('用户端错误信息', 400);
throw new AdminException('管理端错误信息', 500);
// 统一返回格式
return $this->success($data);
return $this->fail('错误信息');
```
### 2. DAO层开发规范
#### 2.1 基础DAO结构
```php
class StoreOrderDao extends BaseDao
{
/**
* 设置模型
* @return string
*/
protected function setModel(): string
{
return StoreOrder::class;
}
/**
* 订单搜索方法
* @param array $where 搜索条件
* @param bool $search 是否精确搜索
* @return \crmeb\basic\BaseModel|mixed|\think\Model
*/
public function search(array $where = [], bool $search = false)
{
return parent::search($where, $search)
->when(isset($where['status']), function ($query) use ($where) {
$query->where('status', $where['status']);
})
->when(isset($where['paid']), function ($query) use ($where) {
$query->where('paid', $where['paid']);
});
}
}
```
### 3. Controller层开发规范
#### 3.1 基础Controller结构
```php
class StoreOrderController
{
/**
* @var StoreOrderServices
*/
protected $services;
/**
* 构造函数依赖注入
* @param StoreOrderServices $services
*/
public function __construct(StoreOrderServices $services)
{
$this->services = $services;
}
/**
* 接口方法示例
* @param Request $request
* @return mixed
*/
public function apiMethod(Request $request)
{
// 1. 获取参数
[$param1, $param2] = $request->postMore([
'param1',
['param2', 'defaultValue']
], true);
// 2. 调用服务层
$result = $this->services->businessMethod($param1, $param2);
// 3. 返回结果
return app('json')->success($result);
}
}
```
### 4. 参数验证规范
#### 4.1 Validate层验证
```php
// 在 validate/order/ 目录下创建验证类
class OrderValidate extends Validate
{
protected $rule = [
'order_id' => 'require|number',
'status' => 'require|in:0,1,2,3',
'pay_type' => 'require|in:wechat,alipay,balance'
];
protected $message = [
'order_id.require' => '订单ID不能为空',
'order_id.number' => '订单ID必须是数字',
'status.in' => '订单状态不正确'
];
}
```
## 🔍 关键业务场景实现
### 1. 库存管理
```php
// 订单创建时库存扣减
public function reduceStock(array $cartInfo)
{
foreach ($cartInfo as $item) {
$product = $this->productServices->get($item['product_id']);
if ($product['stock'] < $item['cart_num']) {
throw new ApiException('商品库存不足');
}
// 扣减库存
$this->productServices->decStock($item['product_id'], $item['cart_num']);
// 记录库存变更日志
$this->productLogServices->createLog([
'product_id' => $item['product_id'],
'num' => -$item['cart_num'],
'type' => 'order_reduce',
'order_id' => $this->orderId
]);
}
}
// 订单取消时库存恢复
public function restoreStock(array $cartInfo)
{
foreach ($cartInfo as $item) {
$this->productServices->incStock($item['product_id'], $item['cart_num']);
// 记录库存恢复日志
$this->productLogServices->createLog([
'product_id' => $item['product_id'],
'num' => $item['cart_num'],
'type' => 'order_restore',
'order_id' => $this->orderId
]);
}
}
```
### 2. 价格计算引擎
```php
class OrderPriceCalculator
{
public function calculate(array $params): array
{
// 1. 商品总价
$totalPrice = $this->calculateProductTotal($params['cart_info']);
// 2. 运费计算
$postage = $this->calculatePostage($params['cart_info'], $params['address']);
// 3. 优惠计算
$discount = $this->calculateDiscount($params);
// 4. 最终价格
$payPrice = $totalPrice + $postage - $discount;
return [
'total_price' => $totalPrice,
'postage' => $postage,
'discount' => $discount,
'pay_price' => $payPrice
];
}
}
```
### 3. 订单状态机
```php
class OrderStateMachine
{
const STATUS_TRANSITIONS = [
self::STATUS_UNPAID => [self::STATUS_PAID, self::STATUS_CANCELLED],
self::STATUS_PAID => [self::STATUS_SHIPPED, self::STATUS_REFUNDING],
self::STATUS_SHIPPED => [self::STATUS_RECEIVED, self::STATUS_REFUNDING],
self::STATUS_RECEIVED => [self::STATUS_COMPLETED, self::STATUS_REFUNDING],
];
public function canTransition(int $from, int $to): bool
{
return in_array($to, self::STATUS_TRANSITIONS[$from] ?? []);
}
public function transition(int $orderId, int $toStatus, string $reason = ''): bool
{
$order = $this->orderServices->get($orderId);
if (!$this->canTransition($order['status'], $toStatus)) {
throw new ApiException('状态流转不合法');
}
// 更新订单状态
$this->orderServices->updateStatus($orderId, $toStatus);
// 记录状态变更日志
$this->statusServices->createLog([
'order_id' => $orderId,
'from_status' => $order['status'],
'to_status' => $toStatus,
'reason' => $reason
]);
return true;
}
}
```
## 📊 性能优化建议
### 1. 数据库优化
- 订单表按时间分表存储
- 建立复合索引优化查询性能
- 使用缓存减少数据库访问
### 2. 缓存策略
```php
// 订单信息缓存
$orderCacheKey = "order_info_{$orderId}";
$orderInfo = Cache::remember($orderCacheKey, 3600, function() use ($orderId) {
return $this->dao->get($orderId);
});
// 订单状态缓存
$statusCacheKey = "order_status_{$orderId}";
$status = Cache::get($statusCacheKey);
```
### 3. 异步处理
```php
// 订单创建后的异步处理
public function afterOrderCreate(int $orderId)
{
// 发送邮件通知
MailJob::dispatch($orderId);
// 更新用户等级
UserLevelJob::dispatch($orderId);
// 统计数据更新
StatisticJob::dispatch($orderId);
}
```
## 🧪 测试规范
### 1. 单元测试
```php
class StoreOrderServicesTest extends TestCase
{
public function testCreateOrder()
{
// 准备测试数据
$orderData = [
'uid' => 1,
'cart_info' => [...],
'address_id' => 1
];
// 执行测试
$result = $this->orderServices->createOrder($orderData);
// 断言结果
$this->assertIsArray($result);
$this->assertArrayHasKey('order_id', $result);
$this->assertNotEmpty($result['order_id']);
}
}
```
### 2. 集成测试
```php
class OrderFlowTest extends TestCase
{
public function testCompleteOrderFlow()
{
// 1. 创建订单
$order = $this->createTestOrder();
// 2. 支付订单
$this->payOrder($order['order_id']);
// 3. 发货
$this->shipOrder($order['order_id']);
// 4. 确认收货
$this->confirmOrder($order['order_id']);
// 5. 验证订单状态
$finalOrder = $this->orderServices->get($order['order_id']);
$this->assertEquals(StoreOrderServices::STATUS_COMPLETED, $finalOrder['status']);
}
}
```
## 📝 开发检查清单
### 订单开发前检查
- [ ] 理解业务需求和订单流程
- [ ] 设计数据库表结构
- [ ] 确认状态流转规则
- [ ] 设计接口参数和返回格式
### 代码开发检查
- [ ] 遵循项目架构规范
- [ ] 实现完整的异常处理
- [ ] 添加必要的日志记录
- [ ] 实现参数验证
- [ ] 编写业务逻辑注释
### 测试验证检查
- [ ] 单元测试覆盖核心逻辑
- [ ] 集成测试验证完整流程
- [ ] 性能测试确保响应时间
- [ ] 边界条件测试
### 部署上线检查
- [ ] 数据库迁移脚本
- [ ] 缓存预热脚本
- [ ] 监控指标配置
- [ ] 回滚方案准备
## 🔮 扩展建议
### 1. 微服务拆分
- 订单服务独立部署
- 库存服务独立部署
- 支付服务独立部署
### 2. 消息队列集成
- 使用RabbitMQ/Redis队列处理异步任务
- 实现订单事件驱动架构
### 3. 分布式事务
- 使用Seata处理跨服务事务
- 实现最终一致性方案
### 4. 大数据分析
- 订单数据实时统计
- 用户行为分析
- 销售预测分析
这份文档涵盖了CRMEB订单系统的完整开发流程，为开发团队提供了详细的指导。在实际开发中，请根据具体业务需求进行相应的调整和扩展。

73
.comate/specs/order_development_flow/tasks.md Normal file
View File

@ -0,0 +1,73 @@
# CRMEB 订单开发流程实施任务计划
- [x] 任务1：文档验证与代码结构分析
- 1.1: 验证文档中描述的文件路径与实际项目结构的一致性
- 1.2: 检查订单相关的Service、DAO、Controller类是否存在并符合文档描述
- 1.3: 验证数据库表结构是否与文档中的设计一致
- 1.4: 分析现有代码实现与文档规范的差异点
- [ ] 任务2：订单状态流转机制完善
- 2.1: 实现文档描述的OrderStateMachine状态机类
- 2.2: 在StoreOrderServices中集成状态机验证逻辑
- 2.3: 完善订单状态变更的日志记录机制
- 2.4: 添加状态流转的单元测试用例
- [ ] 任务3：价格计算引擎优化
- 3.1: 创建OrderPriceCalculator独立价格计算类
- 3.2: 重构StoreOrderComputedServices使用新的计算引擎
- 3.3: 实现会员折扣、优惠券、积分等复杂优惠计算逻辑
- 3.4: 添加价格计算的边界测试和性能优化
- [ ] 任务4：库存管理模块增强
- 4.1: 完善订单创建时的库存扣减逻辑
- 4.2: 实现订单取消/退款时的库存恢复机制
- 4.3: 添加库存变更的详细日志记录
- 4.4: 实现库存预警和并发控制机制
- [ ] 任务5：异常处理与参数验证规范化
- 5.1: 为订单相关接口创建完整的Validate验证类
- 5.2: 统一订单模块的异常处理机制
- 5.3: 完善API错误码和错误信息的标准化
- 5.4: 添加接口参数验证的集成测试
- [ ] 任务6：缓存策略实现
- 6.1: 实现订单信息的Redis缓存机制
- 6.2: 添加订单状态的缓存更新策略
- 6.3: 实现缓存失效和预热机制
- 6.4: 添加缓存性能监控和优化
- [ ] 任务7：异步处理任务开发
- 7.1: 创建订单创建后的异步邮件通知Job
- 7.2: 实现用户等级更新的异步处理Job
- 7.3: 添加统计数据更新的异步处理Job
- 7.4: 配置队列处理器和失败重试机制
- [ ] 任务8：订单退款流程完善
- 8.1: 优化部分退款和整单退款的业务逻辑
- 8.2: 完善退款审核流程和状态管理
- 8.3: 实现退款金额计算和验证机制
- 8.4: 添加退款流程的完整测试用例
- [ ] 任务9：物流跟踪功能增强
- 9.1: 集成第三方物流查询API
- 9.2: 实现物流信息的自动更新机制
- 9.3: 添加物流异常状态监控
- 9.4: 完善电子面单和发货通知功能
- [ ] 任务10：监控与日志系统完善
- 10.1: 实现订单操作的全链路日志记录
- 10.2: 添加订单关键指标的业务监控
- 10.3: 实现订单异常的实时告警机制
- 10.4: 添加订单数据统计的定时任务
- [ ] 任务11：API文档与测试覆盖
- 11.1: 为所有订单相关API生成完整的接口文档
- 11.2: 编写订单业务流程的集成测试
- 11.3: 添加API性能测试和压力测试
- 11.4: 实现自动化测试的CI/CD集成
- [ ] 任务12：数据库优化与分表准备
- 12.1: 分析订单表的查询性能瓶颈
- 12.2: 设计订单表的历史数据分表方案
- 12.3: 实现分表查询的DAO层适配
- 12.4: 添加数据迁移和清理脚本

331
.comate/specs/order_flow/doc.md Normal file
View File

@ -0,0 +1,331 @@
# CRMEB订单流程开发文档
## 1. 订单流程概述
CRMEB系统订单流程是一个完整的电商交易处理系统，涵盖从用户下单到订单完成的全生命周期管理。系统支持多种商品类型（普通商品、秒杀、拼团、砍价、预售）、多种支付方式和配送方式，并集成了推广佣金、退款处理等功能。
## 2. 核心架构技术方案
### 2.1 系统架构
- **MVC架构**: 基于ThinkPHP6框架
- **服务层设计**: 采用Services层处理业务逻辑，Dao层数据访问
- **队列处理**: 使用ThinkPHP队列处理异步任务（如自动评价、订单取消）
- **事务管理**: 关键操作使用数据库事务保证数据一致性
### 2.2 核心模块
- **订单管理**: StoreOrder模型和StoreOrderServices服务
- **购物车**: StoreCartServices处理购物车逻辑
- **支付处理**: 支持微信支付、支付宝、余额支付、线下支付
- **物流管理**: 快递发货、门店自提、虚拟发货
- **退款管理**: StoreOrderRefund处理退款申请和流程
- **推广佣金**: 多级分销体系，支持事业部、代理、员工分佣
## 3. 影响文件分析
### 3.1 核心模型文件
- `crmeb/app/model/order/StoreOrder.php` - 订单主模型，包含订单基础信息和关联关系
- `crmeb/app/model/order/StoreOrderStatus.php` - 订单状态变更记录
- `crmeb/app/model/order/StoreOrderRefund.php` - 退款订单模型
- `crmeb/app/model/order/StoreOrderCartInfo.php` - 订单商品信息模型
### 3.2 服务层文件
- `crmeb/app/services/order/StoreOrderServices.php` - 订单核心业务逻辑（3086行）
- `crmeb/app/services/pay/OrderPayServices.php` - 支付处理服务
- `crmeb/app/services/pay/PayNotifyServices.php` - 支付回调处理
- `crmeb/app/services/user/UserBillServices.php` - 用户账单处理
### 3.3 控制器文件
- `crmeb/app/adminapi/controller/order/` - 后台订单管理控制器
- `crmeb/app/api/controller/order/` - 前端订单API控制器
### 3.4 数据库表结构
- `eb_store_order` - 订单主表（72个字段）
- `eb_store_order_cart_info` - 订单商品明细表
- `eb_store_order_status` - 订单状态变更记录表
- `eb_store_order_refund` - 退款订单表
## 4. 实现细节
### 4.1 订单状态流转
```php
// 订单状态定义
const ORDER_STATUS = [
-2 => '退货成功',
-1 => '申请退款/已退款',
0 => '待发货',
1 => '待收货',
2 => '已收货',
3 => '待评价'
];
// 支付状态
const PAY_STATUS = [
0 => '未支付',
1 => '已支付'
];
// 退款状态
const REFUND_STATUS = [
0 => '未退款',
1 => '申请中',
2 => '已退款'
];
```
### 4.2 订单创建流程
```php
public function createOrder($data) {
// 1. 验证商品库存和价格
$this->checkProductStock($data['cart_info']);
// 2. 计算订单金额（含优惠券、积分抵扣）
$orderData = $this->calculateOrderPrice($data);
// 3. 生成订单号和唯一标识
$orderData['order_id'] = $this->generateOrderId();
$orderData['unique'] = md5(uniqid(mt_rand(), true));
// 4. 处理优惠券使用
if ($orderData['coupon_id']) {
$this->useCoupon($orderData['coupon_id'], $orderData['uid']);
}
// 5. 扣减库存
$this->reduceStock($data['cart_info']);
// 6. 创建订单记录
$order = $this->dao->save($orderData);
// 7. 创建订单商品明细
$this->createOrderCartInfo($order['id'], $data['cart_info']);
// 8. 记录订单状态变更
$this->recordOrderStatus($order['id'], 'create', '订单创建');
return $order;
}
```
### 4.3 支付处理流程
```php
public function paySuccess($orderId, $payType, $tradeNo = '') {
// 开启事务
Db::startTrans();
try {
// 1. 更新订单支付状态
$this->dao->update($orderId, [
'paid' => 1,
'pay_time' => time(),
'pay_type' => $payType,
'trade_no' => $tradeNo
]);
// 2. 处理推广佣金
$this->handleBrokerage($orderId);
// 3. 增加用户积分
$this->addUserIntegral($orderId);
// 4. 更新会员等级和经验
$this->updateUserLevel($orderId);
// 5. 处理拼团逻辑
if ($orderInfo['pink_id']) {
app()->make(StorePinkServices::class)->handlePinkPay($orderInfo);
}
// 6. 发送消息通知
$this->sendPaySuccessNotice($orderId);
Db::commit();
return true;
} catch (\Exception $e) {
Db::rollback();
throw new \Exception('支付处理失败: ' . $e->getMessage());
}
}
```
### 4.4 发货处理流程
```php
public function delivery($orderId, $deliveryData) {
// 1. 验证订单状态
$order = $this->dao->get($orderId);
if (!$order || $order['paid'] != 1 || $order['status'] != 0) {
throw new ApiException('订单状态不允许发货');
}
// 2. 处理不同发货类型
switch ($deliveryData['delivery_type']) {
case 'express': // 快递发货
$updateData = [
'delivery_name' => $deliveryData['delivery_name'],
'delivery_id' => $deliveryData['delivery_id'],
'delivery_type' => 'express',
'status' => 1 // 待收货
];
break;
case 'send': // 商家配送
$updateData = [
'delivery_name' => $deliveryData['delivery_name'],
'delivery_id' => $deliveryData['delivery_id'],
'delivery_type' => 'send',
'status' => 1,
'delivery_uid' => $deliveryData['delivery_uid']
];
break;
case 'fictitious': // 虚拟发货
$updateData = [
'fictitious_content' => $deliveryData['fictitious_content'],
'delivery_type' => 'fictitious',
'status' => 2 // 直接完成
];
break;
}
// 3. 更新订单状态
$this->dao->update($orderId, $updateData);
// 4. 记录订单状态变更
$this->recordOrderStatus($orderId, 'delivery', '订单发货');
// 5. 发送发货通知
$this->sendDeliveryNotice($orderId);
return true;
}
```
### 4.5 退款处理流程
```php
public function applyRefund($orderId, $refundData) {
// 1. 验证订单和退款条件
$order = $this->validateRefundCondition($orderId);
// 2. 创建退款记录
$refundData = [
'store_order_id' => $orderId,
'refund_type' => $refundData['refund_type'],
'refund_price' => $refundData['refund_price'],
'refund_reason' => $refundData['refund_reason'],
'refund_reason_wap_explain' => $refundData['explain'] ?? '',
'refund_reason_wap_img' => $refundData['images'] ?? '',
'add_time' => time()
];
$refund = app()->make(StoreOrderRefundServices::class)->save($refundData);
// 3. 更新订单退款状态
$this->dao->update($orderId, [
'refund_status' => 1, // 申请中
'refund_type' => $refundData['refund_type']
]);
// 4. 记录订单状态变更
$this->recordOrderStatus($orderId, 'apply_refund', '申请退款');
// 5. 发送退款申请通知
$this->sendRefundApplyNotice($orderId, $refund['id']);
return $refund;
}
```
## 5. 边界条件与异常处理
### 5.1 库存管理
- **超卖防护**: 使用Redis分布式锁或数据库乐观锁防止超卖
- **库存回滚**: 订单取消或支付失败时自动回滚库存
- **预售商品**: 支持预售商品的库存管理
### 5.2 支付安全
- **重复支付防护**: 通过订单唯一标识防止重复支付
- **支付超时**: 未支付订单自动取消（可配置超时时间）
- **金额校验**: 支付回调时校验金额一致性
### 5.3 退款控制
- **退款时限**: 根据商品类型设置不同的退款时限
- **退款次数**: 限制同一订单的退款申请次数
- **权限控制**: 不同角色处理退款的权限控制
### 5.4 异常处理机制
```php
// 订单创建异常处理
try {
$order = $this->createOrder($orderData);
} catch (\Exception $e) {
// 记录错误日志
Log::error('订单创建失败: ' . $e->getMessage(), ['data' => $orderData]);
// 回滚已处理的数据
if (isset($orderData['coupon_id'])) {
$this->rollbackCoupon($orderData['coupon_id']);
}
throw new ApiException('订单创建失败，请重试');
}
```
## 6. 数据流动路径
### 6.1 订单创建数据流
```
用户下单 → 购物车验证 → 价格计算 → 订单生成 → 库存扣减 → 支付处理 → 订单确认
```
### 6.2 支付处理数据流
```
支付请求 → 支付网关 → 支付回调 → 订单状态更新 → 佣金计算 → 积分奖励 → 消息通知
```
### 6.3 发货处理数据流
```
发货操作 → 物流信息更新 → 订单状态变更 → 状态记录 → 用户通知 → 物流跟踪
```
### 6.4 退款处理数据流
```
退款申请 → 条件验证 → 退款记录 → 状态更新 → 退款处理 → 资金返还 → 完成通知
```
## 7. 预期成果
### 7.1 功能完整性
- ✅ 支持多种商品类型的订单处理
- ✅ 完整的订单状态流转机制
- ✅ 多种支付方式和配送方式
- ✅ 完善的退款处理流程
- ✅ 推广佣金自动计算
- ✅ 积分和会员等级体系
### 7.2 系统性能
- 订单处理响应时间 < 200ms
- 支持高并发订单创建（使用队列异步处理）
- 数据库查询优化，关键索引完备
- 缓存策略应用，减少数据库压力
### 7.3 安全性
- 防重复支付机制
- 订单数据加密存储
- 敏感信息脱敏处理
- 完整的日志审计
### 7.4 扩展性
- 模块化设计，便于功能扩展
- 插件化支付和物流接口
- 灵活的订单状态配置
- 支持多种业务场景定制
## 8. 技术要点总结
1. **数据一致性**: 关键操作使用数据库事务保证
2. **异步处理**: 耗时操作使用队列异步执行
3. **状态机**: 订单状态流转严格遵循状态机模式
4. **缓存策略**: 商品信息、用户信息等使用缓存提升性能
5. **日志记录**: 完整的操作日志便于问题排查
6. **异常处理**: 完善的异常处理和回滚机制
7. **监控告警**: 关键指标监控和异常告警机制
该订单流程设计具备高可用性、高性能、高安全性的特点，能够满足大型电商平台的业务需求。

106
.trae/rules/project_rules.md Normal file
View File

@ -0,0 +1,106 @@
# CRMEB 项目专属 Chat 规则
## 1. 项目概述
- **名称**: CRMEB 开源商城系统（PHP版）
- **技术栈**: ThinkPHP 6 + ElementUI + UniApp
- **版本**: 5.6.4
- **许可证**: Apache-2.0
## 2. 代码风格规范
### 2.1 PHP 规范
- 遵循 PSR-2 命名规范
- 使用 Restful 接口设计
- 代码分层清晰，注释简洁
- 类名 PascalCase，方法/变量 camelCase
- 常量全大写，下划线分隔
- 4空格缩进，禁止制表符
### 2.2 Vue 规范
- 组件名 PascalCase
- 方法/变量 camelCase
- 模板使用 kebab-case
- 遵循 Vue 官方风格指南
### 2.3 数据库规范
- 表名小写下划线分隔
- 主键统一命名为 `id`
- 外键格式 `表名_id`
- 时间字段 `create_time`/`update_time`
- 状态字段 `status`，默认值 0
## 3. 技术选择限制
- **后端**: ThinkPHP 6.x（禁止升级到 7.x）
- **前端**: Vue 2.x + ElementUI（Admin）、UniApp（移动端）、Nuxt（PC）
- **数据库**: MySQL 5.7~8.0（InnoDB）
- **缓存**: Redis（推荐）
- **队列**: ThinkPHP 内置队列
- **长连接**: Workerman
## 4. 开发流程规范
### 4.1 开发环境
- PHP 7.1~7.4
- 开发工具：PHPStorm/VS Code
- 版本控制：Git
### 4.2 代码提交
- 提交信息清晰，中文描述
- 格式：`[模块名] 操作描述`
- 禁止一次提交多个不相关功能
### 4.3 二开流程
1. 阅读项目文档和代码注释
2. 使用代码生成工具创建基础功能
3. 遵循系统架构，不破坏原有结构
4. 使用系统事件扩展功能
5. 测试通过后提交
## 5. 安全规范
- 操作必须记录系统日志
- 敏感数据加密存储
- 禁止直接拼接 SQL，使用参数绑定
- 验证用户输入，防止 XSS/CSRF 攻击
- 使用内置权限管理系统，禁止硬编码权限
- 合理使用缓存，减少数据库查询
- 高并发场景使用队列处理
## 6. 部署规范
### 6.1 运行环境
- 操作系统：Linux/Windows
- Web 服务器：Nginx/Apache/IIS
- PHP 扩展：fileinfo（可选）、redis（可选）
- 禁用危险函数：`proc_open`、`pcntl_signal` 等
### 6.2 启动命令
- 消息队列：`php think queue:listen --queue`（Supervisor 管理）
- 长连接：`sudo -u www php think workerman start --d`
- 定时任务：`php think timer start --d`
## 7. 常用开发命令
- 代码生成：`php think crmeb:build`
- 数据库迁移：`php think migrate:run`
- 查看路由：`php think route:list`
- 清除缓存：`php think clear`
## 8. 文档与支持
- 官方文档：https://doc.crmeb.com/single_open
- 技术社区：https://www.crmeb.com/ask/thread/list/147
## 9. 注意事项
- 确保代码兼容 PHP 7.1~7.4
- 前端兼容主流浏览器和移动端系统
- 避免复杂 SQL 关联查询
- 大数组分批处理
- 保持代码简洁，注释适当
- 遵循单一职责原则
## 10. 违规处理
- 违反规范的提交将被拒绝
- 影响系统稳定性的代码将被回滚
- 多次违规者禁止提交代码
---
以上规则适用于 CRMEB 项目所有开发人员，确保代码一致性、可维护性和安全性。

273
.trae/skills/docs规范/SKILL.md Normal file
View File

@ -0,0 +1,273 @@
---
name: docs规范
description: 文档写作规范
---
# CRMEB 项目文档写作规范
## 0. 自动调用场景
### 0.1 触发条件
- **目录浏览时**：当浏览文档相关目录时自动调用
- 打开 `docs/` 目录时触发
- 打开 `docs/phpapi/` 目录时触发
- 打开 `docs/admin/` 目录时触发
- 打开 `docs/uniapp/` 目录时触发
- 打开 `docs/nuxt/` 目录时触发
- **文档创建时**：当创建新的 Markdown 文档文件时自动调用
- **文档编辑时**：当编辑现有文档文件时自动调用
- **关键词触发**：当文档内容包含以下关键词时自动调用
- `文档`、`说明`、`指南`、`手册`、`规范`
- `API`、`接口`、`部署`、`开发`、`需求`
### 0.2 适用文件类型
- `.md` (Markdown 文件)
- `.txt` (文本文件)
- `.doc`/`.docx` (Word 文档)
- `.pdf` (PDF 文档)
### 0.3 调用优先级
- 当多个技能同时触发时，文档规范技能优先级中等
- 仅在文档相关操作时被触发
- 不影响其他技能的正常使用
## 1. 文档类型
### 1.1 技术文档
- **API 文档**：接口设计、参数说明、返回格式
- **开发文档**：架构设计、模块说明、开发流程
- **部署文档**：环境要求、安装步骤、配置说明
- **接口文档**：接口列表、请求参数、返回示例
### 1.2 业务文档
- **需求文档**：功能描述、业务流程、数据结构
- **测试文档**：测试用例、测试结果、缺陷报告
- **用户手册**：功能介绍、操作指南、常见问题
## 2. 格式规范
### 2.1 文件名规范
- 使用小写下划线分隔
- 清晰描述文档内容
- 示例：`api接口文档.md`、`部署指南.md`
### 2.2 标题层级
- 使用 `#` 表示标题层级
- 一级标题：文档主题
- 二级标题：主要章节
- 三级标题：细分内容
- 最多使用四级标题
### 2.3 文本格式
- 正文使用宋体/无衬线字体，14px
- 代码块使用 ``` 包裹，指定语言
- 列表使用 `-` 或 `1.` 表示
- 强调内容使用 `**加粗**` 或 `*斜体*`
### 2.4 代码规范
- 代码块必须指定语言
- 缩进一致，格式清晰
- 关键代码添加注释
- 示例：
```php
// 获取用户信息
public function getUserInfo($id) {
return $this->where('id', $id)->find();
}
```
### 2.5 文档存放目录
- 文档保存到 `docs` 目录中
- 后端接口文档存放 `docs/phpapi` 目录中
- 后端前端 ElementUI（Admin）文档存放 `docs/admin` 目录中
- 移动端前端 UniApp（移动端）文档存放 `docs/uniapp` 目录中
- PC 端 Nuxt（PC）文档存放 `docs/nuxt` 目录中
## 3. 内容要求
### 3.1 结构清晰
- 引言：文档目的、适用范围
- 主体：详细内容，逻辑连贯
- 结论：总结、后续计划
- 附录：参考资料、术语表
### 3.2 语言要求
- 使用简洁、准确的语言
- 避免歧义，术语统一
- 中文文档使用规范汉字
- 英文文档语法正确
### 3.3 内容完整性
- 包含必要的背景信息
- 步骤清晰，可操作
- 提供示例和截图
- 注明版本和更新日期
### 3.4 可维护性
- 定期更新，保持时效性
- 使用版本控制管理文档
- 注明作者和联系方式
- 便于搜索和导航
## 4. 文档工具
### 4.1 编辑工具
- 推荐使用 Markdown 格式
- 支持工具：VS Code、Typora、语雀
- 图片存储：项目内部或图床
### 4.2 版本管理
- 与代码一同纳入 Git 管理
- 提交信息清晰，说明文档变更
- 定期备份，防止丢失
## 5. 审核与发布
### 5.1 审核流程
1. 编写完成后进行自我检查
2. 提交给相关人员审核
3. 根据反馈修改完善
4. 最终确认发布
### 5.2 发布规范
- 发布前检查格式和内容
- 明确文档版本号
- 通知相关人员文档更新
- 确保文档可访问
## 6. Markdown 文档模板
```markdown
# 文档标题
## 1. 引言
### 1.1 文档目的
- 说明文档的编写目的
### 1.2 适用范围
- 说明文档的适用范围
### 1.3 术语定义
- 解释文档中使用的专业术语
## 2. 主体内容
### 2.1 功能描述
- 详细描述功能特性
### 2.2 实现方案
- 说明技术实现方案
### 2.3 代码示例
```php
// 代码示例
function example() {
return true;
}
```
### 2.4 操作步骤
1. 第一步操作
2. 第二步操作
3. 第三步操作
## 3. 结论
### 3.1 总结
- 总结文档的主要内容
### 3.2 后续计划
- 说明后续的工作计划
## 4. 附录
### 4.1 参考资料
- 列出参考的文档和资源
### 4.2 联系方式
- 提供联系人信息
---
**版本**: 1.0
**作者**: 文档作者
**更新日期**: YYYY-MM-DD
```
## 7. Markdown 语法指南
### 7.1 标题
```markdown
# 一级标题
## 二级标题
### 三级标题
#### 四级标题
```
### 7.2 列表
- 无序列表项 1
- 无序列表项 2
- 嵌套列表项
1. 有序列表项 1
2. 有序列表项 2
### 7.3 链接和图片
- [链接文本](https://example.com)
- ![图片描述](https://example.com/image.jpg)
### 7.4 代码块
```javascript
// JavaScript 代码
console.log('Hello World');
```
### 7.5 表格
| 表头 1 | 表头 2 |
| ------ | ------ |
| 单元格 1 | 单元格 2 |
| 单元格 3 | 单元格 4 |
### 7.6 引用
> 这是一段引用文本
## 8. 注意事项
- 避免冗长，重点突出
- 保持格式统一
- 定期更新文档
- 确保内容准确无误
- 便于他人理解和使用
- 生成文档最后说明由AI生成
---
以上规范适用于 CRMEB 项目所有文档写作，确保文档质量和一致性。

468
.trae/skills/uniapp说明/SKILL.md Normal file
View File

@ -0,0 +1,468 @@
---
name: uniapp说明
description: 移动端uniapp开发说明
---
# uniapp 说明
## 0. 自动触发说明
### 0.1 触发条件
#### 0.1.1 操作触发
- **文件浏览时**: 当浏览 uniapp 相关目录时自动调用
- 打开 uniapp 项目根目录时触发
- 打开 pages 目录时触发
- 浏览 components 目录时触发
- 查看 uniapp 配置文件时触发
- **文件操作时**: 当对 uniapp 文件进行操作时自动调用
- 创建新页面文件时触发
- 修改组件文件时触发
- 删除 uniapp 文件时触发
- 修改配置文件时触发
- **目录操作时**: 当对 uniapp 目录进行操作时自动调用
- 创建新页面目录时触发
- 重命名组件目录时触发
- 删除 uniapp 目录时触发
#### 0.1.2 内容触发
- **关键词触发**: 当文件内容包含以下关键词时自动调用
- 移动端关键词: `移动端`、`app`、`手机`、`小程序`、`H5`
- uniapp 关键词: `uniapp`、`uni-app`、`uView`、`uniCloud`
- 功能关键词: `登录`、`注册`、`首页`、`商品`、`购物车`、`订单`
- **代码触发**: 当查看特定类型 uniapp 代码时自动调用
- 页面代码 (`*.vue`)
- 组件代码 (`components`)
- 配置代码 (`pages.json`、`manifest.json`)
- API 调用代码 (`uni.` 开头的 API)
#### 0.1.3 命令触发
- **终端命令触发**: 当执行以下命令时自动调用
- `npm run dev:h5` (启动 H5 开发)
- `npm run dev:mp-weixin` (启动微信小程序开发)
- `npm run build:h5` (构建 H5)
- `npm run build:mp-weixin` (构建微信小程序)
- `uni` 相关命令
### 0.2 适用场景
#### 0.2.1 核心场景
- **移动端开发**: 开发 uniapp 移动应用时
- **页面开发**: 创建或修改 uniapp 页面时
- **组件开发**: 开发可复用的 uniapp 组件时
- **功能集成**: 集成新功能到移动端应用时
#### 0.2.2 辅助场景
- **跨端调试**: 调试不同平台的兼容性问题时
- **性能优化**: 优化移动端应用性能时
- **样式调整**: 调整移动端界面样式时
- **API 调用**: 使用 uniapp 原生 API 时
### 0.3 触发机制
#### 0.3.1 调用时机
- **实时触发**: 页面文件操作时立即触发
- **延迟触发**: 复杂配置修改时延迟1秒触发
- **批量触发**: 批量文件操作时合并触发
#### 0.3.2 调用频率
- 文件浏览: 最多每10秒触发一次
- 文件操作: 最多每5秒触发一次
- 命令执行: 最多每3秒触发一次
#### 0.3.3 调用优先级
- **优先级等级**: 中优先级 (3/5)
- **竞争处理**: 当多个技能同时触发时
- 最高优先级: 系统核心技能
- 高优先级: 代码结构技能
- 中等优先级: uniapp 技能、管理端前端技能
- 低优先级: 辅助工具技能
- **触发限制**: 仅在 uniapp 相关操作时被触发，不影响其他技能的正常使用
### 0.4 触发后行为
#### 0.4.1 自动分析
- **结构分析**: 分析 uniapp 项目目录结构
- **组件分析**: 分析页面组件依赖关系
- **配置分析**: 分析 uniapp 配置文件
- **性能分析**: 分析移动端性能瓶颈
#### 0.4.2 自动展示
- **目录结构**: 展示 uniapp 项目目录结构
- **页面说明**: 展示核心页面功能说明
- **技术栈**: 展示 uniapp 技术栈
- **开发规范**: 展示移动端开发规范
#### 0.4.3 自动建议
- **开发建议**: 提供 uniapp 开发建议
- **优化建议**: 提供移动端性能优化建议
- **规范建议**: 提供代码规范遵循建议
- **跨端建议**: 提供跨端兼容性建议
## 1. uniapp 架构介绍
### 1.1 整体架构
- **跨端框架**: 基于 Vue 2.x 的跨端应用框架
- **多端发布**: 支持 H5、小程序、App 等多端发布
- **组件化开发**: 基于 Vue 组件化开发模式
- **原生能力**: 调用各平台原生 API 能力
- **状态管理**: Vuex 或 Pinia 状态管理
### 1.2 技术栈
- **核心框架**: Vue 2.x / Vue 3.x
- **UI 组件库**: uView UI、ColorUI、uni-ui
- **状态管理**: Vuex 3.x / Pinia
- **HTTP 客户端**: uni.request、axios
- **构建工具**: Webpack、Vite
- **包管理器**: npm/yarn
- **代码规范**: ESLint + Prettier
### 1.3 目录结构
#### 1.3.1 核心目录
```
uniapp/
├── pages/ # 页面目录
├── components/ # 组件目录
├── static/ # 静态资源目录
├── utils/ # 工具函数目录
├── api/ # API 接口目录
├── store/ # 状态管理目录
├── common/ # 公共目录
├── mixins/ # 混合器目录
├── pages.json # 页面路由配置
├── manifest.json # 应用配置
├── main.js # 入口文件
├── App.vue # 根组件
└── uni.scss # 全局样式
```
#### 1.3.2 页面目录
```
pages/
├── index/ # 首页
├── goods/ # 商品
├── cart/ # 购物车
├── order/ # 订单
├── user/ # 用户中心
├── login/ # 登录
└── detail/ # 详情页
```
## 2. 核心功能模块
### 2.1 登录认证模块
- **功能**: 用户登录、注册、密码找回、第三方登录
- **关键页面**: `login.vue`、`register.vue`
- **核心功能**:
- 手机号密码登录
- 验证码登录
- 微信登录
- 注册功能
- 密码找回
- 登录状态管理
### 2.2 首页模块
- **功能**: 应用入口、轮播图、推荐商品、分类入口
- **关键页面**: `index.vue`
- **核心功能**:
- 轮播图展示
- 分类导航
- 推荐商品
- 活动入口
- 搜索功能
- 快捷入口
### 2.3 商品模块
- **功能**: 商品列表、商品搜索、商品筛选、商品详情
- **关键页面**: `goods/list.vue`、`goods/detail.vue`
- **核心功能**:
- 商品列表展示
- 商品搜索
- 商品筛选
- 商品详情
- 商品评价
- 商品分享
### 2.4 购物车模块
- **功能**: 商品管理、数量调整、价格计算、结算
- **关键页面**: `cart/index.vue`
- **核心功能**:
- 商品添加/删除
- 数量调整
- 价格计算
- 商品结算
- 购物车清空
- 选择商品
### 2.5 订单模块
- **功能**: 订单创建、订单列表、订单详情、订单支付
- **关键页面**: `order/create.vue`、`order/list.vue`、`order/detail.vue`
- **核心功能**:
- 订单创建
- 订单列表
- 订单详情
- 订单支付
- 订单取消
- 订单退款
### 2.6 用户中心模块
- **功能**: 用户信息、收货地址、优惠券、收藏、历史记录
- **关键页面**: `user/index.vue`、`user/info.vue`
- **核心功能**:
- 用户信息管理
- 收货地址管理
- 优惠券管理
- 商品收藏
- 浏览历史
- 个人设置
## 3. 技术特点
### 3.1 跨端开发
- **一次开发多端发布**: 支持 H5、小程序、App 等多端
- **条件编译**: 根据不同平台编写特定代码
- **平台差异处理**: 处理各平台 API 差异
- **原生能力调用**: 调用各平台原生能力
### 3.2 组件化开发
- **页面组件**: 页面级组件开发
- **通用组件**: 可复用的通用组件
- **业务组件**: 特定业务逻辑组件
- **组件通信**: Props/Events、Vuex、EventBus
### 3.3 状态管理
- **Vuex 模块化**: 按功能模块划分 store
- **状态持久化**: 使用 localStorage/sessionStorage
- **异步操作**: 使用 Actions 处理异步请求
- **getters**: 派生状态计算
### 3.4 API 调用
- **uni.request**: uniapp 内置请求方法
- **请求封装**: 统一 API 调用方式
- **拦截器**: 请求/响应拦截器
- **API 模块化**: 按功能模块划分 API
## 4. 开发规范
### 4.1 代码规范
- **Vue 风格指南**: 遵循 Vue 官方风格指南
- **ESLint 规则**: 严格遵循 ESLint 规则
- **代码缩进**: 4空格缩进
- **命名规范**:
- 组件名: PascalCase
- 方法/变量: camelCase
- 常量: 全大写
- 文件名: kebab-case
### 4.2 目录规范
- **页面目录**: 按功能模块组织页面
- **组件目录**: 按类型组织组件
- **资源目录**: 分类存放静态资源
- **工具目录**: 按功能分类工具函数
### 4.3 命名规范
- **页面命名**: 使用语义化的页面名称
- **组件命名**: 与功能模块名称对应
- **store 命名**: 与功能模块名称对应
- **API 命名**: 与后端接口名称对应
### 4.4 注释规范
- **页面注释**: 页面功能、参数说明
- **组件注释**: 组件功能、props、events 说明
- **方法注释**: 方法功能、参数、返回值说明
- **复杂逻辑注释**: 关键逻辑步骤说明
## 5. 性能优化
### 5.1 加载优化
- **路由懒加载**: 按需加载页面组件
- **组件懒加载**: 按需加载大型组件
- **图片优化**: 图片压缩、懒加载、WebP 格式
- **资源压缩**: JS/CSS 压缩
- **预加载**: 预加载关键资源
### 5.2 渲染优化
- **虚拟列表**: 长列表使用虚拟滚动
- **计算属性缓存**: 使用 computed 缓存计算结果
- **避免频繁更新**: 使用 v-once、v-memo
- **合理使用 key**: 列表渲染时使用唯一 key
- **减少 DOM 操作**: 批量更新 DOM
### 5.3 网络优化
- **API 请求合并**: 合并相同请求
- **请求缓存**: 缓存重复请求结果
- **防抖节流**: 优化频繁触发的事件
- **WebSocket**: 实时数据使用 WebSocket
- **HTTP/2**: 启用 HTTP/2 协议
### 5.4 构建优化
- **Tree Shaking**: 移除未使用的代码
- **代码分割**: 按路由分割代码
- **环境变量**: 区分开发/生产环境
- **分包加载**: 小程序分包加载
## 6. 跨端兼容
### 6.1 平台差异
- **H5 端**: 浏览器兼容性
- **小程序端**: 各平台小程序限制
- **App 端**: iOS/Android 差异
### 6.2 兼容策略
- **条件编译**: 使用 `#ifdef`/`#endif` 处理平台差异
- **API 兼容**: 封装统一的 API 调用
- **样式兼容**: 处理各平台样式差异
- **功能降级**: 不支持的功能提供降级方案
### 6.3 测试策略
- **多端测试**: 在各平台进行测试
- **兼容性测试**: 测试不同版本的兼容性
- **性能测试**: 测试各平台性能表现
- **用户体验测试**: 测试各平台用户体验
## 7. 安全防护
### 7.1 数据安全
- **敏感数据加密**: 加密存储敏感信息
- **本地存储安全**: 合理使用 localStorage
- **API 接口安全**: HTTPS、接口签名
- **数据验证**: 前端数据验证
### 7.2 权限管理
- **权限申请**: 合理申请设备权限
- **权限提示**: 向用户说明权限用途
- **权限降级**: 无权限时提供降级方案
### 7.3 防作弊措施
- **请求频率限制**: 防止恶意请求
- **参数验证**: 验证请求参数
- **签名验证**: 验证请求签名
- **设备标识**: 合理使用设备标识
## 8. 最佳实践
### 8.1 开发流程
1. **需求分析**: 明确功能需求
2. **设计阶段**: 设计页面结构和组件
3. **编码实现**: 遵循开发规范编码
4. **多端测试**: 在各平台进行测试
5. **性能优化**: 优化应用性能
6. **发布上线**: 构建和发布
### 8.2 页面开发
- **布局规范**: 遵循移动端布局规范
- **响应式设计**: 适配不同屏幕尺寸
- **用户体验**: 优化移动端交互体验
- **性能考虑**: 页面加载和渲染性能
### 8.3 组件开发
- **单一职责**: 组件功能单一
- **可配置性**: 组件参数可配置
- **跨端兼容**: 考虑各平台兼容性
- **性能优化**: 优化组件性能
### 8.4 调试技巧
- **uni-app 开发工具**: 使用官方开发工具
- **真机调试**: 使用真机进行调试
- **控制台调试**: 合理使用 console 方法
- **网络调试**: 分析 API 请求和响应
## 9. 常见问题
### 9.1 兼容性问题
- **API 兼容性**: 处理各平台 API 差异
- **样式兼容性**: 处理各平台样式差异
- **功能兼容性**: 处理各平台功能差异
### 9.2 性能问题
- **启动速度**: 优化应用启动速度
- **页面加载**: 优化页面加载速度
- **滚动性能**: 优化页面滚动性能
- **内存占用**: 优化应用内存占用
### 9.3 打包问题
- **包体积**: 优化应用包体积
- **分包加载**: 合理使用分包加载
- **资源文件**: 优化资源文件大小
### 9.4 上架问题
- **应用商店审核**: 遵循各应用商店审核规则
- **小程序审核**: 遵循各小程序平台审核规则
- **内容合规**: 确保应用内容合规
## 10. 部署与发布
### 10.1 构建流程
- **H5 构建**: `npm run build:h5`
- **微信小程序构建**: `npm run build:mp-weixin`
- **App 构建**: 使用 HBuilderX 云打包
### 10.2 发布流程
- **H5 发布**: 部署到静态文件服务器
- **小程序发布**: 提交到各小程序平台
- **App 发布**: 提交到应用商店
### 10.3 版本管理
- **版本号规范**: 遵循语义化版本规范
- **发布日志**: 记录版本变更内容
- **灰度发布**: 采用灰度发布策略
## 11. 开发工具推荐
### 11.1 IDE 推荐
- **HBuilderX**: uniapp 官方推荐 IDE
- **VS Code**: 配合 uniapp 插件使用
- **WebStorm**: 专业的前端 IDE
### 11.2 插件推荐
- **uni-app 插件市场**: 官方插件市场
- **uView UI**: 移动端 UI 组件库
- **ColorUI**: 移动端 UI 组件库
- **uni-ui**: 官方 UI 组件库
### 11.3 工具推荐
- **Charles**: 网络调试工具
- **Postman**: API 测试工具
- **Figma/Sketch**: UI 设计工具
- **Lighthouse**: 性能分析工具
## 12. 参考资源
### 12.1 官方文档
- [uni-app 官方文档](https://uniapp.dcloud.io/)
- [uView UI 文档](https://uviewui.com/)
- [Vue 官方文档](https://v2.vuejs.org/)
- [微信小程序文档](https://developers.weixin.qq.com/miniprogram/dev/framework/)
### 12.2 学习资源
- [uni-app 教程](https://uniapp.dcloud.io/tutorial/)
- [Vue Mastery](https://www.vuemastery.com/)
- [MDN Web Docs](https://developer.mozilla.org/zh-CN/)
- [CSS-Tricks](https://css-tricks.com/)
### 12.3 社区资源
- [uni-app 社区](https://ask.dcloud.net.cn/forum-79-1.html)
- [GitHub](https://github.com/)
- [Stack Overflow](https://stackoverflow.com/)
- [掘金](https://juejin.cn/)
## 13. 团队协作
### 13.1 协作流程
- **需求评审**: 团队评审需求
- **任务分配**: 合理分配开发任务
- **代码审查**: 代码质量检查
- **多端测试**: 团队成员负责不同平台测试
### 13.2 规范约定
- **代码规范**: 统一代码风格
- **命名规范**: 统一命名规则
- **文档规范**: 统一文档格式
- **提交规范**: 统一提交信息格式
### 13.3 工具协作
- **项目管理**: 使用项目管理工具
- **代码托管**: 使用代码托管平台
- **CI/CD**: 持续集成/持续部署
- **文档协作**: 团队文档协作工具

288
.trae/skills/目录结构/SKILL.md Normal file
View File

@ -0,0 +1,288 @@
---
name: 目录结构
description: 代码结构说明
---
# CRMEB 项目代码结构分析
## 0. 自动触发说明
### 0.1 触发条件
#### 0.1.1 操作触发
- **文件浏览时**: 当浏览项目目录结构时自动调用
- 打开项目根目录时触发
- 打开核心目录时触发
- 浏览文件树时触发
- **文件操作时**: 当对文件进行操作时自动调用
- 创建新文件时触发
- 移动文件时触发
- 删除文件时触发
- **目录操作时**: 当对目录进行操作时自动调用
- 创建新目录时触发
- 重命名目录时触发
- 删除目录时触发
#### 0.1.2 内容触发
- **关键词触发**: 当文件内容包含以下关键词时自动调用
- 结构关键词: `目录`、`结构`、`架构`、`组织`、`层次`
- 模块关键词: `模块`、`组件`、`服务`、`控制器`、`模型`
- 路径关键词: `路径`、`位置`、`存放`、`位于`、`所在`
- **代码触发**: 当查看特定类型代码时自动调用
- 控制器代码 (`Controller`)
- 模型代码 (`Model`)
- 服务代码 (`Service`)
- 配置代码 (`Config`)
#### 0.1.3 命令触发
- **终端命令触发**: 当执行以下命令时自动调用
- `ls`/`ls -la` (查看目录)
- `find` (查找文件)
- `tree` (查看文件树)
- `du` (查看目录大小)
### 0.2 适用场景
#### 0.2.1 核心场景
- **项目探索**: 新成员了解项目结构时
- **代码导航**: 查找特定文件或模块时
- **架构分析**: 分析项目架构设计时
- **重构规划**: 规划代码重构时
#### 0.2.2 辅助场景
- **文件定位**: 快速定位文件位置时
- **模块了解**: 了解特定模块功能时
- **依赖分析**: 分析模块间依赖关系时
- **性能优化**: 分析代码结构以优化性能时
### 0.3 触发机制
#### 0.3.1 调用时机
- **实时触发**: 目录操作时立即触发
- **延迟触发**: 复杂文件操作时延迟1秒触发
- **批量触发**: 批量文件操作时合并触发
#### 0.3.2 调用频率
- 目录浏览: 最多每10秒触发一次
- 文件操作: 最多每5秒触发一次
- 命令执行: 最多每3秒触发一次
#### 0.3.3 调用优先级
- **优先级等级**: 高优先级 (4/5)
- **竞争处理**: 当多个技能同时触发时
- 最高优先级: 系统核心技能
- 高优先级: 代码结构技能
- 中等优先级: 文档规范技能
- 低优先级: 辅助工具技能
- **触发限制**: 仅在代码相关操作时被触发，不影响其他技能的正常使用
### 0.4 触发后行为
#### 0.4.1 自动分析
- **结构分析**: 分析项目目录结构
- **模块分析**: 分析核心模块功能
- **文件统计**: 统计各类型文件数量
- **依赖分析**: 分析模块间依赖关系
#### 0.4.2 自动展示
- **目录树**: 展示项目目录树结构
- **模块说明**: 展示核心模块功能说明
- **文件统计**: 展示语言和文件类型统计
- **关键文件**: 展示项目关键文件位置
#### 0.4.3 自动建议
- **导航建议**: 提供快速导航到核心目录的建议
- **结构建议**: 提供优化目录结构的建议
- **组织建议**: 提供代码组织的最佳实践建议
### 0.5 自定义触发规则
#### 0.5.1 全局配置
- 可在 `.trae/config.json` 中配置触发规则
- 可调整触发频率和优先级
- 可启用/禁用特定触发条件
#### 0.5.2 项目配置
- 可在项目根目录创建 `.crmebmap-config.json` 文件
- 可定义项目特定的触发规则
- 可指定特定目录的触发行为
#### 0.5.3 个人配置
- 可在用户目录创建 `.crmebmap-prefs.json` 文件
- 可自定义个人偏好的触发行为
- 可调整分析深度和展示方式
## 1. 目录结构
### 1.1 根目录结构
├── app/ # 应用核心目录
│ ├── api/ # API 接口层 (23个文件)
│ ├── controller/ # 控制器层 (15个文件)
│ ├── dao/ # 数据访问层 (28个文件)
│ ├── model/ # 模型层 (42个文件)
│ ├── services/ # 业务逻辑层 (12个文件)
│ ├── event/ # 事件处理层
│ ├── middleware/ # 中间件层
│ └── validate/ # 数据验证层
├── config/ # 配置文件目录 (18个文件)
├── crmeb/ # 核心库目录 (56个文件)
│ ├── basic/ # 基础类库
│ ├── exception/ # 异常处理
│ └── services/ # 核心服务
├── public/ # 静态资源目录 (124个文件)
│ ├── admin/ # 后台管理前端
│ ├── api/ # API 接口文档
│ └── mobile/ # 移动端前端
├── docker-compose/ # Docker 配置目录
├── docs/ # 文档目录
├── template/ # 模板目录
└── .trae/ # Trae 配置目录
### 1.2 核心目录详解
#### 1.2.1 app 目录
- **api/**：RESTful API 接口实现，处理移动端和第三方请求
- **controller/**：MVC 控制器，处理 HTTP 请求和响应
- **dao/**：数据访问对象，封装数据库操作，提供数据访问方法
- **model/**：数据模型，定义数据库表结构和关系
- **services/**：业务逻辑服务，实现核心业务功能
- **event/**：事件处理器，响应系统事件
- **middleware/**：中间件，处理请求前的验证和处理
- **validate/**：数据验证器，验证用户输入数据
#### 1.2.2 config 目录
- **app.php**：应用主配置
- **database.php**：数据库配置
- **route.php**：路由配置
- **cache.php**：缓存配置
- **queue.php**：队列配置
#### 1.2.3 crmeb 目录
- **basic/**：基础类库，提供通用工具和基类
- **exception/**：异常处理类，定义系统异常
- **services/**：核心服务，提供系统级功能
#### 1.2.4 public 目录
- **admin/**：后台管理系统前端代码
- **api/**：API 接口文档和测试工具
- **mobile/**：移动端前端代码
- **static/**：静态资源文件 (CSS/JS/图片)
## 2. 核心模块
### 2.1 控制器模块 (`app/controller/`)
- **功能**：处理 HTTP 请求，路由分发，响应客户端
- **特点**：RESTful 风格，分层清晰，参数验证
- **关键文件**：`BaseController.php` (控制器基类)
### 2.2 服务模块 (`app/services/`)
- **功能**：实现核心业务逻辑，封装业务规则
- **特点**：业务逻辑集中，可复用性高，易于测试
- **关键文件**：各业务服务类
### 2.3 数据访问模块 (`app/dao/`)
- **功能**：封装数据库操作，提供数据访问方法
- **特点**：SQL 集中管理，防止 SQL 注入，提高安全性
- **关键文件**：各数据访问对象类
### 2.4 模型模块 (`app/model/`)
- **功能**：定义数据模型，处理数据关系
- **特点**：ORM 映射，自动表结构，关联查询
- **关键文件**：`BaseModel.php` (模型基类)
### 2.5 核心库模块 (`crmeb/`)
- **功能**：提供基础类和工具方法
- **特点**：通用性强，系统级支持
- **关键文件**：基础工具类和服务类
## 3. 根目录说明
- **app/**：应用核心目录，包含所有业务逻辑和数据访问代码
- **config/**：配置文件目录，存储应用的配置参数
- **crmeb/**：核心库目录，包含基础类和工具方法
- **public/**：静态资源目录，包含前端代码和公开访问的文件
- **docker-compose/**：Docker 配置文件目录，用于容器化部署
- **docs/**：文档目录，包含项目文档和 API 文档
- **template/**：模板目录，包含前端模板文件
- **.trae/**：Trae 配置目录，包含项目的 Trae 配置文件
- **readme.md**：项目介绍文件，包含项目背景、功能介绍、安装指南等
## 4. 语言统计
- **PHP**：214个文件 (68.5%) - 后端核心代码
- **JavaScript**：63个文件 (20.1%) - 前端逻辑和脚本
- **Vue**：18个文件 (5.8%) - 前端组件
- **HTML**：11个文件 (3.5%) - 页面结构
- **CSS**：6个文件 (1.9%) - 样式文件
- **其他**：3个文件 (0.2%) - 配置和文档文件
## 5. 关键文件
### 5.1 核心入口文件
- `public/index.php`：项目入口文件，处理所有 HTTP 请求
- `think`：命令行工具入口，执行 ThinkPHP 命令
### 5.2 基础类文件
- `app/BaseController.php`：控制器基类，提供通用控制器方法
- `crmeb/basic/BaseModel.php`：模型基类，提供通用模型方法
- `crmeb/basic/BaseServices.php`：服务基类，提供通用服务方法
### 5.3 配置文件
- `config/app.php`：应用主配置，定义应用基本参数
- `config/database.php`：数据库配置，定义数据库连接参数
- `config/route.php`：路由配置，定义 URL 路由规则
### 5.4 核心服务文件
- `crmeb/services/SystemServices.php`：系统服务，提供系统级功能
- `crmeb/services/UploadServices.php`：上传服务，处理文件上传
- `crmeb/services/WechatServices.php`：微信服务，处理微信相关功能
## 6. 架构特点
### 6.1 分层架构
- **表现层**：controller/api - 处理请求和响应
- **业务层**：services - 实现业务逻辑
- **数据层**：dao/model - 数据访问和模型
- **基础层**：crmeb/basic - 基础类和工具
### 6.2 设计模式
- **MVC**：模型-视图-控制器模式
- **RESTful**：API 设计风格
- **依赖注入**：服务容器和依赖管理
- **事件驱动**：事件系统和观察者模式
### 6.3 技术特点
- **模块化**：功能模块化，易于扩展
- **可测试**：分层设计，易于单元测试
- **高性能**：缓存机制和数据库优化
- **安全性**：输入验证和 SQL 注入防护
## 7. 使用示例
### 7.1 快速导航
- **查看控制器**：浏览 `app/controller/` 目录
- **查看模型**：浏览 `app/model/` 目录
- **查看服务**：浏览 `app/services/` 目录
- **查看配置**：浏览 `config/` 目录
### 7.2 常用操作
- **查找文件**：使用 `find` 命令或 IDE 搜索
- **查看目录结构**：使用 `tree` 命令
- **查看文件统计**：使用 `ls -la` 命令
- **分析代码结构**：使用本技能自动分析
## 8. 最佳实践
### 8.1 代码组织
- 遵循分层架构，不要跨层调用
- 控制器只负责请求处理，业务逻辑放在服务层
- 数据库操作封装在 DAO 层，模型只定义结构
### 8.2 目录管理
- 按照功能模块组织目录结构
- 保持目录层次清晰，避免过深嵌套
- 使用语义化的目录和文件命名
### 8.3 性能优化
- 合理使用缓存，减少数据库查询
- 避免复杂的 SQL 关联查询
- 使用队列处理耗时操作
- 优化文件和目录结构，提高加载速度

450
.trae/skills/管理端文档说明/SKILL.md Normal file
View File

@ -0,0 +1,450 @@
---
name: 管理端前端说明
description: 管理端前端开发说明
---
# 管理端前端说明
## 0. 自动触发说明
### 0.1 触发条件
#### 0.1.1 操作触发
- **文件浏览时**: 当浏览管理端前端相关目录时自动调用
- 打开 `public/admin/` 目录时触发
- 打开前端组件目录时触发
- 浏览前端代码文件时触发
- **文件操作时**: 当对管理端前端文件进行操作时自动调用
- 创建新前端文件时触发
- 修改前端组件时触发
- 删除前端文件时触发
- **目录操作时**: 当对管理端前端目录进行操作时自动调用
- 创建新前端目录时触发
- 重命名前端目录时触发
- 删除前端目录时触发
#### 0.1.2 内容触发
- **关键词触发**: 当文件内容包含以下关键词时自动调用
- 管理端关键词: `管理端`、`后台`、`admin`、`后台管理`
- 前端关键词: `前端`、`Vue`、`组件`、`页面`、`路由`
- 功能关键词: `登录`、`权限`、`菜单`、` dashboard`、`统计`
- **代码触发**: 当查看特定类型前端代码时自动调用
- Vue 组件代码 (`*.vue`)
- 前端路由代码 (`router`)
- 前端状态管理代码 (`store`)
- 前端 API 调用代码 (`api`)
#### 0.1.3 命令触发
- **终端命令触发**: 当执行以下命令时自动调用
- `npm run dev` (启动开发服务器)
- `npm run build` (构建前端项目)
- `npm run lint` (代码检查)
- `vue` 相关命令
### 0.2 适用场景
#### 0.2.1 核心场景
- **管理端开发**: 开发管理端前端功能时
- **组件开发**: 创建或修改管理端组件时
- **页面开发**: 开发管理端页面时
- **功能集成**: 集成新功能到管理端时
#### 0.2.2 辅助场景
- **前端调试**: 调试管理端前端问题时
- **性能优化**: 优化管理端前端性能时
- **样式调整**: 调整管理端界面样式时
- **权限配置**: 配置管理端权限时
### 0.3 触发机制
#### 0.3.1 调用时机
- **实时触发**: 前端文件操作时立即触发
- **延迟触发**: 复杂前端构建时延迟1秒触发
- **批量触发**: 批量前端文件操作时合并触发
#### 0.3.2 调用频率
- 文件浏览: 最多每10秒触发一次
- 文件操作: 最多每5秒触发一次
- 命令执行: 最多每3秒触发一次
#### 0.3.3 调用优先级
- **优先级等级**: 中优先级 (3/5)
- **竞争处理**: 当多个技能同时触发时
- 最高优先级: 系统核心技能
- 高优先级: 代码结构技能
- 中等优先级: 管理端前端技能、文档规范技能
- 低优先级: 辅助工具技能
- **触发限制**: 仅在管理端前端相关操作时被触发，不影响其他技能的正常使用
### 0.4 触发后行为
#### 0.4.1 自动分析
- **结构分析**: 分析管理端前端目录结构
- **组件分析**: 分析前端组件依赖关系
- **路由分析**: 分析前端路由配置
- **性能分析**: 分析前端性能瓶颈
#### 0.4.2 自动展示
- **目录结构**: 展示管理端前端目录结构
- **组件说明**: 展示核心组件功能说明
- **技术栈**: 展示管理端前端技术栈
- **开发规范**: 展示前端开发规范
#### 0.4.3 自动建议
- **开发建议**: 提供管理端前端开发建议
- **优化建议**: 提供前端性能优化建议
- **规范建议**: 提供代码规范遵循建议
- **安全建议**: 提供前端安全防护建议
## 1. 管理端前端架构
### 1.1 整体架构
- **单页应用**: 基于 Vue 2.x 的单页应用
- **前后端分离**: 与后端通过 RESTful API 交互
- **模块化设计**: 功能模块化，易于扩展
- **响应式布局**: 适配不同屏幕尺寸
### 1.2 技术栈
- **核心框架**: Vue 2.x
- **UI 组件库**: Element UI
- **状态管理**: Vuex
- **路由管理**: Vue Router
- **HTTP 客户端**: Axios
- **构建工具**: Webpack
- **包管理器**: npm/yarn
- **代码规范**: ESLint + Prettier
### 1.3 目录结构
#### 1.3.1 核心目录
```
public/admin/
├── index.html # 入口 HTML 文件
├── static/ # 静态资源
│ ├── css/ # 样式文件
│ ├── js/ # JavaScript 文件
│ └── img/ # 图片资源
├── favicon.ico # 网站图标
└── manifest.json # PWA 配置文件
```
#### 1.3.2 源代码目录 (src)
```
src/
├── api/ # API 接口定义
├── assets/ # 静态资源
├── components/ # 公共组件
├── layout/ # 布局组件
├── pages/ # 页面组件
├── router/ # 路由配置
├── store/ # 状态管理
├── utils/ # 工具函数
├── directive/ # 自定义指令
├── filters/ # 自定义过滤器
├── mixins/ # 混合器
├── App.vue # 根组件
└── main.js # 入口文件
```
## 2. 核心模块
### 2.1 登录认证模块
- **功能**: 用户登录、权限验证、会话管理
- **关键组件**: `Login.vue`、`Auth.vue`
- **核心功能**:
- 用户名密码登录
- 验证码验证
- 记住密码
- 登录状态管理
- 权限令牌管理
### 2.2 菜单导航模块
- **功能**: 管理端菜单展示、权限控制、路由导航
- **关键组件**: `Sidebar.vue`、`Topbar.vue`
- **核心功能**:
- 动态菜单生成
- 菜单权限控制
- 面包屑导航
- 标签页管理
- 菜单折叠/展开
### 2.3 仪表盘模块
- **功能**: 系统概览、数据统计、关键指标展示
- **关键组件**: `Dashboard.vue`、`Statistics.vue`
- **核心功能**:
- 销售数据统计
- 订单数据统计
- 用户数据统计
- 商品数据统计
- 系统状态监控
### 2.4 用户管理模块
- **功能**: 管理员账号管理、权限分配、角色管理
- **关键组件**: `UserList.vue`、`RoleList.vue`、`PermissionList.vue`
- **核心功能**:
- 用户增删改查
- 角色管理
- 权限分配
- 密码重置
- 登录日志查看
### 2.5 系统设置模块
- **功能**: 系统配置、参数设置、数据备份
- **关键组件**: `SystemConfig.vue`、`Backup.vue`
- **核心功能**:
- 系统基本设置
- 支付配置
- 邮件配置
- 短信配置
- 数据备份/恢复
## 3. 技术特点
### 3.1 组件化开发
- **可复用组件**: 封装常用 UI 组件
- **组件通信**: Props/Events、Vuex、EventBus
- **组件生命周期**: 合理使用生命周期钩子
- **组件命名规范**: 遵循 PascalCase 命名
### 3.2 状态管理
- **Vuex 模块化**: 按功能模块划分 store
- **状态持久化**: 使用 localStorage/sessionStorage
- **异步操作**: 使用 Actions 处理异步请求
- **getters**: 派生状态计算
### 3.3 路由管理
- **动态路由**: 根据权限生成路由
- **路由守卫**: 全局/局部路由守卫
- **路由懒加载**: 提高首屏加载速度
- **嵌套路由**: 实现复杂页面结构
### 3.4 API 调用
- **Axios 封装**: 统一 API 调用方式
- **请求拦截器**: 添加认证令牌
- **响应拦截器**: 统一错误处理
- **API 模块化**: 按功能模块划分 API
## 4. 开发规范
### 4.1 代码规范
- **Vue 风格指南**: 遵循 Vue 官方风格指南
- **ESLint 规则**: 严格遵循 ESLint 规则
- **代码缩进**: 4空格缩进
- **命名规范**:
- 组件名: PascalCase
- 方法/变量: camelCase
- 常量: 全大写
- 文件名: kebab-case 或 PascalCase
### 4.2 目录规范
- **组件目录**: 按功能模块组织组件
- **页面目录**: 按路由结构组织页面
- **资源目录**: 分类存放静态资源
- **工具目录**: 按功能分类工具函数
### 4.3 命名规范
- **组件命名**: 使用语义化的组件名称
- **路由命名**: 与页面组件名称对应
- **store 命名**: 与功能模块名称对应
- **API 命名**: 与后端接口名称对应
### 4.4 注释规范
- **组件注释**: 组件功能、props、events 说明
- **方法注释**: 方法功能、参数、返回值说明
- **复杂逻辑注释**: 关键逻辑步骤说明
- **TODO 注释**: 待完成功能标记
## 5. 性能优化
### 5.1 加载优化
- **路由懒加载**: 按需加载页面组件
- **组件懒加载**: 按需加载大型组件
- **图片优化**: 图片压缩、懒加载
- **资源压缩**: JS/CSS 压缩
- **CDN 加速**: 静态资源使用 CDN
### 5.2 渲染优化
- **虚拟列表**: 长列表使用虚拟滚动
- **计算属性缓存**: 使用 computed 缓存计算结果
- **避免频繁更新**: 使用 v-once、v-memo
- **合理使用 key**: 列表渲染时使用唯一 key
- **减少 DOM 操作**: 批量更新 DOM
### 5.3 网络优化
- **API 请求合并**: 合并相同请求
- **请求缓存**: 缓存重复请求结果
- **防抖节流**: 优化频繁触发的事件
- **WebSocket**: 实时数据使用 WebSocket
- **HTTP/2**: 启用 HTTP/2 协议
### 5.4 构建优化
- **Tree Shaking**: 移除未使用的代码
- **代码分割**: 按路由分割代码
- **预加载**: 预加载关键资源
- **环境变量**: 区分开发/生产环境
## 6. 安全防护
### 6.1 XSS 防护
- **输入验证**: 验证用户输入
- **输出编码**: 对输出进行 HTML 编码
- **CSP**: 配置内容安全策略
- **Vue 自动转义**: 利用 Vue 的 HTML 转义功能
### 6.2 CSRF 防护
- **Token 验证**: 使用 CSRF Token
- **同源策略**: 遵循浏览器同源策略
- **请求头验证**: 验证请求来源
### 6.3 权限控制
- **前端权限验证**: 路由权限控制
- **后端权限验证**: 接口权限验证
- **按钮级别权限**: 细粒度权限控制
- **敏感操作验证**: 重要操作二次确认
### 6.4 数据安全
- **敏感数据加密**: 加密存储敏感信息
- **本地存储安全**: 合理使用 localStorage
- **API 接口安全**: HTTPS、接口签名
## 7. 最佳实践
### 7.1 开发流程
1. **需求分析**: 明确功能需求
2. **设计阶段**: 设计页面结构和组件
3. **编码实现**: 遵循开发规范编码
4. **测试验证**: 功能测试和性能测试
5. **代码审查**: 代码质量检查
6. **部署上线**: 构建和部署
### 7.2 组件开发
- **单一职责**: 组件功能单一
- **可配置性**: 组件参数可配置
- **文档完善**: 组件使用文档
- **测试覆盖**: 组件单元测试
### 7.3 页面开发
- **布局规范**: 遵循统一布局规范
- **响应式设计**: 适配不同屏幕尺寸
- **用户体验**: 优化交互体验
- **性能考虑**: 页面加载和渲染性能
### 7.4 调试技巧
- **Vue DevTools**: 使用 Vue 开发工具
- **控制台调试**: 合理使用 console 方法
- **网络调试**: 分析 API 请求和响应
- **性能分析**: 使用浏览器性能分析工具
## 8. 常见问题
### 8.1 登录问题
- **令牌过期**: 处理令牌过期逻辑
- **权限不足**: 权限验证失败处理
- **登录状态保持**: 持久化登录状态
### 8.2 路由问题
- **404 页面**: 配置 404 路由
- **路由重定向**: 合理配置路由重定向
- **路由权限**: 动态路由权限控制
### 8.3 性能问题
- **首屏加载慢**: 优化首屏加载速度
- **页面卡顿**: 优化页面渲染性能
- **内存泄漏**: 避免内存泄漏
### 8.4 兼容性问题
- **浏览器兼容**: 支持主流浏览器
- **分辨率兼容**: 适配不同分辨率
- **设备兼容**: 适配不同设备
## 9. 部署与发布
### 9.1 构建流程
- **开发环境**: `npm run dev`
- **测试环境**: `npm run build:test`
- **生产环境**: `npm run build:prod`
### 9.2 部署方式
- **静态部署**: 部署到静态文件服务器
- **容器部署**: 使用 Docker 容器部署
- **CDN 加速**: 静态资源使用 CDN
### 9.3 发布流程
1. **代码提交**: 提交代码到版本控制系统
2. **构建测试**: 构建并测试
3. **部署上线**: 部署到生产环境
4. **监控运行**: 监控系统运行状态
## 10. 开发工具推荐
### 10.1 IDE 推荐
- **VS Code**: 轻量级编辑器，丰富的插件
- **WebStorm**: 专业的前端 IDE
- **Sublime Text**: 快速的代码编辑器
### 10.2 插件推荐
- **Vetur**: Vue 开发插件
- **ESLint**: 代码检查插件
- **Prettier**: 代码格式化插件
- **GitLens**: Git 增强插件
- **Debugger for Chrome**: 浏览器调试插件
### 10.3 工具推荐
- **Postman**: API 测试工具
- **Charles**: 网络调试工具
- **Figma/Sketch**: UI 设计工具
- **Zeplin**: 设计协作工具
- **Lighthouse**: 性能分析工具
## 11. 参考资源
### 11.1 官方文档
- [Vue 2 官方文档](https://v2.vuejs.org/)
- [Element UI 官方文档](https://element.eleme.io/#/zh-CN)
- [Vuex 官方文档](https://vuex.vuejs.org/zh/)
- [Vue Router 官方文档](https://router.vuejs.org/zh/)
- [Axios 官方文档](https://axios-http.com/zh/docs/intro)
### 11.2 学习资源
- [Vue Mastery](https://www.vuemastery.com/)
- [Vue School](https://vueschool.io/)
- [MDN Web Docs](https://developer.mozilla.org/zh-CN/)
- [CSS-Tricks](https://css-tricks.com/)
### 11.3 社区资源
- [Vue 论坛](https://forum.vuejs.org/)
- [Element UI 社区](https://github.com/ElemeFE/element)
- [GitHub](https://github.com/)
- [Stack Overflow](https://stackoverflow.com/)
## 12. 版本管理
### 12.1 版本控制
- **Git**: 使用 Git 进行版本控制
- **分支管理**: 主分支、开发分支、功能分支
- **提交规范**: 语义化提交信息
### 12.2 版本发布
- **语义化版本**: 遵循 SemVer 规范
- **发布日志**: 记录版本变更内容
- **回滚方案**: 版本回滚策略
## 13. 团队协作
### 13.1 协作流程
- **需求评审**: 团队评审需求
- **任务分配**: 合理分配开发任务
- **代码审查**: 代码质量检查
- **测试协作**: 开发与测试协作
### 13.2 规范约定
- **代码规范**: 统一代码风格
- **命名规范**: 统一命名规则
- **文档规范**: 统一文档格式
- **提交规范**: 统一提交信息格式
### 13.3 工具协作
- **项目管理**: 使用项目管理工具
- **代码托管**: 使用代码托管平台
- **CI/CD**: 持续集成/持续部署
- **文档协作**: 团队文档协作工具

133
docs/AI代码理解指南.md Normal file
View File

@ -0,0 +1,133 @@
# AI代码理解指南
## 🧠 代码理解方法论
### 1. 分层理解法
- **架构层**：理解整体项目结构和技术栈
- **模块层**：分析功能模块划分和交互关系
- **类层**：研究核心类的职责和接口
- **方法层**：理解具体方法的实现逻辑
### 2. 调用链追踪
```mermaid
graph TD
A[Controller] -->|调用| B[Service]
B -->|调用| C[DAO]
C -->|操作| D[数据库]
```
### 3. 上下文关联
- 向上追溯：该方法被谁调用？
- 向下深入：该方法调用了哪些其他方法？
- 横向关联：是否有相似功能的其他方法？
## 🔍 核心代码解读
### 1. 控制器层
```php
// 典型控制器方法
public function createOrder() {
// 1. 参数验证
$params = $this->request->post();
$this->validate($params);
// 2. 调用服务层
$orderId = $orderService->createOrder($params);
// 3. 返回结果
return $this->success(['order_id' => $orderId]);
}
```
### 2. 服务层
```php
// 典型服务方法
public function createOrder($params) {
// 1. 校验商品
$this->checkProducts($params['products']);
// 2. 计算价格
$amount = $this->calculateAmount($params);
// 3. 创建订单
$orderId = $this->orderDao->create([
'user_id' => $params['user_id'],
'amount' => $amount,
'status' => 'unpaid'
]);
// 4. 扣减库存
$this->productService->deductStock($params['products']);
return $orderId;
}
```
### 3. DAO层
```php
// 典型DAO方法
public function create($data) {
$data['create_time'] = time();
return Db::name('order')->insertGetId($data);
}
```
## 📚 代码学习路径
### 1. 入门路径
1. 从控制器入口理解业务流
2. 跟踪核心业务的服务层实现
3. 了解基础数据访问操作
### 2. 进阶路径
1. 研究异常处理机制
2. 分析中间件实现
3. 理解事件和监听机制
### 3. 高级路径
1. 研究性能优化点
2. 分析安全防护措施
3. 理解扩展机制
## 💡 理解技巧
### 1. 调试技巧
```php
// 使用日志输出关键变量
Log::info('Order create params: ' . json_encode($params));
// 使用断点调试
xdebug_break();
```
### 2. 可视化工具
- 使用UML工具绘制类图
- 使用时序图描述调用流程
- 使用思维导图整理功能模块
### 3. 文档辅助
- 结合接口文档理解参数
- 参考数据库字典理解数据结构
- 查看测试用例了解预期行为
## 🛠️ 常见问题解决
### 1. 如何快速定位业务逻辑？
- 搜索相关关键词（如方法名、表名）
- 跟踪核心数据表的变化
- 分析日志中的调用链
### 2. 如何理解复杂算法？
- 分解为小步骤逐步验证
- 编写单元测试验证边界条件
- 使用可视化工具展示数据流
### 3. 如何评估代码质量？
- 检查分层是否清晰
- 评估单元测试覆盖率
- 分析代码重复度
- 检查异常处理是否完备
---
> **提示**：该文档由AI生成，仅供参考。

1129
docs/admin/后台管理前端架构说明.md Normal file
View File

File diff suppressed because it is too large Load Diff

707
docs/admin/管理端前端目录结构详细说明.md Normal file
View File

@ -0,0 +1,707 @@
# CRMEB 管理端前端目录结构详细说明
## 📋 项目概览
**技术栈**: Vue.js 2.x + Element UI + Vuex + SCSS
**UI框架**: Element UI + VXE-Table + Vue Awesome Swiper
**项目版本**: CRMEB标准版 5.6.2
**开发模式**: 组件化 + 模块化 + 响应式布局
## 🏗️ 整体架构设计
```
template/admin/
├── public/ # 静态HTML模板
│ ├── image/ # 网站图标资源
│ ├── favicon.ico # 网站图标
│ └── index.html # HTML入口模板
├── src/ # 源码目录
│ ├── api/ # 接口服务层 (30+ API模块)
│ ├── assets/ # 静态资源层
│ ├── components/ # 组件层 (80+ 可复用组件)
│ ├── config/ # 配置层
│ ├── directive/ # 指令层
│ ├── filters/ # 过滤器层
│ ├── i18n/ # 国际化层
│ ├── layout/ # 布局层
│ ├── libs/ # 工具库层
│ ├── mixins/ # 混入层
│ ├── pages/ # 页面层 (17个业务模块)
│ ├── plugin/ # 插件层
│ ├── router/ # 路由层
│ ├── services/ # 服务层
│ ├── store/ # 状态管理层 (17+ Vuex模块)
│ ├── styles/ # 样式层
│ ├── theme/ # 主题层
│ ├── utils/ # 工具函数层
│ ├── App.vue # 应用根组件
│ ├── main.js # 应用入口
│ └── setting.js # 应用设置
├── package.json # 依赖配置
└── .babelrc # Babel配置
```
## 📊 详细目录结构解析
### 1. 📁 api/ - 接口服务层
按业务模块划分的API接口管理：
```javascript
api/
├── account.js # 账户管理接口
├── agent.js # 代理商接口
├── app.js # 应用配置接口
├── cms.js # 内容管理接口
├── common.js # 公共接口
├── crud.js # 增删改查通用接口
├── diy.php # 装修配置接口
├── export.php # 数据导出接口
├── finance.js # 财务接口
├── index.php # 首页接口
├── kefu_mobile.js # 移动端客服接口
├── kefu.js # 客服系统接口
├── live.js # 直播接口
├── lottery.js # 抽奖活动接口
├── marketing.js # 营销活动接口
├── membershipLevel.js # 会员等级接口
├── notification.php # 通知消息接口
├── order.js # 订单管理接口
├── product.js # 产品管理接口
├── setting.php # 系统设置接口
├── statistic.php # 统计数据接口
├── system.php # 系统配置接口
├── systemAdmin.php # 管理员接口
├── systemBackendRouting.php # 路由配置接口
├── systemCodeGeneration.php # 代码生成器接口
├── systemMenus.php # 菜单管理接口
├── systemOutAccount.php # 第三方账号接口
├── upload.php # 上传接口
├── uploadPictures.php # 图片上传接口
└── user.php # 用户管理接口
```
**接口设计特点**:
- RESTful风格设计
- 统一的请求拦截和响应处理
- 支持文件上传和下载
- 完善的错误处理机制
### 2. 📁 components/ - 组件层
丰富的组件库，采用原子化设计思想：
#### 2.1 基础组件
- `Pagination/` - 分页组件
- `pagesHeader/` - 页面头部组件
- `common-icon/` - 通用图标组件
- `cards/` - 卡片组件
- `copyright/` - 版权组件
- `icons/` - 图标选择组件
#### 2.2 表单组件
- `cropperImg/` - 图片裁剪组件
- `from/` - 表单组件
- `iconFrom/` - 图标表单组件
- `dateRadio/` - 日期单选组件
- `labelList/` - 标签列表组件
- `goodsLabel/` - 商品标签组件
#### 2.3 上传组件
- `uploadPictures/` - 图片上传组件
- `model.vue` - 上传弹窗
- `upload.vue` - 上传组件
- `uploadVideo/` - 视频上传组件
- `uploadVideo2/` - 视频上传组件v2
- `upload/` - 通用上传组件
#### 2.4 业务组件
- `couponList/` - 优惠券列表组件
- `customerInfo/` - 客户信息组件
- `goodsList/` - 商品列表组件
- `freightTemplate/` - 运费模板组件
- `hotpotModal/` - 热区弹窗组件
- `link/` - 链接选择组件
- `linkaddress/` - 链接地址组件
#### 2.5 可视化组件
- `echarts/` - 图表组件
- `echartsNew/` - 新版图表组件
- `tree-table/` - 树形表格组件
#### 2.6 移动端配置组件
```
mobileConfig/ # 移动端DIY组件库
├── c_auxiliary_box.vue # 辅助盒子
├── c_auxiliary_line.vue # 辅助线
├── c_banner.vue # 轮播图
├── c_home_bargain.vue # 砍价组件
├── c_home_comb.vue # 拼团组件
├── c_home_coupon.vue # 优惠券组件
├── c_home_goods_list.vue # 商品列表
├── c_home_hot.vue # 热门组件
├── c_home_menu.vue # 菜单组件
├── c_home_pink.vue # Pink拼团
├── c_home_product.vue # 商品组件
├── c_home_seckill.vue # 秒杀组件
├── c_home_service.vue # 服务中心
├── c_home_store_list.vue # 门店列表
├── c_home_title.vue # 标题组件
├── c_hotspot.vue # 热区组件
├── c_nav_bar.vue # 导航栏
├── c_new_list.vue # 新闻列表
├── c_new_vip.vue # 新增VIP
├── c_news_roll.vue # 新闻滚动
├── c_picture_cube.vue # 图片方块
├── c_points_mall.vue # 积分商城
├── c_presale.vue # 预售组件
├── c_ranking.vue # 排行榜
├── c_search_box.vue # 搜索框
├── c_short_video.vue # 短视频
├── c_sign_in.vue # 签到组件
├── c_ueditor_box.vue # 富文本框
├── c_userInfor.vue # 用户信息
├── c_video.vue # 视频组件
├── c_wechat_attention.vue # 微信关注
├── c_wechat_live.vue # 微信直播
├── index.js # 组件导出
├── pageFoot.vue # 页面底部
└── pageTitle.vue # 页面标题
```
#### 2.7 移动端右侧配置组件
```
mobileConfigRight/ # 移动端右侧配置组件库
├── c_bg_color.vue # 背景颜色
├── c_brand.vue # 品牌组件
├── c_button_img.vue # 按钮图片
├── c_button_style.vue # 按钮样式
├── c_cascader.vue # 级联选择
├── c_checkbox.vue # 复选框
├── c_classify.vue # 分类组件
├── c_comb_data.vue # 拼团数据
├── c_fillet.vue # 圆角设置
├── c_foot.vue # 底部配置
├── c_goods_label.vue # 商品标签
├── c_goods_search.vue # 商品搜索
├── c_goods.vue # 商品组件
├── c_hot_box.vue # 热区盒子
├── c_hot_imgs.vue # 热门图片
├── c_hot_word.vue # 热词组件
├── c_input_item.vue # 输入项
└── c_input_number.vue # 数字输入
```
#### 2.8 DIY装修组件
```
diyComponents/ # DIY装修组件库
├── c_bg_color.vue # 背景颜色
├── c_goods.vue # 商品组件
├── c_hot_word.vue # 热词组件
├── c_input_list.vue # 输入列表
├── c_input_number.vue # 数字输入
├── c_is_show.vue # 显示控制
├── c_page_ueditor.vue # 页面编辑器
├── c_select.vue # 选择器
├── c_tab_bar.vue # 标签栏
├── c_tab.vue # 标签组件
├── c_txt_list.vue # 文本列表
├── c_txt_tab.vue # 文本标签
├── c_upload_img.vue # 图片上传
├── c_upload_list.vue # 列表上传
├── c_upload_video.vue # 视频上传
└── index.js # 组件导出
```
### 3. 📁 pages/ - 页面层（17个业务模块）
#### 3.1 账户管理 (account)
```
pages/account/
├── accountList/ # 账户列表
├── balanceWithdraw/ # 余额提现
├── expenditure/ # 支出记录
├── recharge/ # 充值记录
└── revenue/ # 收入记录
```
#### 3.2 代理商管理 (agent)
```
pages/agent/
├── agentList/ # 代理商列表
├── agentOrder/ # 代理商订单
└── levelList/ # 代理商等级
```
#### 3.3 应用配置 (app)
```
pages/app/
├── appStyle/ # 应用风格
├── appVersion/ # 应用版本
├── distribution/ # 分销配置
├── diy/ # DIY装修
│ ├── index/ # 装修首页
│ ├── menu/ # 菜单装修
│ ├── page/ # 页面装修
│ └── user/ # 用户页装修
├── login_record/ # 登录记录
├── maintenance/ # 系统维护
├── membershipLevel/ # 会员等级
├── notice/ # 消息通知
├── userAgreement/ # 用户协议
└── wechatMenu/ # 微信菜单
```
#### 3.4 内容管理 (cms)
```
pages/cms/
├── article/ # 文章管理
│ ├── articleCate/ # 文章分类
│ └── articleList/ # 文章列表
├── feedback/ # 反馈管理
├── articleAttr/ # 文章属性
├── articleTag/ # 文章标签
├── articleCreate/ # 创建文章
├── links/ # 友情链接
├── visit/ # 访问记录
└── notice/ # 公告管理
```
#### 3.5 自动化运维 (crud)
```
pages/crud/
├── generate/ # 代码生成
├── generateEdit/ # 编辑生成
├── index/ # CRUD首页
├── table/ # 表格配置
└── template/ # 模板管理
```
#### 3.6 分销管理 (division)
```
pages/division/
├── setting/ # 分销设置
├── level/ # 分销等级
├── user/ # 分销用户
├── commission/ # 佣金管理
├── extraction/ # 提现管理
├── order/ # 分销订单
├── statistics/ # 分销统计
└── contract/ # 分销协议
```
#### 3.7 财务管理 (finance)
```
pages/finance/
├── bill/ # 账单管理
├── userbill/ # 用户账单
├── extract/ # 提现管理
├── recharge/ # 充值管理
├── invoice/ # 发票管理
└── account/ # 账户管理
```
#### 3.8 首页仪表盘 (index)
```
pages/index/
├── index/ # 管理后台首页
└── owerManagement/ # 管理员设置
```
#### 3.9 客服管理 (kefu)
```
pages/kefu/
├── chat/ # 客服聊天
├── kefuList/ # 客服列表
├── kefuRecord/ # 客服记录
├── kefuSetting/ # 客服设置
└── userList/ # 用户列表
```
#### 3.10 营销管理 (marketing)
```
pages/marketing/
├── bargain/ # 砍价活动
├── coupon/ # 优惠券管理
├── integral/ # 积分商城
├── lottery/ # 抽奖活动
├── promotion/ # 促销活动
├── seckill/ # 秒杀活动
├── storeCoupon/ # 门店优惠券
└── combination/ # 拼团活动
```
#### 3.11 通知管理 (notify)
```
pages/notify/
├── sms/ # 短信通知
├── template/ # 通知模板
└── sysMessages/ # 系统消息
```
#### 3.12 订单管理 (order)
```
pages/order/
├── orderList/ # 订单列表
├── orderDetail/ # 订单详情
├── orderCancellation/ # 订单核销
├── deliver/ # 发货管理
├── batchDeliver/ # 批量发货
├── exportOrder/ # 订单导出
└── orderStatistics/ # 订单统计
```
#### 3.13 商品管理 (product)
```
pages/product/
├── productList/ # 商品列表
├── productAttr/ # 商品属性
├── productCate/ # 商品分类
├── productCreate/ # 商品创建
├── productReply/ # 商品评价
├── productSpec/ # 商品规格
├── stock/ # 库存管理
└── storeStaff/ # 门店员工
```
#### 3.14 系统设置 (setting)
```
pages/setting/
├── system/ # 系统设置
│ ├── clearCache/ # 清理缓存
│ ├── systemLog/ # 系统日志
│ └── systemStore/ # 门店设置
└── systemMenus/ # 菜单设置
```
#### 3.15 统计报表 (statistic)
```
pages/statistic/
├── analysis/ # 数据分析
├── userChart/ # 用户统计
├── orderChart/ # 订单统计
├── productChart/ # 商品统计
├── financeChart/ # 财务统计
└── marketingChart/ # 营销统计
```
#### 3.16 系统管理 (system)
```
pages/system/
├── admin/ # 管理员
├── adminAdd/ # 添加管理员
├── adminRole/ # 角色管理
├── systemRole/ # 系统角色
├── systemMenus/ # 菜单管理
├── systemLogs/ # 日志管理
├── systemStorage/ # 存储设置
├── systemClear/ # 清理设置
├── systemQueue/ # 队列配置
├── systemNotice/ # 系统公告
└── codeGeneration/ # 代码生成
```
#### 3.17 用户管理 (user)
```
pages/user/
├── userList/ # 用户列表
├── userLevel/ # 用户等级
├── userLabel/ # 用户标签
├── userMember/ # 会员管理
├── userFrom/ # 用户来源
├── userNotice/ # 用户通知
├── userExport/ # 用户导出
└── userBalance/ # 用户余额
```
### 4. 📁 layout/ - 布局层
```
layout/
├── aside/ # 侧边栏
│ └── index.vue
├── component/ # 布局组件
│ ├── Breadcrumb/ # 面包屑
│ ├── Center/ # 居中布局
│ ├── Columns/ # 多列布局
│ ├── FirmOrder/ # 固顶订单
│ ├── Header/ # 头部组件
│ ├── Iocn/ # 图标组件
│ ├── Logo/ # LOGO组件
│ └── NavBars/ # 导航栏
│ ├── index.vue
│ ├── breadcrumb.vue
│ ├── setings.vue # 设置弹窗
│ └── topic.vue
├── main.vue # 主布局
├── mixins/ # 布局混入
│ └── mobileMenu.js
├── navBars/ # 导航栏组件
│ └── breadcrumbs.vue
└── upgrade/ # 升级提示
└── index.vue
```
### 5. 📁 store/ - 状态管理层
Vuex模块化状态管理（17+个模块）：
```javascript
store/
├── module/ # 状态模块
│ ├── user.js # 用户状态
│ ├── app.js # 应用状态
│ ├── menus.js # 菜单状态
│ ├── menu.js # 菜单数据
│ ├── userInfo.js # 用户信息
│ ├── userLevel.js # 用户等级
│ ├── order.js # 订单状态
│ ├── media.js # 媒体状态
│ ├── goodSelect.js # 商品选择
│ ├── moren.js # 默认状态
│ ├── shopping.js # 购物状态
│ ├── fresh.js # 刷新状态
│ ├── kefu.js # 客服状态
│ ├── integralOrder.js # 积分订单
│ ├── mobildConfig.js # 移动配置
│ ├── upgrade.js # 升级状态
│ ├── layout.js # 布局状态
│ ├── themeConfig.js # 主题配置
│ ├── routesList.js # 路由列表
│ ├── tagsViewRoutes.js # 标签路由
│ ├── userInfos.js # 用户信息
│ └── keepAliveNames.js # 缓存页面
└── index.js # Store主入口
```
**状态管理特点**:
- Vuex持久化存储
- 模块化状态划分
- 严格的状态修改
- 支持多设备响应式
### 6. 📁 libs/ - 工具库层
```javascript
libs/
├── util.js # 通用工具函数
├── wechat.js # 微信SDK封装
├── dialog.js # 弹窗工具
├── timeOptions.js # 时间选项
├── loading.js # 加载动画
├── auth.js # 权限工具
├── authLapse.js # 权限过期处理
├── public.js # 公共工具
├── formCreate # 表单生成器
└── excel.js # Excel处理
```
### 7. 📁 utils/ - 工具函数层
```javascript
utils/
├── storage.js # 本地存储工具
├── modalForm.js # 弹窗表单
├── newToExcel.js # Excel导出
├── videoCloud.js # 视频云处理
├── public.js # 公共方法
├── authLapse.js # 权限过期
├── public_fun.js # 公共函数
├── loading.js # 加载动画
└── auth.js # 权限验证
```
### 8. 📁 router/ - 路由层
```javascript
router/
├── index.js # 路由主文件
└── routers.js # 路由配置
```
**路由特点**:
- 动态路由加载
- 路由权限控制
- 菜单权限过滤
- Keep-alive缓存
### 9. 📁 static/ - 静态资源层
#### 9.1 样式资源
```
static/css/ 或 assets/
├── fonts/ # 字体文件
│ └── D-DIN-PRO-*.ttf
├── iconfont/ # 图标字体
│ ├── iconfont.css
│ ├── iconfont.js
│ └── iconfont.json
├── iconfontYI/ # 业务图标
│ └── iconfontYI.css
├── icons/ # 系统图标
└── js/ # JS资源
├── canvas-nest.min.js
├── jigsaw.css
└── jigsaw.js
```
#### 9.2 图片资源
```
assets/images/
├── error-page/ # 错误页面图片
│ ├── error-401.svg
│ ├── error-404.svg
│ └── error-500.svg
├── login-bg.jpg # 登录背景
├── logo.png # LOGO图片
├── default.jpg # 默认图片
└── 各种业务图片资源
```
### 10. 📁 theme/ - 主题层
```
theme/
├── index.scss # 主题入口
├── mixin.scss # SCSS混入
├── var.scss # 变量定义
└── element/ # Element主题覆盖
```
### 11. 📁 directive/ - 指令层
```
directive/
├── limit.js # 输入限制指令
├── copy.js # 复制指令
├── auth.js # 权限指令
├── clickOutside.js # 点击外部指令
└── waves/ # 水波纹指令
```
### 12. 📁 i18n/ - 国际化层
```
i18n/
├── lang/ # 语言包
│ ├── zh.js # 中文
│ └── en.js # 英文
└── index.js # 国际化配置
```
### 13. 📁 mixins/ - 混入层
```javascript
mixins/
├── mobileMenu.js # 移动端菜单混入
├── popuppicker.js # 弹窗选择器混入
└── lists.js # 列表页混入
```
### 14. 📁 plugin/ - 插件层
```
plugin/
├── emoji-awesome/ # 表情插件
│ └── css/
└── ...
```
## 🚀 核心技术特性
### 1. UI框架集成
```javascript
// Element UI
Vue.use(Element, { i18n, size: 'small' })
// VXE-Table (高性能表格)
Vue.use(VxeTable)
Vue.use(VxeUIAll)
// 树形表格
Vue.use(TreeTable)
Vue.use(VOrgTree)
```
### 2. 高级组件库
- **VueAwesomeSwiper** - 轮播组件
- **VueLazyload** - 图片懒加载
- **Viewer** - 图片查看器
- **VueDND** - 拖拽排序
- **formCreate** - 表单生成器
- **VueCodeMirror** - 代码编辑器
- **VueTreeList** - 树形列表
### 3. 权限控制
- 角色权限管理
- 动态路由加载
- 菜单权限过滤
- 按钮级权限控制
### 4. 响应式布局
```javascript
// 设备检测
matchMedia('(max-width: 600px)') // 移动端
matchMedia('(max-width: 992px)') // 平板
else // 桌面端
```
### 5. 数据可视化
- ECharts图表集成
- 自定义图表组件
- 实时数据更新
## 📋 开发规范
### 1. 命名规范
- **目录命名**: 小写字母，使用连字符
- **文件命名**: Vue组件使用帕斯卡命名
- **变量命名**: 驼峰命名
- **样式命名**: BEM命名或CSS模块
### 2. 代码组织
- 组件单一职责
- Props类型验证
- 错误边界处理
- 合理注释
### 3. Git提交规范
- feat: 新功能
- fix: 修复bug
- docs: 文档更新
- style: 代码格式
- refactor: 重构
## 🛠️ 开发命令
```bash
# 开发环境
npm run dev
npm run serve
# 生产构建
npm run build
# 代码检查
npm run lint
# 单元测试
npm run test
```
## 📝 注意事项
1. **环境配置**: 配置API地址和密钥
2. **权限设置**: 正确配置角色权限
3. **数据安全**: 敏感数据加密处理
4. **性能优化**: 合理使用Keep-alive
5. **兼容性**: 注意浏览器兼容性
---
*本文档基于CRMEB 5.6.2版本分析生成，最后更新: 2026-01-19*
*📧 如有疑问请联系开发团队: admin@crmeb.com*
---
> **提示**：该文档由AI生成，仅供参考。

336
docs/docker安装说明文档.md Normal file
View File

@ -0,0 +1,336 @@
# CRMEB Docker 安装说明文档
## 1. 环境准备
### 1.1 安装 Docker
请根据您的操作系统选择对应的 Docker 安装方式：
#### Windows / macOS
访问 Docker 官网下载并安装 Docker Desktop：
[https://www.docker.com/products/docker-desktop](https://www.docker.com/products/docker-desktop)
#### Linux
使用以下命令安装 Docker：
```bash
curl -sSL https://get.daocloud.io/docker | sh
```
### 1.2 安装 Docker Compose
#### Windows / macOS
Docker Desktop 已包含 Docker Compose，无需额外安装。
#### Linux
请参考官方文档安装 Docker Compose：
[https://docs.docker.com/compose/install/](https://docs.docker.com/compose/install/)
## 2. 下载 CRMEB 程序
1. 下载最新开源代码：
[https://gitee.com/ZhongBangKeJi/CRMEB](https://gitee.com/ZhongBangKeJi/CRMEB)
2. 将程序解压并放置在与 `docker-compose` 目录同级的位置。
## 3. 不同操作系统的安装配置
### 3.1 通用配置（默认）
适用于大多数 Linux 系统和 macOS Intel 芯片。
配置文件路径：`docker-compose/docker-compose.yml`
### 3.2 Linux 系统
Linux 专用配置，包含平台兼容性设置。
配置文件路径：`docker-compose/linux/docker-compose.yml`
### 3.3 macOS（Intel 芯片）
macOS Intel 芯片专用配置。
配置文件路径：`docker-compose/MacIntel/docker-compose.yml`
### 3.4 macOS（Apple Silicon 芯片）
MacBook M1/M2/M3 等 Apple Silicon 芯片专用配置，解决了 MySQL 兼容性问题。
配置文件路径：`docker-compose/MacArm/docker-compose.yml`
### 3.5 Windows 系统
Windows 专用配置。
配置文件路径：`docker-compose/window/docker-compose.yml`
## 4. 服务配置说明
### 4.1 MySQL 数据库
| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| 容器名称 | crmeb_mysql | Docker 容器名称 |
| 镜像 | mysql:5.7 | 数据库镜像（MacArm 使用 mysql/mysql-server） |
| 端口 | 3336:3306 | 宿主机端口:容器端口 |
| 用户名 | root | 数据库用户名 |
| 密码 | 123456 | 数据库密码 |
| 数据库名 | crmeb | 默认创建的数据库名称 |
| 容器 IP | 192.168.10.11 | 内部网络固定 IP |
### 4.2 Redis 缓存
| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| 容器名称 | crmeb_redis | Docker 容器名称 |
| 镜像 | redis:alpine | Redis 镜像 |
| 端口 | 6379:6379 | 宿主机端口:容器端口 |
| 容器 IP | 192.168.10.10 | 内部网络固定 IP |
### 4.3 PHP 应用
| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| 容器名称 | crmeb_php | Docker 容器名称 |
| 镜像 | crmeb_php | PHP 镜像（通过 Dockerfile 构建） |
| 端口 | 9000:9000 | PHP-FPM 端口 |
| | 20002:20002 | 长连接端口 1 |
| | 20003:20003 | 长连接端口 2 |
| 容器 IP | 192.168.10.90 | 内部网络固定 IP |
| 程序目录 | /var/www | 项目在容器内的路径 |
### 4.4 Nginx 服务器
| 配置项 | 默认值 | 说明 |
|--------|--------|------|
| 容器名称 | crmeb_nginx | Docker 容器名称 |
| 镜像 | nginx:alpine | Nginx 镜像 |
| 端口 | 8011:80 | 宿主机端口:容器端口 |
| 容器 IP | 192.168.10.80 | 内部网络固定 IP |
## 5. 启动项目
### 5.1 基本启动步骤
1. 进入 docker-compose 目录：
```bash
cd docker-compose
```
2. 启动所有服务：
```bash
docker-compose up -d
```
3. 查看容器状态：
```bash
docker-compose ps
```
### 5.2 启动额外服务（必需）
进入 PHP 容器并启动队列、定时任务和长连接服务：
1. 进入 PHP 容器：
```bash
docker exec -it crmeb_php /bin/bash
```
2. 进入项目目录：
```bash
cd /var/www
```
3. 启动定时任务：
```bash
php think timer start --d
```
4. 启动长连接服务：
```bash
php think workerman start --d
```
5. 启动队列服务：
```bash
php think queue:listen --queue
```
## 6. 访问 CRMEB 系统
### 6.1 访问地址
在浏览器中输入以下地址访问 CRMEB 系统：
```
http://localhost:8011/
```
### 6.2 系统安装
首次访问将进入 CRMEB 安装向导，根据提示完成系统安装。
#### 数据库配置
| 配置项 | 值 |
|--------|-----|
| 数据库地址 | 192.168.10.11 |
| 端口 | 3306 |
| 用户名 | root |
| 密码 | 123456 |
| 数据库名 | crmeb |
#### Redis 配置
| 配置项 | 值 |
|--------|-----|
| Redis 地址 | 192.168.10.10 |
| 端口 | 6379 |
| 数据库 | 0 |
| 密码 | 123456 |
## 7. 容器管理
### 7.1 停止服务
```bash
# 停止所有服务
docker-compose down
# 停止指定服务
docker-compose stop <service-name>
```
### 7.2 重启服务
```bash
# 重启所有服务
docker-compose restart
# 重启指定服务
docker-compose restart <service-name>
```
### 7.3 查看日志
```bash
# 查看所有服务日志
docker-compose logs
# 查看指定服务日志
docker-compose logs <service-name>
# 实时查看日志
docker-compose logs -f <service-name>
```
## 8. 常见问题及解决方案
### 8.1 端口被占用
**问题**：启动时出现端口被占用错误
**解决方案**：
1. 修改 `docker-compose.yml` 中的端口映射，例如将 `8011:80` 改为 `8080:80`
2. 重启服务
### 8.2 IP 地址冲突
**问题**：`Error response from daemon: Address already in use`
**解决方案**：
1. 修改 `docker-compose.yml` 中冲突容器的 `ipv4_address`
2. 确保 IP 地址在 `192.168.*.*` 网段内且不与其他设备冲突
### 8.3 MySQL 容器启动失败（Mac ARM 芯片）
**问题**：MySQL 容器无法启动，无日志输出
**解决方案**：
1. 使用 MacArm 目录下的专用配置
2. 确保使用了正确的 MySQL 镜像（`mysql/mysql-server`）
3. 检查文件权限设置
### 8.4 PHP 扩展缺失
**问题**：系统提示缺少某些 PHP 扩展
**解决方案**：
1. 进入 PHP 容器
2. 安装所需扩展
3. 或修改 `docker-compose/php/Dockerfile` 添加扩展并重新构建镜像
### 8.5 文件权限问题
**问题**：程序无法写入文件或创建目录
**解决方案**：
1. 检查宿主机上 `crmeb` 目录的权限
2. 确保容器内 `www-data` 用户有足够的权限
3. 可尝试修改目录权限：
```bash
chmod -R 777 crmeb/runtime
chmod -R 777 crmeb/public/upload
```
## 9. 注意事项
### 9.1 数据持久化
- MySQL 数据默认挂载在 `docker-compose/mysql/data` 目录
- Redis 数据默认未挂载，如需持久化请修改配置文件
- 项目代码挂载在 `crmeb` 目录，修改宿主机上的代码会直接影响容器内的程序
### 9.2 网络配置
- 所有服务运行在 `app_net` 网络中，使用固定 IP 地址
- 宿主机与容器之间通过端口映射通信
- 容器之间可以通过内部 IP 直接通信
### 9.3 性能优化
- 根据服务器配置调整容器资源限制
- 生产环境建议修改默认密码和端口
- 配置合适的日志清理策略
### 9.4 升级说明
1. 停止所有服务
2. 备份数据和配置文件
3. 更新代码
4. 重新启动服务
5. 执行数据库迁移（如有需要）
## 10. 高级配置
### 10.1 修改默认密码
编辑 `docker-compose.yml` 文件，修改以下环境变量：
- MySQL: `MYSQL_ROOT_PASSWORD`, `MYSQL_PASS`
- Redis: 在 `redis.conf` 中配置密码
### 10.2 配置 HTTPS
1. 在 `docker-compose.yml` 中启用 443 端口映射
2. 准备 SSL 证书
3. 修改 `nginx/vhost.conf` 配置 HTTPS
### 10.3 自定义 PHP 配置
修改 `docker-compose/php/php-ini-overrides.ini` 文件来自定义 PHP 配置。
## 11. 技术支持
如果您在安装过程中遇到问题，可以通过以下方式获取帮助：
- CRMEB 官方社区：[https://gitee.com/ZhongBangKeJi/CRMEB/issues](https://gitee.com/ZhongBangKeJi/CRMEB/issues)
- Docker 官方文档：[https://docs.docker.com/](https://docs.docker.com/)
---
**文档版本**：v1.0
**更新日期**：2023-12-04
**适用版本**：CRMEB v5.6+
---
> **提示**：该文档由AI生成，仅供参考。

52
docs/phpapi/API接口文档.md Normal file
View File

@ -0,0 +1,52 @@
# CRMEB API 接口文档
## 📍 API 入口划分
- **后台管理**: `/adminapi/controller/v1/` (需要管理员权限)
- **前端用户**: `/api/controller/v1/` (需要用户登录)
- **公共接口**: `/api/controller/publics/` (无需登录)
## 🔐 认证机制
```php
// JWT Token 认证
'middleware' => [
AuthTokenMiddleware::class, // 用户token验证
AdminAuthTokenMiddleware::class // 管理员token验证
]
```
## 📋 核心接口示例
### 用户管理接口
```
GET /adminapi/v1/user/list # 用户列表
POST /adminapi/v1/user/edit # 编辑用户
GET /api/v1/user/info # 获取用户信息
```
### 订单管理接口
```
GET /adminapi/v1/order/list # 订单列表
POST /api/v1/order/create # 创建订单
GET /api/v1/order/detail # 订单详情
```
## 🏷️ 统一响应格式
```json
{
"status": 200,
"msg": "success",
"data": {...},
"time": "2024-01-01 10:00:00"
}
```
## ⚠️ 错误码规范
- 200: 成功
- 400: 参数错误
- 401: 未授权
- 403: 权限不足
- 500: 服务器错误
---
> **提示**：该文档由AI生成，仅供参考。

40
docs/phpapi/业务流程说明.md Normal file
View File

@ -0,0 +1,40 @@
# 业务流程说明
## 📋 核心业务流程
### 🛒 订单创建流程
1. 用户选择商品 → 加入购物车 → 生成订单
2. 订单验证（库存、价格、优惠券）
3. 创建订单数据
4. 扣减库存
5. 发送订单通知
### 💳 支付处理流程
1. 用户选择支付方式
2. 调用支付接口
3. 支付结果回调
4. 更新订单状态
5. 记录支付流水
### 📦 发货流程
1. 订单状态检查（已支付）
2. 生成发货单
3. 调用物流接口
4. 更新发货状态
5. 通知用户物流信息
### 🔄 售后流程
1. 用户提交售后申请
2. 审核售后请求
3. 处理退款/换货
4. 更新库存和财务
5. 完成售后流程
## ⏱️ 异步任务流程
- 消息队列处理订单相关任务
- 定时任务处理数据统计
- 后台任务处理批量操作
---
> **提示**：该文档由AI生成，仅供参考。

423
docs/phpapi/会员管理开发文档.md Normal file
View File

@ -0,0 +1,423 @@
# 会员管理开发文档
## 1. 文档概述
### 1.1 文档目的
本文档旨在详细说明CRMEB系统中会员管理模块的设计架构、核心功能、代码实现及开发规范，为系统开发人员提供完整的开发参考。
### 1.2 适用范围
本文档适用于CRMEB系统开发人员、维护人员及二次开发人员，用于指导会员管理模块的开发、扩展和维护工作。
### 1.3 术语定义
| 术语 | 解释 |
|------|------|
| 会员等级 | 基于用户经验值划分的等级体系，不同等级享有不同权益 |
| 经验值 | 用户通过各种行为获得的数值，用于提升会员等级 |
| 会员权益 | 不同会员等级享有的专属福利，如折扣、优惠券等 |
| 会员卡片 | 展示会员等级、有效期、权益等信息的可视化卡片 |
| 积分 | 用户通过各种行为获得的可用于消费的数值 |
| 积分商城 | 用于兑换商品或服务的积分兑换平台 |
| 会员有效期 | 会员等级的有效期限，过期后可能降级或失效 |
## 2. 核心功能模块
### 2.1 会员等级管理
- **等级列表**：展示系统配置的会员等级，支持搜索、分页
- **等级添加**：添加新的会员等级，设置等级名称、折扣、经验值要求等
- **等级编辑**：修改会员等级信息，包括名称、折扣、经验值要求等
- **等级删除**：删除会员等级
- **等级状态管理**：启用/禁用会员等级
- **等级排序**：调整会员等级的显示顺序
### 2.2 用户等级管理
- **用户等级列表**：展示用户当前等级信息，支持搜索、分页
- **等级赠送**：手动为用户赠送会员等级
- **等级清除**：清除用户的会员等级
- **等级有效期管理**：设置和修改会员等级的有效期
- **等级自动检测**：定期检测用户是否达到升级条件，自动升级
### 2.3 经验值管理
- **经验值配置**：配置各种行为获得的经验值数量
- **经验值记录**：记录用户经验值的变动情况
- **经验值查询**：查询用户经验值的获取和使用记录
- **经验值统计**：统计用户经验值的来源分布
### 2.4 积分管理
- **积分配置**：配置各种行为获得的积分数量
- **积分增加**：手动为用户增加积分
- **积分扣除**：手动为用户扣除积分
- **积分记录**：记录用户积分的变动情况
- **积分查询**：查询用户积分的获取和使用记录
- **积分统计**：统计用户积分的来源和使用分布
### 2.5 会员权益管理
- **折扣权益**：配置不同等级的商品折扣比例
- **等级图标**：配置各等级的专属图标和背景图
- **会员卡片**：生成和管理会员卡片
- **权益规则**：配置会员享有的其他权益，如专属客服、优先发货等
### 2.6 会员等级升级机制
- **经验值累积**：通过签到、下单、邀请等行为累积经验值
- **升级条件检测**：定期检测用户是否达到升级条件
- **自动升级**：达到升级条件后自动更新会员等级
- **升级通知**：发送等级升级通知给用户
## 3. 代码结构与设计
### 3.1 架构设计
系统采用分层架构设计，严格遵循MVC设计模式：
```
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Models │ │ Daos │ │ Services │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │ │
└───────────────────────┼───────────────────────┘
│
┌─────────────────┐
│ Controllers │
└─────────────────┘
│
┌─────────────────┐
│ Routes │
└─────────────────┘
```
### 3.2 核心文件结构
#### 3.2.1 模型层（Model）
**会员相关模型**：
- `UserLevel.php` - 用户实际会员等级信息模型
- `SystemUserLevel.php` - 系统会员等级配置模型
- `User.php` - 用户基本信息模型，包含经验值、积分等字段
#### 3.2.2 服务层（Services）
**会员管理Services**：
- `UserLevelServices.php` - 会员等级设置与管理，自动检测用户升级条件
- `UserBillServices.php` - 积分增加与扣除，积分记录管理
- `UserServices.php` - 用户基本信息管理，包括等级、经验值、积分等
#### 3.2.3 控制器层（Controller）
**会员控制器**：
- `UserLevel.php` - 会员等级管理控制器
- `User.php` - 用户管理控制器，包含等级、经验值、积分等管理功能
#### 3.2.4 路由配置
**会员路由**：
- `user.php` - 包含会员管理相关的API路由
## 4. 数据库设计
### 4.1 系统会员等级表（system_user_level）
| 字段名 | 数据类型 | 描述 |
|--------|----------|------|
| id | int(10) unsigned | 等级ID |
| name | varchar(20) | 等级名称 |
| icon | varchar(255) | 等级图标 |
| bg | varchar(255) | 等级背景图 |
| grade | int(10) | 等级 |
| experience_min | int(10) | 最低经验值 |
| experience_max | int(10) | 最高经验值 |
| discount | decimal(10,2) | 折扣比例 |
| status | tinyint(1) | 状态（0-禁用，1-启用） |
| is_show | tinyint(1) | 是否显示（0-隐藏，1-显示） |
| sort | int(10) | 排序 |
| add_time | int(10) | 添加时间 |
### 4.2 用户等级表（user_level）
| 字段名 | 数据类型 | 描述 |
|--------|----------|------|
| id | int(10) unsigned | 记录ID |
| uid | int(10) | 用户ID |
| level_id | int(10) | 会员等级ID |
| is_forever | tinyint(1) | 是否永久（0-否，1-是） |
| start_time | int(10) | 开始时间 |
| end_time | int(10) | 结束时间 |
| status | tinyint(1) | 状态（0-过期，1-有效） |
| add_time | int(10) | 添加时间 |
### 4.3 用户表（user）
| 字段名 | 数据类型 | 描述 |
|--------|----------|------|
| uid | int(10) unsigned | 用户ID |
| user_level | int(10) | 当前会员等级ID |
| experience | int(10) | 经验值 |
| integral | int(10) | 积分 |
| sign_num | int(10) | 连续签到天数 |
| sign_integral | int(10) | 已领取签到积分 |
| // 其他用户信息字段 | // 数据类型 | // 描述 |
### 4.4 用户账单表（user_bill）
| 字段名 | 数据类型 | 描述 |
|--------|----------|------|
| id | int(10) unsigned | 账单ID |
| uid | int(10) | 用户ID |
| category | varchar(20) | 资金类型（integral-积分，experience-经验值） |
| type | varchar(20) | 变动类型（sign-签到，order-订单，invite-邀请） |
| pm | tinyint(1) | 收支方向（1-收入，0-支出） |
| number | varchar(50) | 流水号 |
| money | decimal(10,2) | 变动金额 |
| balance | decimal(10,2) | 变动后余额/积分/经验值 |
| mark | varchar(255) | 备注 |
| add_time | int(10) | 添加时间 |
## 5. API接口说明
### 5.1 会员等级管理
#### 5.1.1 获取系统会员等级列表
- **请求URL**：`/adminapi/v1/user/level/list`
- **请求方法**：GET
- **权限要求**：user/user_level/list
- **返回结果**：系统会员等级列表数据
#### 5.1.2 添加系统会员等级
- **请求URL**：`/adminapi/v1/user/level/create`
- **请求方法**：POST
- **权限要求**：user/user_level/create
- **请求参数**：
- name：等级名称
- grade：等级
- experience_min：最低经验值
- experience_max：最高经验值
- discount：折扣比例
- icon：等级图标
- bg：等级背景图
- **返回结果**：操作结果
#### 5.1.3 获取用户等级列表
- **请求URL**：`/adminapi/v1/user/user_level/list`
- **请求方法**：GET
- **权限要求**：user/user/user_level_list
- **请求参数**：
- page：页码
- limit：每页数量
- keyword：搜索关键词
- **返回结果**：用户等级列表数据
#### 5.1.4 为用户赠送会员等级
- **请求URL**：`/adminapi/v1/user/user_level/give/{uid}`
- **请求方法**：POST
- **权限要求**：user/user/user_level_give
- **请求参数**：
- level_id：会员等级ID
- is_forever：是否永久（0-否，1-是）
- days：有效期（天）
- **返回结果**：操作结果
### 5.2 积分管理
#### 5.2.1 获取积分记录列表
- **请求URL**：`/adminapi/v1/user/integral/list`
- **请求方法**：GET
- **权限要求**：user/integral/list
- **请求参数**：
- page：页码
- limit：每页数量
- uid：用户ID
- type：变动类型
- **返回结果**：积分记录列表数据
#### 5.2.2 为用户增加积分
- **请求URL**：`/adminapi/v1/user/integral/add/{uid}`
- **请求方法**：POST
- **权限要求**：user/integral/add
- **请求参数**：
- integral：积分数量
- mark：备注
- **返回结果**：操作结果
#### 5.2.3 为用户扣除积分
- **请求URL**：`/adminapi/v1/user/integral/sub/{uid}`
- **请求方法**：POST
- **权限要求**：user/integral/sub
- **请求参数**：
- integral：积分数量
- mark：备注
- **返回结果**：操作结果
### 5.3 用户端接口
#### 5.3.1 获取会员等级列表
- **请求URL**：`/api/v1/user/level/list`
- **请求方法**：GET
- **权限要求**：登录用户
- **返回结果**：会员等级列表数据
#### 5.3.2 获取用户等级信息
- **请求URL**：`/api/v1/user/level/info`
- **请求方法**：GET
- **权限要求**：登录用户
- **返回结果**：当前用户的等级信息
#### 5.3.3 获取积分记录
- **请求URL**：`/api/v1/user/integral/list`
- **请求方法**：GET
- **权限要求**：登录用户
- **请求参数**：
- page：页码
- limit：每页数量
- **返回结果**：当前用户的积分记录
## 5. 开发规范与流程
### 5.1 代码规范
1. **命名规范**：
- 类名采用大驼峰命名法，如 `UserLevelServices`
- 方法名采用小驼峰命名法，如 `checkUpgradeCondition`
- 变量名采用小驼峰命名法，如 `userExperience`
- 常量名采用全大写，下划线分隔，如 `LEVEL_STATUS_ENABLE`
2. **代码结构**：
- 严格遵循分层架构，禁止跨层调用
- 每个方法职责单一，代码行数控制在50行以内
- 适当添加注释，说明方法功能、参数含义和返回值
- 经验值和积分变动必须记录变动原因和相关业务ID
3. **数据一致性**：
- 所有经验值和积分变动都必须通过事务确保数据一致性
- 会员等级变动必须同步更新相关表的数据
- 必须记录完整的变动日志，便于追溯
### 5.2 开发流程
1. **需求分析**：明确会员管理的功能需求和业务逻辑
2. **设计阶段**：设计数据结构、API接口和业务流程
3. **编码实现**：按照分层架构编写代码
4. **单元测试**：编写单元测试，确保功能正确性
5. **集成测试**：进行模块集成测试，测试会员与其他模块的交互
6. **性能测试**：对经验值和积分变动等高频操作进行性能测试
7. **代码审查**：提交代码审查，确保代码质量
8. **部署上线**：部署到生产环境
## 6. 常见问题与解决方案
### 6.1 会员等级升级不及时
**问题**：用户达到升级条件后，等级没有自动升级
**解决方案**：
1. 检查自动检测任务是否正常运行
2. 检查升级条件配置是否正确
3. 检查升级逻辑是否存在bug
4. 考虑添加手动触发升级的功能
### 6.2 积分计算不准确
**问题**：用户积分的计算与预期不符
**解决方案**：
1. 检查积分配置是否正确
2. 检查积分变动记录，找出问题所在
3. 确保所有积分变动都通过统一的接口处理
4. 添加积分对账功能，定期检查积分一致性
### 6.3 会员权益不生效
**问题**：用户享有某等级权益，但实际未生效
**解决方案**：
1. 检查会员等级是否正确
2. 检查权益配置是否正确
3. 检查权益生效逻辑是否存在bug
4. 添加权益生效日志，便于排查问题
### 6.4 大量用户同时升级导致性能问题
**问题**：系统中有大量用户同时达到升级条件，导致系统性能下降
**解决方案**：
1. 优化升级检测算法，减少数据库查询
2. 使用异步处理方式，避免阻塞主流程
3. 考虑分级处理，先处理活跃用户
4. 增加系统资源，提高并发处理能力
## 7. 扩展与定制
### 7.1 添加新的经验值获取渠道
1. **配置经验值**：在系统配置中添加新的经验值获取渠道和数量
2. **修改代码**：
- 在相关业务逻辑中添加经验值增加的调用
- 在UserBillServices中添加对应的经验值记录类型
3. **前端修改**：在前端添加对应的经验值获取入口和说明
### 7.2 添加新的积分使用方式
1. **配置积分**：在系统配置中添加新的积分使用方式和消耗规则
2. **修改代码**：
- 在相关业务逻辑中添加积分扣除的调用
- 在UserBillServices中添加对应的积分记录类型
3. **前端修改**：在前端添加对应的积分使用入口和说明
### 7.3 扩展会员权益
1. **数据库修改**：在system_user_level表中添加新的权益字段
2. **代码修改**：
- 修改会员等级配置和管理功能
- 在相关业务逻辑中添加权益判断和生效代码
3. **前端修改**：在前端添加对应的权益展示和使用入口
## 8. 文档更新记录
| 版本 | 更新日期 | 更新内容 | 更新人 |
|------|----------|----------|--------|
| 1.0 | 2026-01-19 | 初始版本，包含会员等级管理、用户等级管理、经验值管理、积分管理、会员权益管理、会员等级升级机制等核心功能 | AI Assistant |
## 9. 附录
### 9.1 核心类关系图
```
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Models │ │ Daos │ │ Services │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │ │
└───────────────────────┼───────────────────────┘
│
┌─────────────────┐
│ Controllers │
└─────────────────┘
│
┌─────────────────┐
│ Routes │
└─────────────────┘
```
### 9.2 会员等级升级流程图
```
会员等级升级流程：
1. 用户执行获取经验值的行为（签到、下单、邀请等）
2. 系统增加用户经验值，记录经验值变动
3. 检查用户当前经验值是否达到下一级别要求
4. 达到要求，更新用户等级
5. 记录等级变动日志
6. 发送等级升级通知给用户
7. 更新用户享有的权益
```
### 9.3 积分获取与使用流程图
```
积分获取与使用流程：
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ 积分获取 │ │ 积分管理 │ │ 积分使用 │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │ │
▼ ▼ ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ 签到获得积分 │ │ 积分增加 │ │ 抵扣商品金额 │
│ 下单获得积分 │ │ 积分扣除 │ │ 积分商城兑换 │
│ 邀请获得积分 │ │ 积分记录 │ │ 参与活动消耗 │
│ 活动获得积分 │ │ 积分统计 │ └─────────────────┘
└─────────────────┘ └─────────────────┘
```
### 9.4 会员权益列表
| 权益名称 | 描述 |
|----------|------|
| 折扣优惠 | 不同等级享受不同的商品折扣 |
| 等级图标 | 每个等级拥有专属图标和背景图 |
| 经验值加速 | 高级会员获得经验值的速度更快 |
| 专属客服 | 高级会员享受专属客服服务 |
| 优先发货 | 高级会员订单优先发货 |
| 生日福利 | 会员生日获得专属福利 |
| 专属活动 | 高级会员参与专属活动 |
| 积分翻倍 | 高级会员获得积分的倍数更高 |
---
> **提示**：该文档由AI生成，仅供参考。

139
docs/phpapi/分销系统说明文档.md Normal file
View File

@ -0,0 +1,139 @@
## 💳 佣金提现流程
### 提现申请处理
```php
public function handleWithdraw($id, $status, $rejectReason = '')
{
$withdraw = $this->dao->get($id);
if (!$withdraw) {
throw new AdminException('提现记录不存在');
}
if ($withdraw['status'] != 0) {
throw new AdminException('提现已处理');
}
// 更新状态
$updateData = [
'status' => $status,
'handle_time' => time()
];
if ($status == 2) { // 拒绝
$updateData['reject_reason'] = $rejectReason;
$this->dao->update($id, $updateData);
// 返还金额到用户余额
$this->returnAmountToUser($withdraw);
} else { // 通过
$this->dao->update($id, $updateData);
// 实际打款操作
$this->transferToUser($withdraw);
}
// 发送通知
$this->sendWithdrawResultNotify($withdraw['uid'], $status, $rejectReason);
}
```
### 提现打款方式
1. **手动打款**
- 管理员后台手动转账
- 记录转账凭证
2. **自动打款（需配置）**
- 微信企业付款
- 支付宝转账
- 银行卡转账
## 📊 数据统计与分析
### 分销业绩报表
```sql
SELECT
a.uid,
u.nickname,
COUNT(DISTINCT o.order_id) AS order_count,
SUM(o.pay_price) AS order_amount,
SUM(c.commission_amount) AS total_commission,
COUNT(DISTINCT s.uid) AS spread_count
FROM
eb_user_agent a
LEFT JOIN
eb_user u ON a.uid = u.uid
LEFT JOIN
eb_store_order o ON o.uid = a.uid AND o.paid = 1
LEFT JOIN
eb_agent_commission c ON c.uid = a.uid AND c.status = 1
LEFT JOIN
eb_user_spread s ON s.spread_uid = a.uid
GROUP BY
a.uid
ORDER BY
total_commission DESC
```
### 团队业绩查询
```php
public function getTeamPerformance($uid, $startTime, $endTime)
{
// 获取团队用户ID
$teamUids = $this->getTeamUids($uid);
// 查询团队业绩
return $this->dao->getPerformanceByUids(
$teamUids,
$startTime,
$endTime
);
}
```
## 🛠️ 分销系统API
### 核心API列表
| 接口名称 | 请求方式 | 路径 | 描述 |
|---------|---------|------|------|
| 申请成为分销商 | POST | /api/agent/apply | 提交分销申请 |
| 获取分销信息 | GET | /api/agent/info | 获取分销商信息 |
| 获取佣金明细 | GET | /api/agent/commission | 佣金记录查询 |
| 提现申请 | POST | /api/agent/withdraw | 提交提现申请 |
| 获取团队列表 | GET | /api/agent/team | 获取下级分销商 |
## 🔍 常见问题处理
### 1. 分销关系未正确建立
- **检查点**：
- 用户是否满足分销条件
- 分销功能是否开启
- 推广链接参数是否正确传递
### 2. 佣金未计算
- **检查点**：
- 订单是否已完成
- 分销商状态是否正常
- 佣金比例是否配置
### 3. 提现失败
- **检查点**：
- 余额是否充足
- 提现信息是否完整
- 风控规则是否触发
## 📝 版本更新记录
| 版本 | 日期 | 更新内容 |
|------|------|---------|
| v1.0 | 2024-01-17 | 初版文档创建 |
| v1.1 | 2024-01-18 | 增加多级分销配置 |
---
**文档维护**：技术团队
**最后更新**：2024-01-17
💡 **提示**：分销系统涉及资金流转，请定期审核佣金计算和提现记录，确保财务数据准确。
---
> **提示**：该文档由AI生成，仅供参考。

560
docs/phpapi/后端代码目录结构说明.md Normal file
View File

@ -0,0 +1,560 @@
# CRMEB 后端代码目录结构说明
## 项目概述
CRMEB 是一个基于 ThinkPHP 6.x 框架开发的电商系统，采用多应用架构模式，支持管理后台、用户端API、客服系统等多个应用模块。
## 核心架构
### 架构模式
- **框架**: ThinkPHP 6.x
- **架构模式**: 多应用架构 (Multi-App)
- **设计模式**: MVC + Service + DAO 分层架构
- **依赖注入**: 容器管理
- **数据库**: MySQL (支持主从分离)
### 目录结构总览
```
crmeb/
├── app/ # 应用目录
│ ├── adminapi/ # 管理后台API应用
│ ├── api/ # 用户端API应用
│ ├── kefuapi/ # 客服系统API应用
│ ├── outapi/ # 外部API应用
│ ├── dao/ # 数据访问层 (DAO)
│ ├── http/ # HTTP相关类
│ ├── jobs/ # 队列任务
│ ├── lang/ # 多语言包
│ ├── listener/ # 事件监听器
│ ├── model/ # 数据模型层
│ └── services/ # 业务逻辑服务层
├── config/ # 配置文件目录
├── crmeb/ # 核心框架扩展
├── public/ # 公共资源目录
├── route/ # 路由定义
├── runtime/ # 运行时文件
└── vendor/ # 第三方依赖
```
## 详细目录说明
### 1. 应用目录 (app/)
#### 1.1 管理后台API (app/adminapi/)
```
adminapi/
├── config/route.php # 管理后台路由配置
├── controller/ # 控制器层
│ ├── v1/ # API版本1控制器
│ │ ├── agent/ # 代理管理
│ │ ├── application/ # 应用配置
│ │ ├── cms/ # 内容管理
│ │ ├── diy/ # DIY装修
│ │ ├── export/ # 导出功能
│ │ ├── file/ # 文件管理
│ │ ├── finance/ # 财务管理
│ │ ├── freight/ # 物流管理
│ │ ├── kefu/ # 客服管理
│ │ ├── marketing/ # 营销活动
│ │ ├── merchant/ # 商户管理
│ │ ├── notification/ # 通知管理
│ │ ├── order/ # 订单管理
│ │ ├── product/ # 商品管理
│ │ ├── serve/ # 系统服务
│ │ ├── setting/ # 系统设置
│ │ ├── statistic/ # 统计分析
│ │ ├── system/ # 系统管理
│ │ └── user/ # 用户管理
│ ├── AuthController.php # 权限控制器基类
│ ├── Common.php # 通用控制器
│ ├── Login.php # 登录控制器
│ └── PublicController.php # 公共控制器
├── middleware/ # 中间件
│ ├── AdminAuthTokenMiddleware.php # 管理员Token验证
│ ├── AdminCheckRoleMiddleware.php # 权限检查
│ ├── AdminEditorTokenMiddleware.php # 编辑器Token验证
│ └── AdminLogMiddleware.php # 操作日志中间件
├── route/ # 路由定义
│ ├── agent.php # 代理路由
│ ├── app.php # 应用路由
│ ├── cms.php # 内容管理路由
│ ├── common.php # 通用路由
│ ├── crud.php # CRUD路由
│ ├── diy.php # DIY路由
│ ├── export.php # 导出路由
│ ├── file.php # 文件管理路由
│ ├── finance.php # 财务路由
│ ├── freight.php # 物流路由
│ ├── live.php # 直播路由
│ ├── marketing.php # 营销路由
│ ├── merchant.php # 商户路由
│ ├── notify.php # 通知路由
│ ├── order.php # 订单路由
│ ├── product.php # 商品路由
│ ├── serve.php # 服务路由
│ ├── setting.php # 设置路由
│ ├── statistic.php # 统计路由
│ ├── system.php # 系统路由
│ ├── user.php # 用户路由
│ └── widget.php # 组件路由
└── validate/ # 验证器
├── marketing/ # 营销验证器
├── merchant/ # 商户验证器
├── notification/ # 通知验证器
├── order/ # 订单验证器
├── product/ # 商品验证器
├── serve/ # 服务验证器
├── service/ # 服务验证器
├── setting/ # 设置验证器
└── user/ # 用户验证器
```
#### 1.2 用户端API (app/api/)
```
api/
├── config/route.php # 用户端路由配置
├── controller/ # 控制器层
│ ├── pc/ # PC端控制器
│ ├── v1/ # API版本1
│ │ ├── activity/ # 活动相关
│ │ ├── admin/ # 管理相关
│ │ ├── order/ # 订单相关
│ │ ├── publics/ # 公共接口
│ │ ├── store/ # 商店相关
│ │ ├── user/ # 用户相关
│ │ └── wechat/ # 微信相关
│ ├── v2/ # API版本2
│ ├── CrontabController.php # 定时任务控制器
│ ├── LoginController.php # 登录控制器
│ ├── PayController.php # 支付控制器
│ └── PublicController.php # 公共控制器
├── middleware/ # 中间件
│ ├── AuthTokenMiddleware.php # Token验证中间件
│ ├── BlockerMiddleware.php # 访问限制中间件
│ ├── CustomerMiddleware.php # 客户中间件
│ └── StationOpenMiddleware.php # 站点开放中间件
├── route/ # 路由定义
│ ├── pc.php # PC端路由
│ ├── v1.php # API v1路由
│ └── v2.php # API v2路由
└── validate/ # 验证器
└── user/ # 用户验证器
```
#### 1.3 数据访问层 (app/dao/)
```
dao/
├── activity/ # 活动相关DAO
│ ├── advance/ # 预售活动
│ ├── bargain/ # 砍价活动
│ ├── combination/ # 拼团活动
│ ├── integral/ # 积分商城
│ ├── live/ # 直播活动
│ ├── lottery/ # 抽奖活动
│ └── seckill/ # 秒杀活动
├── card/ # 卡券DAO
├── community/ # 社区DAO
├── configure/ # 配置DAO
├── diy/ # DIY DAO
├── export/ # 导出DAO
├── log/ # 日志DAO
├── message/ # 消息DAO
├── ota/ # OTA相关DAO
├── other/ # 其他DAO
├── pay/ # 支付DAO
├── product/ # 商品DAO
│ ├── category/ # 商品分类
│ ├── label/ # 商品标签
│ ├── product/ # 商品主体
│ ├── reply/ # 商品评价
│ ├── rule/ # 规则模板
│ ├── sku/ # 商品规格
│ └── protection/ # 商品保障
├── queue/ # 队列DAO
├── shipping/ # 物流DAO
├── store/ # 商店DAO
├── system/ # 系统DAO
├── user/ # 用户DAO
│ ├── address/ # 用户地址
│ ├── bill/ # 用户账单
│ ├── feedback/ # 用户反馈
│ ├── group/ # 用户分组
│ ├── label/ # 用户标签
│ ├── level/ # 用户等级
│ ├── member/ # 会员卡
│ ├── recharge/ # 充值记录
│ ├── search/ # 搜索记录
│ ├── spread/ # 推广关系
│ └── withdraw/ # 提现记录
└── work/ # 工作相关DAO
```
#### 1.4 服务层 (app/services/)
```
services/
├── activity/ # 活动服务
├── admin/ # 管理服务
├── agent/ # 代理服务
├── app/ # 应用服务
├── clone/ # 克隆服务
├ ├── community/ # 社区服务
├── crud/ # CRUD代码生成服务
├ ├── diy/ # DIY服务
├ ├── export/ # 导出服务
├ ├── file/ # 文件服务
├ ├── goods/ # 商品服务
├ ├── import/ # 导入服务
├ ├── invoice/ # 发票服务
├ ├── ka/ # 客服服务
├ ├── lang/ # 多语言服务
├ ├── live/ # 直播服务
├ ├── message/ # 消息服务
├ ├── ota/ # OTA服务
├ ├── other/ # 其他服务
├ ├── pay/ # 支付服务
├ ├── phonestore/ # 手机商店服务
├ ├── product/ # 商品服务
├ ├── protect/ # 保护服务
├ ├── queue/ # 队列服务
├ ├── scan/ # 扫码服务
├ ├── serve/ # 服务服务
├ ├── setting/ # 设置服务
├ ├── shipping/ # 物流服务
├ ├── stat/ # 统计服务
├ ├── store/ # 商店服务
├ ├── system/ # 系统服务
├ ├── template/ # 模板服务
├ ├── user/ # 用户服务
├ ├── utils/ # 工具服务
└── work/ # 工作服务
```
#### 1.5 模型层 (app/model/)
```
model/
├── activity/ # 活动模型
├── card/ # 卡券模型
├── community/ # 社区模型
├── configure/ # 配置模型
├── diy/ # DIY模型
├── log/ # 日志模型
├── message/ # 消息模型
├── ota/ # OTA模型
├── other/ # 其他模型
├── pay/ # 支付模型
├── product/ # 商品模型
├── queue/ # 队列模型
├── shipping/ # 物流模型
├── store/ # 商店模型
├── system/ # 系统模型
├── user/ # 用户模型
└── work/ # 工作模型
```
### 2. 核心框架扩展 (crmeb/)
#### 2.1 基础类 (crmeb/basic/)
```
basic/
├── BaseController.php # 控制器基类
├── BaseJobs.php # 任务基类
├── BaseManager.php # 管理器基类
├── BaseModel.php # 模型基类
└── BaseStorage.php # 存储基类
```
#### 2.2 命令行 (crmeb/command/)
```
command/
├── Npm.php # NPM命令
├── Timer.php # 定时器命令
├── Util.php # 工具命令
└── Workerman.php # Workerman命令
```
#### 2.3 异常处理 (crmeb/exceptions/)
```
exceptions/
├── AdminException.php # 管理异常
├── ApiException.php # API异常
├── ApiStatusException.php # API状态异常
├── AuthException.php # 认证异常
├── CrudException.php # CRUD异常
├── PayException.php # 支付异常
└── UploadException.php # 上传异常
```
#### 2.4 接口定义 (crmeb/interfaces/)
```
interfaces/
├── JobInterface.php # 任务接口
├── ListenerInterface.php # 监听器接口
├── MiddlewareInterface.php # 中间件接口
└── ProviderInterface.php # 提供者接口
```
#### 2.5 服务层 (crmeb/services/)
```
services/
├── app/ # 应用服务
│ ├── MiniProgramService.php # 小程序服务
│ ├── WechatOpenService.php # 微信开放服务
│ └── WechatService.php # 微信服务
├── copyproduct/ # 商品复制服务
├── crud/ # CRUD代码生成服务
├── easywechat/ # 微信SDK服务
├── express/ # 快递服务
├── invoice/ # 发票服务
├── oauth/ # OAuth认证服务
├── pay/ # 支付服务
├── printer/ # 打印服务
├── serve/ # 系统服务
├── sms/ # 短信服务
├── template/ # 模板消息服务
├── upload/ # 上传服务
├── workerman/ # Workerman服务
└── 核心服务文件...
```
#### 2.6 特性 (crmeb/traits/)
```
traits/
├── JwtAuthModelTrait.php # JWT认证特性
├── ModelTrait.php # 模型特性
└── QueueTrait.php # 队列特性
```
#### 2.7 工具类 (crmeb/utils/)
```
utils/
├── Arr.php # 数组工具
├── Canvas.php # 画布工具
├── Captcha.php # 验证码工具
├── DownloadImage.php # 图片下载工具
├── fileVerification.php # 文件验证工具
├── Hook.php # 钩子工具
├── Json.php # JSON工具
├── JwtAuth.php # JWT认证工具
├── Queue.php # 队列工具
├── Rsa.php # RSA加密工具
├── Str.php # 字符串工具
├── Terminal.php # 终端工具
└── Translate.php # 翻译工具
```
### 3. 配置文件 (config/)
```
config/
├── ajcaptcha.php # 验证码配置
├── app.php # 应用配置
├── cache.php # 缓存配置
├── captcha.php # 图片验证码配置
├── console.php # 控制台配置
├── cookie.php # Cookie配置
├── database.php # 数据库配置
├── filesystem.php # 文件系统配置
├── lang.php # 多语言配置
├── log.php # 日志配置
├── pay.php # 支付配置
├── plat.php # 平台配置
├── printer.php # 打印配置
├── qrcode.php # 二维码配置
├── queue.php # 队列配置
├── route.php # 路由配置
├── session.php # 会话配置
├── sms.php # 短信配置
├── trace.php # 调试跟踪配置
├── upload.php # 上传配置
├── view.php # 视图配置
└── workerman.php # Workerman配置
```
### 4. 公共资源 (public/)
```
public/
├── admin/ # 管理后台前端
├── assets/ # 静态资源
├── install/ # 安装程序
├── pages/ # 页面文件
├── static/ # 静态文件
├── statics/ # 系统静态文件
├── upgrade/ # 升级程序
├── .htaccess # Apache重写规则
├── favicon.ico # 网站图标
├── index.html # 默认首页
└── 入口文件...
```
### 5. 路由定义 (route/)
```
route/
├── README.md # 路由说明
└── route.php # 主路由文件
```
## 架构设计模式
### 1. 分层架构
- **Controller层**: 处理HTTP请求，参数验证，调用Service
- **Service层**: 业务逻辑处理，事务管理，调用DAO
- **DAO层**: 数据访问，SQL操作，模型映射
- **Model层**: 数据模型定义，关联关系
### 2. 依赖注入
- 使用ThinkPHP容器管理对象依赖
- 通过构造函数注入Service依赖
- 支持接口编程和面向切面编程
### 3. 中间件机制
- 认证授权中间件
- 权限检查中间件
- 操作日志中间件
- 参数过滤中间件
### 4. 事件监听
- 订单状态变更事件
- 用户注册事件
- 支付完成事件
- 商品库存变更事件
## 核心功能模块
### 1. 商品管理
- 商品分类、规格、属性管理
- 库存管理、价格策略
- 商品审核、上下架管理
- 商品导入导出功能
### 2. 订单管理
- 订单创建、支付、发货流程
- 订单状态管理和追踪
- 退款、售后处理
- 订单统计分析
### 3. 用户管理
- 用户注册、登录、认证
- 用户等级、会员体系
- 用户标签、分组管理
- 用户行为分析
### 4. 营销活动
- 优惠券、满减活动
- 拼团、砍价、秒杀
- 积分商城、签到奖励
- 推广分销系统
### 5. 支付系统
- 微信支付、支付宝支付
- 余额支付、积分支付
- 支付回调处理
- 退款对账功能
### 6. 物流配送
- 快递公司对接
- 运费模板管理
- 物流信息查询
- 配送状态跟踪
## 技术特性
### 1. 多应用架构
- 管理后台、用户端、客服系统独立部署
- 统一的认证授权机制
- 模块化设计便于扩展
### 2. 微服务支持
- 队列任务异步处理
- 缓存服务集成
- 分布式文件存储
- 多数据库支持
### 3. 安全机制
- JWT Token认证
- 接口签名验证
- SQL注入防护
- XSS攻击防护
### 4. 性能优化
- 数据库读写分离
- 缓存策略优化
- 静态资源CDN
- 接口响应压缩
## 开发规范
### 1. 命名规范
- 类名: PascalCase (如 StoreProductServices)
- 方法名: camelCase (如 getProductList)
- 变量名: camelCase (如 productId)
- 常量名: UPPER_CASE (如 API_VERSION)
### 2. 文件组织
- Controller按业务模块分组
- Service按功能领域划分
- DAO按数据实体组织
- Model对应数据库表结构
### 3. 注释规范
- 类和方法的PHPDoc注释
- 复杂业务逻辑说明
- API接口文档注释
- 数据库字段说明
### 4. 错误处理
- 统一异常处理机制
- 自定义业务异常类
- 错误日志记录
- 用户友好错误提示
## 部署要求
### 1. 环境要求
- PHP >= 7.4
- MySQL >= 5.7
- Redis >= 4.0
- Nginx/Apache
### 2. 扩展要求
- PDO MySQL
- GD2/ImageMagick
- Curl
- OpenSSL
- Fileinfo
### 3. 权限设置
- runtime目录可写
- public/uploads可写
- 日志目录可写
- 缓存目录可写
## 维护建议
### 1. 代码维护
- 定期代码审查
- 单元测试覆盖
- 性能监控分析
- 安全漏洞扫描
### 2. 数据库维护
- 定期数据备份
- 索引优化调整
- 慢查询分析
- 数据清理归档
### 3. 系统监控
- 服务器资源监控
- 应用性能监控
- 错误日志监控
- 用户行为分析
---
本文档详细说明了CRMEB后端代码的目录结构、架构设计和开发规范，为开发团队提供完整的技术指导和参考。
---
> **提示**：该文档由AI生成，仅供参考。

398
docs/phpapi/后端系统事件文档说明.md Normal file
View File

@ -0,0 +1,398 @@
# CRMEB 后端系统事件文档说明
## 1. 事件机制概述
CRMEB后端系统采用事件驱动架构，通过事件机制实现模块间的解耦和通信。事件系统允许在不直接依赖的情况下，实现不同模块间的交互和业务逻辑扩展。
### 1.1 核心概念
- **事件(Event)**：系统中发生的特定动作或状态变化，如订单创建、用户注册等。
- **监听器(Listener)**：监听特定事件并执行相应处理逻辑的类。
- **事件触发(Trigger)**：在特定业务逻辑点调用事件，通知相关监听器执行。
## 2. 监听器接口定义
所有监听器必须实现 `crmeb\interfaces\ListenerInterface` 接口，该接口定义了统一的事件处理方法。
```php
<?php
namespace crmeb\interfaces;
interface ListenerInterface
{
public function handle($event): void;
}
```
### 2.1 接口说明
- **handle方法**：事件处理的核心方法，接收一个`$event`参数，包含事件触发时传递的数据。
- 返回类型：`void`，监听器处理完成后无需返回值。
## 3. 事件定义与注册
事件通过 `app/event.php` 文件进行定义和注册，该文件返回一个包含事件配置的数组。
### 3.1 事件配置结构
```php
return [
'bind' => [], // 事件绑定
'listen' => [ // 事件监听
'EventName' => [
'Listener1::class',
'Listener2::class',
],
],
];
```
### 3.2 事件注册示例
```php
return [
'listen' => [
'OrderCreateAfterListener' => [\app\listener\order\OrderCreateAfterListener::class], // 订单创建后置事件
'UserRegisterListener' => [\app\listener\user\RegisterListener::class], // 用户注册后置事件
// 更多事件...
],
];
```
## 4. 系统内置事件列表
### 4.1 基础事件
| 事件名称 | 触发时机 | 监听器类 | 说明 |
|---------|---------|---------|------|
| AppInit | 应用初始化 | - | 应用启动时触发 |
| HttpRun | HTTP请求运行 | - | HTTP请求处理开始时触发 |
| HttpEnd | HTTP请求结束 | \app\listener\http\HttpEndListener::class | HTTP请求处理结束时触发 |
| LogLevel | 日志级别 | - | 日志记录级别设置时触发 |
| LogWrite | 日志写入 | - | 日志写入时触发 |
| QueueStartListener | 队列启动 | \app\listener\queue\QueueStartListener::class | 队列启动时触发 |
### 4.2 用户相关事件
| 事件名称 | 触发时机 | 监听器类 | 说明 |
|---------|---------|---------|------|
| UserLoginListener | 用户登录 | \app\listener\user\LoginListener::class | 用户登录成功后触发 |
| AdminLoginListener | 管理员登录 | \app\listener\admin\AdminLoginListener::class | 管理员登录成功后触发 |
| UserRegisterListener | 用户注册 | \app\listener\user\RegisterListener::class | 用户注册成功后触发 |
| WechatAuthListener | 微信授权 | \app\listener\wechat\AuthListener::class | 用户微信授权成功后触发 |
| UserLevelListener | 用户升级 | \app\listener\user\UserLevelListener::class | 用户等级提升时触发 |
| UserVisitListener | 用户访问 | \app\listener\user\UserVisitListener::class | 用户访问页面时触发 |
### 4.3 订单相关事件
| 事件名称 | 触发时机 | 监听器类 | 说明 |
|---------|---------|---------|------|
| OrderCreateAfterListener | 订单创建 | \app\listener\order\OrderCreateAfterListener::class | 订单创建完成后触发 |
| OrderPaySuccessListener | 订单支付成功 | \app\listener\order\OrderPaySuccessListener::class | 订单支付成功后触发 |
| OrderDeliveryListener | 订单发货 | \app\listener\order\OrderDeliveryListener::class | 订单发货后触发 |
| OrderTakeListener | 订单收货 | \app\listener\order\OrderTakeListener::class | 订单确认收货后触发 |
| OrderRefundCreateAfterListener | 售后单生成 | \app\listener\order\OrderRefundCreateAfterListener::class | 售后单创建完成后触发 |
| OrderRefundCancelAfterListener | 售后单取消 | \app\listener\order\OrderRefundCancelAfterListener::class | 售后单取消后触发 |
| OrderShippingListener | 小程序发货管理 | \app\listener\order\OrderShippingListener::class | 小程序发货时触发 |
### 4.4 其他事件
| 事件名称 | 触发时机 | 监听器类 | 说明 |
|---------|---------|---------|------|
| OutPushListener | 对外推送 | \app\listener\out\OutPushListener::class | 对外数据推送时触发 |
| NoticeListener | 通知消息 | \app\listener\notice\NoticeListener::class | 系统通知消息发送时触发 |
| CustomNoticeListener | 自定义通知 | \app\listener\notice\CustomNoticeListener::class | 自定义消息发送时触发 |
| NotifyListener | 支付异步回调 | \app\listener\pay\NotifyListener::class | 支付异步回调处理时触发 |
| CustomEventListener | 自定义事件 | \app\listener\CustomEventListener::class | 自定义业务事件触发时触发 |
## 5. 事件触发方式
事件通过 `event()` 函数进行触发，该函数是ThinkPHP框架提供的全局函数。
### 5.1 基本触发方式
```php
// 触发事件
event('EventName', $eventData);
// 示例：触发订单创建事件
event('OrderCreateAfterListener', [$order, $group, $uid, $key]);
```
### 5.2 事件数据传递
事件触发时，可以传递任意类型的数据，监听器通过 `$event` 参数接收。数据通常以数组形式传递，包含处理业务逻辑所需的所有信息。
## 6. 自定义事件
除了系统内置事件外，CRMEB还支持自定义事件，通过 `CustomEventListener` 实现灵活的业务扩展。
### 6.1 自定义事件触发
```php
// 触发自定义事件
event('CustomEventListener', ['event_mark', ['data1' => 'value1', 'data2' => 'value2']]);
```
### 6.2 自定义事件处理
自定义事件由 `app\listener\CustomEventListener` 处理，该监听器从数据库中获取配置的自定义代码并执行。
```php
<?php
namespace app\listener;
use app\services\system\SystemEventServices;
use think\facade\Log;
class CustomEventListener
{
public function handle($event)
{
[$mark, $data] = $event;
try {
$list = app()->make(SystemEventServices::class)->selectList(['mark' => $mark, 'is_del' => 0, 'is_open' => 1])->toArray();
foreach ($list as $item) {
eval(json_decode($item['customCode']));
}
} catch (\Throwable $e) {
$listener_log_open = config("log.listener_log", false);
if ($listener_log_open) {
$date = date('Y-m-d H:i:s', time());
Log::write($date . '自定义事件错误:' . $e->getMessage(), 'listener');
}
}
}
}
```
## 7. 事件处理流程
1. **事件触发**：在业务逻辑中通过 `event()` 函数触发特定事件。
2. **事件分发**：系统根据事件名称查找对应的监听器列表。
3. **监听器执行**：依次调用每个监听器的 `handle()` 方法，并传递事件数据。
4. **业务处理**：监听器执行各自的业务逻辑，如数据处理、消息发送等。
5. **处理完成**：所有监听器执行完成后，事件处理流程结束。
## 8. 监听器实现示例
### 8.1 订单创建事件监听器
```php
<?php
namespace app\listener\order;
use app\jobs\notice\PrintJob;
use app\jobs\OrderCreateAfterJob;
use app\jobs\OrderJob;
use app\jobs\ProductLogJob;
use app\jobs\UnpaidOrderCancelJob;
use app\jobs\UnpaidOrderSend;
use app\services\order\StoreOrderCreateServices;
use app\services\order\StoreOrderStatusServices;
use crmeb\interfaces\ListenerInterface;
use crmeb\services\CacheService;
use crmeb\services\SystemConfigService;
use crmeb\utils\Arr;
/**
* 订单创建后置事件
* Class OrderCreateAfterListener
* @package app\listener\order
*/
class OrderCreateAfterListener implements ListenerInterface
{
public function handle($event): void
{
[$order, $group, $uid, $key, $combinationId, $seckillId, $bargainId] = $event;
// 订单数据创建之后的商品实际金额计算，佣金计算，优惠折扣计算，设置默认地址，清理购物车
/** @var StoreOrderCreateServices $orderCreate */
$orderCreate = app()->make(StoreOrderCreateServices::class);
$orderCreate->orderCreateAfter($order, $group, $combinationId || $seckillId || $bargainId);
// 清除订单缓存
CacheService::delete('user_order_' . $uid . $key);
// 写入订单记录表
/** @var StoreOrderStatusServices $statusService */
$statusService = app()->make(StoreOrderStatusServices::class);
$statusService->save([
'oid' => $order['id'],
'change_type' => 'cache_key_create_order',
'change_message' => '订单生成',
'change_time' => time()
]);
// 订单自动取消
$this->pushJob($order['id'], $combinationId, $seckillId, $bargainId);
// 下单记录
ProductLogJob::dispatch(['order', ['uid' => $uid, 'order_id' => $order['id']]]);
// 小票打印
PrintJob::dispatch([$order['id'], 2]);
}
/**
* 订单自动取消加入延迟消息队列
* @param int $orderId
* @param int $combinationId
* @param int $seckillId
* @param int $bargainId
* @return mixed
*/
public function pushJob(int $orderId, int $combinationId, int $seckillId, int $bargainId)
{
// 系统预设取消订单时间段
$keyValue = ['order_cancel_time', 'order_activity_time', 'order_bargain_time', 'order_seckill_time', 'order_pink_time'];
// 获取配置
$systemValue = SystemConfigService::more($keyValue);
// 格式化数据
$systemValue = Arr::setValeTime($keyValue, is_array($systemValue) ? $systemValue : []);
if ($combinationId) {
$secs = $systemValue['order_pink_time'] ?: $systemValue['order_activity_time'];
} elseif ($seckillId) {
$secs = $systemValue['order_seckill_time'] ?: $systemValue['order_activity_time'];
} elseif ($bargainId) {
$secs = $systemValue['order_bargain_time'] ?: $systemValue['order_activity_time'];
} else {
$secs = $systemValue['order_cancel_time'];
}
// 未支付10分钟后发送短信
UnpaidOrderSend::dispatchSecs(600, [$orderId]);
// 未支付根据系统设置事件取消订单
UnpaidOrderCancelJob::dispatchSecs((int)($secs * 3600), [$orderId]);
}
}
```
### 8.2 用户注册事件监听器
```php
<?php
namespace app\listener\user;
use app\jobs\AgentJob;
use app\services\activity\coupon\StoreCouponIssueServices;
use app\services\user\UserBillServices;
use app\services\user\UserServices;
use app\services\user\UserSpreadServices;
use crmeb\interfaces\ListenerInterface;
/**
* 注册完成后置事件
* Class RegisterListener
* @package app\listener\user
*/
class RegisterListener implements ListenerInterface
{
/**
* 注册完成后置事件
* @param $event
* @throws \think\db\exception\DataNotFoundException
* @throws \think\db\exception\DbException
* @throws \think\db\exception\ModelNotFoundException
*/
public function handle($event): void
{
[$spreadUid, $userType, $name, $uid, $isNew] = $event;
if ($spreadUid) {
if ($isNew) {
// 邀请新用户增加经验
/** @var UserBillServices $userBill */
$userBill = app()->make(UserBillServices::class);
$userBill->inviteUserIncExp((int)$spreadUid);
// 增加推广佣金
/** @var UserServices $userServices */
$userServices = app()->make(UserServices::class);
$userServices->addBrokeragePrice($uid, $spreadUid);
// 推广新人 处理自己、上级分销等级升级
AgentJob::dispatch([$uid]);
}
// 记录推广绑定关系
/** @var UserSpreadServices $userSpreadServices */
$userSpreadServices = app()->make(UserSpreadServices::class);
$res = $userSpreadServices->setSpread($uid, $spreadUid);
// 自定义消息-下级用户绑定成功
if ($res) {
$phone = app()->make(UserServices::class)->value($spreadUid, 'phone');
event('CustomNoticeListener', [$spreadUid, ['nickname' => $name, 'time' => date('Y-m-d H:i:s'), 'phone' => $phone], 'spread_success']);
}
}
if ($isNew) {
// 新人优惠券发送
/**@var StoreCouponIssueServices $storeCoupon */
$storeCoupon = app()->make(StoreCouponIssueServices::class);
$storeCoupon->userFirstSubGiveCoupon((int)$uid);
// 人人分销开启推广权限
if (sys_config('brokerage_func_status') && sys_config('store_brokerage_statu') == 2) {
/** @var UserServices $userServices */
$userServices = app()->make(UserServices::class);
$userServices->update($uid, ['is_promoter' => 1]);
}
}
}
}
```
## 9. 最佳实践
### 9.1 事件命名规范
- 事件名称应清晰表达事件的含义和触发时机，如 `OrderCreateAfterListener` 表示订单创建后的事件。
- 使用驼峰命名法，首字母大写。
### 9.2 监听器设计原则
- **单一职责**：每个监听器应只负责处理一个特定的业务逻辑。
- **无副作用**：监听器处理不应修改原始事件数据，避免影响其他监听器。
- **异常处理**：在监听器中适当捕获异常，避免单个监听器失败影响整个事件处理流程。
### 9.3 性能优化
- **异步处理**：对于耗时的操作，建议使用队列进行异步处理，如发送短信、生成报表等。
- **缓存使用**：合理使用缓存减少数据库查询，提高处理效率。
- **避免循环依赖**：监听器之间不应相互依赖，避免形成循环调用。
## 10. 常见问题与解决方案
### 10.1 事件不触发
**问题**：调用 `event()` 函数后，监听器未执行。
**解决方案**：
- 检查事件名称是否与 `event.php` 中注册的名称一致。
- 检查监听器类是否正确实现了 `ListenerInterface` 接口。
- 检查监听器类是否正确注册到对应的事件中。
### 10.2 监听器执行顺序
**问题**：需要控制监听器的执行顺序。
**解决方案**：
- 在 `event.php` 中，监听器的注册顺序决定了执行顺序。
- 如需更复杂的控制，可以在监听器中手动触发其他事件。
### 10.3 事件数据传递
**问题**：监听器无法获取完整的事件数据。
**解决方案**：
- 确保事件触发时传递了所有必要的数据。
- 使用数组形式传递数据，便于扩展和维护。
- 在监听器中对数据进行适当的验证和转换。
## 11. 总结
CRMEB的事件系统提供了一种灵活、解耦的模块间通信机制，通过事件和监听器的配合，实现了业务逻辑的分离和扩展。合理使用事件系统可以提高代码的可维护性和可扩展性，同时降低模块间的耦合度。
在开发过程中，应遵循事件命名规范、监听器设计原则和性能优化建议，确保事件系统的高效运行。
---
> **提示**：该文档由AI生成，仅供参考。

480
docs/phpapi/商品管理开发文档.md Normal file
View File

@ -0,0 +1,480 @@
# 商品管理开发文档
## 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 代码规范
1. **命名规范**：
- 类名采用大驼峰命名法
- 方法名采用小驼峰命名法
- 变量名采用小驼峰命名法
- 常量名采用全大写，下划线分隔
2. **代码结构**：
- 严格遵循分层架构，禁止跨层调用
- 每个方法职责单一，代码行数控制在50行以内
- 适当添加注释，说明方法功能、参数含义和返回值
3. **数据库操作**：
- 所有数据库操作必须通过Dao层进行
- 使用ORM提供的查询构建器，避免直接编写SQL
- 批量操作使用事务处理
### 6.2 开发流程
1. **需求分析**：明确功能需求和业务逻辑
2. **设计阶段**：设计数据结构、API接口和业务流程
3. **编码实现**：按照分层架构编写代码
4. **单元测试**：编写单元测试，确保功能正确性
5. **集成测试**：进行模块集成测试
6. **代码审查**：提交代码审查，确保代码质量
7. **部署上线**：部署到生产环境
## 7. 常见问题与解决方案
### 7.1 SKU生成问题
**问题**：商品规格属性过多时，SKU生成数量过大，导致页面卡顿
**解决方案**：
1. 限制单个商品的属性数量和每个属性的取值数量
2. 使用异步加载方式生成SKU
3. 优化SKU生成算法，提高生成效率
### 7.2 商品库存管理
**问题**：高并发场景下，商品库存出现超卖问题
**解决方案**：
1. 使用数据库事务和乐观锁机制
2. 实现库存预扣和释放机制
3. 考虑使用Redis等缓存技术，提高库存操作效率
### 7.3 商品数据同步
**问题**：商品数据在多个终端间同步不及时
**解决方案**：
1. 使用消息队列实现数据同步
2. 实现数据缓存机制，减少数据库查询压力
3. 采用事件驱动架构，确保数据变更及时通知
### 7.4 商品搜索性能
**问题**：商品数量过多时，搜索速度变慢
**解决方案**：
1. 优化数据库索引设计
2. 考虑使用搜索引擎，如Elasticsearch
3. 实现搜索结果缓存
## 8. 扩展与定制
### 8.1 功能扩展
系统设计具有良好的扩展性，可通过以下方式扩展功能：
1. **添加新模型**：继承BaseModel，定义新的数据结构
2. **添加新服务**：继承BaseServices，实现新的业务逻辑
3. **添加新控制器**：继承BaseController，处理新的API请求
4. **添加新路由**：在路由文件中定义新的路由规则
### 8.2 事件扩展
系统在关键业务节点触发事件，可通过监听事件进行功能扩展：
1. **商品添加事件**：ProductAddEvent
2. **商品编辑事件**：ProductUpdateEvent
3. **商品删除事件**：ProductDeleteEvent
4. **商品上下架事件**：ProductStatusEvent
5. **商品库存变动事件**：ProductStockChangeEvent
### 8.3 钩子扩展
系统提供了多个钩子点，可通过钩子函数进行功能扩展：
1. **商品添加前钩子**：product_add_before
2. **商品添加后钩子**：product_add_after
3. **商品编辑前钩子**：product_edit_before
4. **商品编辑后钩子**：product_edit_after
5. **商品删除前钩子**：product_delete_before
6. **商品删除后钩子**：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生成，仅供参考。

455
docs/phpapi/客服系统开发文档.md Normal file
View File

@ -0,0 +1,455 @@
# 客服系统开发文档
## 1. 文档概述
### 1.1 文档目的
本文档旨在详细说明CRMEB系统中客服系统模块的设计架构、核心功能、代码实现及开发规范，为系统开发人员提供完整的开发参考。
### 1.2 适用范围
本文档适用于CRMEB系统开发人员、维护人员及二次开发人员，用于指导客服系统模块的开发、扩展和维护工作。
### 1.3 术语定义
| 术语 | 解释 |
|------|------|
| 客服系统 | 用于商家与用户进行实时沟通的系统 |
| WebSocket | 一种在单个TCP连接上进行全双工通信的协议 |
| 会话转接 | 将当前聊天会话转交给其他客服处理 |
| 客服话术 | 客服常用的回复模板 |
| 全局话术 | 所有客服均可使用的话术 |
| 个人话术 | 仅当前客服可使用的话术 |
| 游客模式 | 未登录用户发起聊天的模式 |
## 2. 核心功能模块
### 2.1 客服账号管理
- **客服登录**：支持账号密码登录和微信扫码登录
- **权限控制**：不同角色客服拥有不同权限
- **在线状态管理**：显示客服在线/离线状态
- **客服资料管理**：修改客服基本信息
### 2.2 客服聊天功能
- **实时通信**：基于WebSocket的实时聊天
- **消息类型**：支持文本、图片等多种消息类型
- **聊天记录**：聊天记录持久化存储，支持历史记录查询
- **用户识别**：支持游客和注册用户两种聊天模式
- **消息提醒**：新消息实时提醒
- **消息已读状态**：显示消息已读/未读状态
### 2.3 用户管理
- **用户信息**：查看用户详细信息
- **用户标签**：为用户添加/移除标签
- **用户分组**：将用户分配到不同分组
- **聊天历史**：查看用户历史聊天记录
- **行为记录**：查看用户浏览、购买等行为记录
### 2.4 订单处理
- **订单列表**：查看用户订单列表
- **订单发货**：处理订单发货
- **订单退款**：处理订单退款申请
- **订单改价**：修改订单价格
- **订单备注**：添加订单备注
### 2.5 商品相关
- **商品详情**：查看商品详细信息
- **购买记录**：查看用户购买记录
- **浏览记录**：查看用户浏览记录
- **热销商品**：查看热销商品列表
### 2.6 客服话术管理
- **话术分类**：管理话术分类
- **话术添加**：添加新的话术
- **话术编辑**：修改已有话术
- **话术删除**：删除无用话术
- **全局话术**：所有客服均可使用的话术
- **个人话术**：仅当前客服可使用的话术
### 2.7 客服转接
- **会话转接**：支持客服之间的会话转接
- **转接历史**：查看会话转接历史
- **实时通知**：转接时实时通知相关客服
- **聊天记录保留**：转接时保留完整聊天记录
## 3. 代码结构与设计
### 3.1 架构设计
客服系统采用前后端分离架构，后端使用ThinkPHP框架，前端使用Vue.js，基于WebSocket实现实时通信：
```
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ 前端应用 │────▶│ WebSocket服务器 │────▶│ 后端API服务 │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│
▼
┌─────────────────┐
│ 数据库 │
└─────────────────┘
```
### 3.2 核心文件结构
#### 3.2.1 后端目录
**客服API**：`/crmeb/app/kefuapi/`
- `controller/` - 客服API控制器
- `middleware/` - 客服API中间件
- `route/` - 客服API路由
- `validate/` - 客服API验证器
#### 3.2.2 模型层
**服务模型**：`/crmeb/app/model/service/`
- `StoreService.php` - 客服信息模型
- `StoreServiceRecord.php` - 客服聊天用户记录模型
- `StoreServiceLog.php` - 客服聊天记录模型
- `StoreServiceSpeechcraft.php` - 客服话术模型
#### 3.2.3 服务层
**客服服务**：`/crmeb/app/services/kefu/`
- `KefuLoginServices.php` - 客服登录服务
- `KefuUserServices.php` - 客服用户服务
- `KefuServiceServices.php` - 客服服务管理
- `KefuSpeechcraftServices.php` - 客服话术服务
#### 3.2.4 前端目录
**客服前端API**：`/template/admin/src/api/kefu.js`
- 包含客服系统前端调用的所有API接口
#### 3.2.5 WebSocket服务
**WebSocket实现**：基于Workerman框架实现
- 提供实时聊天功能
- 处理消息推送和接收
## 4. 数据库设计
### 4.1 客服信息表（store_service）
| 字段名 | 数据类型 | 描述 |
|--------|----------|------|
| id | int(10) unsigned | 客服ID |
| uid | int(10) | 关联用户ID |
| nick_name | varchar(20) | 客服昵称 |
| avatar | varchar(255) | 客服头像 |
| phone | varchar(20) | 客服手机号 |
| password | varchar(60) | 客服密码 |
| salt | varchar(10) | 密码盐 |
| status | tinyint(1) | 状态（0-禁用，1-启用） |
| is_online | tinyint(1) | 在线状态（0-离线，1-在线） |
| add_time | int(10) | 添加时间 |
### 4.2 客服聊天用户记录表（store_service_record）
| 字段名 | 数据类型 | 描述 |
|--------|----------|------|
| id | int(10) unsigned | 记录ID |
| uid | int(10) | 用户ID |
| service_id | int(10) | 客服ID |
| last_msg | varchar(255) | 最后一条消息内容 |
| last_time | int(10) | 最后消息时间 |
| is_visitor | tinyint(1) | 是否游客（0-否，1-是） |
| visitor_id | varchar(50) | 游客ID |
| status | tinyint(1) | 状态（0-结束，1-进行中） |
| add_time | int(10) | 添加时间 |
### 4.3 客服聊天记录表（store_service_log）
| 字段名 | 数据类型 | 描述 |
|--------|----------|------|
| id | int(10) unsigned | 记录ID |
| from_id | int(10) | 发送者ID |
| to_id | int(10) | 接收者ID |
| service_id | int(10) | 客服ID |
| message | text | 消息内容 |
| type | tinyint(1) | 消息类型（0-文本，1-图片） |
| is_read | tinyint(1) | 是否已读（0-未读，1-已读） |
| is_visitor | tinyint(1) | 是否游客（0-否，1-是） |
| visitor_id | varchar(50) | 游客ID |
| add_time | int(10) | 添加时间 |
### 4.4 客服话术表（store_service_speechcraft）
| 字段名 | 数据类型 | 描述 |
|--------|----------|------|
| id | int(10) unsigned | 话术ID |
| uid | int(10) | 客服ID（0-全局话术） |
| cate_id | int(10) | 分类ID |
| title | varchar(100) | 话术标题 |
| content | text | 话术内容 |
| sort | int(10) | 排序 |
| status | tinyint(1) | 状态（0-禁用，1-启用） |
| add_time | int(10) | 添加时间 |
## 5. API接口说明
### 5.1 客服登录相关
#### 5.1.1 客服登录
- **请求URL**：`/kefuapi/login`
- **请求方法**：POST
- **请求参数**：
- username：用户名
- password：密码
- **返回结果**：登录状态、token等
#### 5.1.2 微信扫码登录
- **请求URL**：`/kefuapi/key`
- **请求方法**：GET
- **返回结果**：扫码登录key
#### 5.1.3 检测扫码情况
- **请求URL**：`/kefuapi/scan/:key`
- **请求方法**：GET
- **返回结果**：扫码状态
### 5.2 聊天相关
#### 5.2.1 获取聊天用户列表
- **请求URL**：`/kefuapi/user/record`
- **请求方法**：GET
- **请求参数**：
- page：页码
- limit：每页数量
- status：状态
- **返回结果**：聊天用户列表
#### 5.2.2 获取聊天记录
- **请求URL**：`/kefuapi/service/list`
- **请求方法**：GET
- **请求参数**：
- uid：用户ID
- visitor_id：游客ID
- page：页码
- limit：每页数量
- **返回结果**：聊天记录列表
#### 5.2.3 客服转接
- **请求URL**：`/kefuapi/service/transfer`
- **请求方法**：POST
- **请求参数**：
- uid：用户ID
- visitor_id：游客ID
- to_service_id：转接目标客服ID
- **返回结果**：转接结果
### 5.3 用户管理相关
#### 5.3.1 获取用户详细信息
- **请求URL**：`/kefuapi/user/info/:uid`
- **请求方法**：GET
- **返回结果**：用户详细信息
#### 5.3.2 获取用户标签
- **请求URL**：`/kefuapi/user/label/:uid`
- **请求方法**：GET
- **返回结果**：用户标签列表
#### 5.3.3 设置用户标签
- **请求URL**：`/kefuapi/user/label/:uid`
- **请求方法**：PUT
- **请求参数**：
- label_ids：标签ID数组
- **返回结果**：操作结果
### 5.4 订单处理相关
#### 5.4.1 获取用户订单列表
- **请求URL**：`/kefuapi/order/list/:uid`
- **请求方法**：GET
- **请求参数**：
- page：页码
- limit：每页数量
- status：订单状态
- **返回结果**：用户订单列表
#### 5.4.2 订单发货
- **请求URL**：`/kefuapi/order/delivery/:id`
- **请求方法**：POST
- **请求参数**：
- express_id：快递公司ID
- express_no：快递单号
- **返回结果**：操作结果
#### 5.4.3 订单退款
- **请求URL**：`/kefuapi/order/refund`
- **请求方法**：POST
- **请求参数**：
- order_id：订单ID
- refund_money：退款金额
- refund_reason：退款原因
- **返回结果**：操作结果
### 5.5 话术管理相关
#### 5.5.1 获取话术列表
- **请求URL**：`/kefuapi/service/speechcraft`
- **请求方法**：GET
- **请求参数**：
- cate_id：分类ID
- type：类型（0-全局，1-个人）
- **返回结果**：话术列表
#### 5.5.2 添加话术
- **请求URL**：`/kefuapi/service/speechcraft`
- **请求方法**：POST
- **请求参数**：
- cate_id：分类ID
- title：话术标题
- content：话术内容
- type：类型（0-全局，1-个人）
- **返回结果**：操作结果
## 5. 开发规范与流程
### 5.1 代码规范
1. **命名规范**：
- 类名采用大驼峰命名法，如 `KefuLoginServices`
- 方法名采用小驼峰命名法，如 `getUserList`
- 变量名采用小驼峰命名法，如 `chatMessage`
- 常量名采用全大写，下划线分隔，如 `KEFU_STATUS_ONLINE`
2. **代码结构**：
- 严格遵循分层架构，禁止跨层调用
- 每个方法职责单一，代码行数控制在50行以内
- 适当添加注释，说明方法功能、参数含义和返回值
- 所有聊天消息必须记录日志，便于追溯
3. **WebSocket规范**：
- WebSocket连接必须进行身份验证
- 消息格式必须统一，便于前后端解析
- 必须处理连接断开、重连等异常情况
- 消息发送必须实现重试机制
### 5.2 开发流程
1. **需求分析**：明确客服系统的功能需求和业务逻辑
2. **设计阶段**：设计数据结构、API接口和业务流程
3. **编码实现**：
- 实现后端API接口
- 实现WebSocket服务
- 实现前端页面和交互
4. **单元测试**：编写单元测试，确保功能正确性
5. **集成测试**：进行模块集成测试，测试客服系统与其他模块的交互
6. **性能测试**：对WebSocket连接、消息推送等进行性能测试
7. **安全性测试**：测试登录认证、权限控制等安全性功能
8. **代码审查**：提交代码审查，确保代码质量
9. **部署上线**：部署到生产环境
## 6. 常见问题与解决方案
### 6.1 WebSocket连接问题
**问题**：WebSocket连接失败或频繁断开
**解决方案**：
1. 检查WebSocket服务器是否正常运行
2. 检查防火墙设置，确保WebSocket端口开放
3. 实现连接心跳机制，保持长连接
4. 实现自动重连机制，处理连接断开情况
### 6.2 消息推送延迟
**问题**：消息推送延迟严重
**解决方案**：
1. 优化WebSocket服务器性能，增加并发处理能力
2. 使用消息队列处理消息推送，避免阻塞
3. 优化网络环境，减少网络延迟
4. 实现消息优先级，确保重要消息优先推送
### 6.3 聊天记录丢失
**问题**：聊天记录丢失或不完整
**解决方案**：
1. 确保聊天记录及时持久化存储
2. 使用事务处理，确保数据一致性
3. 实现聊天记录备份机制
4. 定期检查聊天记录完整性
### 6.4 客服转接问题
**问题**：客服转接失败或聊天记录丢失
**解决方案**：
1. 确保转接逻辑正确，保留完整聊天记录
2. 实现转接状态通知，确保相关客服收到通知
3. 测试各种转接场景，确保转接功能稳定
## 7. 扩展与定制
### 7.1 添加新的消息类型
1. **数据库修改**：在store_service_log表中添加新的消息类型枚举
2. **后端修改**：
- 在消息处理逻辑中添加新消息类型的处理
- 更新API接口，支持新消息类型
3. **前端修改**：
- 添加新消息类型的渲染组件
- 更新消息发送组件，支持新消息类型
### 7.2 扩展客服权限
1. **数据库修改**：在store_service表中添加权限字段
2. **后端修改**：
- 在权限验证中间件中添加新权限的验证
- 更新API接口的权限控制
3. **前端修改**：
- 根据权限动态显示菜单和功能按钮
- 添加权限管理页面
### 7.3 集成第三方客服系统
1. **设计适配层**：设计与第三方客服系统的适配层
2. **实现API对接**：实现与第三方客服系统的API对接
3. **数据同步**：实现客服数据、聊天记录等数据的同步
4. **前端集成**：在前端页面中集成第三方客服系统的功能
## 8. 文档更新记录
| 版本 | 更新日期 | 更新内容 | 更新人 |
|------|----------|----------|--------|
| 1.0 | 2026-01-19 | 初始版本，包含客服账号管理、客服聊天功能、用户管理、订单处理、商品相关、客服话术管理、客服转接等核心功能 | AI Assistant |
## 9. 附录
### 9.1 核心类关系图
```
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ 前端应用 │────▶│ WebSocket服务器 │────▶│ 后端API服务 │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│
▼
┌─────────────────┐
│ 数据库 │
└─────────────────┘
```
### 9.2 聊天流程图
```
聊天流程：
1. 用户访问网站，发起聊天请求
2. 系统分配客服（或用户选择客服）
3. 建立WebSocket连接
4. 用户和客服开始聊天
a. 发送消息
b. 接收消息
c. 消息已读状态更新
5. 聊天结束，保存聊天记录
6. 关闭WebSocket连接
```
### 9.3 客服转接流程图
```
客服转接流程：
1. 当前客服发起转接请求
2. 系统验证转接权限
3. 选择目标客服
4. 发送转接请求给目标客服
5. 目标客服接受转接
6. 系统更新会话归属
7. 通知当前客服和目标客服
8. 转接完成，保留聊天记录
```
### 9.4 客服权限列表
| 权限名称 | 描述 |
|----------|------|
| kefu_login | 客服登录权限 |
| kefu_chat | 聊天功能权限 |
| kefu_user | 用户管理权限 |
| kefu_order | 订单处理权限 |
| kefu_product | 商品查看权限 |
| kefu_speechcraft | 话术管理权限 |
| kefu_transfer | 客服转接权限 |
---
> **提示**：该文档由AI生成，仅供参考。

101
docs/phpapi/开发规范说明.md Normal file
View File

@ -0,0 +1,101 @@
# 开发规范说明
## 🎯 基于已有规范的扩展
### 1. Service层命名和使用规范
```php
// ✅ 正确示例
class UserServices extends BaseServices {
public function getUserInfo(int $uid) {}
public function updateUserStatus(int $uid, int $status) {}
}
// ❌ 避免在Controller中直接操作数据库
// 不要这样写：Db::name('user')->where('id', $uid)->update($data)
```
### 2. DAO层职责划分
```php
// ✅ DAO只负责基础CRUD
class UserDao extends BaseDao {
public function getById(int $id) {}
public function updateById(int $id, array $data) {}
}
// Service调用DAO
class UserServices {
public function complexBusiness() {
$user = $this->dao->getById($id);
// 业务逻辑处理
$this->dao->updateById($id, $data);
}
}
```
### 3. 异常处理标准
```php
// 使用项目特定异常类
throw new ApiException('错误信息', 400);
throw new AdminException('管理端错误', 500);
// 统一返回格式
return $this->success($data);
return $this->fail('错误信息');
```
### 4. 参数验证位置
```php
// 验证放在validate目录下对应文件
// adminapi/validate/user/UserValidata.php
class UserValidata extends Validate {
protected $rule = [
'nickname' => 'require|max:25',
'phone' => 'require|mobile'
];
}
```
### 5. 注释标准补充
```php
/**
* 获取用户信息（包含扩展信息）
* @param int $uid 用户ID
* @param array $with 关联查询 ['order', 'address']
* @return array
* @throws ApiException
*/
public function getUserDetail(int $uid, array $with = []) {
// 业务逻辑
}
```
## 🔧 工具类使用规范
- 使用 `crmeb\utils\` 下的工具类
- 配置获取使用 `SystemConfigService`
- 缓存操作使用 `CacheService`
- 文件上传使用 `UploadService`
## 📝 代码提交规范
1. 提交前运行测试
2. 提交信息格式：`[类型] 描述`
- `[feat] 新增用户积分功能`
- `[fix] 修复订单状态更新问题`
- `[docs] 更新API文档`
- `[style] 调整代码格式`
3. 避免大块提交，每个提交专注于一个功能或修复
## 🚧 分支管理
- `master` - 生产环境代码
- `develop` - 开发分支
- `feature/xxx` - 功能开发分支
- `hotfix/xxx` - 紧急修复分支
## 🧪 测试规范
1. 单元测试覆盖核心业务逻辑
2. 集成测试覆盖API接口
3. 测试数据使用工厂模式生成
4. 测试用例命名：`testMethodNameWhenConditionThenResult`
---
> **提示**：该文档由AI生成，仅供参考。

313
docs/phpapi/支付开发流程文档-V2.md Normal file
View File

@ -0,0 +1,313 @@
# CRMEB 支付开发流程文档
## 🎯 支付功能概述
基于CRMEB 5.6.4+版本的支付系统分析，项目采用统一的支付服务架构，支持多种支付方式集成。
### 支持的支付方式
```php
// app/services/pay/PayServices.php
const WEIXIN_PAY = 'weixin'; // 微信支付
const YUE_PAY = 'yue'; // 余额支付
const OFFLINE_PAY = 'offline'; // 线下支付
const ALIAPY_PAY = 'alipay'; // 支付宝
const ALLIN_PAY = 'allinpay'; // 通联支付
const FRIEND = 'friend'; // 好友代付
const BANK = 'bank'; // 银行转账
```
## 🏗️ 支付系统架构
### 核心服务类结构
```
app/services/pay/
├── PayServices.php # 统一支付入口服务
├── OrderPayServices.php # 订单支付服务
├── PayNotifyServices.php # 支付回调服务
├── YuePayServices.php # 余额支付服务
└── RechargeServices.php # 充值服务
crmeb/services/pay/
├── Pay.php # 支付基础驱动
├── storage/
│ ├── WechatPay.php # 微信支付驱动
│ ├── AliPay.php # 支付宝驱动
│ ├── AllinPay.php # 通联支付驱动
│ └── V3WechatPay.php # 微信支付V3驱动
```
### 支付流程
#### 1. 支付请求流程
```mermaid
graph TD
A[客户端] --> B[支付控制器]
B --> C[PayServices]
C --> D[支付驱动 WechatPay/AliPay]
D --> E[第三方支付平台]
E --> F[返回支付参数]
F --> A
```
#### 2. 支付回调流程
```mermaid
graph TD
A[第三方支付] --> B[支付回调接口]
B --> C[PayNotifyServices]
C --> D[订单状态更新]
C --> E[支付记录更新]
D --> F[业务处理]
```
## 🔧 核心代码解析
### 统一支付入口 (PayServices.php)
```php
public function pay(string $payType, string $orderId, string $price, string $successAction, string $body, array $options = [])
{
try {
// 支付类型映射处理
if (in_array($payType, ['routine', 'weixinh5', 'weixin', 'pc', 'store'])) {
$payType = 'wechat_pay';
// V3接口判断
if (sys_config('pay_wechat_type') == 1) {
$payType = 'v3_wechat_pay';
}
} elseif ($payType == 'alipay') {
$payType = 'ali_pay';
} elseif ($payType == 'allinpay') {
$payType = 'allin_pay';
}
// 创建支付实例
$pay = app()->make(Pay::class, [$payType]);
return $pay->create($orderId, $price, $successAction, $body, '', $options);
} catch (\Exception $e) {
throw new ApiException($e->getMessage());
}
}
```
### 微信支付驱动 (WechatPay.php)
```php
public function create(string $orderId, string $totalFee, string $attach, string $body, string $detail, array $options = [])
{
$this->authSetPayType();
switch ($this->payType) {
case Order::NATIVE: // 扫码支付
return WechatService::nativePay(null, $orderId, $totalFee, $attach, $body, $detail);
case Order::APP: // APP支付
return WechatService::appPay($options['openid'], $orderId, $totalFee, $attach, $body, $detail);
case Order::JSAPI: // 小程序/公众号支付
if (request()->isRoutine()) {
// 小程序支付
if ($options['pay_new_weixin_open']) {
return MiniProgramService::newJsPay($options['openid'], $orderId, $totalFee, $attach, $body, $detail, $options);
}
return MiniProgramService::jsPay($options['openid'], $orderId, $totalFee, $attach, $body, $detail);
}
return WechatService::jsPay($options['openid'], $orderId, $totalFee, $attach, $body, $detail);
case 'h5': // H5支付
return WechatService::paymentPrepare(null, $orderId, $totalFee, $attach, $body, $detail, 'MWEB');
default:
throw new PayException('微信支付:支付类型错误');
}
}
```
### 支付回调处理 (PayNotifyServices.php)
```php
public function wechatProduct(string $order_id = null, string $trade_no = null, string $payType = PayServices::WEIXIN_PAY)
{
try {
$services = app()->make(StoreOrderSuccessServices::class);
$orderInfo = $services->getOne(['order_id' => $order_id]);
if (!$orderInfo) return true;
if ($orderInfo->paid) return true;
return $services->paySuccess($orderInfo->toArray(), $payType, ['trade_no' => $trade_no]);
} catch (\Exception $e) {
return false;
}
}
```
## 🛠️ 开发指南
### 1. 支付配置设置
在后台管理系统配置：
- 微信支付参数（APPID、商户号、API密钥、证书）
- 支付宝配置
- 通联支付配置
- 支付方式开关
### 2. 发起支付调用
```php
// 在控制器中调用
public function createPayment()
{
$params = $this->request->post();
// 参数验证
validate(PaymentValidate::class)->scene('create')->check($params);
$payServices = app()->make(PayServices::class);
$result = $payServices->pay(
$params['pay_type'],
$params['order_id'],
$params['amount'],
url('api/v1/payment/notify/wechat', [], true, true),
'商品购买'
);
return $this->success($result);
}
```
### 3. 支付回调配置
```php
// 路由配置
Route::post('api/v1/payment/notify/:type', 'api/v1/payment/notify');
// 回调控制器
public function notify($type)
{
$notifyService = app()->make(PayNotifyServices::class);
switch ($type) {
case 'wechat':
return $notifyService->wechatProduct(
$this->request->post('out_trade_no'),
$this->request->post('transaction_id')
);
case 'alipay':
// 支付宝回调处理
break;
}
return response('SUCCESS');
}
```
## 🧪 测试指南
### 单元测试示例
```php
class PaymentTest extends TestCase
{
public function testWechatPaymentCreation()
{
$payService = new PayServices();
$result = $payService->pay(
'weixin',
'TEST20240117001',
'100.00',
'https://domain.com/notify',
'测试商品'
);
$this->assertArrayHasKey('timeStamp', $result);
$this->assertArrayHasKey('nonceStr', $result);
$this->assertArrayHasKey('package', $result);
}
}
```
### 沙箱环境配置
```bash
# 微信支付沙箱
WECHAT_SANDBOX=true
WECHAT_APPID=sandbox_appid
WECHAT_MCHID=sandbox_mchid
# 支付宝沙箱
ALIPAY_SANDBOX=true
ALIPAY_GATEWAY=https://openapi.alipaydev.com/gateway.do
```
## 📊 数据库设计
### 支付记录表 (eb_store_pay)
```sql
CREATE TABLE `eb_store_pay` (
`id` int(10) UNSIGNED NOT NULL AUTO_INCREMENT,
`uid` int(10) UNSIGNED NOT NULL DEFAULT '0' COMMENT '用户id',
`oid` int(10) UNSIGNED NOT NULL DEFAULT '0' COMMENT '订单id',
`order_id` varchar(32) NOT NULL DEFAULT '' COMMENT '订单号',
`out_trade_no` varchar(32) NOT NULL DEFAULT '' COMMENT '支付流水号',
`pay_type` varchar(20) NOT NULL DEFAULT '' COMMENT '支付方式',
`pay_price` decimal(10,2) UNSIGNED NOT NULL DEFAULT '0.00' COMMENT '支付金额',
`trade_no` varchar(64) DEFAULT NULL COMMENT '第三方支付流水号',
`paid` tinyint(1) UNSIGNED NOT NULL DEFAULT '0' COMMENT '支付状态',
`pay_time` int(10) UNSIGNED DEFAULT NULL COMMENT '支付时间',
`add_time` int(10) UNSIGNED NOT NULL DEFAULT '0' COMMENT '创建时间',
PRIMARY KEY (`id`),
UNIQUE KEY `out_trade_no` (`out_trade_no`),
KEY `order_id` (`order_id`),
KEY `paid` (`paid`)
) ENGINE=InnoDB COMMENT='支付记录表';
```
## 🚀 部署运维
### 生产环境配置
```bash
# 微信支付配置
WECHAT_APPID=your_appid
WECHAT_MCHID=your_mchid
WECHAT_KEY=your_key
WECHAT_CERT_PATH=/path/to/cert.pem
WECHAT_KEY_PATH=/path/to/key.pem
# SSL证书配置
ssl_certificate /path/to/ssl/cert.pem;
ssl_certificate_key /path/to/ssl/key.pem;
```
### 监控告警
```php
// 支付监控指标
$metrics = [
'payment_success_rate' => ($successCount / $totalCount) * 100,
'payment_response_time' => microtime(true) - $startTime,
'payment_error_count' => $errorCount
];
// 日志记录
Log::info('支付监控', $metrics);
```
## 🔧 故障处理
### 常见问题
1. **支付回调失败**：检查nginx配置、SSL证书、防火墙
2. **签名错误**：验证支付密钥配置
3. **金额不一致**：检查金额单位和优惠计算
4. **重复支付**：添加防重机制和状态检查
### 应急处理
```bash
# 查看支付日志
tail -f runtime/log/payment.log
# 禁用问题支付方式
php think pay:disable weixin
# 启用备用支付
php think pay:enable alipay
```
---
**文档版本**: v2.0
**更新日期**: 2024-01-17
**适用版本**: CRMEB 5.6.4+
💡 提示：支付功能涉及资金安全，请严格遵循安全规范，定期进行安全审计。
---
> **提示**：该文档由AI生成，仅供参考。

600
docs/phpapi/支付开发流程文档.md Normal file
View File

@ -0,0 +1,600 @@
# 支付开发流程文档
## 🎯 支付功能概述
### 支付场景
- **商品购买支付**：普通商品订单支付
- **服务购买支付**：虚拟服务、会员购买
- **充值支付**：余额充值、积分充值
- **保证金支付**：商户保证金、服务保证金
- **退款处理**：订单退款、冲正处理
### 支持的支付方式
```php
const PAY_TYPE_WECHAT = 'wechat'; // 微信支付
const PAY_TYPE_ALIPAY = 'alipay'; // 支付宝
const PAY_TYPE_BALANCE = 'balance'; // 余额支付
const PAY_TYPE_INTEGRAL = 'integral'; // 积分支付
const PAY_TYPE_UNION = 'union'; // 云闪付
const PAY_TYPE_BANK = 'bank'; // 银行卡支付
```
## 🏗️ 支付系统架构
### 支付模块架构
```
┌─────────────────────────────────────────────────────┐
│ 支付控制器 (Controller) │
│ - 支付入口处理 │
│ - 参数验证 │
│ - 结果返回 │
└─────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────┐
│ 支付服务层 (PaymentService) │
│ - 支付逻辑处理 │
│ - 支付方式路由 │
│ - 支付状态管理 │
└─────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────┐
│ 支付渠道适配层 (PaymentAdapter) │
│ - 微信支付适配器 (WechatPayment) │
│ - 支付宝适配器 (AlipayPayment) │
│ - 余额支付适配器 (BalancePayment) │
│ - 积分支付适配器 (IntegralPayment) │
└─────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────┐
│ 第三方支付SDK │
│ - 微信支付官方SDK │
│ - 支付宝官方SDK │
│ - 银行支付接口 │
└─────────────────────────────────────────────────────┘
```
### 数据库设计
```sql
-- 支付记录表
CREATE TABLE `store_pay` (
`id` int(11) NOT NULL AUTO_INCREMENT,
`order_id` varchar(32) NOT NULL COMMENT '订单号',
`out_trade_no` varchar(32) NOT NULL COMMENT '支付流水号',
`pay_type` varchar(20) NOT NULL COMMENT '支付方式',
`pay_price` decimal(10,2) NOT NULL COMMENT '支付金额',
`trade_no` varchar(64) DEFAULT NULL COMMENT '第三方支付流水号',
`pay_status` tinyint(1) NOT NULL DEFAULT '0' COMMENT '支付状态',
`pay_time` int(11) DEFAULT NULL COMMENT '支付时间',
`create_time` int(11) NOT NULL COMMENT '创建时间',
`update_time` int(11) NOT NULL COMMENT '更新时间',
PRIMARY KEY (`id`),
UNIQUE KEY `idx_out_trade_no` (`out_trade_no`),
KEY `idx_order_id` (`order_id`),
KEY `idx_pay_status` (`pay_status`)
) ENGINE=InnoDB COMMENT='支付记录表';
-- 退款记录表
CREATE TABLE `store_refund` (
`id` int(11) NOT NULL AUTO_INCREMENT,
`order_id` varchar(32) NOT NULL COMMENT '订单号',
`refund_no` varchar(32) NOT NULL COMMENT '退款流水号',
`refund_amount` decimal(10,2) NOT NULL COMMENT '退款金额',
`refund_reason` varchar(255) DEFAULT NULL COMMENT '退款原因',
`refund_status` tinyint(1) NOT NULL DEFAULT '0' COMMENT '退款状态',
`refund_time` int(11) DEFAULT NULL COMMENT '退款时间',
`create_time` int(11) NOT NULL COMMENT '创建时间',
PRIMARY KEY (`id`),
UNIQUE KEY `idx_refund_no` (`refund_no`),
KEY `idx_order_id` (`order_id`)
) ENGINE=InnoDB COMMENT='退款记录表';
```
## 🔧 开发流程
### 1. 需求分析与设计
```markdown
1. 确定支付场景和需求
2. 选择支持的支付方式
3. 设计支付流程和状态流转
4. 确定退款政策和规则
5. 设计对账和清算流程
```
### 2. 环境准备
```bash
# 安装支付SDK依赖
composer require overtrue/wechat
composer require alipay-sdk/php-all
# 配置支付参数
cp .env.example .env
# 配置微信支付参数
WECHAT_APPID=your_appid
WECHAT_MCHID=your_mchid
WECHAT_KEY=your_key
WECHAT_APPSECRET=your_appsecret
# 配置支付宝参数
ALIPAY_APPID=your_appid
ALIPAY_PRIVATE_KEY=your_private_key
ALIPAY_PUBLIC_KEY=your_public_key
```
### 3. 支付控制器开发
```php
<?php
namespace app\api\controller\v1;
use app\services\PaymentService;
use app\validate\PaymentValidate;
class PaymentController
{
/**
* 发起支付
* @route('api/v1/payment/create')
*/
public function createPayment()
{
// 参数验证
$params = $this->request->post();
validate(PaymentValidate::class)->scene('create')->check($params);
// 调用支付服务
$paymentService = app()->make(PaymentService::class);
$result = $paymentService->createPayment($params);
return $this->success($result);
}
/**
* 支付回调处理
* @route('api/v1/payment/notify/:type')
*/
public function paymentNotify($type)
{
try {
$paymentService = app()->make(PaymentService::class);
$result = $paymentService->handleNotify($type, $this->request->post());
// 返回第三方支付要求的成功响应
return response($result['response']);
} catch (\Exception $e) {
Log::error('支付回调处理失败: ' . $e->getMessage());
return response('FAIL');
}
}
}
```
### 4. 支付服务层开发
```php
<?php
namespace app\services;
use app\exception\PaymentException;
use app\services\payment\WechatPayment;
use app\services\payment\AlipayPayment;
use app\services\payment\BalancePayment;
class PaymentService extends BaseService
{
/**
* 创建支付
*/
public function createPayment(array $params): array
{
// 验证订单状态
$orderInfo = $this->validateOrder($params['order_id']);
// 选择支付方式
$paymentAdapter = $this->getPaymentAdapter($params['pay_type']);
// 创建支付记录
$payData = $this->createPayRecord($orderInfo, $params);
// 调用支付适配器
return $paymentAdapter->createPayment($payData);
}
/**
* 获取支付适配器
*/
protected function getPaymentAdapter(string $payType): PaymentInterface
{
switch ($payType) {
case 'wechat':
return app()->make(WechatPayment::class);
case 'alipay':
return app()->make(AlipayPayment::class);
case 'balance':
return app()->make(BalancePayment::class);
default:
throw new PaymentException('不支持的支付方式', 5001);
}
}
/**
* 处理支付回调
*/
public function handleNotify(string $payType, array $notifyData): array
{
$paymentAdapter = $this->getPaymentAdapter($payType);
$verifyResult = $paymentAdapter->verifyNotify($notifyData);
if (!$verifyResult['success']) {
throw new PaymentException('回调验证失败', 5002);
}
// 更新支付状态
$this->updatePaymentStatus($verifyResult['out_trade_no'], $verifyResult);
return ['response' => 'SUCCESS'];
}
}
```
### 5. 支付适配器开发（以微信支付为例）
```php
<?php
namespace app\services\payment;
use EasyWeChat\Factory;
use app\exception\PaymentException;
class WechatPayment implements PaymentInterface
{
protected $app;
public function __construct()
{
$config = [
'app_id' => env('wechat.app_id'),
'mch_id' => env('wechat.mch_id'),
'key' => env('wechat.key'),
'cert_path' => env('wechat.cert_path'),
'key_path' => env('wechat.key_path'),
'notify_url' => env('wechat.notify_url'),
];
$this->app = Factory::payment($config);
}
/**
* 创建支付
*/
public function createPayment(array $payData): array
{
try {
$result = $this->app->order->unify([
'body' => $payData['body'],
'out_trade_no' => $payData['out_trade_no'],
'total_fee' => $payData['total_fee'],
'trade_type' => 'JSAPI',
'openid' => $payData['openid'],
]);
if ($result['return_code'] === 'SUCCESS' && $result['result_code'] === 'SUCCESS') {
return [
'pay_params' => $this->app->jssdk->bridgeConfig($result['prepay_id']),
'pay_type' => 'wechat'
];
} else {
throw new PaymentException($result['return_msg'] ?? '微信支付创建失败', 5003);
}
} catch (\Exception $e) {
throw new PaymentException('微信支付异常: ' . $e->getMessage(), 5004);
}
}
/**
* 验证回调
*/
public function verifyNotify(array $notifyData): array
{
try {
$message = $this->app->handlePaidNotify(function($message, $fail) {
// 验证支付状态
if ($message['return_code'] !== 'SUCCESS') {
return $fail('通信失败，请稍后再通知我');
}
if ($message['result_code'] !== 'SUCCESS') {
return $fail('支付失败，请稍后再通知我');
}
return [
'out_trade_no' => $message['out_trade_no'],
'trade_no' => $message['transaction_id'],
'pay_amount' => $message['total_fee'] / 100,
'pay_time' => strtotime($message['time_end']),
'success' => true
];
});
return $message;
} catch (\Exception $e) {
throw new PaymentException('回调验证异常: ' . $e->getMessage(), 5005);
}
}
}
```
### 6. 支付接口定义
```php
<?php
namespace app\services\payment;
interface PaymentInterface
{
/**
* 创建支付
*/
public function createPayment(array $payData): array;
/**
* 处理支付回调
*/
public function verifyNotify(array $notifyData): array;
/**
* 查询支付状态
*/
public function queryPayment(string $outTradeNo): array;
/**
* 申请退款
*/
public function refund(array $refundData): array;
}
```
## 🧪 测试流程
### 1. 单元测试
```php
<?php
namespace tests\services;
use app\services\PaymentService;
use app\services\payment\WechatPayment;
use think\testing\TestCase;
class PaymentServiceTest extends TestCase
{
public function testCreatePayment()
{
// 模拟支付参数
$params = [
'order_id' => 'TEST202401170001',
'pay_type' => 'wechat',
'pay_amount' => 100.00
];
// 创建支付服务实例
$paymentService = new PaymentService();
// 测试支付创建
$result = $paymentService->createPayment($params);
$this->assertArrayHasKey('pay_params', $result);
$this->assertEquals('wechat', $result['pay_type']);
}
public function testPaymentNotify()
{
// 模拟微信支付回调数据
$notifyData = [
'return_code' => 'SUCCESS',
'result_code' => 'SUCCESS',
'out_trade_no' => 'TEST202401170001',
'transaction_id' => '420000202401170001',
'total_fee' => '10000',
'time_end' => '20240117153000'
];
$paymentService = new PaymentService();
$result = $paymentService->handleNotify('wechat', $notifyData);
$this->assertEquals('SUCCESS', $result['response']);
}
}
```
### 2. 集成测试
```bash
# 运行支付相关测试
php think test tests/services/PaymentServiceTest
php think test tests/services/payment/WechatPaymentTest
php think test tests/services/payment/AlipayPaymentTest
# 生成测试覆盖率报告
php think test --coverage-html coverage/payment
```
### 3. 沙箱环境测试
```php
// 配置沙箱环境
'wechat' => [
'app_id' => '沙箱appid',
'mch_id' => '沙箱商户号',
'key' => '沙箱key',
'sandbox' => true, // 开启沙箱模式
]
// 支付宝沙箱配置
'alipay' => [
'app_id' => '沙箱appid',
'gateway_url' => 'https://openapi.alipaydev.com/gateway.do',
'sign_type' => 'RSA2',
'sandbox' => true,
]
```
## 🚀 部署上线
### 1. 生产环境配置
```bash
# 设置生产环境配置
cp .env.production .env
# 配置生产环境支付参数
WECHAT_APPID=生产环境appid
WECHAT_MCHID=生产环境商户号
WECHAT_KEY=生产环境key
WECHAT_CERT_PATH=/path/to/cert/apiclient_cert.pem
WECHAT_KEY_PATH=/path/to/cert/apiclient_key.pem
ALIPAY_APPID=生产环境appid
ALIPAY_PRIVATE_KEY=生产环境私钥
ALIPAY_PUBLIC_KEY=生产环境公钥
```
### 2. SSL证书配置
```nginx
# Nginx SSL配置
server {
listen 443 ssl http2;
server_name yourdomain.com;
ssl_certificate /path/to/ssl/cert.pem;
ssl_certificate_key /path/to/ssl/key.pem;
# 支付回调接口
location /api/v1/payment/notify/ {
proxy_pass http://127.0.0.1:8000;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
}
}
```
### 3. 监控告警配置
```yaml
# 支付监控指标
payment:
success_rate:
type: gauge
help: 支付成功率
labels: [pay_type]
response_time:
type: histogram
help: 支付响应时间分布
labels: [pay_type]
error_count:
type: counter
help: 支付错误次数
labels: [pay_type, error_code]
```
## 📊 运维监控
### 1. 日志监控
```php
// 支付关键日志记录
Log::info('支付创建', [
'order_id' => $orderId,
'pay_type' => $payType,
'amount' => $amount,
'user_id' => $userId
]);
Log::error('支付失败', [
'order_id' => $orderId,
'error_code' => $errorCode,
'error_msg' => $errorMsg,
'trace' => debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS, 3)
]);
```
### 2. 性能监控
```bash
# 监控支付接口性能
# 平均响应时间 < 200ms
# 95%响应时间 < 500ms
# 错误率 < 0.1%
# 使用Prometheus监控
payment_api_duration_seconds_bucket{pay_type="wechat",le="0.1"} 12345
payment_api_duration_seconds_bucket{pay_type="wechat",le="0.5"} 23456
```
### 3. 对账处理
```php
/**
* 每日对账任务
*/
public function dailyReconciliation()
{
$yesterday = strtotime('yesterday');
$today = strtotime('today');
// 查询本地支付记录
$localRecords = $this->payDao->getRecordsByTime($yesterday, $today);
// 查询第三方支付记录
foreach (['wechat', 'alipay'] as $payType) {
$adapter = $this->getPaymentAdapter($payType);
$thirdPartyRecords = $adapter->queryBill($yesterday, $today);
// 对账处理
$result = $this->reconcile($localRecords, $thirdPartyRecords);
// 记录对账结果
$this->saveReconciliationResult($result);
}
}
```
## 🔧 故障处理
### 常见问题处理
```markdown
1. **支付回调失败**
- 检查网络连通性
- 验证证书有效性
- 检查回调地址配置
2. **支付签名错误**
- 检查密钥配置
- 验证签名算法
- 检查参数编码
3. **支付金额不符**
- 检查金额单位（分/元）
- 验证金额计算逻辑
- 检查优惠券抵扣
4. **重复支付**
- 检查支付状态验证
- 添加防重机制
- 人工审核处理
```
### 应急处理流程
```bash
# 1. 暂停支付功能
php think payment:disable wechat
# 2. 查看支付日志
tail -f runtime/log/payment.log
# 3. 回滚有问题的版本
git revert <commit-hash>
# 4. 启用备用支付通道
php think payment:enable alipay
```
---
**文档版本**: v1.0
**最后更新**: 2024-01-17
**维护人员**: 支付开发团队
💡 **提示**: 支付功能涉及资金安全，请严格遵循安全规范和审计要求。
---
> **提示**：该文档由AI生成，仅供参考。

116
docs/phpapi/数据库结构设计.md Normal file
View File

@ -0,0 +1,116 @@
# 数据库结构设计
## 📊 核心数据表
### 用户相关表
```
user # 用户主表
user_level # 用户等级表
user_label # 用户标签表
user_address # 用户地址表
user_collect # 用户收藏表
user_cart # 购物车表
user_balance # 用户余额表
user_integral # 用户积分表
```
### 商品相关表
```
store_product # 商品主表
store_product_attr # 商品属性表
store_product_attr_value # 商品属性值表
store_category # 商品分类表
store_product_reply # 商品评价表
store_product_visit # 商品浏览记录表
store_product_cate # 商品分类关联表
```
### 订单相关表
```
store_order # 订单主表
store_order_cart_info # 订单购物车信息表
store_order_status # 订单状态记录表
store_order_refund # 退款记录表
store_order_invoice # 发票信息表
store_pay # 支付记录表
```
### 营销相关表
```
store_coupon # 优惠券表
store_coupon_user # 用户优惠券表
store_combination # 拼团活动表
store_bargain # 砍价活动表
store_seckill # 秒杀活动表
store_integral_goods # 积分商品表
store_gift # 赠品表
```
### 公众号/小程序相关表
```
wechat_user # 微信用户表
wechat_message # 微信消息表
wechat_qrcode # 二维码表
wechat_template # 模板消息表
```
### 系统配置表
```
system_config # 系统配置表
system_admin # 管理员表
system_role # 角色表
system_menus # 菜单表
system_log # 操作日志表
```
## 🔗 表关系说明
### 订单核心关系
```
store_order (1) ──→ (N) store_order_cart_info
store_order (1) ──→ (N) store_order_status
store_order (1) ──→ (N) store_pay
store_order (1) ──→ (N) store_order_refund
```
### 用户与订单关系
```
user (1) ──→ (N) store_order
user (1) ──→ (N) user_address
user (1) ──→ (N) user_cart
user (1) ──→ (N) store_coupon_user
```
### 商品核心关系
```
store_product (1) ──→ (N) store_product_attr
store_product (1) ──→ (N) store_product_attr_value
store_product (1) ──→ (N) store_category
store_product (1) ──→ (N) store_product_reply
```
## 📝 索引设计
### 主键索引
所有表均以 `id` 字段作为主键自增索引
### 常用查询索引
```
user表: phone, openid, unionid
store_order表: order_id, uid, status, add_time
store_product表: cate_id, is_hot, is_new, is_benefit
wechat_user表: openid, uid
```
### 联合索引
```sql
-- 订单列表查询
INDEX idx_order_list (uid, add_time, status)
-- 商品列表查询
INDEX idx_product_list (cate_id, is_hot, is_new)
```
---
> **提示**：该文档由AI生成，仅供参考。

425
docs/phpapi/服务管理开发文档.md Normal file
View File

@ -0,0 +1,425 @@
# 服务管理开发文档
## 1. 文档概述
### 1.1 文档目的
本文档旨在详细说明CRMEB系统中服务管理模块的设计架构、核心功能、代码实现及开发规范，为系统开发人员提供完整的开发参考。
### 1.2 适用范围
本文档适用于CRMEB系统开发人员、维护人员及二次开发人员，用于指导服务管理模块的开发、扩展和维护工作。
### 1.3 术语定义
| 术语 | 解释 |
|------|------|
| 服务套餐 | 系统提供的各种增值服务组合 |
| 电子面单 | 在线生成的快递单模板 |
| 短信服务 | 用于发送验证码、通知等短信的服务 |
| 商品复制 | 从其他平台复制商品信息到本地系统的服务 |
| 小票打印 | 打印订单小票的服务 |
| 电子发票 | 在线生成和管理电子发票的服务 |
| Access Token | 服务API的认证令牌 |
## 2. 核心功能模块
### 2.1 服务开通与管理
- **服务套餐管理**：查看和购买各种服务套餐
- **服务开通**：开通和配置各种服务
- **服务状态管理**：查看和管理已开通服务的状态
- **服务配置管理**：配置服务的各项参数
### 2.2 消费记录管理
- **消费记录查询**：按类型、时间等条件查询消费记录
- **消费统计**：统计各项服务的消费情况
- **消费详情**：查看消费记录的详细信息
### 2.3 用户信息管理
- **服务平台登录**：登录服务管理平台
- **用户信息获取**：获取服务平台用户信息
- **密码修改**：修改服务平台登录密码
- **手机号修改**：修改绑定的手机号
### 2.4 短信服务管理
- **短信服务开通**：开通短信服务
- **短信模板管理**：申请和管理短信模板
- **签名修改**：修改短信签名
- **短信发送配置**：配置短信发送参数
### 2.5 电子面单服务
- **电子面单开通**：开通电子面单服务
- **电子面单配置**：配置电子面单参数
- **电子面单生成**：生成电子面单
- **电子面单模板管理**：管理电子面单模板
### 2.6 商品复制服务
- **商品复制开通**：开通商品复制服务
- **商品复制配置**：配置商品复制参数
- **商品复制操作**：从其他平台复制商品信息
### 2.7 小票打印服务
- **小票打印开通**：开通小票打印服务
- **小票打印配置**：配置小票打印参数
- **小票模板管理**：管理小票打印模板
### 2.8 电子发票服务
- **电子发票开通**：开通电子发票服务
- **电子发票配置**：配置电子发票参数
- **电子发票生成**：生成电子发票
- **电子发票管理**：管理电子发票记录
## 3. 代码结构与设计
### 3.1 架构设计
系统采用分层架构设计，严格遵循MVC设计模式，并采用驱动模式支持多种服务提供商：
```
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Routes │────▶│ Controllers │────▶│ Services │────▶│ Storage │
└─────────────────┘ └─────────────────┘ └─────────────────┘ └─────────────────┘
▲ ▲ ▲ ▲
│ │ │ │
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Request & │ │ FormBuilder │ │ BaseManager │ │ External APIs │
│ Response │ └─────────────────┘ └─────────────────┘ └─────────────────┘
└─────────────────┘
```
### 3.2 核心文件结构
#### 3.2.1 路由配置
**服务路由**：`crmeb/app/adminapi/route/serve.php`
- 包含服务管理相关的所有API路由
- 模块化设计：平台登录、电子面单、用户信息、支付套餐、短信服务、消费记录等
#### 3.2.2 控制器层（Controller）
**服务控制器**：`crmeb/app/adminapi/controller/v1/serve/`
- `Serve.php` - 核心服务控制器，处理服务套餐、支付、开通、记录查询等功能
- `Export.php` - 处理电子面单相关功能
- `Sms.php` - 处理短信服务相关功能
- `Login.php` - 处理服务平台登录相关功能
#### 3.2.3 服务层（Services）
**服务管理Services**：`crmeb/app/services/serve/`
- `ServeServices.php` - 核心服务管理服务，提供服务实例化方法
- `sms()`：短信服务
- `copy()`：商品复制服务
- `express()`：电子面单服务
- `orderPrint()`：小票打印服务
- `user()`：用户服务
- `invoice()`：电子发票服务
#### 3.2.4 服务管理器
**服务管理器**：`crmeb/crmeb/services/serve/Serve.php`
- 基于BaseManager实现，采用驱动模式设计
- 支持多种服务驱动，默认使用CRMEB服务
- 提供服务实例化和管理功能
#### 3.2.5 服务存储层
**服务存储**：`crmeb/crmeb/services/serve/storage/Crmeb.php`
- 与外部服务API交互
- 获取用户信息
- 查询用量记录
- 处理服务开通和配置
#### 3.2.6 认证服务
**AccessToken服务**：`crmeb/app/services/serve/AccessTokenServeService.php`
- 处理服务API的认证和授权
- 生成和管理Access Token
- 验证API请求的合法性
## 4. 数据库设计
### 4.1 服务套餐表（serve_meal）
| 字段名 | 数据类型 | 描述 |
|--------|----------|------|
| id | int(10) unsigned | 套餐ID |
| name | varchar(100) | 套餐名称 |
| type | varchar(20) | 服务类型 |
| price | decimal(10,2) | 套餐价格 |
| description | text | 套餐描述 |
| days | int(10) | 有效期（天） |
| status | tinyint(1) | 状态（0-关闭，1-开启） |
| sort | int(10) | 排序 |
| add_time | int(10) | 添加时间 |
### 4.2 服务开通记录表（serve_open）
| 字段名 | 数据类型 | 描述 |
|--------|----------|------|
| id | int(10) unsigned | 记录ID |
| uid | int(10) | 用户ID |
| type | varchar(20) | 服务类型 |
| status | tinyint(1) | 状态（0-未开通，1-已开通，2-已过期） |
| start_time | int(10) | 开始时间 |
| end_time | int(10) | 结束时间 |
| add_time | int(10) | 添加时间 |
### 4.3 服务消费记录表（serve_record）
| 字段名 | 数据类型 | 描述 |
|--------|----------|------|
| id | int(10) unsigned | 记录ID |
| uid | int(10) | 用户ID |
| type | varchar(20) | 服务类型 |
| money | decimal(10,2) | 消费金额 |
| mark | varchar(255) | 消费原因 |
| add_time | int(10) | 消费时间 |
### 4.4 短信模板表（sms_template）
| 字段名 | 数据类型 | 描述 |
|--------|----------|------|
| id | int(10) unsigned | 模板ID |
| name | varchar(100) | 模板名称 |
| content | text | 模板内容 |
| status | tinyint(1) | 状态（0-审核中，1-已通过，2-未通过） |
| add_time | int(10) | 添加时间 |
| audit_time | int(10) | 审核时间 |
| audit_msg | varchar(255) | 审核备注 |
### 4.5 电子面单配置表（express_config）
| 字段名 | 数据类型 | 描述 |
|--------|----------|------|
| id | int(10) unsigned | 配置ID |
| uid | int(10) | 用户ID |
| company | varchar(50) | 快递公司 |
| app_id | varchar(100) | 应用ID |
| app_key | varchar(100) | 应用密钥 |
| config | text | 其他配置（JSON格式） |
| status | tinyint(1) | 状态（0-未开通，1-已开通） |
| add_time | int(10) | 添加时间 |
## 5. API接口说明
### 5.1 服务套餐管理
#### 5.1.1 获取服务套餐列表
- **请求URL**：`/adminapi/v1/serve/meal/list`
- **请求方法**：GET
- **权限要求**：serve/meal/list
- **返回结果**：服务套餐列表数据
#### 5.1.2 购买服务套餐
- **请求URL**：`/adminapi/v1/serve/meal/buy/{id}`
- **请求方法**：POST
- **权限要求**：serve/meal/buy
- **请求参数**：
- pay_type：支付方式
- **返回结果**：支付信息
### 5.2 服务开通管理
#### 5.2.1 获取已开通服务列表
- **请求URL**：`/adminapi/v1/serve/open/list`
- **请求方法**：GET
- **权限要求**：serve/open/list
- **返回结果**：已开通服务列表数据
#### 5.2.2 开通服务
- **请求URL**：`/adminapi/v1/serve/open/{type}`
- **请求方法**：POST
- **权限要求**：serve/open
- **请求参数**：服务配置参数
- **返回结果**：操作结果
### 5.3 消费记录管理
#### 5.3.1 获取消费记录列表
- **请求URL**：`/adminapi/v1/serve/record/list`
- **请求方法**：GET
- **权限要求**：serve/record/list
- **请求参数**：
- page：页码
- limit：每页数量
- type：服务类型
- start_time：开始时间
- end_time：结束时间
- **返回结果**：消费记录列表数据
### 5.4 短信服务管理
#### 5.4.1 获取短信模板列表
- **请求URL**：`/adminapi/v1/serve/sms/template/list`
- **请求方法**：GET
- **权限要求**：serve/sms/template/list
- **返回结果**：短信模板列表数据
#### 5.4.2 申请短信模板
- **请求URL**：`/adminapi/v1/serve/sms/template/apply`
- **请求方法**：POST
- **权限要求**：serve/sms/template/apply
- **请求参数**：
- name：模板名称
- content：模板内容
- remark：备注
- **返回结果**：操作结果
### 5.5 电子面单管理
#### 5.5.1 开通电子面单
- **请求URL**：`/adminapi/v1/serve/export/open`
- **请求方法**：POST
- **权限要求**：serve/export/open
- **请求参数**：
- company：快递公司
- app_id：应用ID
- app_key：应用密钥
- **返回结果**：操作结果
#### 5.5.2 生成电子面单
- **请求URL**：`/adminapi/v1/serve/export/generate`
- **请求方法**：POST
- **权限要求**：serve/export/generate
- **请求参数**：
- company：快递公司
- order_id：订单ID
- recipient：收件人信息
- sender：发件人信息
- **返回结果**：电子面单数据
## 5. 开发规范与流程
### 5.1 代码规范
1. **命名规范**：
- 类名采用大驼峰命名法，如 `ServeServices`
- 方法名采用小驼峰命名法，如 `getMealList`
- 变量名采用小驼峰命名法，如 `serviceConfig`
- 常量名采用全大写，下划线分隔，如 `SERVE_TYPE_SMS`
2. **代码结构**：
- 严格遵循分层架构，禁止跨层调用
- 每个方法职责单一，代码行数控制在50行以内
- 适当添加注释，说明方法功能、参数含义和返回值
- 服务驱动类应继承自BaseManager
3. **API交互**：
- 所有外部API请求必须经过AccessTokenServeService认证
- API请求和响应必须使用统一的格式
- 必须处理API请求异常，提供友好的错误提示
### 5.2 开发流程
1. **需求分析**：明确服务管理的功能需求和业务逻辑
2. **设计阶段**：设计数据结构、API接口和业务流程
3. **编码实现**：按照分层架构编写代码
4. **单元测试**：编写单元测试，确保功能正确性
5. **集成测试**：进行模块集成测试，测试服务与其他模块的交互
6. **性能测试**：对API调用进行性能测试
7. **代码审查**：提交代码审查，确保代码质量
8. **部署上线**：部署到生产环境
## 6. 常见问题与解决方案
### 6.1 API认证问题
**问题**：API请求认证失败
**解决方案**：
1. 检查AccessToken是否过期，及时刷新
2. 确保请求参数正确，特别是签名参数
3. 检查服务是否已开通，状态是否正常
4. 检查IP白名单设置（如果有）
### 6.2 服务开通失败
**问题**：服务开通或配置失败
**解决方案**：
1. 检查服务套餐是否有效
2. 确保支付状态正常
3. 检查配置参数是否正确
4. 查看服务日志，定位具体错误
### 6.3 API请求超时
**问题**：外部API请求超时
**解决方案**：
1. 检查网络连接是否正常
2. 优化API请求，减少请求次数
3. 实现请求重试机制，设置合理的超时时间
4. 考虑使用异步请求，避免阻塞主流程
### 6.4 服务数据同步问题
**问题**：本地数据与服务平台数据不同步
**解决方案**：
1. 实现定期同步机制，确保数据一致性
2. 在关键操作后立即同步数据
3. 提供手动同步功能，允许管理员手动触发同步
## 7. 扩展与定制
### 7.1 添加新的服务类型
1. **创建服务驱动类**：继承BaseManager，实现服务的核心功能
2. **添加服务配置表**：为新服务类型创建配置表
3. **实现服务控制器**：处理新服务的API请求
4. **添加路由配置**：在serve.php中添加新服务的路由
5. **更新服务管理器**：在ServeServices中添加新服务的实例化方法
### 7.2 更换服务提供商
1. **创建新的服务存储类**：继承自服务存储基类，实现与新服务提供商的交互
2. **更新服务配置**：修改服务配置，切换到新的服务提供商
3. **测试服务功能**：确保所有服务功能正常工作
### 7.3 扩展服务功能
1. **添加新的API接口**：在控制器中添加新的方法，实现扩展功能
2. **更新路由配置**：添加新接口的路由
3. **实现业务逻辑**：在服务层实现新的业务逻辑
4. **更新数据库**：如果需要，添加或修改数据库表
## 8. 文档更新记录
| 版本 | 更新日期 | 更新内容 | 更新人 |
|------|----------|----------|--------|
| 1.0 | 2026-01-19 | 初始版本，包含服务开通与管理、消费记录管理、用户信息管理、短信服务管理、电子面单服务、商品复制服务、小票打印服务、电子发票服务等核心功能 | AI Assistant |
## 9. 附录
### 9.1 核心类关系图
```
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Routes │────▶│ Controllers │────▶│ Services │────▶│ Storage │
└─────────────────┘ └─────────────────┘ └─────────────────┘ └─────────────────┘
▲ ▲ ▲ ▲
│ │ │ │
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Request & │ │ FormBuilder │ │ BaseManager │ │ External APIs │
│ Response │ └─────────────────┘ └─────────────────┘ └─────────────────┘
└─────────────────┘
```
### 9.2 服务开通流程图
```
服务开通流程：
1. 用户选择服务套餐
2. 系统生成服务订单
3. 用户支付订单
4. 支付成功后，系统调用服务API开通服务
5. 系统更新服务状态
6. 系统记录消费记录
7. 发送服务开通通知给用户
```
### 9.3 API请求流程图
```
API请求流程：
1. 客户端发起API请求
2. 服务端验证请求参数
3. AccessTokenServeService验证AccessToken
4. 服务控制器处理请求
5. 服务层调用相应的服务驱动
6. 服务驱动调用外部API
7. 外部API返回结果
8. 服务驱动处理结果
9. 服务控制器返回响应给客户端
```
### 9.4 服务类型常量
| 常量 | 描述 |
|------|------|
| SERVE_TYPE_SMS | 短信服务 |
| SERVE_TYPE_COPY | 商品复制服务 |
| SERVE_TYPE_EXPRESS | 电子面单服务 |
| SERVE_TYPE_ORDER_PRINT | 小票打印服务 |
| SERVE_TYPE_INVOICE | 电子发票服务 |
---
> **提示**：该文档由AI生成，仅供参考。

441
docs/phpapi/消息通知开发文档.md Normal file
View File

@ -0,0 +1,441 @@
# 消息通知开发文档
## 1. 文档概述
### 1.1 文档目的
本文档旨在详细说明CRMEB系统中消息通知模块的设计架构、核心功能、代码实现及开发规范，为系统开发人员提供完整的开发参考。
### 1.2 适用范围
本文档适用于CRMEB系统开发人员、维护人员及二次开发人员，用于指导消息通知模块的开发、扩展和维护工作。
### 1.3 术语定义
| 术语 | 解释 |
|------|------|
| 系统消息 | 存储在数据库中的站内信，通过系统内部推送 |
| 模板消息 | 包括公众号模板消息和小程序订阅消息 |
| 短信通知 | 通过第三方短信服务商发送给用户手机的消息 |
| 企业微信消息 | 发送给管理员和客服的企业微信消息 |
| 事件驱动 | 通过触发事件来处理各种通知场景 |
| 通知渠道 | 消息发送的方式，如站内信、短信、模板消息等 |
| 通知场景 | 触发通知的业务场景，如订单支付、发货等 |
## 2. 核心功能模块
### 2.1 系统消息管理
- **消息列表**：展示系统消息，支持搜索、分页
- **消息添加**：添加新的系统消息
- **消息编辑**：修改系统消息内容
- **消息删除**：删除系统消息
- **消息发送**：发送系统消息给指定用户或用户组
- **消息阅读**：记录用户消息阅读状态
- **消息统计**：统计消息发送和阅读情况
### 2.2 短信通知管理
- **短信模板管理**：添加、编辑、删除短信模板
- **短信发送记录**：查看短信发送记录和状态
- **短信配置**：配置短信服务商、API密钥等
- **短信签名管理**：管理短信签名
- **短信场景配置**：配置不同场景下的短信模板
### 2.3 模板消息管理
- **公众号模板消息管理**：添加、编辑、删除公众号模板消息
- **小程序订阅消息管理**：添加、编辑、删除小程序订阅消息
- **模板消息发送记录**：查看模板消息发送记录和状态
- **模板消息配置**：配置不同场景下的模板消息
### 2.4 企业微信消息管理
- **企业微信配置**：配置企业微信API密钥、AgentId等
- **企业微信消息模板**：添加、编辑、删除企业微信消息模板
- **企业微信消息发送记录**：查看企业微信消息发送记录和状态
### 2.5 通知场景配置
- **通知场景列表**：展示系统支持的各种通知场景
- **场景通知配置**：配置每个场景下需要发送的通知渠道
- **通知模板配置**：为每个场景配置对应的通知模板
- **通知状态管理**：开启/关闭特定场景的通知
## 3. 代码结构与设计
### 3.1 架构设计
系统采用事件驱动的架构设计，通过监听器统一处理各种通知事件：
```
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ 业务事件触发 │────▶│ 事件监听器 │────▶│ 通知服务处理 │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│
▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ 系统消息发送 │◀────│ 多渠道通知 │────▶│ 短信通知发送 │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│
▼
┌─────────────────────────┐
│ 模板消息发送 │
├─────────────────────────┤
│ - 公众号模板消息 │
│ - 小程序订阅消息 │
└─────────────────────────┘
│
▼
┌─────────────────────────┐
│ 企业微信消息发送 │
└─────────────────────────┘
```
### 3.2 核心文件结构
#### 3.2.1 服务层（Services）
**消息通知服务**：
- `NoticeService.php` - 通知服务基类，用于设置和管理通知事件
- `SystemNotificationServices.php` - 系统通知配置管理类，包含各种通知场景的定义
- `MessageSystemServices.php` - 站内信服务类，处理用户站内消息的发送、查询和管理
- `SmsService.php` - 短信服务类，支持多种短信服务商
- `TemplateMessageServices.php` - 模板消息管理类，管理公众号模板消息和小程序订阅消息
#### 3.2.2 监听器（Listener）
**通知事件监听器**：
- `NoticeListener.php` - 核心事件监听器，处理各种通知事件，映射了30+种通知场景到对应的处理方法
- `CustomNoticeListener.php` - 自定义通知监听器，用于处理特殊通知场景
#### 3.2.3 模型层（Model）
**消息相关模型**：
- `MessageSystem.php` - 系统消息模型
- `SmsRecord.php` - 短信发送记录模型
- `SystemNotification.php` - 系统通知配置模型
- `TemplateMessage.php` - 模板消息模型
#### 3.2.4 控制器层（Controller）
**消息通知控制器**：
- `SystemNotification.php` - 系统通知配置控制器
- `MessageSystem.php` - 系统消息控制器
- `Sms.php` - 短信管理控制器
- `TemplateMessage.php` - 模板消息控制器
#### 3.2.5 路由配置
**消息通知路由**：
- 包含消息通知相关的API路由，如系统消息管理、短信配置、模板消息管理等
## 4. 数据库设计
### 4.1 系统消息表（message_system）
| 字段名 | 数据类型 | 描述 |
|--------|----------|------|
| id | int(10) unsigned | 消息ID |
| uid | int(10) | 接收用户ID |
| title | varchar(100) | 消息标题 |
| content | text | 消息内容 |
| type | varchar(20) | 消息类型 |
| status | tinyint(1) | 阅读状态（0-未读，1-已读） |
| add_time | int(10) | 添加时间 |
| read_time | int(10) | 阅读时间 |
### 4.2 短信发送记录表（sms_record）
| 字段名 | 数据类型 | 描述 |
|--------|----------|------|
| id | int(10) unsigned | 记录ID |
| phone | varchar(20) | 接收手机号 |
| template_id | varchar(50) | 短信模板ID |
| template_param | text | 模板参数（JSON格式） |
| content | text | 短信内容 |
| status | tinyint(1) | 发送状态（0-失败，1-成功） |
| error_msg | varchar(255) | 错误信息 |
| add_time | int(10) | 发送时间 |
### 4.3 系统通知配置表（system_notification）
| 字段名 | 数据类型 | 描述 |
|--------|----------|------|
| id | int(10) unsigned | 配置ID |
| mark | varchar(50) | 通知标识 |
| title | varchar(100) | 通知标题 |
| scene | varchar(50) | 通知场景 |
| type | varchar(20) | 通知类型（system-系统消息，sms-短信，wechat-微信模板消息） |
| template | text | 通知模板 |
| is_open | tinyint(1) | 是否开启（0-关闭，1-开启） |
| sort | int(10) | 排序 |
| add_time | int(10) | 添加时间 |
### 4.4 模板消息表（template_message）
| 字段名 | 数据类型 | 描述 |
|--------|----------|------|
| id | int(10) unsigned | 模板ID |
| type | varchar(20) | 模板类型（wechat-公众号，routine-小程序） |
| name | varchar(50) | 模板名称 |
| template_id | varchar(100) | 微信模板ID |
| short_key | varchar(50) | 模板短键 |
| content | text | 模板内容 |
| example | text | 模板示例 |
| status | tinyint(1) | 状态（0-禁用，1-启用） |
| add_time | int(10) | 添加时间 |
## 5. API接口说明
### 5.1 系统消息管理
#### 5.1.1 获取系统消息列表
- **请求URL**：`/adminapi/v1/message/system/list`
- **请求方法**：GET
- **权限要求**：message/system/list
- **请求参数**：
- page：页码
- limit：每页数量
- keyword：搜索关键词
- status：阅读状态
- **返回结果**：系统消息列表数据
#### 5.1.2 发送系统消息
- **请求URL**：`/adminapi/v1/message/system/send`
- **请求方法**：POST
- **权限要求**：message/system/send
- **请求参数**：
- uids：用户ID数组
- title：消息标题
- content：消息内容
- type：消息类型
- **返回结果**：操作结果
### 5.2 短信管理
#### 5.2.1 获取短信模板列表
- **请求URL**：`/adminapi/v1/message/sms/template/list`
- **请求方法**：GET
- **权限要求**：message/sms/template/list
- **返回结果**：短信模板列表数据
#### 5.2.2 发送短信
- **请求URL**：`/adminapi/v1/message/sms/send`
- **请求方法**：POST
- **权限要求**：message/sms/send
- **请求参数**：
- phone：接收手机号
- template_id：短信模板ID
- params：模板参数（JSON格式）
- **返回结果**：操作结果
### 5.3 模板消息管理
#### 5.3.1 获取模板消息列表
- **请求URL**：`/adminapi/v1/message/template/list`
- **请求方法**：GET
- **权限要求**：message/template/list
- **请求参数**：
- type：模板类型（wechat-公众号，routine-小程序）
- **返回结果**：模板消息列表数据
#### 5.3.2 发送模板消息
- **请求URL**：`/adminapi/v1/message/template/send`
- **请求方法**：POST
- **权限要求**：message/template/send
- **请求参数**：
- openid：用户openid
- template_id：模板ID
- data：模板数据（JSON格式）
- page：跳转页面
- **返回结果**：操作结果
### 5.4 通知场景配置
#### 5.4.1 获取通知场景列表
- **请求URL**：`/adminapi/v1/message/notification/list`
- **请求方法**：GET
- **权限要求**：message/notification/list
- **返回结果**：通知场景列表数据
#### 5.4.2 配置通知场景
- **请求URL**：`/adminapi/v1/message/notification/config`
- **请求方法**：POST
- **权限要求**：message/notification/config
- **请求参数**：
- scene：通知场景
- config：通知配置（JSON格式，包含各通知渠道的开启状态和模板）
- **返回结果**：操作结果
### 5.5 用户端接口
#### 5.5.1 获取用户消息列表
- **请求URL**：`/api/v1/user/message/list`
- **请求方法**：GET
- **权限要求**：登录用户
- **请求参数**：
- page：页码
- limit：每页数量
- type：消息类型
- **返回结果**：用户消息列表数据
#### 5.5.2 标记消息为已读
- **请求URL**：`/api/v1/user/message/read/{id}`
- **请求方法**：PUT
- **权限要求**：登录用户
- **返回结果**：操作结果
## 5. 开发规范与流程
### 5.1 代码规范
1. **命名规范**：
- 类名采用大驼峰命名法，如 `NoticeService`
- 方法名采用小驼峰命名法，如 `sendSystemMessage`
- 变量名采用小驼峰命名法，如 `messageContent`
- 常量名采用全大写，下划线分隔，如 `NOTICE_SCENE_ORDER_PAY`
2. **代码结构**：
- 严格遵循分层架构，禁止跨层调用
- 每个方法职责单一，代码行数控制在50行以内
- 适当添加注释，说明方法功能、参数含义和返回值
- 所有通知发送必须记录日志，便于追溯
3. **事件驱动**：
- 所有通知场景必须通过事件触发
- 事件名称必须清晰明了，反映触发场景
- 事件监听器必须统一处理，便于管理
### 5.2 开发流程
1. **需求分析**：明确消息通知的功能需求和业务场景
2. **设计阶段**：设计事件结构、API接口和业务流程
3. **编码实现**：
- 定义事件类（如果需要）
- 在NoticeListener中添加事件处理方法
- 实现通知发送逻辑
- 添加API接口
4. **单元测试**：编写单元测试，确保功能正确性
5. **集成测试**：进行模块集成测试，测试通知与其他模块的交互
6. **性能测试**：对高频通知场景进行性能测试
7. **代码审查**：提交代码审查，确保代码质量
8. **部署上线**：部署到生产环境
## 6. 常见问题与解决方案
### 6.1 通知发送失败
**问题**：通知发送失败，如短信发送失败、模板消息发送失败
**解决方案**：
1. 检查配置是否正确，如API密钥、模板ID等
2. 检查第三方服务是否正常，如短信服务商、微信接口等
3. 查看发送日志，定位具体错误原因
4. 实现重试机制，对发送失败的通知进行重试
### 6.2 通知延迟
**问题**：通知发送延迟，如订单支付后很久才收到通知
**解决方案**：
1. 检查队列配置，确保队列服务正常运行
2. 优化通知发送逻辑，减少处理时间
3. 增加队列消费者数量，提高处理能力
4. 实现异步发送，避免阻塞主流程
### 6.3 通知重复发送
**问题**：同一通知重复发送给用户
**解决方案**：
1. 实现幂等性处理，确保同一事件不会触发多次通知
2. 检查事件触发逻辑，避免重复触发
3. 在通知发送前检查是否已经发送过
4. 实现去重机制，过滤重复通知
### 6.4 通知模板管理混乱
**问题**：通知模板过多，管理混乱
**解决方案**：
1. 对模板进行分类管理，如按通知渠道、按业务场景
2. 建立模板命名规范，清晰反映模板用途
3. 定期清理无用模板
4. 实现模板版本管理，便于回滚
## 7. 扩展与定制
### 7.1 添加新的通知场景
1. **定义场景常量**：在相关常量类中添加新的通知场景常量
2. **添加事件处理**：在NoticeListener中添加对应的事件处理方法
3. **配置模板**：在system_notification表中添加对应的通知模板配置
4. **添加触发点**：在业务逻辑中添加事件触发代码
5. **前端配置**：在后台管理界面中添加对应的配置项
### 7.2 添加新的通知渠道
1. **实现服务类**：创建新的通知服务类，继承NoticeService
2. **添加配置项**：在系统配置中添加新的通知渠道配置
3. **更新事件监听器**：在NoticeListener中添加新渠道的通知发送逻辑
4. **前端配置**：在后台管理界面中添加对应的配置项
### 7.3 自定义通知模板
1. **添加模板字段**：在system_notification表中添加模板字段
2. **更新模板管理**：修改模板管理功能，支持自定义模板
3. **实现模板渲染**：在通知服务中添加模板渲染逻辑
4. **前端配置**：在后台管理界面中添加模板编辑功能
## 8. 文档更新记录
| 版本 | 更新日期 | 更新内容 | 更新人 |
|------|----------|----------|--------|
| 1.0 | 2026-01-19 | 初始版本，包含系统消息管理、短信通知管理、模板消息管理、企业微信消息管理、通知场景配置等核心功能 | AI Assistant |
## 9. 附录
### 9.1 核心类关系图
```
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ NoticeService │────▶│ NoticeListener │────▶│ 各种通知服务 │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│
▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ SystemMessage │◀────│ MessageSystem │ │ SmsService │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│
▼
┌─────────────────────────┐
│ TemplateMessageServices │
├─────────────────────────┤
│ - 公众号模板消息 │
│ - 小程序订阅消息 │
└─────────────────────────┘
```
### 9.2 通知流程示意图
```
通知流程：
1. 业务系统触发事件（如订单支付成功）
2. 事件监听器捕获事件
3. 根据事件类型查找对应的通知配置
4. 遍历配置的通知渠道
5. 调用对应服务发送通知
a. 发送系统消息
b. 发送短信通知
c. 发送模板消息
d. 发送企业微信消息
6. 记录通知发送日志
7. 返回发送结果
```
### 9.3 支持的通知场景
| 场景名称 | 描述 |
|----------|------|
| order_pay | 订单支付成功 |
| order_delivery | 订单发货 |
| order_received | 订单收货 |
| order_refund | 订单退款 |
| order_price_edit | 订单改价 |
| recharge_success | 充值成功 |
| extract_success | 提现成功 |
| extract_fail | 提现失败 |
| brokerage_arrive | 佣金到账 |
| bargain_success | 砍价成功 |
| pink_success | 拼团成功 |
| pink_fail | 拼团失败 |
| user_register | 用户注册 |
| user_login | 用户登录 |
| spread_bind | 推广关系绑定 |
### 9.4 支持的通知渠道
| 渠道名称 | 描述 |
|----------|------|
| system | 系统消息（站内信） |
| sms | 短信通知 |
| wechat | 公众号模板消息 |
| routine | 小程序订阅消息 |
| enterprise_wechat | 企业微信消息 |
---
> **提示**：该文档由AI生成，仅供参考。

423
docs/phpapi/物流管理开发文档.md Normal file
View File

@ -0,0 +1,423 @@
# 物流管理开发文档
## 1. 文档概述
### 1.1 文档目的
本文档旨在详细说明CRMEB系统中物流管理模块的设计架构、核心功能、代码实现及开发规范，为系统开发人员提供完整的开发参考。
### 1.2 适用范围
本文档适用于CRMEB系统开发人员、维护人员及二次开发人员，用于指导物流管理模块的开发、扩展和维护工作。
### 1.3 术语定义
| 术语 | 解释 |
|------|------|
| 快递公司 | 提供物流配送服务的公司，如顺丰、中通、圆通等 |
| 物流模板 | 定义商品运费计算规则的模板，包含计费方式、区域配送规则等 |
| 电子面单 | 在线生成的快递单，可直接打印使用 |
| 配送员 | 负责配送订单的人员 |
| 物流单号 | 快递包裹的唯一标识，用于查询物流信息 |
| 批量发货 | 一次处理多个订单的发货操作 |
## 2. 核心功能模块
### 2.1 快递公司管理
- **快递公司列表**：展示所有快递公司，支持搜索、分页
- **快递公司添加**：添加新的快递公司
- **快递公司编辑**：修改快递公司信息，包括名称、编码、状态等
- **快递公司删除**：删除快递公司
- **快递公司状态管理**：启用/禁用快递公司
- **同步平台快递公司**：从物流平台同步最新的快递公司信息
- **物流信息查询接口**：提供物流信息查询API
### 2.2 物流模板管理
- **物流模板列表**：展示所有物流模板，支持搜索、分页
- **物流模板添加**：添加新的物流模板
- **物流模板编辑**：修改物流模板信息
- **物流模板删除**：删除物流模板
- **计费方式设置**：支持按件数、按重量、按体积计费
- **区域配送设置**：设置不同地区的配送规则
- **包邮规则设置**：设置指定地区的包邮条件
- **不送达区域设置**：设置不配送的地区
- **模板排序与状态管理**：调整模板排序和状态
### 2.3 订单配送管理
- **订单发货**：处理订单发货，支持快递发货、自提配送
- **物流信息查询**：查询订单的物流信息
- **批量发货**：支持批量处理多个订单的发货
- **电子面单打印**：在线生成和打印电子面单
- **配送员管理**：添加、编辑、删除配送员
- **物流单号管理**：管理订单的物流单号
- **订单拆分发货**：将一个订单拆分成多个包裹发货
- **商家寄件**：支持商家通过系统下单寄件
## 3. 代码结构与设计
### 3.1 架构设计
系统采用分层架构设计，严格遵循MVC设计模式：
```
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Controllers │ │ Services │ │ Daos │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │ │
└───────────────────────┼───────────────────────┘
│
┌─────────────────┐
│ Models │
└─────────────────┘
│
┌─────────────────┐
│ 数据库 │
└─────────────────┘
```
### 3.2 核心文件结构
#### 3.2.1 快递公司管理
- **控制器**：`crmeb/app/adminapi/controller/v1/freight/Express.php`
- **服务层**：`crmeb/app/services/shipping/ExpressServices.php`
- **数据访问层**：`crmeb/app/dao/shipping/ExpressDao.php`
- **路由配置**：`crmeb/app/adminapi/route/freight.php`
#### 3.2.2 物流模板管理
- **控制器**：`crmeb/app/adminapi/controller/v1/setting/ShippingTemplates.php`
- **服务层**：`crmeb/app/services/shipping/ShippingTemplatesServices.php`
- **数据访问层**：`crmeb/app/dao/shipping/ShippingTemplatesDao.php`
- **模型**：`crmeb/app/model/shipping/ShippingTemplates.php`
#### 3.2.3 订单配送管理
- **订单控制器**：`crmeb/app/adminapi/controller/v1/order/StoreOrder.php`
- **配送员管理控制器**：`crmeb/app/adminapi/controller/v1/order/DeliveryService.php`
- **配送服务层**：`crmeb/app/services/order/DeliveryServiceServices.php`
- **订单配送服务**：`crmeb/app/services/order/StoreOrderDeliveryServices.php`
## 4. 数据库设计
### 4.1 快递公司表（express）
| 字段名 | 数据类型 | 描述 |
|--------|----------|------|
| id | int(10) unsigned | 快递公司ID |
| name | varchar(50) | 快递公司名称 |
| code | varchar(20) | 快递公司编码 |
| logo | varchar(255) | 快递公司Logo |
| sort | int(10) | 排序 |
| status | tinyint(1) | 状态（0-禁用，1-启用） |
| is_show | tinyint(1) | 是否显示（0-不显示，1-显示） |
| add_time | int(10) | 添加时间 |
### 4.2 物流模板表（shipping_templates）
| 字段名 | 数据类型 | 描述 |
|--------|----------|------|
| id | int(10) unsigned | 模板ID |
| name | varchar(50) | 模板名称 |
| type | tinyint(1) | 计费方式（0-按件数，1-按重量，2-按体积） |
| sregion | text | 配送区域（JSON格式） |
| srules | text | 配送规则（JSON格式） |
| sort | int(10) | 排序 |
| status | tinyint(1) | 状态（0-禁用，1-启用） |
| add_time | int(10) | 添加时间 |
### 4.3 物流模板区域表（shipping_templates_region）
| 字段名 | 数据类型 | 描述 |
|--------|----------|------|
| id | int(10) unsigned | 区域ID |
| temp_id | int(10) | 模板ID |
| region | text | 区域（JSON格式） |
| first | decimal(10,2) | 首件/首重/首体积 |
| first_price | decimal(10,2) | 首件/首重/首体积价格 |
| continue | decimal(10,2) | 续件/续重/续体积 |
| continue_price | decimal(10,2) | 续件/续重/续体积价格 |
| add_time | int(10) | 添加时间 |
### 4.4 订单表（store_order）
| 字段名 | 数据类型 | 描述 |
|--------|----------|------|
| id | int(10) unsigned | 订单ID |
| express_code | varchar(20) | 快递公司编码 |
| express_no | varchar(50) | 物流单号 |
| shipping_type | tinyint(1) | 配送方式（0-快递，1-自提） |
| delivery_type | tinyint(1) | 发货方式（0-未发货，1-已发货，2-已完成） |
| delivery_time | int(10) | 发货时间 |
| // 其他订单字段 | // 数据类型 | // 描述 |
### 4.5 配送员表（delivery_service）
| 字段名 | 数据类型 | 描述 |
|--------|----------|------|
| id | int(10) unsigned | 配送员ID |
| name | varchar(20) | 配送员姓名 |
| phone | varchar(20) | 配送员手机号 |
| avatar | varchar(255) | 配送员头像 |
| status | tinyint(1) | 状态（0-禁用，1-启用） |
| add_time | int(10) | 添加时间 |
## 5. API接口说明
### 5.1 快递公司管理
#### 5.1.1 获取快递公司列表
- **请求URL**：`/adminapi/v1/freight/express/list`
- **请求方法**：GET
- **权限要求**：freight/express/list
- **请求参数**：
- page：页码
- limit：每页数量
- keyword：搜索关键词
- status：状态
- **返回结果**：快递公司列表数据
#### 5.1.2 添加快递公司
- **请求URL**：`/adminapi/v1/freight/express/create`
- **请求方法**：POST
- **权限要求**：freight/express/create
- **请求参数**：
- name：快递公司名称
- code：快递公司编码
- logo：快递公司Logo
- sort：排序
- **返回结果**：操作结果
#### 5.1.3 同步平台快递公司
- **请求URL**：`/adminapi/v1/freight/express/sync`
- **请求方法**：POST
- **权限要求**：freight/express/sync
- **返回结果**：操作结果
### 5.2 物流模板管理
#### 5.2.1 获取物流模板列表
- **请求URL**：`/adminapi/v1/setting/shipping/template/list`
- **请求方法**：GET
- **权限要求**：setting/shipping/template/list
- **请求参数**：
- page：页码
- limit：每页数量
- keyword：搜索关键词
- **返回结果**：物流模板列表数据
#### 5.2.2 添加物流模板
- **请求URL**：`/adminapi/v1/setting/shipping/template/create`
- **请求方法**：POST
- **权限要求**：setting/shipping/template/create
- **请求参数**：
- name：模板名称
- type：计费方式
- sregion：配送区域
- srules：配送规则
- **返回结果**：操作结果
### 5.3 订单配送管理
#### 5.3.1 订单发货
- **请求URL**：`/adminapi/v1/order/delivery/{id}`
- **请求方法**：PUT
- **权限要求**：order/delivery
- **请求参数**：
- delivery_type：发货类型（0-快递发货，1-电子面单，2-商家寄件）
- express_code：快递公司编码
- express_no：物流单号
- delivery_name：发货人姓名
- delivery_phone：发货人手机号
- **返回结果**：操作结果
#### 5.3.2 批量发货
- **请求URL**：`/adminapi/v1/order/delivery/batch`
- **请求方法**：POST
- **权限要求**：order/delivery/batch
- **请求参数**：
- orders：订单ID数组
- delivery_type：发货类型
- express_code：快递公司编码
- express_no：物流单号
- **返回结果**：操作结果
#### 5.3.3 查询物流信息
- **请求URL**：`/adminapi/v1/order/express/{id}`
- **请求方法**：GET
- **权限要求**：order/express
- **返回结果**：物流信息数据
#### 5.3.4 获取配送员列表
- **请求URL**：`/adminapi/v1/order/delivery/service/list`
- **请求方法**：GET
- **权限要求**：order/delivery/service/list
- **请求参数**：
- page：页码
- limit：每页数量
- keyword：搜索关键词
- **返回结果**：配送员列表数据
## 5. 开发规范与流程
### 5.1 代码规范
1. **命名规范**：
- 类名采用大驼峰命名法，如 `ExpressServices`
- 方法名采用小驼峰命名法，如 `getExpressList`
- 变量名采用小驼峰命名法，如 `shippingTemplate`
- 常量名采用全大写，下划线分隔，如 `SHIPPING_TYPE_EXPRESS`
2. **代码结构**：
- 严格遵循分层架构，禁止跨层调用
- 每个方法职责单一，代码行数控制在50行以内
- 适当添加注释，说明方法功能、参数含义和返回值
- 所有物流操作必须记录日志，便于追溯
3. **性能优化**：
- 物流查询结果必须缓存，减少API调用次数
- 批量操作必须使用事务，确保数据一致性
- 大数据量操作必须使用队列，避免阻塞主流程
### 5.2 开发流程
1. **需求分析**：明确物流管理的功能需求和业务逻辑
2. **设计阶段**：设计数据结构、API接口和业务流程
3. **编码实现**：
- 实现物流服务层逻辑
- 实现物流控制器接口
- 实现物流模板和计费规则
4. **单元测试**：编写单元测试，确保功能正确性
5. **集成测试**：进行模块集成测试，测试物流与订单等模块的交互
6. **性能测试**：对物流查询、批量发货等操作进行性能测试
7. **代码审查**：提交代码审查，确保代码质量
8. **部署上线**：部署到生产环境
## 6. 常见问题与解决方案
### 6.1 物流信息查询失败
**问题**：调用物流查询API失败
**解决方案**：
1. 检查快递公司编码是否正确
2. 检查物流单号是否正确
3. 检查物流平台API密钥是否有效
4. 实现重试机制，处理网络异常
5. 添加日志记录，便于排查问题
### 6.2 批量发货超时
**问题**：批量处理大量订单发货时超时
**解决方案**：
1. 使用队列异步处理批量发货
2. 优化数据库操作，减少查询次数
3. 实现分批处理，减少单次处理数量
4. 增加服务器资源，提高并发处理能力
### 6.3 物流模板计算错误
**问题**：根据物流模板计算的运费与预期不符
**解决方案**：
1. 检查物流模板配置是否正确
2. 检查区域划分是否合理
3. 检查计费规则是否正确
4. 添加运费计算日志，便于排查问题
### 6.4 电子面单打印失败
**问题**：电子面单生成或打印失败
**解决方案**：
1. 检查电子面单配置是否正确
2. 检查打印机连接是否正常
3. 检查模板格式是否正确
4. 实现重试机制，处理打印异常
## 7. 扩展与定制
### 7.1 添加新的物流公司
1. **数据库操作**：在express表中添加新的物流公司信息
2. **代码修改**：
- 更新快递公司列表
- 实现该物流公司的物流查询接口
3. **前端修改**：在前端添加新的物流公司选项
### 7.2 扩展物流模板计费方式
1. **数据库修改**：在shipping_templates表中添加新的计费方式
2. **代码修改**：
- 更新物流模板配置功能
- 实现新的计费方式计算逻辑
3. **前端修改**：在前端添加新的计费方式选项
### 7.3 集成第三方物流平台
1. **设计集成方案**：确定与第三方物流平台的集成方式
2. **实现API对接**：实现与第三方物流平台的API对接
3. **更新物流查询逻辑**：使用第三方物流平台的查询接口
4. **前端修改**：在前端添加第三方物流平台的相关功能
## 8. 文档更新记录
| 版本 | 更新日期 | 更新内容 | 更新人 |
|------|----------|----------|--------|
| 1.0 | 2026-01-19 | 初始版本，包含快递公司管理、物流模板管理、订单配送管理等核心功能 | AI Assistant |
## 9. 附录
### 9.1 核心类关系图
```
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Controllers │ │ Services │ │ Daos │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │ │
└───────────────────────┼───────────────────────┘
│
┌─────────────────┐
│ Models │
└─────────────────┘
│
┌─────────────────┐
│ 数据库 │
└─────────────────┘
```
### 9.2 订单发货流程图
```
订单发货流程：
1. 管理员进入订单详情页
2. 点击"发货"按钮
3. 选择发货方式（快递发货、电子面单、商家寄件）
4. 填写物流信息（快递公司、物流单号等）
5. 提交发货请求
6. 系统更新订单状态为已发货
7. 系统记录物流信息
8. 触发物流通知事件
9. 发送物流通知给用户
```
### 9.3 物流查询流程图
```
物流查询流程：
1. 用户或管理员请求查询物流信息
2. 系统验证请求合法性
3. 检查缓存中是否有物流信息
4. 缓存命中，返回缓存数据
5. 缓存未命中，调用物流查询API
6. 解析API返回结果
7. 缓存物流信息
8. 返回物流信息给请求方
```
### 9.4 物流模板计费方式
| 计费方式 | 描述 |
|----------|------|
| 按件数 | 按照商品件数计算运费 |
| 按重量 | 按照商品重量计算运费 |
| 按体积 | 按照商品体积计算运费 |
### 9.5 订单配送状态
| 状态值 | 描述 |
|--------|------|
| 0 | 未发货 |
| 1 | 已发货 |
| 2 | 已完成 |
### 9.6 配送方式
| 方式值 | 描述 |
|--------|------|
| 0 | 快递配送 |
| 1 | 门店自提 |
---
> **提示**：该文档由AI生成，仅供参考。

404
docs/phpapi/系统分销开发文档.md Normal file
View File

@ -0,0 +1,404 @@
# 系统分销开发文档
## 1. 分销机制概述
CRMEB系统实现了完整的分销功能，支持二级分销、分销等级、佣金计算、分销申请审核等核心功能。分销系统通过推广关系链实现用户之间的推广和佣金分配，帮助商家扩大销售渠道，提高用户粘性。
### 1.1 核心功能
- **二级分销**：支持一级和二级分销关系，可配置分销层级
- **分销等级**：支持多级分销等级，不同等级享受不同的佣金比例
- **佣金计算**：支持按商品售价比例计算佣金，可配置一二级佣金比例
- **自购返佣**：支持用户自购返佣功能，可配置是否开启
- **分销申请**：支持用户申请成为分销员，需管理员审核
- **分销关系管理**：支持查看和管理用户的分销关系链
- **佣金提现**：支持分销员申请提现佣金，管理员审核后发放
## 2. 核心组件
### 2.1 数据模型
- **AgentLevel**：分销等级模型，定义分销等级信息和佣金比例
- **AgentLevelTask**：分销等级任务模型，定义升级所需完成的任务
- **AgentLevelTaskRecord**：分销等级任务记录模型，记录用户任务完成情况
- **User**：用户模型，扩展了分销相关字段（spread_uid、agent_level等）
- **StoreOrder**：订单模型，记录订单的佣金信息
- **UserExtract**：用户提现模型，记录用户的提现申请
- **UserBrokerage**：用户佣金模型，记录用户的佣金流水
### 2.2 服务层
- **AgentLevelServices**：分销等级服务，处理分销等级的增删改查和升级逻辑
- **AgentManageServices**：分销管理服务，处理分销员的管理和统计
- **UserServices**：用户服务，扩展了分销相关功能
- **StoreOrderCreateServices**：订单创建服务，处理订单佣金计算
### 2.3 控制器
- **AgentManage**：分销员管理控制器，提供分销员列表和统计功能
- **AgentLevel**：分销等级控制器，提供分销等级的管理功能
- **SpreadApply**：分销申请控制器，处理用户的分销申请
## 3. 分销配置
### 3.1 系统配置项
分销功能的核心配置项在系统配置中管理，主要包括：
| 配置项 | 描述 | 默认值 |
|-------|------|-------|
| brokerage_func_status | 分销功能开关 | 0 |
| store_brokerage_ratio | 一级分销佣金比例 | 0 |
| store_brokerage_two | 二级分销佣金比例 | 0 |
| brokerage_level | 分销层级（1或2） | 2 |
| store_brokerage_statu | 分销员申请开关 | 0 |
| store_brokerage_binding_status | 分销绑定模式 | 0 |
| is_self_brokerage | 是否开启自购返佣 | 0 |
### 3.2 配置示例
```php
// 获取分销功能开关状态
sys_config('brokerage_func_status');
// 获取一级分销佣金比例
sys_config('store_brokerage_ratio');
// 获取二级分销佣金比例
sys_config('store_brokerage_two');
```
## 4. 分销等级
### 4.1 等级模型
分销等级模型定义了分销员的等级信息，包括佣金比例、升级条件等：
```php
class AgentLevel extends BaseModel
{
protected $pk = 'id';
protected $name = 'agent_level';
// 关联等级任务
public function task()
{
return $this->hasMany(AgentLevelTask::class, 'level_id', 'id')->where('is_del', 0);
}
}
```
### 4.2 等级升级机制
用户可以通过完成指定任务升级分销等级，享受更高的佣金比例：
```php
// 检查用户等级任务完成情况
public function checkUserLevelFinish($uid)
{
// 获取用户当前等级
$userInfo = app()->make(UserServices::class)->getUserInfo($uid);
if (!$userInfo) return false;
// 获取下一级等级信息
$levelList = $this->dao->getList(['is_del' => 0, 'status' => 1], '*', [], 0, 0, $userInfo['agent_level']);
// 检查任务完成情况
foreach ($levelList as $levelInfo) {
// 获取等级任务
$task_list = $levelInfo['task'] ?? [];
// 检查每个任务是否完成
foreach ($task_list as $task) {
$levelTaskServices->checkLevelTaskFinish($uid, (int)$task['id'], $task);
}
// 统计完成的任务数量
$finish_task = $levelTaskRecordServices->count([
'level_id' => $levelInfo['id'],
'uid' => $uid,
'task_id' => array_column($task_list, 'id')
]);
// 任务完成升级
if ($finish_task >= $levelInfo['task_num']) {
$userServices->update($uid, ['agent_level' => $levelInfo['id']]);
}
}
}
```
## 5. 佣金计算
### 5.1 佣金计算逻辑
佣金计算在订单创建时完成，根据商品售价和佣金比例计算：
```php
public function computeOrderProductTruePrice($cartInfo, $priceData, $addressId, $uid, $orderInfo)
{
// 获取分销佣金比例和返佣人员
[$storeBrokerageRatio, $storeBrokerageTwo, $spread_one_uid, $spread_two_uid] = $this->getSpreadDate($uid);
// 计算佣金
if ($storeBrokerageRatio > 0 || $storeBrokerageTwo > 0 || $staffPercent > 0 || $agentPercent > 0 || $divisionPercent > 0) {
// 计算商品售价
$price = bcsub((string)$cart['truePrice'], (string)$cart['truePostage'], 2);
// 计算一级佣金
if ($storeBrokerageRatio > 0) {
$brokerageRatio = bcdiv($storeBrokerageRatio, 100, 4);
$oneBrokerage = bcmul((string)$price, (string)$brokerageRatio, 2);
}
// 计算二级佣金
if ($storeBrokerageTwo > 0) {
$brokerageTwo = bcdiv($storeBrokerageTwo, 100, 4);
$twoBrokerage = bcmul((string)$price, (string)$brokerageTwo, 2);
}
// 记录佣金信息
$cart['one_brokerage'] = $oneBrokerage;
$cart['two_brokerage'] = $twoBrokerage;
}
return [$cartInfo, [$spread_one_uid, $spread_two_uid]];
}
```
### 5.2 分销层级控制
系统支持配置分销层级（1或2级），可根据配置调整佣金计算：
```php
// 判断返佣层级为一级时，将二级用户uid和二级分佣比例改为0
if (sys_config('brokerage_level') == 1) {
$storeBrokerageTwo = $spread_two_uid = 0;
}
```
### 5.3 自购返佣
系统支持配置用户自购返佣功能：
```php
// 获取上级和上上级的uid，开启自购获取自己和上级的uid
$spread_one_uid = $userServices->getSpreadUid($uid, $userInfo);
```
## 6. 分销申请与审核
### 6.1 分销申请
用户可以申请成为分销员，申请信息存储在数据库中等待管理员审核：
```php
// 分销申请接口
public function apply()
{
// 检查分销功能是否开启
if (!sys_config('brokerage_func_status')) {
throw new ApiException(100209);
}
// 检查是否已经是分销员
if ($this->services->checkUserPromoter($this->uid)) {
throw new ApiException(100210);
}
// 提交申请
$this->services->applySpread($this->uid, $this->request->post());
return app('json')->success(100211);
}
```
### 6.2 申请审核
管理员可以审核用户的分销申请，审核通过后用户成为分销员：
```php
// 分销申请审核接口
public function applyExamine($id, $uid, $status)
{
// 检查参数
if (!$id || !$uid || !in_array($status, [0, 1])) {
throw new AdminException(100026);
}
// 审核申请
$this->services->examineSpreadApply($id, $uid, $status);
return app('json')->success(100014);
}
```
## 7. 分销关系管理
### 7.1 推广关系绑定
用户通过分享链接或二维码注册时，会自动绑定推广关系：
```php
// 保存用户信息并绑定推广关系
public function setUserInfo($user, int $spreadUid = 0, string $userType = 'wechat')
{
$data = [
// 用户基本信息
'nickname' => $user['nickname'] ?? '',
'avatar' => $user['headimgurl'] ?? '',
// ... 其他字段
];
// 绑定推广关系
if ($spreadUid) {
$data['spread_uid'] = $spreadUid;
$data['spread_time'] = time();
}
// 保存用户信息
$res = $this->dao->save($data);
// 触发用户注册事件
event('UserRegisterListener', [$spreadUid, $userType, $user['nickname'], $res->uid, 1]);
return $res;
}
```
### 7.2 推广关系查询
系统提供接口查询用户的推广关系链：
```php
// 获取用户的一级和二级推广用户
public function getSpreadList(int $uid, array $where, bool $is_page = true)
{
// 获取一级推广用户
$one_list = $this->dao->getSpreadUserList($where, $uid, 1, $is_page);
// 获取二级推广用户
$two_list = $this->dao->getSpreadUserList($where, $uid, 2, $is_page);
return ['one_list' => $one_list, 'two_list' => $two_list];
}
```
## 8. 分销等级任务
### 8.1 任务类型
系统支持多种分销等级任务类型：
- **推广人数**：推广指定数量的用户
- **订单金额**：完成指定金额的订单
- **订单数量**：完成指定数量的订单
- **自购金额**：自购指定金额的商品
- **自购数量**：自购指定数量的商品
### 8.2 任务完成检查
系统会定期检查用户的任务完成情况，满足条件时自动升级：
```php
// 检查任务完成情况
public function checkLevelTaskFinish($uid, $taskId, $task)
{
// 根据任务类型检查完成情况
switch ($task['type']) {
case 1: // 推广人数
$count = $this->dao->getSpreadUserCount($uid);
break;
case 2: // 订单金额
$count = $this->dao->getUserOrderAmount($uid);
break;
case 3: // 订单数量
$count = $this->dao->getUserOrderCount($uid);
break;
// ... 其他任务类型
}
// 更新任务完成记录
if ($count >= $task['value']) {
$this->taskRecordServices->updateTaskRecord($uid, $taskId);
}
}
```
## 9. API接口
### 9.1 分销员管理接口
- **GET /api/admin/agent/manage/index**：分销员列表
- **GET /api/admin/agent/manage/get_badge**：分销员统计
- **GET /api/admin/agent/manage/get_stair_list**：推广人列表
### 9.2 分销等级接口
- **GET /api/admin/agent/level/index**：分销等级列表
- **POST /api/admin/agent/level/save**：添加分销等级
- **PUT /api/admin/agent/level/update/:id**：编辑分销等级
### 9.3 分销申请接口
- **GET /api/admin/agent/spread/apply/list**：分销申请列表
- **POST /api/admin/agent/spread/apply/examine/:id/:uid/:status**：分销申请审核
### 9.4 用户端接口
- **POST /api/user/spread/apply**：用户申请成为分销员
- **GET /api/user/spread/list**：获取推广用户列表
- **GET /api/user/agent/level_task_list**：获取分销等级任务列表
## 10. 最佳实践
### 10.1 分销等级设计
- **合理设置等级数量**：建议设置3-5个分销等级，过多等级会增加管理复杂度
- **梯度设置佣金比例**：不同等级的佣金比例应该有明显差异，激励用户升级
- **设置合理的升级条件**：升级条件应该具有可实现性，避免设置过高的门槛
### 10.2 佣金设置
- **合理设置佣金比例**：根据商品利润率设置合理的佣金比例，避免影响商家利润
- **控制分销层级**：建议使用二级分销，符合国家相关法规要求
- **开启自购返佣**：可以提高用户的购买积极性，增加销售额
### 10.3 推广关系管理
- **明确推广规则**：制定清晰的推广规则，避免用户之间的纠纷
- **定期清理无效关系**：定期清理长期不活跃的推广关系，保持数据整洁
- **保护用户隐私**：在展示推广关系时，注意保护用户的隐私信息
## 11. 常见问题
### 11.1 分销功能不生效
- 检查分销功能开关是否开启
- 检查佣金比例是否设置正确
- 检查用户是否具有推广资格
### 11.2 佣金计算错误
- 检查佣金比例设置是否正确
- 检查订单金额是否正确
- 检查分销层级设置是否正确
### 11.3 推广关系绑定失败
- 检查推广链接是否正确
- 检查推广参数是否传递正确
- 检查用户注册流程是否正确
### 11.4 分销等级不升级
- 检查升级条件是否设置正确
- 检查任务完成情况是否正确
- 检查升级逻辑是否存在bug
## 12. 总结
CRMEB系统的分销功能提供了完整的二级分销解决方案，支持分销等级、佣金计算、分销申请审核等核心功能。通过合理配置和使用分销功能，商家可以扩大销售渠道，提高用户粘性，实现销售增长。开发人员可以根据业务需求，基于现有框架扩展更多的分销功能，如三级分销、团队奖励等。
---
> **提示**：该文档由AI生成，仅供参考。

700
docs/phpapi/系统安装流程文档.md Normal file
View File

@ -0,0 +1,700 @@
# CRMEB 系统安装流程文档
## 📋 文档概述
本文档提供CRMEB开源商城系统的完整安装流程，适用于CRMEB 5.6.4+版本。
## 🖥️ 服务器环境要求
### 基础配置要求
| 配置项 | 最低配置 | 推荐配置 |
|--------|---------|---------|
| CPU | 1核 | 2核及以上 |
| 内存 | 1GB | 2GB及以上 |
| 硬盘 | 20GB SSD | 50GB SSD及以上 |
| 带宽 | 1Mbps | 5Mbps及以上 |
### 操作系统要求
| 系统类型 | 支持版本 |
|---------|---------|
| Linux | CentOS 7+/Ubuntu 18+/Debian 10+ |
| Windows | Windows Server 2012+ |
| macOS | 仅用于开发环境 |
### 软件环境要求
| 软件 | 最低版本 | 推荐版本 | 说明 |
|------|---------|---------|------|
| PHP | 7.1 | 7.4 | 必须开启PDO扩展 |
| MySQL | 5.7 | 8.0 | 推荐InnoDB引擎 |
| Redis | 3.0 | 7.0 | 可选，提升性能 |
| Nginx | 1.18 | 1.22 | 反向代理服务器 |
| Composer | 1.8 | 2.x | PHP依赖管理 |
| Git | 2.0 | 最新版本 | 代码版本控制 |
### PHP扩展要求
```
必须开启的扩展：
- fileinfo (文件信息)
- pdo (数据库操作)
- pdo_mysql (MySQL驱动)
- openssl (加密处理)
- mbstring (字符串处理)
- curl (HTTP请求)
- json (JSON处理)
- session (会话管理)
推荐开启的扩展：
- redis (Redis缓存)
- gd (图片处理)
- zip (压缩处理)
- bcmath (高精度计算)
```
### 禁用函数列表
```php
// php.ini 中需要取消禁用的函数
disable_functions =
; 移除以下函数：
; proc_open
; pcntl_signal
; pcntl_signal_dispatch
; pcntl_fork
; pcntl_wait
; pcntl_alarm
```
## 🐳 方式一：Docker 一键部署（推荐）
### 1. 环境准备
```bash
# 检查Docker是否安装
docker --version
# Docker version 20.10.x, build xxxxx
# 检查Docker Compose
docker-compose --version
# Docker Compose version v2.x.x
# 如未安装，请先安装Docker
# Ubuntu系统安装：
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
# 安装Docker Compose
sudo curl -L "https://github.com/docker/compose/releases/download/v2.20.0/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose
```
### 2. 获取项目代码
```bash
# 克隆项目
git clone https://gitee.com/ZhongBangKeJi/CRMEB.git crmeb
cd crmeb
# 切换到稳定版本分支（根据需要选择）
git checkout -b v5.6.4 origin/v5.6.4
```
### 3. 配置环境变量
```bash
# 复制环境变量模板
cp .env.example .env
# 编辑环境变量
vim .env
```
```ini
# 数据库配置
DB_HOST=mysql
DB_PORT=3306
DB_DATABASE=crmeb
DB_USERNAME=root
DB_PASSWORD=crmeb123456
# Redis配置
REDIS_HOST=redis
REDIS_PORT=6379
REDIS_PASSWORD=
# 应用配置
APP_DEBUG=true
APP_URL=http://localhost
# Admin后台配置
ADMIN_HTTPS=false
```
### 4. 一键启动
```bash
# 构建并启动所有服务
docker-compose up -d --build
# 查看服务状态
docker-compose ps
# 输出示例：
# Name Command State Ports
# ----------------------------------------------------------------------
# crmeb-app docker-php-entrypoint apach ... Up 0.0.0.0:80->80/tcp
# crmeb-mysql docker-entrypoint.sh mysqld ... Up 3306/tcp
# crmeb-redis docker-entrypoint.sh redis ... Up 6379/tcp
```
### 5. 访问安装向导
打开浏览器访问：`http://your-server-ip`
按照安装向导步骤完成系统安装：
1. 环境检测
2. 目录权限检查
3. 数据库配置
4. 管理员账号设置
5. 安装完成
### Docker 管理命令
```bash
# 启动服务
docker-compose start
# 停止服务
docker-compose stop
# 重启服务
docker-compose restart
# 查看日志
docker-compose logs -f
# 删除服务（保留数据）
docker-compose down
# 删除服务（包含数据卷）
docker-compose down -v
```
## 🖥️ 方式二：手动部署（宝塔面板）
### 1. 安装宝塔面板
```bash
# CentOS系统
yum install -y wget && wget -O install.sh http://download.bt.cn/install/install_6.0.sh && sh install.sh
# Ubuntu/Debian系统
wget -O install.sh http://download.bt.cn/install/install-ubuntu_6.0.sh && sudo bash install.sh
```
### 2. 登录宝塔面板
安装完成后，记录面板登录地址、用户名和密码，登录宝塔面板。
### 3. 安装环境套件
在宝塔面板中：
1. 点击「软件商店」
2. 安装以下软件：
- Nginx 1.22
- MySQL 5.7/8.0
- PHP 7.4
- phpMyAdmin 4.7（可选，用于数据库管理）
### 4. 创建站点
1. 点击「网站」→「添加站点」
2. 填写站点信息：
- 域名：`your-domain.com`（或IP用于测试）
- 根目录：`/www/wwwroot/crmeb`
- PHP版本：选择 7.4
- 数据库：选择创建数据库
- 数据库用户名和密码
- FTP：选择创建
### 5. 上传项目代码
```bash
# 方法一：通过宝塔面板上传
# 1. 在本地下载项目源码
# 2. 通过宝塔文件管理上传并解压
# 方法二：通过命令行
cd /www/wwwroot
wget https://gitee.com/ZhongBangKeJi/CRMEB/repository/archive/master.zip
unzip master.zip
mv CRMEB-master crmeb
```
### 6. 配置目录权限
```bash
# 设置目录权限
chmod -R 755 /www/wwwroot/crmeb
chmod -R 755 /www/wwwroot/crmeb/runtime
chmod -R 755 /www/wwwroot/crmeb/public/uploads
# 设置所有者
chown -R www:www /www/wwwroot/crmeb
```
### 7. 配置伪静态
在宝塔面板中：
1. 点击对应站点的「设置」
2. 选择「伪静态」
3. 添加以下规则：
```nginx
# ThinkPHP 伪静态规则
location / {
if (!-e $request_filename) {
rewrite ^(.*)$ /index.php?s=$1 last;
break;
}
}
# PHP配置
location ~ \.php$ {
fastcgi_pass unix:/tmp/php-cgi-74.sock;
fastcgi_index index.php;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
include fastcgi_params;
}
```
### 8. 配置PHP上传限制
在宝塔「软件商店」→「PHP 7.4」→「配置修改」中：
- upload_max_filesize：100M
- post_max_size：100M
- max_execution_time：300
- max_input_time：300
- memory_limit：256M
### 9. 访问安装
打开浏览器访问：`http://your-domain.com`
按照安装向导完成系统安装。
## 🖥️ 方式三：手动部署（命令行）
### 1. 安装PHP环境
```bash
# CentOS 7
yum install epel-release -y
yum install -y yum-utils
# 添加Remi源
yum install http://rpms.remirepo.net/enterprise/remi-release-7.rpm -y
# 安装PHP 7.4
yum-config-manager --enable remi-php74
yum install -y php php-cli php-fpm php-mysql php-xml php-mbstring php-curl php-redis php-gd php-zip php-bcmath
# 启动PHP-FPM
systemctl start php-fpm
systemctl enable php-fpm
```
### 2. 安装Nginx
```bash
# CentOS
yum install -y nginx
# 启动Nginx
systemctl start nginx
systemctl enable nginx
```
### 3. 安装MySQL
```bash
# CentOS 7 - 安装MySQL 5.7
wget https://dev.mysql.com/get/mysql57-community-release-el7-9.noarch.rpm
rpm -ivh mysql57-community-release-el7-9.noarch.rpm
yum install -y mysql-community-server
# 启动MySQL
systemctl start mysqld
systemctl enable mysqld
# 查看初始密码
grep 'temporary password' /var/log/mysqld.log
# 登录并修改密码
mysql -u root -p
```
```sql
-- MySQL 5.7 初始化
ALTER USER 'root'@'localhost' IDENTIFIED BY 'YourNewPassword!';
-- 创建数据库
CREATE DATABASE crmeb DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
-- 创建用户并授权
CREATE USER 'crmeb'@'localhost' IDENTIFIED BY 'crmeb_password!';
GRANT ALL PRIVILEGES ON crmeb.* TO 'crmeb'@'localhost';
FLUSH PRIVILEGES;
```
### 4. 安装Redis
```bash
# CentOS
yum install -y redis
# 启动Redis
systemctl start redis
systemctl enable redis
# 配置密码（编辑 /etc/redis.conf）
requirepass your_redis_password
```
### 5. 安装Composer
```bash
# 下载安装
curl -sS https://getcomposer.org/installer | php
mv composer.phar /usr/local/bin/composer
# 切换中国镜像（加速下载）
composer config -g repo.packagist composer https://mirrors.aliyun.com/composer/
```
### 6. 获取项目代码
```bash
# 克隆项目
cd /var/www
git clone https://gitee.com/ZhongBangKeJi/CRMEB.git crmeb
cd crmeb
# 切换到稳定版本
git checkout -b v5.6.4 origin/v5.6.4
```
### 7. 配置环境变量
```bash
# 复制环境变量模板
cp .env.example .env
# 编辑配置
vim .env
```
```ini
[APP]
DEBUG = true
DEFAULT_TIMEZONE = Asia/Shanghai
[DATABASE]
TYPE = mysql
HOSTNAME = 127.0.0.1
DATABASE = crmeb
USERNAME = crmeb
PASSWORD = crmeb_password!
HOSTPORT = 3306
CHARSET = utf8mb4
DEBUG = true
PREFIX = eb_
[CACHE]
TYPE = redis
HOST = 127.0.0.1
PORT = 6379
PREFIX = crmeb:
[LANG]
default_lang = zh-cn
```
### 8. 安装依赖
```bash
# 切换到项目目录
cd /var/www/crmeb
# 安装项目依赖
composer install --no-dev --optimize-autoloader
```
### 9. 配置Nginx站点
```bash
# 创建站点配置
vim /etc/nginx/conf.d/crmeb.conf
```
```nginx
server {
listen 80;
server_name your-domain.com;
root /var/www/crmeb/public;
index index.php index.html;
# 日志配置
access_log /var/log/nginx/crmeb_access.log;
error_log /var/log/nginx/crmeb_error.log;
# 静态文件缓存
location ~* \.(jpg|jpeg|png|gif|ico|css|js|woff|woff2|ttf|svg)$ {
expires 30d;
add_header Cache-Control "public, immutable";
}
# 主路由规则
location / {
try_files $uri $uri/ /index.php?s=$uri&$args;
}
# PHP处理
location ~ \.php$ {
fastcgi_pass 127.0.0.1:9000;
fastcgi_index index.php;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
include fastcgi_params;
# 超时配置
fastcgi_connect_timeout 300;
fastcgi_send_timeout 300;
fastcgi_read_timeout 300;
}
# 禁止访问敏感文件
location ~ /\.(env|git|htaccess) {
deny all;
}
}
```
```bash
# 测试配置
nginx -t
# 重载Nginx
nginx -s reload
```
### 10. 配置目录权限
```bash
# 设置权限
chmod -R 755 /var/www/crmeb
chmod -R 755 /var/www/crmeb/runtime
chmod -R 755 /var/www/crmeb/public/uploads
# 设置所有者
chown -R nginx:nginx /var/www/crmeb
```
### 11. 启动消息队列（可选）
```bash
# 使用Supervisor管理队列
yum install -y supervisor
# 配置Supervisor
vim /etc/supervisord.d/crmeb.ini
```
```ini
[program:crmeb-queue]
command=php /var/www/crmeb/think queue:listen --queue
directory=/var/www/crmeb
user=nginx
autostart=true
autorestart=true
stopasgroup=true
killasgroup=true
```
```bash
# 启动Supervisor
systemctl start supervisord
systemctl enable supervisord
# 启动队列任务
supervisorctl update
supervisorctl start crmeb-queue
```
### 12. 启动定时任务（可选）
```bash
# 编辑定时任务
crontab -e
# 添加以下任务
* * * * * cd /var/www/crmeb && php think timer start >> /dev/null 2>&1
```
### 13. 访问安装
打开浏览器访问：`http://your-domain.com`
按照安装向导完成系统安装。
## 🔧 安装后配置
### 1. 配置HTTPS（推荐）
```nginx
server {
listen 443 ssl http2;
server_name your-domain.com;
ssl_certificate /etc/nginx/ssl/crmeb.crt;
ssl_certificate_key /etc/nginx/ssl/crmeb.key;
ssl_session_timeout 5m;
ssl_protocols TLSv1.2 TLSv1.3;
ssl_ciphers ECDHE-RSA-AES128-GCM-SHA256:HIGH:!aNULL:!MD5:!RC4:!DHE;
# 其他配置同上...
}
# HTTP重定向到HTTPS
server {
listen 80;
server_name your-domain.com;
return 301 https://$server_name$request_uri;
}
```
### 2. 配置七牛云存储（可选）
在后台管理系统中：
1. 进入「系统设置」→「附件配置」
2. 选择「七牛云存储」
3. 配置以下参数：
- AccessKey
- SecretKey
- Bucket（存储空间名称）
- Domain（访问域名）
### 3. 配置短信服务（可选）
在后台管理系统中：
1. 进入「系统设置」→「短信设置」
2. 选择短信服务商（阿里云、腾讯云等）
3. 配置API密钥和签名
## 🧪 常见问题处理
### 问题1：页面显示500错误
```bash
# 检查PHP错误日志
tail -f /var/log/php-fpm/error.log
# 检查Nginx错误日志
tail -f /var/log/nginx/crmeb_error.log
# 检查项目runtime日志
tail -f /var/www/crmeb/runtime/log/xxx.log
```
### 问题2：数据库连接失败
```bash
# 测试MySQL连接
mysql -h localhost -u crmeb -p
# 检查数据库配置
cat /var/www/crmeb/.env | grep DB_
```
### 问题3：验证码不显示
```bash
# 检查PHP GD扩展
php -m | grep gd
# 检查目录权限
ls -la /var/www/crmeb/runtime/
```
### 问题4：上传文件失败
```bash
# 检查upload目录权限
chmod -R 755 /var/www/crmeb/public/uploads
chown -R nginx:nginx /var/www/crmeb/public/uploads
# 检查PHP配置
php -i | grep file_uploads
php -i | grep upload_max_filesize
```
### 问题5：微信支付回调失败
```bash
# 检查防火墙
systemctl status firewalld
iptables -L -n | grep 80
# 检查域名配置
# 确保回调域名已备案且可访问
```
## 🔐 安全加固建议
### 1. 修改默认后台路径
```bash
# 重命名admin目录
mv public/admin public/backend
# 修改路由配置
vim config/route.php
```
### 2. 配置安全密钥
```bash
# 在.env中配置
APP_KEY=your_random_string_32_chars
```
### 3. 定期更新系统
```bash
# 定期更新CRMEB
cd /var/www/crmeb
git fetch origin
git pull origin v5.6.4
# 更新依赖
composer update
```
## 📞 获取技术支持
- **官方文档**：https://doc.crmeb.com/
- **技术社区**：https://www.crmeb.com/ask/
- **Gitee Issues**：https://gitee.com/ZhongBangKeJi/CRMEB/issues
---
**文档版本**: v1.0
**更新日期**: 2024-01-17
**适用版本**: CRMEB 5.6.4+
💡 提示：建议生产环境使用HTTPS协议，定期备份数据库和文件。
---
> **提示**：该文档由AI生成，仅供参考。

403
docs/phpapi/系统用户管理开发文档.md Normal file
View File

@ -0,0 +1,403 @@
# 系统用户管理开发文档
## 1. 文档概述
### 1.1 文档目的
本文档旨在详细说明CRMEB系统中用户管理模块的设计架构、核心功能、代码实现及开发规范，为系统开发人员提供完整的开发参考。
### 1.2 适用范围
本文档适用于CRMEB系统开发人员、维护人员及二次开发人员，用于指导用户管理模块的开发、扩展和维护工作。
### 1.3 术语定义
| 术语 | 解释 |
|------|------|
| 用户 | 系统注册的终端用户，包括普通用户、会员用户等 |
| 会员等级 | 基于用户消费金额、积分等条件划分的用户等级 |
| 用户分组 | 用于管理用户的自定义分组 |
| 用户标签 | 用于标记用户特征的标签 |
| 推广关系 | 用户之间的推广绑定关系 |
| 分销 | 基于推广关系的销售分成模式 |
## 2. 核心功能模块
### 2.1 用户基本管理
- **用户列表**：展示用户基本信息，支持多条件搜索、分页
- **用户详情**：查看用户完整信息，包括基本信息、财务信息、等级信息等
- **用户添加**：后台手动添加用户
- **用户编辑**：修改用户信息
- **用户删除**：删除用户（物理删除/逻辑删除）
- **用户状态管理**：启用/禁用用户账号
- **密码重置**：重置用户登录密码
### 2.2 用户财务与积分管理
- **余额管理**：增加/减少用户余额，生成余额变动记录
- **积分管理**：增加/减少用户积分，生成积分变动记录
- **佣金管理**：管理用户分销佣金，生成佣金记录
### 2.3 会员等级管理
- **等级赠送**：后台手动赠送会员等级
- **等级清除**：清除用户会员等级
- **时长管理**：管理付费会员有效期
- **等级任务**：配置会员等级晋升任务
### 2.4 用户分类管理
- **用户分组**：创建、编辑、删除用户分组，将用户分配到不同分组
- **用户标签**：创建、编辑、删除用户标签，为用户添加/移除标签
- **标签分类**：管理标签分类
### 2.5 推广关系管理
- **推广人管理**：管理用户推广关系
- **推广绑定**：绑定/解绑用户推广关系
- **推广统计**：统计用户推广数据
### 2.6 其他功能
- **微信用户同步**：同步微信用户信息
- **用户注销管理**：处理用户注销请求
- **新人礼配置**：配置新用户注册奖励
## 3. 代码结构与设计
### 3.1 架构设计
系统采用分层架构设计，严格遵循MVC设计模式：
```
├── Model：模型层，定义数据结构和关联关系
├── Dao：数据访问层，处理数据库操作
├── Services：业务逻辑层，实现核心业务逻辑
├── Controller：控制层，处理HTTP请求和响应
└── Route：路由层，定义API路由
```
### 3.2 核心文件结构
#### 3.2.1 模型层（Model）
**文件路径**：`crmeb/app/model/user/User.php`
**核心功能**：
- 定义用户表结构和主键
- 包含自动填充字段（add_time, add_ip, last_time, last_ip）
- 定义与其他表的关联关系
- 提供丰富的搜索器方法
**主要关联关系**：
| 关联名称 | 关联模型 | 关联类型 |
|----------|----------|----------|
| systemUserLevel | SystemUserLevel | 一对一 |
| userGroup | UserGroup | 一对一 |
| spreadUser | User | 一对一 |
| spreadCount | User | 一对多 |
| label | UserLabel | 多对多 |
| address | UserAddress | 一对多 |
| extract | UserExtract | 一对多 |
| order | StoreOrder | 一对多 |
| agentLevel | AgentLevel | 一对一 |
| bill | UserBill | 一对多 |
#### 3.2.2 数据访问层（DAO）
**文件路径**：`crmeb/app/dao/user/UserDao.php`
**核心功能**：
- 继承自BaseDao，实现基础数据库操作
- 提供用户列表查询、统计计数、字段更新等方法
- 支持分页、条件搜索
- 包含分销用户、推广人列表等特殊查询
#### 3.2.3 业务服务层（Services）
**文件路径**：`crmeb/app/services/user/UserServices.php`
**核心功能**：
- 用户基本信息管理（增删改查）
- 积分和余额管理（增加、减少、记录）
- 会员等级管理（赠送、清除、时长管理）
- 用户标签和分组管理
- 推广关系管理
- 微信用户同步
- 新人礼奖励
- 各种统计数据生成
#### 3.2.4 控制器层（Controller）
**文件路径**：`crmeb/app/adminapi/controller/v1/user/User.php`
**核心功能**：
- 处理后台用户管理的API请求
- 提供用户列表、添加、编辑、删除等接口
- 支持会员等级赠送、付费会员时长管理
- 提供积分和余额调整功能
- 支持用户标签和分组管理
#### 3.2.5 路由配置
**文件路径**：`crmeb/app/adminapi/route/user.php`
**核心功能**：
- 定义完整的用户管理路由体系
- 包含用户管理、等级管理、分组管理、标签管理等模块
- 配置权限中间件
## 4. 数据库设计
### 4.1 用户表（user）
| 字段名 | 数据类型 | 描述 |
|--------|----------|------|
| uid | int(10) unsigned | 用户ID（主键） |
| user_type | tinyint(1) | 用户类型 |
| user_level | int(10) | 会员等级ID |
| agent_level | int(10) | 分销等级ID |
| group_id | int(10) | 用户分组ID |
| spread_uid | int(10) | 推广人ID |
| nickname | varchar(50) | 昵称 |
| avatar | varchar(255) | 头像 |
| phone | varchar(20) | 手机号 |
| email | varchar(50) | 邮箱 |
| password | varchar(60) | 密码 |
| salt | varchar(10) | 密码盐 |
| sex | tinyint(1) | 性别 |
| birthday | date | 生日 |
| add_time | int(10) | 添加时间 |
| add_ip | varchar(15) | 添加IP |
| last_time | int(10) | 最后登录时间 |
| last_ip | varchar(15) | 最后登录IP |
| user_money | decimal(10,2) | 用户余额 |
| frozen_money | decimal(10,2) | 冻结金额 |
| pay_money | decimal(10,2) | 消费金额 |
|积分字段 | int(10) | 积分 |
| sign_num | int(10) | 连续签到次数 |
| status | tinyint(1) | 用户状态 |
| del | tinyint(1) | 是否删除 |
### 4.2 用户扩展表
- **用户标签表（user_label）**：存储用户标签
- **用户分组表（user_group）**：存储用户分组
- **用户地址表（user_address）**：存储用户收货地址
- **用户余额变动表（user_bill）**：记录用户余额、积分、佣金变动
- **用户推广关系表（user_spread）**：记录用户推广关系
- **用户会员等级表（user_member）**：记录用户会员等级信息
## 5. API接口说明
### 5.1 基础接口
#### 5.1.1 用户列表
- **请求URL**：`/adminapi/v1/user/list`
- **请求方法**：GET
- **权限要求**：user/user/list
- **请求参数**：
- page：页码
- limit：每页数量
- keyword：搜索关键词
- date：时间范围
- user_level：会员等级
- group_id：用户分组
- status：用户状态
- **返回结果**：用户列表数据
#### 5.1.2 用户详情
- **请求URL**：`/adminapi/v1/user/detail/{uid}`
- **请求方法**：GET
- **权限要求**：user/user/detail
- **返回结果**：用户详细信息
#### 5.1.3 添加用户
- **请求URL**：`/adminapi/v1/user/create`
- **请求方法**：POST
- **权限要求**：user/user/create
- **请求参数**：用户基本信息
- **返回结果**：操作结果
#### 5.1.4 编辑用户
- **请求URL**：`/adminapi/v1/user/update/{uid}`
- **请求方法**：PUT
- **权限要求**：user/user/update
- **请求参数**：用户基本信息
- **返回结果**：操作结果
#### 5.1.5 删除用户
- **请求URL**：`/adminapi/v1/user/delete/{uid}`
- **请求方法**：DELETE
- **权限要求**：user/user/delete
- **返回结果**：操作结果
### 5.2 财务相关接口
#### 5.2.1 调整用户余额
- **请求URL**：`/adminapi/v1/user/money/{uid}`
- **请求方法**：PUT
- **权限要求**：user/user/money
- **请求参数**：
- money：变动金额
- mark：变动备注
- **返回结果**：操作结果
#### 5.2.2 调整用户积分
- **请求URL**：`/adminapi/v1/user/integral/{uid}`
- **请求方法**：PUT
- **权限要求**：user/user/integral
- **请求参数**：
- integral：变动积分
- mark：变动备注
- **返回结果**：操作结果
### 5.3 会员等级相关接口
#### 5.3.1 赠送会员等级
- **请求URL**：`/adminapi/v1/user/level/{uid}`
- **请求方法**：PUT
- **权限要求**：user/user/level
- **请求参数**：
- level：等级ID
- time：有效期（天）
- **返回结果**：操作结果
#### 5.3.2 清除会员等级
- **请求URL**：`/adminapi/v1/user/level/clear/{uid}`
- **请求方法**：PUT
- **权限要求**：user/user/level/clear
- **返回结果**：操作结果
### 5.4 用户分组与标签接口
#### 5.4.1 设置用户分组
- **请求URL**：`/adminapi/v1/user/group/{uid}`
- **请求方法**：PUT
- **权限要求**：user/user/group
- **请求参数**：
- group_id：分组ID
- **返回结果**：操作结果
#### 5.4.2 设置用户标签
- **请求URL**：`/adminapi/v1/user/label/{uid}`
- **请求方法**：PUT
- **权限要求**：user/user/label
- **请求参数**：
- label_ids：标签ID数组
- **返回结果**：操作结果
## 5. 开发规范与流程
### 5.1 代码规范
1. **命名规范**：
- 类名采用大驼峰命名法
- 方法名采用小驼峰命名法
- 变量名采用小驼峰命名法
- 常量名采用全大写，下划线分隔
2. **代码结构**：
- 严格遵循分层架构，禁止跨层调用
- 每个方法职责单一，代码行数控制在50行以内
- 适当添加注释，说明方法功能、参数含义和返回值
3. **数据库操作**：
- 所有数据库操作必须通过Dao层进行
- 使用ORM提供的查询构建器，避免直接编写SQL
- 批量操作使用事务处理
### 5.2 开发流程
1. **需求分析**：明确功能需求和业务逻辑
2. **设计阶段**：设计数据结构、API接口和业务流程
3. **编码实现**：按照分层架构编写代码
4. **单元测试**：编写单元测试，确保功能正确性
5. **集成测试**：进行模块集成测试
6. **代码审查**：提交代码审查，确保代码质量
7. **部署上线**：部署到生产环境
## 6. 常见问题与解决方案
### 6.1 用户密码加密
**问题**：用户密码如何加密存储？
**解决方案**：系统采用bcrypt算法对用户密码进行加密存储，确保密码安全。
### 6.2 用户登录状态管理
**问题**：如何管理用户登录状态？
**解决方案**：系统使用token机制管理用户登录状态，登录成功后生成token，后续请求携带token进行身份验证。
### 6.3 推广关系绑定
**问题**：如何处理用户推广关系的绑定？
**解决方案**：用户注册时，通过URL参数或邀请码获取推广人ID，自动绑定推广关系。
### 6.4 会员等级有效期计算
**问题**：如何计算会员等级有效期？
**解决方案**：系统根据当前时间加上有效期天数计算会员等级过期时间，过期后自动降级。
## 7. 扩展与定制
### 7.1 功能扩展
系统设计具有良好的扩展性，可通过以下方式扩展功能：
1. **添加新模型**：继承BaseModel，定义新的数据结构
2. **添加新服务**：继承BaseServices，实现新的业务逻辑
3. **添加新控制器**：继承BaseController，处理新的API请求
4. **添加新路由**：在路由文件中定义新的路由规则
### 7.2 事件扩展
系统在关键业务节点触发事件，可通过监听事件进行功能扩展：
1. **用户注册事件**：UserRegisterEvent
2. **用户登录事件**：UserLoginEvent
3. **用户积分变动事件**：UserIntegralChangeEvent
4. **用户余额变动事件**：UserMoneyChangeEvent
5. **会员等级变动事件**：UserLevelChangeEvent
### 7.3 钩子扩展
系统提供了多个钩子点，可通过钩子函数进行功能扩展：
1. **用户注册前钩子**：user_register_before
2. **用户注册后钩子**：user_register_after
3. **用户登录前钩子**：user_login_before
4. **用户登录后钩子**：user_login_after
5. **用户信息更新前钩子**：user_update_before
6. **用户信息更新后钩子**：user_update_after
## 8. 文档更新记录
| 版本 | 更新日期 | 更新内容 | 更新人 |
|------|----------|----------|--------|
| 1.0 | 2026-01-19 | 初始版本，包含用户管理核心功能 | AI Assistant |
## 9. 附录
### 9.1 核心类关系图
```
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ UserModel │ │ UserDao │ │ UserServices │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │ │
└───────────────────────┼───────────────────────┘
│
┌─────────────────┐
│ UserController│
└─────────────────┘
│
┌─────────────────┐
│ Routes │
└─────────────────┘
```
### 9.2 核心业务流程图
```
用户注册流程：
1. 用户提交注册信息
2. 验证手机号/邮箱
3. 生成用户记录
4. 绑定推广关系
5. 触发注册奖励
6. 返回注册结果
会员等级晋升流程：
1. 用户满足等级条件
2. 系统自动检查等级条件
3. 更新用户等级
4. 记录等级变动日志
5. 触发等级变动事件
用户积分变动流程：
1. 触发积分变动事件
2. 验证变动合法性
3. 更新用户积分
4. 生成积分变动记录
5. 返回变动结果
```
---
> **提示**：该文档由AI生成，仅供参考。

537
docs/phpapi/系统设置开发文档.md Normal file
View File

@ -0,0 +1,537 @@
# 系统设置开发文档
## 1. 文档概述
### 1.1 文档目的
本文档旨在详细说明CRMEB系统中系统设置模块的设计架构、核心功能、代码实现及开发规范，为系统开发人员提供完整的开发参考。
### 1.2 适用范围
本文档适用于CRMEB系统开发人员、维护人员及二次开发人员，用于指导系统设置模块的开发、扩展和维护工作。
### 1.3 术语定义
| 术语 | 解释 |
|------|------|
| RBAC | 基于角色的权限控制（Role-Based Access Control） |
| 管理员等级 | 管理员的层级关系，上级可管理下级 |
| 角色 | 权限的集合，用于分配给管理员 |
| 菜单权限 | 控制管理员可访问的菜单 |
| 操作权限 | 控制管理员可执行的操作 |
| 配置项 | 系统的各项设置参数 |
| 云存储 | 用于存储图片、文件等资源的云服务 |
| 定时任务 | 系统自动执行的任务 |
## 2. 核心功能模块
### 2.1 管理员管理
- **管理员列表**：展示管理员基本信息，支持搜索、分页
- **管理员添加**：添加新管理员，设置基本信息、角色、等级等
- **管理员编辑**：修改管理员信息，包括角色、等级、状态等
- **管理员删除**：删除管理员账号
- **状态管理**：启用/禁用管理员账号
- **密码重置**：重置管理员登录密码
- **权限继承**：基于等级的权限控制，上级可管理下级
### 2.2 角色管理
- **角色列表**：展示角色基本信息，支持搜索、分页
- **角色添加**：添加新角色，设置角色名称、等级、权限等
- **角色编辑**：修改角色信息，包括名称、等级、权限等
- **角色删除**：删除角色
- **状态管理**：启用/禁用角色
- **权限分配**：为角色分配菜单权限和操作权限
- **权限继承**：基于等级的角色控制
### 2.3 菜单管理
- **菜单列表**：展示菜单树状结构，支持搜索、分页
- **菜单添加**：添加新菜单，设置菜单名称、路径、图标、权限等
- **菜单编辑**：修改菜单信息，包括名称、路径、图标、权限等
- **菜单删除**：删除菜单
- **状态管理**：显示/隐藏菜单
- **权限标识管理**：设置菜单的权限标识
- **批量保存**：支持批量保存菜单信息
- **左侧菜单获取**：提供获取当前管理员可访问菜单的接口
### 2.4 系统配置
- **配置分类管理**：管理系统配置的分类
- **配置项管理**：添加、编辑、删除系统配置项
- **配置编辑**：编辑系统基本配置，如网站名称、LOGO、联系方式等
- **配置状态管理**：启用/禁用配置项
- **配置缓存**：管理配置缓存，提高系统性能
### 2.5 存储配置
- **存储方式管理**：配置系统使用的存储方式，如本地存储、阿里云OSS、腾讯云COS等
- **云存储配置**：配置各云存储服务的参数
- **存储域名管理**：设置资源访问域名
- **存储状态管理**：启用/禁用存储方式
### 2.6 系统日志
- **日志记录**：记录系统操作日志、登录日志等
- **日志查询**：支持按条件查询日志
- **日志分页**：分页展示日志信息
- **日志清理**：清理过期日志
### 2.7 数据备份
- **数据库备份**：备份系统数据库
- **备份管理**：管理备份文件，支持下载、删除
- **数据库恢复**：从备份文件恢复数据库
- **数据库优化**：优化数据库性能
### 2.8 定时任务
- **任务列表**：展示系统定时任务
- **任务添加**：添加新的定时任务
- **任务编辑**：修改定时任务信息
- **任务删除**：删除定时任务
- **任务状态管理**：启用/禁用定时任务
- **任务执行**：手动执行定时任务
### 2.9 系统路由管理
- **路由列表**：展示系统路由
- **路由同步**：同步系统路由到数据库
- **路由权限管理**：为路由分配权限
### 2.10 代码生成
- **代码生成配置**：配置代码生成规则
- **代码生成**：根据数据库表生成模型、控制器、视图等代码
- **生成记录管理**：管理代码生成记录
## 3. 代码结构与设计
### 3.1 架构设计
系统采用分层架构设计，严格遵循MVC设计模式：
```
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Routes │ │ Controllers │ │ Services │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │ │
└───────────────────────┼───────────────────────┘
│
┌─────────────────┐
│ Models │
└─────────────────┘
│
┌─────────────────┐
│ Daos │
└─────────────────┘
```
### 3.2 核心文件结构
#### 3.2.1 路由配置
- **系统设置路由**：`crmeb/app/adminapi/route/setting.php` - 包含管理员、角色、菜单、系统配置等路由
- **系统维护路由**：`crmeb/app/adminapi/route/system.php` - 包含存储配置、系统日志、数据备份、定时任务等路由
- **公共路由**：`crmeb/app/adminapi/route/common.php` - 包含左侧菜单获取等公共接口
#### 3.2.2 控制器层（Controller）
**系统设置控制器**：`crmeb/app/adminapi/controller/v1/setting/`
- `SystemAdmin.php` - 管理员管理控制器
- `SystemRole.php` - 角色管理控制器
- `SystemMenus.php` - 菜单管理控制器
- `SystemConfig.php` - 系统配置控制器
- `SystemStorage.php` - 存储配置控制器
- `SystemRoute.php` - 路由管理控制器
- `SystemCrud.php` - 代码生成控制器
**系统维护控制器**：`crmeb/app/adminapi/controller/v1/system/`
- `SystemLog.php` - 系统日志控制器
- `SystemDatabackup.php` - 数据备份控制器
- `SystemCrontab.php` - 定时任务控制器
#### 3.2.3 服务层（Services）
**系统设置Services**：`crmeb/app/services/system/`
- `SystemAdminServices.php` - 管理员管理服务
- `SystemRoleServices.php` - 角色管理服务
- `SystemMenusServices.php` - 菜单管理服务
- `SystemConfigServices.php` - 系统配置服务
- `SystemStorageServices.php` - 存储配置服务
- `SystemRouteServices.php` - 路由管理服务
- `SystemCrudServices.php` - 代码生成服务
**系统维护Services**：
- `SystemLogServices.php` - 系统日志服务
- `SystemDatabackupServices.php` - 数据备份服务
- `SystemCrontabServices.php` - 定时任务服务
#### 3.2.4 模型层（Model）
**系统设置模型**：`crmeb/app/model/system/`
- `SystemAdmin.php` - 管理员模型
- `SystemRole.php` - 角色模型
- `SystemMenus.php` - 菜单模型
- `SystemConfig.php` - 系统配置模型
- `SystemStorage.php` - 存储配置模型
- `SystemRoute.php` - 路由模型
**系统维护模型**：
- `SystemLog.php` - 系统日志模型
- `SystemDatabackup.php` - 数据备份模型
- `SystemCrontab.php` - 定时任务模型
## 4. 数据库设计
### 4.1 管理员表（system_admin）
| 字段名 | 数据类型 | 描述 |
|--------|----------|------|
| id | int(10) unsigned | 管理员ID |
| role_id | int(10) | 角色ID |
| level | tinyint(1) | 管理员等级 |
| username | varchar(20) | 用户名 |
| password | varchar(60) | 密码 |
| salt | varchar(10) | 密码盐 |
| real_name | varchar(20) | 真实姓名 |
| avatar | varchar(255) | 头像 |
| phone | varchar(20) | 手机号 |
| email | varchar(50) | 邮箱 |
| last_login_ip | varchar(15) | 最后登录IP |
| last_login_time | int(10) | 最后登录时间 |
| login_num | int(10) | 登录次数 |
| status | tinyint(1) | 状态（0-禁用，1-启用） |
| is_delete | tinyint(1) | 是否删除 |
| add_time | int(10) | 添加时间 |
### 4.2 角色表（system_role）
| 字段名 | 数据类型 | 描述 |
|--------|----------|------|
| id | int(10) unsigned | 角色ID |
| role_name | varchar(20) | 角色名称 |
| level | tinyint(1) | 角色等级 |
| auth_rules | text | 权限规则（JSON格式） |
| status | tinyint(1) | 状态（0-禁用，1-启用） |
| is_delete | tinyint(1) | 是否删除 |
| add_time | int(10) | 添加时间 |
### 4.3 菜单表（system_menus）
| 字段名 | 数据类型 | 描述 |
|--------|----------|------|
| id | int(10) unsigned | 菜单ID |
| pid | int(10) | 父菜单ID |
| menu_name | varchar(20) | 菜单名称 |
| menu_type | tinyint(1) | 菜单类型（0-目录，1-菜单，2-按钮） |
| url | varchar(100) | 菜单路径 |
| icon | varchar(50) | 菜单图标 |
| auth | varchar(50) | 权限标识 |
| open_type | varchar(10) | 打开方式（_self, _blank） |
| sort | int(10) | 排序 |
| is_show | tinyint(1) | 是否显示（0-隐藏，1-显示） |
| status | tinyint(1) | 状态（0-禁用，1-启用） |
| add_time | int(10) | 添加时间 |
### 4.4 系统配置表（system_config）
| 字段名 | 数据类型 | 描述 |
|--------|----------|------|
| id | int(10) unsigned | 配置ID |
| menu_name | varchar(20) | 菜单名称 |
| type | tinyint(1) | 配置类型 |
| title | varchar(50) | 配置标题 |
| name | varchar(50) | 配置名称 |
| value | text | 配置值 |
| placeholder | varchar(100) | 配置说明 |
| tips | varchar(255) | 配置提示 |
| sort | int(10) | 排序 |
| status | tinyint(1) | 状态（0-禁用，1-启用） |
| add_time | int(10) | 添加时间 |
### 4.5 存储配置表（system_storage）
| 字段名 | 数据类型 | 描述 |
|--------|----------|------|
| id | int(10) unsigned | 配置ID |
| name | varchar(20) | 存储名称 |
| type | varchar(20) | 存储类型（local, oss, cos, qiniu） |
| config | text | 存储配置（JSON格式） |
| is_default | tinyint(1) | 是否默认（0-否，1-是） |
| status | tinyint(1) | 状态（0-禁用，1-启用） |
| add_time | int(10) | 添加时间 |
### 4.6 系统日志表（system_log）
| 字段名 | 数据类型 | 描述 |
|--------|----------|------|
| id | int(10) unsigned | 日志ID |
| admin_id | int(10) | 管理员ID |
| admin_name | varchar(20) | 管理员名称 |
| ip | varchar(15) | 操作IP |
| url | varchar(255) | 操作URL |
| method | varchar(10) | 请求方法 |
| param | text | 请求参数 |
| type | tinyint(1) | 日志类型（0-登录日志，1-操作日志） |
| content | varchar(255) | 操作内容 |
| add_time | int(10) | 添加时间 |
## 5. API接口说明
### 5.1 管理员管理接口
#### 5.1.1 管理员列表
- **请求URL**：`/adminapi/v1/setting/admin/list`
- **请求方法**：GET
- **权限要求**：setting/admin/list
- **请求参数**：
- page：页码
- limit：每页数量
- keyword：搜索关键词
- status：状态
- **返回结果**：管理员列表数据
#### 5.1.2 添加管理员
- **请求URL**：`/adminapi/v1/setting/admin/create`
- **请求方法**：POST
- **权限要求**：setting/admin/create
- **请求参数**：
- role_id：角色ID
- username：用户名
- password：密码
- real_name：真实姓名
- phone：手机号
- email：邮箱
- **返回结果**：操作结果
#### 5.1.3 编辑管理员
- **请求URL**：`/adminapi/v1/setting/admin/update/{id}`
- **请求方法**：PUT
- **权限要求**：setting/admin/update
- **请求参数**：
- role_id：角色ID
- real_name：真实姓名
- phone：手机号
- email：邮箱
- status：状态
- **返回结果**：操作结果
### 5.2 角色管理接口
#### 5.2.1 角色列表
- **请求URL**：`/adminapi/v1/setting/role/list`
- **请求方法**：GET
- **权限要求**：setting/role/list
- **请求参数**：
- page：页码
- limit：每页数量
- keyword：搜索关键词
- status：状态
- **返回结果**：角色列表数据
#### 5.2.2 添加角色
- **请求URL**：`/adminapi/v1/setting/role/create`
- **请求方法**：POST
- **权限要求**：setting/role/create
- **请求参数**：
- role_name：角色名称
- level：角色等级
- auth_rules：权限规则（JSON格式）
- **返回结果**：操作结果
#### 5.2.3 权限分配
- **请求URL**：`/adminapi/v1/setting/role/permission/{id}`
- **请求方法**：PUT
- **权限要求**：setting/role/permission
- **请求参数**：
- auth_rules：权限规则（JSON格式）
- **返回结果**：操作结果
### 5.3 菜单管理接口
#### 5.3.1 菜单列表
- **请求URL**：`/adminapi/v1/setting/menu/list`
- **请求方法**：GET
- **权限要求**：setting/menu/list
- **返回结果**：菜单列表数据（树状结构）
#### 5.3.2 添加菜单
- **请求URL**：`/adminapi/v1/setting/menu/create`
- **请求方法**：POST
- **权限要求**：setting/menu/create
- **请求参数**：
- pid：父菜单ID
- menu_name：菜单名称
- menu_type：菜单类型
- url：菜单路径
- icon：菜单图标
- auth：权限标识
- **返回结果**：操作结果
#### 5.3.3 获取左侧菜单
- **请求URL**：`/adminapi/v1/common/menu`
- **请求方法**：GET
- **权限要求**：登录用户
- **返回结果**：当前用户可访问的左侧菜单
### 5.4 系统配置接口
#### 5.4.1 配置列表
- **请求URL**：`/adminapi/v1/setting/config/list`
- **请求方法**：GET
- **权限要求**：setting/config/list
- **请求参数**：
- menu_name：配置分类
- **返回结果**：配置列表数据
#### 5.4.2 编辑配置
- **请求URL**：`/adminapi/v1/setting/config/update`
- **请求方法**：PUT
- **权限要求**：setting/config/update
- **请求参数**：
- config：配置项（JSON格式，键为配置名称，值为配置值）
- **返回结果**：操作结果
## 5. 开发规范与流程
### 5.1 代码规范
1. **命名规范**：
- 类名采用大驼峰命名法，如 `SystemAdminServices`
- 方法名采用小驼峰命名法，如 `getAdminList`
- 变量名采用小驼峰命名法，如 `rolePermission`
- 常量名采用全大写，下划线分隔，如 `MENU_TYPE_CATALOG`
2. **代码结构**：
- 严格遵循分层架构，禁止跨层调用
- 每个方法职责单一，代码行数控制在50行以内
- 适当添加注释，说明方法功能、参数含义和返回值
- 权限相关代码必须添加权限验证
3. **权限控制**：
- 所有管理接口必须添加权限验证
- 权限验证通过中间件实现
- 权限标识必须唯一，格式规范
- 角色权限必须包含所有下级角色的权限
### 5.2 开发流程
1. **需求分析**：明确系统设置的功能需求和业务逻辑
2. **设计阶段**：设计数据结构、API接口和业务流程
3. **编码实现**：按照分层架构编写代码
4. **单元测试**：编写单元测试，确保功能正确性
5. **集成测试**：进行模块集成测试，测试权限控制等功能
6. **安全测试**：对权限控制、密码加密等进行安全测试
7. **代码审查**：提交代码审查，确保代码质量
8. **部署上线**：部署到生产环境
## 6. 常见问题与解决方案
### 6.1 权限继承问题
**问题**：上级管理员无法管理下级管理员或角色
**解决方案**：
1. 检查管理员等级设置，确保上级等级低于下级等级
2. 检查角色等级设置，确保上级角色等级低于下级角色等级
3. 检查权限分配逻辑，确保上级拥有管理下级的权限
### 6.2 菜单显示问题
**问题**：管理员无法看到某些菜单
**解决方案**：
1. 检查菜单状态，确保菜单已启用
2. 检查菜单是否设置为显示
3. 检查管理员所属角色是否拥有该菜单的权限
4. 检查菜单权限标识是否正确
### 6.3 配置不生效问题
**问题**：修改系统配置后不生效
**解决方案**：
1. 检查配置是否已保存成功
2. 检查配置是否已启用
3. 清理配置缓存
4. 检查配置读取逻辑，确保正确读取最新配置
### 6.4 日志记录问题
**问题**：系统操作没有记录日志
**解决方案**：
1. 检查日志中间件是否已启用
2. 检查日志记录逻辑，确保覆盖所有操作
3. 检查日志表是否有写入权限
## 7. 扩展与定制
### 7.1 添加新的配置项
1. **数据库操作**：在system_config表中添加新的配置项
2. **代码修改**：
- 在SystemConfigServices中添加配置项的读取方法
- 在配置控制器中添加配置项的编辑功能
3. **前端修改**：在前端配置页面添加对应的配置表单
### 7.2 添加新的菜单类型
1. **数据库操作**：在system_menus表中添加新的菜单类型常量
2. **代码修改**：
- 在SystemMenusServices中添加菜单类型的处理逻辑
- 在菜单控制器中添加菜单类型的验证
3. **前端修改**：在前端菜单管理页面添加对应的菜单类型选项
### 7.3 扩展权限控制
1. **设计扩展**：扩展权限模型，添加更细粒度的权限控制
2. **代码修改**：
- 扩展角色权限表，添加更细粒度的权限字段
- 修改权限验证逻辑，支持更细粒度的权限控制
3. **前端修改**：在前端权限分配页面添加对应的权限选项
## 8. 文档更新记录
| 版本 | 更新日期 | 更新内容 | 更新人 |
|------|----------|----------|--------|
| 1.0 | 2026-01-19 | 初始版本，包含管理员管理、角色管理、菜单管理、系统配置、存储配置、系统日志、数据备份、定时任务等核心功能 | AI Assistant |
## 9. 附录
### 9.1 核心类关系图
```
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Routes │ │ Controllers │ │ Services │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │ │
└───────────────────────┼───────────────────────┘
│
┌─────────────────┐
│ Models │
└─────────────────┘
│
┌─────────────────┐
│ Daos │
└─────────────────┘
```
### 9.2 权限控制流程图
```
权限控制流程：
1. 用户登录系统，获取token
2. 发起API请求，携带token
3. 权限中间件验证token合法性
4. 获取用户所属角色
5. 获取角色拥有的权限
6. 验证请求的路由是否在权限列表中
7. 验证通过，执行请求；验证失败，返回权限错误
```
### 9.3 菜单权限继承图
```
菜单权限继承关系：
┌─────────────────┐
│ 超级管理员 │
└─────────┬───────┘
│
┌─────────▼───────┐
│ 一级管理员 │
└─────────┬───────┘
│
┌─────────▼───────┐
│ 二级管理员 │
└─────────────────┘
说明：上级管理员可以管理所有下级管理员，拥有下级管理员的所有权限
```
### 9.4 配置分类列表
| 分类名称 | 描述 |
|----------|------|
| basic | 基本配置 |
| shop | 商城配置 |
| payment | 支付配置 |
| sms | 短信配置 |
| storage | 存储配置 |
| wechat | 微信配置 |
| express | 物流配置 |
| marketing | 营销配置 |
---
> **提示**：该文档由AI生成，仅供参考。

321
docs/phpapi/系统错误码说明.md Normal file
View File

@ -0,0 +1,321 @@
# 系统错误码说明
## 📋 错误码规范
### 总体规范
- **格式**: 3位数字错误码 + 错误信息
- **分类**: 按照模块和错误类型分类
- **统一响应**: 所有错误都通过统一异常处理返回
### 响应格式
```json
{
"status": 400,
"msg": "参数错误",
"data": null,
"time": "2024-01-17 15:30:00"
}
```
## 🔢 错误码分类
| 错误码范围 | 错误类型 | 说明 |
|-----------|---------|------|
| 200 | 成功 | 请求成功 |
| 400-499 | 客户端错误 | 参数错误、权限不足等 |
| 500-599 | 服务器错误 | 系统异常、数据库错误等 |
| 1000-1999 | 用户相关错误 | 登录、注册、用户信息等 |
| 2000-2999 | 订单相关错误 | 订单创建、支付、售后等 |
| 3000-3999 | 商品相关错误 | 商品信息、库存、分类等 |
| 4000-4999 | 营销相关错误 | 优惠券、活动、积分等 |
| 5000-5999 | 支付相关错误 | 支付处理、退款等 |
| 6000-6999 | 第三方服务错误 | 微信、短信、物流等 |
## 📊 通用错误码
### 成功状态
| 错误码 | 错误信息 | 说明 |
|--------|---------|------|
| 200 | success | 请求成功 |
### 系统级错误
| 错误码 | 错误信息 | 说明 |
|--------|---------|------|
| 400 | 参数错误 | 请求参数不符合要求 |
| 401 | 未授权 | 用户未登录或Token无效 |
| 403 | 权限不足 | 用户没有操作权限 |
| 404 | 资源不存在 | 请求的资源不存在 |
| 405 | 方法不允许 | 请求方法不正确 |
| 408 | 请求超时 | 请求处理超时 |
| 429 | 请求过于频繁 | 请求频率超过限制 |
| 500 | 服务器内部错误 | 服务器处理异常 |
| 501 | 功能未实现 | 请求的功能暂未实现 |
| 502 | 网关错误 | 上游服务不可用 |
| 503 | 服务不可用 | 服务暂时不可用 |
| 504 | 网关超时 | 上游服务响应超时 |
## 👥 用户相关错误码 (1000-1999)
### 认证相关
| 错误码 | 错误信息 | 说明 |
|--------|---------|------|
| 1001 | 用户名或密码错误 | 登录认证失败 |
| 1002 | 验证码错误 | 图形验证码或短信验证码错误 |
| 1003 | 验证码已过期 | 验证码超过有效时间 |
| 1004 | 账号已被禁用 | 用户账号被管理员禁用 |
| 1005 | 账号未激活 | 用户账号未完成激活流程 |
| 1006 | Token已过期 | JWT Token超过有效期 |
| 1007 | Token无效 | JWT Token格式错误或已失效 |
| 1008 | 登录状态异常 | 登录状态检查失败 |
### 注册相关
| 错误码 | 错误信息 | 说明 |
|--------|---------|------|
| 1101 | 手机号已注册 | 手机号已经被其他用户注册 |
| 1102 | 邮箱已注册 | 邮箱已经被其他用户注册 |
| 1103 | 用户名已存在 | 用户名已经被其他用户使用 |
| 1104 | 邀请码无效 | 注册时使用的邀请码无效 |
| 1105 | 注册信息不完整 | 注册必填信息缺失 |
### 用户信息相关
| 错误码 | 错误信息 | 说明 |
|--------|---------|------|
| 1201 | 用户不存在 | 指定的用户ID不存在 |
| 1202 | 用户信息更新失败 | 更新用户信息时发生错误 |
| 1203 | 原密码错误 | 修改密码时原密码验证失败 |
| 1204 | 手机号格式错误 | 手机号格式不符合要求 |
| 1205 | 邮箱格式错误 | 邮箱格式不符合要求 |
| 1206 | 实名认证失败 | 实名认证信息验证失败 |
## 🛒 订单相关错误码 (2000-2999)
### 订单创建
| 错误码 | 错误信息 | 说明 |
|--------|---------|------|
| 2001 | 商品库存不足 | 下单时商品库存不足 |
| 2002 | 商品已下架 | 下单时商品已下架 |
| 2003 | 收货地址无效 | 选择的收货地址不可用 |
| 2004 | 优惠券不可用 | 选择的优惠券不符合使用条件 |
| 2005 | 积分不足 | 积分支付时积分余额不足 |
| 2006 | 余额不足 | 余额支付时余额不足 |
| 2007 | 订单金额计算错误 | 订单金额计算异常 |
### 订单支付
| 错误码 | 错误信息 | 说明 |
|--------|---------|------|
| 2101 | 支付方式不支持 | 选择的支付方式不可用 |
| 2102 | 支付密码错误 | 余额支付时支付密码错误 |
| 2103 | 支付超时 | 支付操作超时 |
| 2104 | 支付金额不匹配 | 支付金额与订单金额不一致 |
| 2105 | 支付状态异常 | 支付状态不符合预期 |
### 订单操作
| 错误码 | 错误信息 | 说明 |
|--------|---------|------|
| 2201 | 订单状态不允许操作 | 当前订单状态不支持该操作 |
| 2202 | 订单不存在 | 指定的订单ID不存在 |
| 2203 | 订单取消失败 | 取消订单时发生错误 |
| 2204 | 订单删除失败 | 删除订单时发生错误 |
| 2205 | 订单确认收货失败 | 确认收货操作失败 |
### 售后相关
| 错误码 | 错误信息 | 说明 |
|--------|---------|------|
| 2301 | 申请售后时间已过 | 超过可申请售后的时间限制 |
| 2302 | 售后申请重复提交 | 同一订单重复提交售后申请 |
| 2303 | 退款金额超过限制 | 退款金额超过可退款金额 |
| 2304 | 售后状态不允许操作 | 当前售后状态不支持该操作 |
| 2305 | 退货物流信息错误 | 退货物流单号或公司错误 |
## 🏪 商品相关错误码 (3000-3999)
### 商品信息
| 错误码 | 错误信息 | 说明 |
|--------|---------|------|
| 3001 | 商品不存在 | 指定的商品ID不存在 |
| 3002 | 商品已删除 | 商品已被逻辑删除 |
| 3003 | 商品分类不存在 | 指定的分类ID不存在 |
| 3004 | 商品规格无效 | 商品规格选择错误 |
| 3005 | 商品属性错误 | 商品属性信息错误 |
### 库存相关
| 错误码 | 错误信息 | 说明 |
|--------|---------|------|
| 3101 | 库存扣减失败 | 扣减商品库存时发生错误 |
| 3102 | 库存回滚失败 | 回滚商品库存时发生错误 |
| 3103 | 库存锁定失败 | 锁定商品库存时发生错误 |
| 3104 | 库存不足 | 操作时商品库存不足 |
### 购物车相关
| 错误码 | 错误信息 | 说明 |
|--------|---------|------|
| 3201 | 购物车商品不存在 | 购物车中商品不存在 |
| 3202 | 购物车商品数量超限 | 商品数量超过购买限制 |
| 3203 | 购物车操作失败 | 购物车添加、删除操作失败 |
## 🎯 营销相关错误码 (4000-4999)
### 优惠券相关
| 错误码 | 错误信息 | 说明 |
|--------|---------|------|
| 4001 | 优惠券不存在 | 指定的优惠券不存在 |
| 4002 | 优惠券已领完 | 优惠券已被领取完毕 |
| 4003 | 优惠券领取超限 | 超过单人领取数量限制 |
| 4004 | 优惠券已过期 | 优惠券已超过有效期 |
| 4005 | 优惠券使用条件不满足 | 不符合优惠券使用条件 |
| 4006 | 优惠券状态异常 | 优惠券状态不可用 |
### 活动相关
| 错误码 | 错误信息 | 说明 |
|--------|---------|------|
| 4101 | 活动不存在 | 指定的活动不存在 |
| 4102 | 活动未开始 | 活动尚未开始 |
| 4103 | 活动已结束 | 活动已经结束 |
| 4104 | 活动参与人数已满 | 活动参与人数达到上限 |
| 4105 | 活动资格不足 | 不符合活动参与条件 |
### 积分相关
| 错误码 | 错误信息 | 说明 |
|--------|---------|------|
| 4201 | 积分不足 | 积分余额不足 |
| 4202 | 积分操作失败 | 积分增减操作失败 |
| 4203 | 积分规则不存在 | 积分规则配置错误 |
## 💳 支付相关错误码 (5000-5999)
### 支付处理
| 错误码 | 错误信息 | 说明 |
|--------|---------|------|
| 5001 | 支付渠道不可用 | 支付渠道配置错误或不可用 |
| 5002 | 支付签名错误 | 支付签名验证失败 |
| 5003 | 支付回调验证失败 | 支付回调数据验证失败 |
| 5004 | 支付订单不存在 | 支付订单记录不存在 |
| 5005 | 支付金额错误 | 支付金额异常 |
### 退款相关
| 错误码 | 错误信息 | 说明 |
|--------|---------|------|
| 5101 | 退款申请失败 | 退款申请操作失败 |
| 5102 | 退款金额错误 | 退款金额超过可退款金额 |
| 5103 | 退款状态异常 | 退款状态不符合预期 |
| 5104 | 退款凭证错误 | 退款凭证信息错误 |
## 🌐 第三方服务错误码 (6000-6999)
### 微信相关
| 错误码 | 错误信息 | 说明 |
|--------|---------|------|
| 6001 | 微信授权失败 | 微信授权登录失败 |
| 6002 | 微信支付失败 | 微信支付操作失败 |
| 6003 | 微信模板消息发送失败 | 模板消息发送失败 |
| 6004 | 微信公众号配置错误 | 公众号配置信息错误 |
### 短信相关
| 错误码 | 错误信息 | 说明 |
|--------|---------|------|
| 6101 | 短信发送失败 | 短信发送接口调用失败 |
| 6102 | 短信模板不存在 | 短信模板配置错误 |
| 6103 | 短信验证码失效 | 短信验证码验证失败 |
### 物流相关
| 错误码 | 错误信息 | 说明 |
|--------|---------|------|
| 6201 | 物流查询失败 | 物流信息查询失败 |
| 6202 | 物流公司不支持 | 不支持的物流公司 |
| 6203 | 物流单号错误 | 物流单号格式错误 |
### 文件存储相关
| 错误码 | 错误信息 | 说明 |
|--------|---------|------|
| 6301 | 文件上传失败 | 文件上传到服务器失败 |
| 6302 | 文件格式不支持 | 不支持的文件格式 |
| 6303 | 文件大小超限 | 文件大小超过限制 |
| 6304 | 云存储配置错误 | 云存储服务配置错误 |
## 🛠️ 错误处理最佳实践
### 控制器层处理
```php
try {
// 业务逻辑处理
$result = $service->doSomething($params);
return $this->success($result);
} catch (ApiException $e) {
// 捕获业务异常
return $this->fail($e->getMessage(), $e->getCode());
} catch (\Exception $e) {
// 捕获系统异常
Log::error('系统异常: ' . $e->getMessage());
return $this->fail('系统繁忙，请稍后重试', 500);
}
```
### 服务层抛出异常
```php
// 业务验证失败时抛出异常
if (!$user) {
throw new ApiException('用户不存在', 1201);
}
if ($stock < $quantity) {
throw new ApiException('商品库存不足', 2001);
}
```
### 自定义异常类
```php
class ApiException extends \Exception
{
public function __construct($message = "", $code = 400, \Throwable $previous = null)
{
parent::__construct($message, $code, $previous);
}
}
class AdminException extends ApiException
{
// 管理端专用异常
}
```
## 📝 错误码维护规范
### 新增错误码
1. 选择合适的错误码范围
2. 在本文档中记录错误码和说明
3. 在对应的异常处理中添加错误码映射
### 错误码使用原则
1. **唯一性**: 每个错误码对应唯一的错误场景
2. **可读性**: 错误信息清晰明确，便于理解
3. **一致性**: 相同类型的错误使用相同的错误码范围
4. **扩展性**: 为后续功能扩展预留错误码空间
## 🔍 错误排查指南
### 常见错误排查步骤
1. **确认错误码**: 根据返回的错误码定位问题类别
2. **查看日志**: 检查相关业务逻辑的日志记录
3. **验证参数**: 检查请求参数是否符合要求
4. **检查状态**: 确认相关数据的状态是否正常
5. **测试环境**: 在测试环境复现问题并调试
### 日志记录规范
```php
// 记录错误日志
Log::error('错误信息', [
'error_code' => $errorCode,
'params' => $requestParams,
'user_id' => $userId,
'trace' => debug_backtrace(DEBUG_BACKTRACE_IGNORE_ARGS, 5)
]);
```
---
**最后更新**: 2024-01-17
**维护人员**: 开发团队
**文档版本**: v1.0
---
> **提示**：该文档由AI生成，仅供参考。

400
docs/phpapi/系统队列任务开发文档.md Normal file
View File

@ -0,0 +1,400 @@
# 系统队列任务开发文档
## 1. 队列机制概述
CRMEB系统采用基于ThinkPHP Queue的队列任务机制，用于处理耗时操作，提高系统响应速度和并发能力。队列任务支持异步执行、延迟执行、失败重试等功能，适用于订单处理、消息推送、数据分析等场景。
### 1.1 核心组件
- **任务接口**：`JobInterface` - 定义任务执行的标准接口
- **任务基类**：`BaseJobs` - 提供任务执行的基础实现
- **队列工具**：`Queue` - 提供队列任务的创建和管理功能
- **队列特性**：`QueueTrait` - 提供快捷的队列调度方法
- **配置文件**：`queue.php` - 配置队列的驱动和参数
## 2. 队列配置
### 2.1 配置文件
队列配置文件位于 `/crmeb/config/queue.php`，主要配置项包括：
```php
return [
// 默认队列驱动
'default' => 'redis',
// 队列连接方式配置
'connections' => [
'sync' => [
'type' => 'sync',
],
'database' => [
'type' => 'database',
'queue' => 'default',
'table' => 'jobs',
'connection' => null,
],
'redis' => [
'type' => 'redis',
'queue' => 'default',
'host' => env('redis.host', '127.0.0.1'),
'port' => env('redis.port', 6379),
'password' => env('redis.password', ''),
'select' => env('redis.select', 0),
'timeout' => 0,
'persistent' => false,
],
],
// 失败队列配置
'failed' => [
'type' => 'none',
'table' => 'failed_jobs',
],
];
```
### 2.2 配置说明
- **default**：默认队列驱动，支持sync（同步）、database（数据库）、redis（Redis）
- **connections**：队列连接配置，可配置多种队列驱动
- **failed**：失败队列配置，用于存储执行失败的任务
## 3. 任务接口定义
### 3.1 JobInterface
任务接口定义了队列任务的标准执行方法：
```php
namespace crmeb\interfaces;
use think\queue\Job;
interface JobInterface
{
public function fire(Job $job, $data): void;
}
```
- **fire**：任务执行的入口方法，接收Job对象和任务数据
## 4. 任务基类
### 4.1 BaseJobs
任务基类实现了`JobInterface`接口，提供了任务执行的基础逻辑：
```php
namespace crmeb\basic;
use crmeb\interfaces\JobInterface;
use think\queue\Job;
use think\facade\Log;
abstract class BaseJobs implements JobInterface
{
/**
* @param Job $job
* @param $data
*/
public function fire(Job $job, $data): void
{
try {
$method = $data['method'] ?? 'doJob';
if (method_exists($this, $method)) {
if (!isset($data['data'])) {
$res = $this->{$method}();
} else {
$res = $this->{$method}(...$data['data']);
}
if ($res) {
$job->delete();
} else {
if ($job->attempts() > 3) {
$job->delete();
} else {
$job->release();
}
}
} else {
$job->delete();
}
} catch (\Throwable $e) {
Log::error('队列任务执行失败：' . $e->getMessage());
if ($job->attempts() > 3) {
$job->delete();
} else {
$job->release();
}
}
}
}
```
- **fire**：实现JobInterface接口的方法，处理任务执行、错误捕获和失败重试
- **doJob**：默认的任务执行方法，子类可以重写
## 5. 队列工具类
### 5.1 Queue
队列工具类提供了链式调用的方式来创建和管理队列任务：
```php
namespace crmeb\utils;
use think\facade\Config;
use think\facade\Queue as QueueThink;
use think\facade\Log;
class Queue
{
// 任务执行方法
protected $do = 'doJob';
// 任务类名
protected $job;
// 错误次数
protected $errorCount = 3;
// 数据
protected $data;
// 队列名
protected $queueName = null;
// 延迟执行秒数
protected $secs = 0;
// ... 其他方法
}
```
### 5.2 QueueTrait
队列特性提供了快捷的队列调度方法：
```php
namespace crmeb\traits;
trait QueueTrait
{
/**
* 加入队列
* @param string $queueName
* @param array $data
* @return bool
*/
public static function dispatch(string $queueName = null, ...$data)
{
$class = get_called_class();
return Queue::instance()->job($class)->data($data)->queue($queueName)->push();
}
/**
* 延迟加入队列
* @param int $secs
* @param string|null $queueName
* @param array $data
* @return bool
*/
public static function dispatchSecs(int $secs, string $queueName = null, ...$data)
{
$class = get_called_class();
return Queue::instance()->job($class)->data($data)->secs($secs)->queue($queueName)->push();
}
}
```
## 6. 创建队列任务
### 6.1 任务创建步骤
1. 创建任务类，继承`BaseJobs`
2. 实现`doJob`方法或自定义方法
3. 使用`QueueTrait`提供的快捷方法调度任务
### 6.2 任务示例
```php
namespace app\jobs;
use crmeb\basic\BaseJobs;
use crmeb\traits\QueueTrait;
use think\facade\Log;
class OrderCreateAfterJob extends BaseJobs
{
use QueueTrait;
/**
* 订单后置处理
* @param $orderInfo
* @param $data
* @param $activity
* @return bool
*/
public function doJob($orderInfo, $data, $activity)
{
try {
// 处理订单逻辑
// ...
return true;
} catch (\Throwable $e) {
Log::error('订单后置处理失败：' . $e->getMessage());
return false;
}
}
}
```
## 7. 调度队列任务
### 7.1 基本调度
使用`QueueTrait`提供的`dispatch`方法调度任务：
```php
// 调度订单后置处理任务
OrderCreateAfterJob::dispatch(null, $orderInfo, $data, $activity);
```
### 7.2 延迟调度
使用`QueueTrait`提供的`dispatchSecs`方法延迟调度任务：
```php
// 延迟10秒执行订单后置处理任务
OrderCreateAfterJob::dispatchSecs(10, null, $orderInfo, $data, $activity);
```
### 7.3 使用Queue工具调度
使用`Queue`工具类进行更灵活的调度：
```php
use crmeb\utils\Queue;
// 创建并调度任务
Queue::instance()
->job(OrderCreateAfterJob::class)
->data($orderInfo, $data, $activity)
->secs(10)
->queue('order')
->push();
```
## 8. 任务执行流程
1. **任务调度**：通过`dispatch`或`Queue`工具将任务加入队列
2. **任务消费**：队列消费者进程从队列中获取任务
3. **任务执行**：调用任务类的`fire`方法执行任务
4. **结果处理**：
- 执行成功：删除任务
- 执行失败：根据重试次数决定是否重新执行
- 重试超限：将任务移至失败队列（如果配置）
## 9. 队列管理
### 9.1 启动队列消费者
使用ThinkPHP的命令行工具启动队列消费者：
```bash
# 启动默认队列的消费者
php think queue:listen
# 启动指定队列的消费者
php think queue:listen --queue order
# 启动守护进程模式的消费者
php think queue:work --daemon
```
### 9.2 查看队列状态
```bash
# 查看队列任务数
php think queue:status
# 查看失败任务
php think queue:failed
# 重试失败任务
php think queue:retry all
# 删除失败任务
php think queue:flush
```
## 10. 最佳实践
### 10.1 任务设计原则
- **单一职责**：每个任务只负责一个功能
- **幂等性**：任务重复执行不会产生副作用
- **数据完整性**：确保任务执行所需的数据完整
- **错误处理**：妥善处理任务执行中的异常
### 10.2 性能优化
- 合理设置失败重试次数，避免无限重试
- 对耗时任务进行拆分，提高并发处理能力
- 使用合适的队列驱动，Redis适用于高并发场景
- 定期清理失败队列，避免数据堆积
### 10.3 监控与日志
- 记录任务执行日志，便于问题排查
- 监控队列长度，及时发现处理瓶颈
- 设置告警机制，当队列任务堆积时及时通知
## 11. 常见问题
### 11.1 任务执行失败
- 检查任务数据是否完整
- 检查任务依赖的服务是否可用
- 查看日志文件，定位错误原因
- 检查队列驱动是否正常工作
### 11.2 队列任务堆积
- 增加队列消费者进程数量
- 优化任务执行逻辑，减少执行时间
- 检查队列驱动的性能瓶颈
- 考虑使用更高效的队列驱动
### 11.3 延迟任务不执行
- 检查队列消费者是否正常运行
- 检查延迟时间设置是否正确
- 检查队列驱动是否支持延迟任务
- 查看队列日志，定位问题原因
## 12. 内置任务列表
CRMEB系统内置了多个队列任务，用于处理各种业务场景：
| 任务类名 | 功能描述 |
|---------|---------|
| OrderCreateAfterJob | 订单创建后置处理 |
| PinkJob | 拼团任务处理 |
| MiniOrderJob | 小程序订单处理 |
| StoreOrderStatusJob | 订单状态处理 |
| UserBrokerageJob | 用户佣金处理 |
| StoreProductStockJob | 商品库存处理 |
| StoreOrderRefundJob | 订单退款处理 |
| StoreOrderSendJob | 订单发货处理 |
| StoreOrderTakeJob | 订单收货处理 |
| StoreOrderPayJob | 订单支付处理 |
## 13. 总结
CRMEB系统的队列任务机制提供了强大的异步处理能力，通过合理使用队列任务，可以提高系统的响应速度和并发能力，改善用户体验。开发人员可以根据业务需求创建自定义队列任务，实现各种异步处理逻辑。
---
> **提示**：该文档由AI生成，仅供参考。

612
docs/phpapi/系统队列任务文档说明.md Normal file
View File

@ -0,0 +1,612 @@
# CRMEB 系统队列任务文档说明
## 概述
CRMEB 系统采用基于 Redis 的消息队列机制，通过 ThinkPHP 框架的队列组件实现异步任务处理。队列系统在提高系统性能、优化用户体验、保证数据一致性方面发挥着重要作用。
## 队列系统架构
### 1. 技术栈
- **队列驱动**: Redis (主) + Database (备) + Sync (同步)
- **队列服务**: ThinkPHP Queue
- **定时任务**: Workerman + Crontab
- **任务调度**: 基于事件的异步处理
### 2. 核心组件
#### 2.1 队列配置 (config/queue.php)
```php
return [
'default' => 'redis', // 默认驱动
'prefix' => 'crmeb_', // 队列前缀
'connections' => [
'redis' => [
'driver' => 'redis',
'queue' => 'CRMEB', // 队列名称
'host' => '127.0.0.1',
'port' => 6379,
'password' => '',
'select' => 0,
],
],
'failed' => [
'type' => 'database',
'table' => 'failed_jobs', // 失败任务表
],
];
```
#### 2.2 基础任务类 (BaseJobs)
```php
abstract class BaseJobs implements JobInterface
{
// 任务执行入口
public function fire(Job $job, $data): void
// 任务重试机制
protected function runJob(string $action, Job $job, array $infoData, int $errorCount = 3)
}
```
#### 2.3 队列特性 (QueueTrait)
```php
trait QueueTrait
{
// 立即推送任务
public static function dispatch($action, array $data = [], string $queueName = null)
// 延迟推送任务
public static function dispatchSecs(int $secs, $action, array $data = [], string $queueName = null)
}
```
## 队列任务分类
### 1. 订单相关任务
#### 1.1 OrderJob - 订单处理任务
**功能**: 订单支付成功后的后续处理
**触发时机**: 订单支付成功时
**主要处理**:
- 计算商品节省金额
- 更新用户支付订单数量
- 检测并设置推广人身份
- 添加用户购买标签
- 发送客服通知消息
- 检测会员等级升级
- 向后台发送新订单消息
```php
// 使用示例
OrderJob::dispatch('doJob', [$orderInfo]);
```
#### 1.2 OrderCreateAfterJob - 订单创建后处理
**功能**: 订单创建后的数据处理
**触发时机**: 订单创建完成后
**主要处理**:
- 计算订单实际价格
- 处理推广关系
- 计算佣金分配
- 更新订单附加信息
#### 1.3 UnpaidOrderCancelJob - 未支付订单取消
**功能**: 自动取消超时未支付订单
**触发时机**: 定时任务或延迟队列
**处理逻辑**:
- 检查订单支付状态
- 回退积分和优惠券
- 恢复商品库存
- 标记订单为已取消
```php
// 延迟30分钟后执行
UnpaidOrderCancelJob::dispatchSecs(1800, 'doJob', [$orderId]);
```
### 2. 商品相关任务
#### 2.1 ProductLogJob - 商品日志记录
**功能**: 记录商品相关行为日志
**触发时机**: 商品浏览、加购、下单等
**日志类型**:
- `visit`: 商品访问
- `cart`: 加入购物车
- `order`: 下单
- `pay`: 支付
- `collect`: 收藏
- `refund`: 退款
```php
ProductLogJob::dispatch('doJob', ['visit', $productData]);
```
#### 2.2 ProductStockJob - 商品库存处理
**功能**: 商品库存计算和更新
**触发时机**: 商品操作后
**处理功能**:
- 分布式库存计算
- 规格库存汇总
- 库存同步更新
#### 2.3 ProductCopyJob - 商品复制任务
**功能**: 异步复制商品信息
**触发时机**: 商品复制操作
**处理内容**:
- 商品基本信息复制
- 规格属性复制
- 图片资源复制
### 3. 通知相关任务
#### 3.1 SmsJob - 短信发送任务
**功能**: 异步发送短信通知
**触发时机**: 各种业务事件
**支持场景**:
- 订单通知
- 支付提醒
- 注册验证
- 营销推广
```php
SmsJob::dispatch('doJob', [$phone, $data, $template]);
```
#### 3.2 TemplateJob - 模板消息任务
**功能**: 发送微信模板消息
**触发时机**: 业务状态变更
**消息类型**:
- 订单状态通知
- 支付成功通知
- 物流更新通知
#### 3.3 SyncMessageJob - 消息同步任务
**功能**: 多端消息同步
**触发时机**: 消息发送时
**同步范围**:
- 客服系统
- 管理后台
- 用户端
### 4. 营销相关任务
#### 4.1 PinkJob - 拼团任务
**功能**: 拼团活动处理
**触发时机**: 拼团相关操作
**处理内容**:
- 拼团状态更新
- 拼团失败处理
- 拼团成功通知
#### 4.2 LiveJob - 直播任务
**功能**: 直播相关处理
**触发时机**: 直播事件
**处理内容**:
- 直播状态同步
- 商品上下架
- 观众数据统计
#### 4.3 AutoCommentJob - 自动评论任务
**功能**: 自动生成商品评论
**触发时机**: 订单完成后
**处理逻辑**:
- 根据商品信息生成评论
- 模拟用户评价
- 提升商品活跃度
### 5. 系统维护任务
#### 5.1 TaskJob - 定时任务
**功能**: 系统定时维护
**执行频率**: 每日定时
**维护内容**:
- 清理过期文件
- 数据统计汇总
- 系统健康检查
```php
// 清理昨日海报
TaskJob::dispatch('emptyYesterdayAttachment');
```
#### 5.2 UpgradeJob - 系统升级任务
**功能**: 系统升级处理
**触发时机**: 手动触发或定时
**处理内容**:
- 数据库结构更新
- 配置文件升级
- 兼容性检查
#### 5.3 CheckQueueJob - 队列检查任务
**功能**: 监控队列健康状态
**执行频率**: 定时检查
**检查项目**:
- 队列堆积情况
- 失败任务统计
- 系统资源使用
### 6. 用户相关任务
#### 6.1 UserJob - 用户处理任务
**功能**: 用户相关异步处理
**触发时机**: 用户操作
**处理内容**:
- 用户等级计算
- 积分统计分析
- 行为数据更新
#### 6.2 AgentJob - 代理任务
**功能**: 代理商相关处理
**触发时机**: 代理业务
**处理内容**:
- 佣金计算
- 等级升级
- 数据统计
### 7. 物流相关任务
#### 7.1 OrderExpressJob - 订单物流任务
**功能**: 物流信息处理
**触发时机**: 物流状态变更
**处理内容**:
- 物流信息同步
- 状态更新通知
- 异常情况处理
#### 7.2 TakeOrderJob - 订单接收任务
**功能**: 订单接收处理
**触发时机**: 订单创建
**处理内容**:
- 订单数据验证
- 库存检查
- 自动分配
### 8. 财务相关任务
#### 8.1 OrderInvoiceJob - 订单发票任务
**功能**: 发票处理
**触发时机**: 发票申请
**处理内容**:
- 发票生成
- 状态同步
- 通知发送
#### 8.2 OutPushJob - 外部推送任务
**功能**: 数据外部推送
**触发时机**: 数据变更
**推送内容**:
- 订单数据
- 用户数据
- 商品数据
## 定时任务系统
### 1. Timer 命令
基于 Workerman 实现的定时任务调度器
```bash
# 启动定时任务
php think timer start
# 守护进程方式启动
php think timer start -d
# 停止定时任务
php think timer stop
# 重启定时任务
php think timer reload
```
### 2. 系统定时任务
数据库表: `system_crontab`
**字段说明**:
- `name`: 任务名称
- `task_type`: 任务类型
- `mark`: 任务标识
- `content`: 任务内容
- `max_execution_time`: 最大执行时间
- `execution_cycle`: 执行周期
- `is_open`: 是否开启
- `next_execution_time`: 下次执行时间
- `last_execution_time`: 上次执行时间
### 3. 内置定时任务
#### 3.1 订单相关
- **未支付订单取消**: 每分钟检查一次
- **预售商品下架**: 每小时检查一次
- **拼团失败处理**: 每5分钟检查一次
#### 3.2 数据统计
- **日统计汇总**: 每日凌晨执行
- **用户行为分析**: 每小时执行
- **销售数据统计**: 每日执行
#### 3.3 系统维护
- **日志清理**: 每周执行
- **临时文件清理**: 每日执行
- **缓存刷新**: 定时执行
## 队列监控与管理
### 1. 队列状态监控
```php
// 检查队列状态
Queue::instance()->getQueueInfo();
// 获取队列长度
Queue::instance()->getQueueLength();
// 获取失败任务
Queue::instance()->getFailedJobs();
```
### 2. 任务管理
```php
// 重新执行失败任务
Queue::instance()->retryFailed($jobId);
// 清空队列
Queue::instance()->clearQueue($queueName);
// 暂停队列
Queue::instance()->pauseQueue($queueName);
```
### 3. 日志记录
所有队列任务都有详细的日志记录:
- 成功执行日志
- 失败重试日志
- 异常堆栈信息
- 性能执行统计
## 队列配置最佳实践
### 1. 队列分组
根据业务重要性分组:
```php
// 高优先级队列
'order_pay' => 'CRMEB_ORDER_PAY'
'sms' => 'CRMEB_SMS'
'email' => 'CRMEB_EMAIL'
// 普通优先级队列
'statistics' => 'CRMEB_STATISTICS'
'log' => 'CRMEB_LOG'
// 低优先级队列
'report' => 'CRMEB_REPORT'
'cleanup' => 'CRMEB_CLEANUP'
```
### 2. 重试策略
```php
// 不同任务的重试次数
'order_pay' => 3 // 支付任务重试3次
'sms' => 5 // 短信任务重试5次
'email' => 3 // 邮件任务重试3次
'statistics' => 1 // 统计任务重试1次
```
### 3. 延迟设置
```php
// 常见延迟时间
UnpaidOrderCancelJob::dispatchSecs(1800, 'doJob', [$orderId]); // 30分钟
OrderRemindJob::dispatchSecs(86400, 'doJob', [$orderId]); // 24小时
CleanupJob::dispatchSecs(604800, 'doJob', [$data]); // 7天
```
## 性能优化建议
### 1. 队列优化
- 使用 Redis 集群提高可用性
- 合理设置队列数量避免热点
- 定期清理过期队列数据
- 监控队列长度及时扩容
### 2. 任务优化
- 避免单个任务过于复杂
- 合理拆分大任务为小任务
- 使用事务保证数据一致性
- 添加超时控制避免阻塞
### 3. 资源优化
- 控制并发任务数量
- 合理设置内存限制
- 优化数据库查询性能
- 使用连接池减少开销
## 故障处理
### 1. 常见问题
#### 1.1 队列堆积
**现象**: 队列长度持续增长
**原因**: 消费速度小于生产速度
**解决**:
- 增加消费者进程数
- 优化任务执行效率
- 检查系统资源使用
#### 1.2 任务重复执行
**现象**: 同一任务被执行多次
**原因**: 任务重复入队或幂等性问题
**解决**:
- 添加任务唯一标识
- 实现幂等性检查
- 优化任务重试逻辑
#### 1.3 内存泄漏
**现象**: 进程内存持续增长
**原因**: 任务中存在资源未释放
**解决**:
- 检查对象引用
- 及时释放大对象
- 定期重启消费者进程
### 2. 应急处理
#### 2.1 队列暂停
```bash
# 暂停所有队列
php think queue:pause
# 暂停指定队列
php think queue:pause --queue=order_pay
```
#### 2.2 强制清空
```bash
# 清空指定队列
php think queue:clear --queue=statistics
# 清空所有队列
php think queue:clear --all
```
#### 2.3 重建队列
```bash
# 重建队列表
php think queue:table
# 重新发布失败任务
php think queue:retry all
```
## 开发指南
### 1. 创建新任务
#### 1.1 创建任务类
```php
<?php
namespace app\jobs;
use crmeb\basic\BaseJobs;
use crmeb\traits\QueueTrait;
class CustomJob extends BaseJobs
{
use QueueTrait;
/**
* 执行任务
* @param array $data
* @return bool
*/
public function doJob(array $data): bool
{
try {
// 业务逻辑处理
$this->processData($data);
return true;
} catch (\Exception $e) {
// 记录错误日志
Log::error('任务执行失败: ' . $e->getMessage());
return false;
}
}
private function processData(array $data): void
{
// 具体业务逻辑
}
}
```
#### 1.2 调度任务
```php
// 立即执行
CustomJob::dispatch('doJob', [$data]);
// 延迟执行
CustomJob::dispatchSecs(300, 'doJob', [$data]);
// 指定队列
CustomJob::dispatch('doJob', [$data], 'custom_queue');
```
### 2. 测试队列任务
#### 2.1 单元测试
```php
public function testCustomJob()
{
$job = new CustomJob();
$result = $job->doJob($testData);
$this->assertTrue($result);
}
```
#### 2.2 集成测试
```php
public function testQueueDispatch()
{
// 模拟队列调度
Queue::fake();
CustomJob::dispatch('doJob', [$testData]);
Queue::assertPushed(CustomJob::class, function ($job) use ($testData) {
return $job->data[0] === $testData;
});
}
```
### 3. 监控和调试
#### 3.1 添加日志
```php
public function doJob(array $data): bool
{
Log::info('任务开始执行', ['data' => $data]);
try {
// 业务逻辑
Log::info('任务执行成功');
return true;
} catch (\Exception $e) {
Log::error('任务执行失败', [
'error' => $e->getMessage(),
'trace' => $e->getTraceAsString()
]);
return false;
}
}
```
#### 3.2 性能监控
```php
public function doJob(array $data): bool
{
$startTime = microtime(true);
try {
// 业务逻辑
$endTime = microtime(true);
$executeTime = ($endTime - $startTime) * 1000; // 毫秒
Log::info('任务执行完成', [
'execute_time' => $executeTime . 'ms',
'memory_usage' => memory_get_usage(true)
]);
return true;
} catch (\Exception $e) {
Log::error('任务执行失败', ['error' => $e->getMessage()]);
return false;
}
}
```
## 总结
CRMEB 的队列任务系统是系统高性能运行的关键组件，通过合理的任务分类、优先级管理、错误处理和监控机制，确保了系统的稳定性和可扩展性。在实际使用中，需要根据业务特点合理设计任务粒度，优化执行效率，并建立完善的监控告警机制。
队列系统的正确使用可以显著提升用户体验，降低系统负载，提高数据处理的一致性。建议开发团队充分理解队列机制，在合适场景下合理应用，并持续优化和改进队列性能。
---
> **提示**：该文档由AI生成，仅供参考。

433
docs/phpapi/统计分析开发文档.md Normal file
View File

@ -0,0 +1,433 @@
# 统计分析开发文档
## 1. 文档概述
### 1.1 文档目的
本文档旨在详细说明CRMEB系统中统计分析模块的设计架构、核心功能、代码实现及开发规范，为系统开发人员提供完整的开发参考。
### 1.2 适用范围
本文档适用于CRMEB系统开发人员、维护人员及二次开发人员，用于指导统计分析模块的开发、扩展和维护工作。
### 1.3 术语定义
| 术语 | 解释 |
|------|------|
| PV | 页面访问量（Page View），即页面浏览次数 |
| UV | 独立访客数（Unique Visitor），即不同IP地址访问网站的用户数 |
| 转化率 | 转化次数与访问次数的比率，如注册转化率、下单转化率 |
| 复购率 | 重复购买用户数与总购买用户数的比率 |
| 环比 | 本期统计数据与上期统计数据的比较 |
| 同比 | 本期统计数据与上年同期统计数据的比较 |
| 资金流水 | 系统中所有资金的流入流出记录 |
## 2. 核心功能模块
### 2.1 流量统计
- **PV/UV统计**：统计网站的页面访问量和独立访客数
- **访问趋势分析**：支持按小时、日、周、月维度查看访问趋势
- **访问来源分析**：分析用户的访问来源渠道
- **页面热度分析**：统计各个页面的访问热度
- **访问设备分析**：分析用户使用的设备类型（PC、移动端、平板等）
### 2.2 用户统计
- **用户基础信息统计**：新增用户数、成交用户数、充值用户数、付费用户数
- **用户增长趋势**：按时间维度查看用户增长情况
- **用户地域分布**：统计用户的地域分布（按省份、城市）
- **用户性别分布**：统计用户的性别分布
- **用户年龄分布**：统计用户的年龄分布
- **微信用户分析**：微信用户关注/取关统计
- **用户行为分析**：用户浏览、搜索、购买等行为分析
### 2.3 销售统计
- **订单金额统计**：统计订单总金额、实付金额、退款金额等
- **订单数量统计**：统计订单总数、成交订单数、退款订单数等
- **订单趋势分析**：按时间维度查看订单趋势
- **订单来源分析**：分析订单的来源渠道
- **订单类型分布**：统计不同类型订单的分布情况
- **实时交易数据**：实时展示交易数据
- **支付方式分析**：分析不同支付方式的使用情况
### 2.4 资金统计
- **资金流水统计**：统计系统中的资金流入流出记录
- **账单记录**：生成日/周/月账单
- **余额统计**：统计用户余额情况
- **余额趋势分析**：按时间维度查看余额趋势
- **余额来源分析**：分析余额的来源渠道
- **余额类型分析**：分析不同类型余额的分布
### 2.5 商品统计
- **商品销售基础数据**：商品销售额、销量、访客数、转化率等
- **商品销售趋势**：按时间维度查看商品销售趋势
- **商品排行**：商品销售额排行、销量排行、访客数排行等
- **商品分类统计**：按商品分类统计销售情况
- **商品属性分析**：分析商品不同属性的销售情况
## 3. 代码结构与设计
### 3.1 架构设计
系统采用分层架构设计，严格遵循MVC设计模式：
```
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Controllers │ │ Services │ │ Daos │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │ │
└───────────────────────┼───────────────────────┘
│
┌─────────────────┐
│ Models │
└─────────────────┘
│
┌─────────────────┐
│ 数据库 │
└─────────────────┘
```
### 3.2 核心文件结构
#### 3.2.1 控制器层（Controller）
**统计分析控制器**：`/crmeb/app/adminapi/controller/v1/statistic/`
- `FlowStatistic.php` - 资金流水统计控制器
- `UserStatistic.php` - 用户统计控制器
- `OrderStatistic.php` - 订单统计控制器
- `TradeStatistic.php` - 交易统计控制器
- `ProductStatistic.php` - 商品统计控制器
- `BalanceStatistic.php` - 余额统计控制器
#### 3.2.2 服务层（Services）
**统计分析服务**：`/crmeb/app/services/statistic/`
- `CapitalFlowServices.php` - 资金流水统计服务
- `UserStatisticServices.php` - 用户统计服务
- `OrderStatisticServices.php` - 订单统计服务
- `TradeStatisticServices.php` - 交易统计服务
- `ProductStatisticServices.php` - 商品统计服务
- `BalanceStatisticServices.php` - 余额统计服务
#### 3.2.3 数据访问层（Dao）
**统计分析Dao**：与各个业务模块的Dao共用，如用户Dao、订单Dao、商品Dao等
#### 3.2.4 模型层（Model）
**统计分析模型**：与各个业务模块的模型共用，如用户模型、订单模型、商品模型等
## 4. 数据库设计
### 4.1 资金流水表（capital_flow）
| 字段名 | 数据类型 | 描述 |
|--------|----------|------|
| id | int(10) unsigned | 流水ID |
| uid | int(10) | 用户ID |
| link_id | int(10) | 关联ID（如订单ID、充值ID等） |
| type | varchar(20) | 交易类型（pay-支付订单，refund-退款，recharge-充值，extract-提现等） |
| money | decimal(10,2) | 交易金额 |
| pm | tinyint(1) | 收支方向（1-收入，0-支出） |
| balance | decimal(10,2) | 交易后余额 |
| mark | varchar(255) | 备注 |
| add_time | int(10) | 添加时间 |
### 4.2 访问记录表（visit_log）
| 字段名 | 数据类型 | 描述 |
|--------|----------|------|
| id | int(10) unsigned | 记录ID |
| uid | int(10) | 用户ID（0-游客） |
| ip | varchar(15) | 访问IP |
| url | varchar(255) | 访问URL |
| referer | varchar(255) | 来源URL |
| user_agent | text | 用户代理信息 |
| device | varchar(20) | 设备类型（pc, mobile, tablet） |
| browser | varchar(20) | 浏览器 |
| os | varchar(20) | 操作系统 |
| add_time | int(10) | 访问时间 |
### 4.3 销售统计表（sale_statistics）
| 字段名 | 数据类型 | 描述 |
|--------|----------|------|
| id | int(10) unsigned | 统计ID |
| date | date | 统计日期 |
| order_count | int(10) | 订单数量 |
| order_amount | decimal(10,2) | 订单总金额 |
| pay_amount | decimal(10,2) | 实付金额 |
| refund_count | int(10) | 退款订单数量 |
| refund_amount | decimal(10,2) | 退款金额 |
| user_count | int(10) | 成交用户数 |
| add_time | int(10) | 添加时间 |
## 5. API接口说明
### 5.1 流量统计接口
#### 5.1.1 获取PV/UV统计
- **请求URL**：`/adminapi/v1/statistic/flow/pvuv`
- **请求方法**：GET
- **权限要求**：statistic/flow/pvuv
- **请求参数**：
- type：时间维度（hour, day, week, month）
- start_time：开始时间
- end_time：结束时间
- **返回结果**：PV/UV统计数据
#### 5.1.2 获取访问来源分析
- **请求URL**：`/adminapi/v1/statistic/flow/source`
- **请求方法**：GET
- **权限要求**：statistic/flow/source
- **请求参数**：
- start_time：开始时间
- end_time：结束时间
- **返回结果**：访问来源分析数据
### 5.2 用户统计接口
#### 5.2.1 获取用户基础统计
- **请求URL**：`/adminapi/v1/statistic/user/basic`
- **请求方法**：GET
- **权限要求**：statistic/user/basic
- **请求参数**：
- start_time：开始时间
- end_time：结束时间
- **返回结果**：用户基础统计数据
#### 5.2.2 获取用户增长趋势
- **请求URL**：`/adminapi/v1/statistic/user/trend`
- **请求方法**：GET
- **权限要求**：statistic/user/trend
- **请求参数**：
- type：时间维度（hour, day, week, month）
- start_time：开始时间
- end_time：结束时间
- **返回结果**：用户增长趋势数据
#### 5.2.3 获取用户地域分布
- **请求URL**：`/adminapi/v1/statistic/user/region`
- **请求方法**：GET
- **权限要求**：statistic/user/region
- **请求参数**：
- start_time：开始时间
- end_time：结束时间
- **返回结果**：用户地域分布数据
### 5.3 销售统计接口
#### 5.3.1 获取订单统计
- **请求URL**：`/adminapi/v1/statistic/order/basic`
- **请求方法**：GET
- **权限要求**：statistic/order/basic
- **请求参数**：
- start_time：开始时间
- end_time：结束时间
- **返回结果**：订单统计数据
#### 5.3.2 获取订单趋势
- **请求URL**：`/adminapi/v1/statistic/order/trend`
- **请求方法**：GET
- **权限要求**：statistic/order/trend
- **请求参数**：
- type：时间维度（hour, day, week, month）
- start_time：开始时间
- end_time：结束时间
- **返回结果**：订单趋势数据
### 5.4 资金统计接口
#### 5.4.1 获取资金流水列表
- **请求URL**：`/adminapi/v1/statistic/flow/list`
- **请求方法**：GET
- **权限要求**：statistic/flow/list
- **请求参数**：
- page：页码
- limit：每页数量
- type：交易类型
- start_time：开始时间
- end_time：结束时间
- **返回结果**：资金流水列表数据
#### 5.4.2 获取账单记录
- **请求URL**：`/adminapi/v1/statistic/flow/bill`
- **请求方法**：GET
- **权限要求**：statistic/flow/bill
- **请求参数**：
- type：账单类型（day, week, month）
- date：统计日期
- **返回结果**：账单记录数据
### 5.5 商品统计接口
#### 5.5.1 获取商品销售基础数据
- **请求URL**：`/adminapi/v1/statistic/product/basic`
- **请求方法**：GET
- **权限要求**：statistic/product/basic
- **请求参数**：
- product_id：商品ID
- start_time：开始时间
- end_time：结束时间
- **返回结果**：商品销售基础数据
#### 5.5.2 获取商品销售排行
- **请求URL**：`/adminapi/v1/statistic/product/rank`
- **请求方法**：GET
- **权限要求**：statistic/product/rank
- **请求参数**：
- type：排行类型（sales, amount, visitor）
- start_time：开始时间
- end_time：结束时间
- limit：返回数量
- **返回结果**：商品销售排行数据
## 5. 开发规范与流程
### 5.1 代码规范
1. **命名规范**：
- 类名采用大驼峰命名法，如 `UserStatisticServices`
- 方法名采用小驼峰命名法，如 `getUserBasicInfo`
- 变量名采用小驼峰命名法，如 `visitorCount`
- 常量名采用全大写，下划线分隔，如 `STATISTIC_TYPE_HOUR`
2. **代码结构**：
- 严格遵循分层架构，禁止跨层调用
- 每个方法职责单一，代码行数控制在50行以内
- 适当添加注释，说明方法功能、参数含义和返回值
- 所有统计数据必须包含完整的时间范围
3. **性能优化**：
- 统计查询必须使用索引，避免全表扫描
- 复杂统计查询必须使用缓存，减少数据库压力
- 统计数据必须定期汇总，避免实时计算大量数据
- 使用合适的统计周期，如小时、日、周、月
### 5.2 开发流程
1. **需求分析**：明确统计分析的功能需求和业务逻辑
2. **设计阶段**：设计数据结构、API接口和业务流程
3. **编码实现**：
- 实现统计服务层逻辑
- 实现统计控制器接口
- 实现数据汇总和缓存机制
4. **单元测试**：编写单元测试，确保统计结果正确性
5. **性能测试**：对统计查询进行性能测试，优化查询效率
6. **代码审查**：提交代码审查，确保代码质量
7. **部署上线**：部署到生产环境
## 6. 常见问题与解决方案
### 6.1 统计数据不准确
**问题**：统计数据与实际数据不符
**解决方案**：
1. 检查统计逻辑，确保统计范围正确
2. 检查数据来源，确保数据完整
3. 检查时间范围，确保时间格式正确
4. 检查统计周期，确保周期划分正确
5. 实现数据校验机制，定期核对统计数据
### 6.2 统计查询性能问题
**问题**：统计查询耗时过长，影响系统性能
**解决方案**：
1. 使用索引优化查询
2. 实现统计数据缓存
3. 定期预计算统计数据
4. 优化数据库结构，如分表、分区
5. 使用数据仓库或OLAP数据库处理复杂统计
### 6.3 统计维度不足
**问题**：无法满足多维度统计需求
**解决方案**：
1. 设计灵活的统计架构，支持自定义统计维度
2. 实现统计维度扩展机制
3. 使用数据立方体技术，支持多维数据分析
### 6.4 实时统计问题
**问题**：实时统计数据延迟或不准确
**解决方案**：
1. 使用流处理技术，如Kafka、Flink等
2. 实现准实时统计，平衡实时性和准确性
3. 优化实时数据处理流程，减少延迟
## 7. 扩展与定制
### 7.1 添加新的统计维度
1. **设计统计逻辑**：确定新统计维度的计算逻辑
2. **修改服务层**：在相应的统计服务中添加新的统计方法
3. **添加API接口**：在相应的控制器中添加新的API接口
4. **前端修改**：在前端页面中添加新的统计图表和展示
### 7.2 实现自定义统计报表
1. **设计报表结构**：确定报表的字段、维度和指标
2. **实现报表生成逻辑**：在统计服务中添加报表生成方法
3. **添加报表管理功能**：实现报表的创建、编辑、删除功能
4. **前端修改**：在前端页面中添加报表展示和导出功能
### 7.3 集成第三方统计工具
1. **设计集成方案**：确定与第三方统计工具的集成方式
2. **实现数据同步**：实现与第三方统计工具的数据同步
3. **添加API接口**：添加获取第三方统计数据的API接口
4. **前端修改**：在前端页面中集成第三方统计图表
## 8. 文档更新记录
| 版本 | 更新日期 | 更新内容 | 更新人 |
|------|----------|----------|--------|
| 1.0 | 2026-01-19 | 初始版本，包含流量统计、用户统计、销售统计、资金统计、商品统计等核心功能 | AI Assistant |
## 9. 附录
### 9.1 核心类关系图
```
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Controllers │ │ Services │ │ Daos │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │ │
└───────────────────────┼───────────────────────┘
│
┌─────────────────┐
│ Models │
└─────────────────┘
│
┌─────────────────┐
│ 数据库 │
└─────────────────┘
```
### 9.2 统计流程示意图
```
统计流程：
1. 系统收集原始数据（访问日志、订单数据、用户数据等）
2. 定期汇总原始数据，生成统计数据
3. 将统计数据存储到统计表中
4. 提供API接口，供前端查询统计数据
5. 前端展示统计图表和数据
6. 支持统计数据导出
```
### 9.3 支持的统计维度
| 维度名称 | 描述 |
|----------|------|
| 时间维度 | 小时、日、周、月、年 |
| 地域维度 | 省份、城市 |
| 设备维度 | PC、移动端、平板 |
| 渠道维度 | 微信、支付宝、APP、小程序等 |
| 商品维度 | 商品分类、商品属性、品牌等 |
| 用户维度 | 性别、年龄、会员等级等 |
| 订单维度 | 订单类型、支付方式、配送方式等 |
### 9.4 统计指标列表
| 指标名称 | 描述 |
|----------|------|
| PV | 页面访问量 |
| UV | 独立访客数 |
| 新增用户数 | 新增注册用户数 |
| 成交用户数 | 完成交易的用户数 |
| 复购率 | 重复购买用户数与总购买用户数的比率 |
| 转化率 | 转化次数与访问次数的比率 |
| 订单总金额 | 订单的总金额 |
| 实付金额 | 实际支付的金额 |
| 订单数量 | 订单总数 |
| 客单价 | 平均每笔订单的金额 |
| 商品销售额 | 商品的销售总额 |
| 商品销量 | 商品的销售数量 |
| 资金流入 | 系统中的资金流入总额 |
| 资金流出 | 系统中的资金流出总额 |
---
> **提示**：该文档由AI生成，仅供参考。

580
docs/phpapi/营销活动开发文档.md Normal file
View File

@ -0,0 +1,580 @@
# 营销活动开发文档
## 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 代码规范
1. **命名规范**：
- 类名采用大驼峰命名法，如 `StoreSeckillServices`
- 方法名采用小驼峰命名法，如 `getSeckillList`
- 变量名采用小驼峰命名法，如 `seckillProduct`
- 常量名采用全大写，下划线分隔，如 `COUPON_TYPE_FULL`
2. **代码结构**：
- 严格遵循分层架构，禁止跨层调用
- 每个方法职责单一，代码行数控制在50行以内
- 适当添加注释，说明方法功能、参数含义和返回值
3. **数据库操作**：
- 所有数据库操作必须通过Dao层进行
- 使用ORM提供的查询构建器，避免直接编写SQL
- 涉及资金、库存等关键数据操作必须使用事务处理
### 5.2 开发流程
1. **需求分析**：明确营销活动的功能需求和业务逻辑
2. **设计阶段**：设计数据结构、API接口和业务流程
3. **编码实现**：按照分层架构编写代码
4. **单元测试**：编写单元测试，确保功能正确性
5. **集成测试**：进行模块集成测试，测试活动与商品、订单等模块的交互
6. **性能测试**：对高并发场景进行性能测试，如秒杀活动
7. **代码审查**：提交代码审查，确保代码质量
8. **部署上线**：部署到生产环境
## 6. 常见问题与解决方案
### 6.1 高并发处理
**问题**：秒杀、拼团等活动在高并发场景下可能出现超卖、数据不一致等问题
**解决方案**：
1. 使用数据库事务和乐观锁机制
2. 实现库存预扣和释放机制
3. 使用Redis等缓存技术，提高库存操作效率
4. 采用分布式锁，确保数据一致性
5. 实现流量削峰，如使用队列、限流等技术
### 6.2 活动时间管理
**问题**：活动开始和结束时间的精确控制
**解决方案**：
1. 使用定时器任务，定期检查活动状态
2. 在关键操作（如用户参与活动）时，再次验证活动时间
3. 使用Redis的过期时间功能，自动更新活动状态
### 6.3 活动数据统计
**问题**：实时统计活动参与人数、销售额等数据
**解决方案**：
1. 使用Redis缓存实时数据，定期同步到数据库
2. 采用异步处理方式，避免影响主业务流程
3. 实现数据报表功能，支持多维度查询
### 6.4 活动冲突处理
**问题**：同一商品参与多个活动时的冲突
**解决方案**：
1. 设计活动优先级机制，明确活动执行顺序
2. 在用户参与活动时，验证商品是否可以同时参与多个活动
3. 提供活动冲突检测功能，在创建活动时提示冲突
## 7. 扩展与定制
### 7.1 功能扩展
系统设计具有良好的扩展性，可通过以下方式扩展功能：
1. **添加新活动类型**：
- 在 `model/activity/` 目录下创建新的活动模型
- 在 `dao/activity/` 目录下创建对应的DAO
- 在 `services/activity/` 目录下创建对应的Services
- 在 `controller/` 目录下创建对应的控制器
- 在路由文件中添加新的路由
2. **扩展现有活动功能**：
- 在现有模型中添加新字段
- 在现有Services中添加新方法
- 在现有控制器中添加新接口
### 7.2 事件扩展
系统在关键业务节点触发事件，可通过监听事件进行功能扩展：
1. **活动开始事件**：ActivityStartEvent
2. **活动结束事件**：ActivityEndEvent
3. **用户参与活动事件**：UserJoinActivityEvent
4. **活动订单创建事件**：ActivityOrderCreateEvent
5. **活动订单支付事件**：ActivityOrderPayEvent
### 7.3 钩子扩展
系统提供了多个钩子点，可通过钩子函数进行功能扩展：
1. **活动创建前钩子**：activity_create_before
2. **活动创建后钩子**：activity_create_after
3. **活动编辑前钩子**：activity_edit_before
4. **活动编辑后钩子**：activity_edit_after
5. **活动删除前钩子**：activity_delete_before
6. **活动删除后钩子**：activity_delete_after
7. **用户参与活动前钩子**：user_join_activity_before
8. **用户参与活动后钩子**：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生成，仅供参考。

188
docs/phpapi/订单模块说明.md Normal file
View File

@ -0,0 +1,188 @@
# 订单模块说明
## 📦 订单状态流转
### 订单核心状态
```php
const ORDER_STATUS_UNPAID = 0; // 未支付
const ORDER_STATUS_PAID = 1; // 已支付
const ORDER_STATUS_SHIPPED = 2; // 已发货
const ORDER_STATUS_COMPLETED = 3; // 已完成
const ORDER_STATUS_CANCELLED = -1; // 已取消
const ORDER_STATUS_REFUNDING = -2; // 退款中
const ORDER_STATUS_REFUNDED = -3; // 已退款
```
### 支付状态
```php
const PAY_STATUS_UNPAID = 0; // 未支付
const PAY_STATUS_PAID = 1; // 已支付
const PAY_STATUS_REFUNDING = 2; // 退款中
const PAY_STATUS_REFUNDED = 3; // 已退款
```
## 🔄 订单创建流程
### 1. 参数验证
```php
// 验证收货地址、商品信息、优惠券等
$validate = new OrderValidate();
if (!$validate->scene('create')->check($params)) {
throw new ApiException($validate->getError());
}
```
### 2. 商品校验
```php
// 检查商品库存、价格、状态
foreach ($cartInfo as $item) {
$product = $productService->getProductInfo($item['product_id']);
if ($product['stock'] < $item['cart_num']) {
throw new ApiException('商品库存不足');
}
}
```
### 3. 优惠计算
```php
// 计算优惠券、积分、满减等
$couponAmount = $couponService->calculateCoupon($uid, $cartInfo);
$integralAmount = $integralService->calculateIntegral($uid, $totalAmount);
$finalAmount = $totalAmount - $couponAmount - $integralAmount;
```
### 4. 创建订单
```php
// 生成订单数据
$orderData = [
'order_id' => $this->getNewOrderId(),
'uid' => $uid,
'total_price' => $totalAmount,
'pay_price' => $finalAmount,
'status' => self::ORDER_STATUS_UNPAID,
'add_time' => time()
];
// 保存订单
$orderId = $this->dao->save($orderData);
```
## 💳 支付处理
### 支付方式
```php
const PAY_TYPE_WECHAT = 'wechat'; // 微信支付
const PAY_TYPE_ALIPAY = 'alipay'; // 支付宝
const PAY_TYPE_BALANCE = 'balance'; // 余额支付
const PAY_TYPE_INTEGRAL = 'integral'; // 积分支付
```
### 支付回调处理
```php
public function payNotify($params) {
// 验证支付结果
if ($this->verifyPayResult($params)) {
// 更新订单状态
$this->updateOrderStatus($params['order_id'], self::ORDER_STATUS_PAID);
// 记录支付流水
$this->savePayRecord($params);
// 发送支付成功通知
$this->sendPaySuccessNotify($params['order_id']);
}
}
```
## 📦 发货处理
### 发货流程
```php
public function deliverOrder($orderId, $expressData) {
// 检查订单状态
$order = $this->getOrderInfo($orderId);
if ($order['status'] != self::ORDER_STATUS_PAID) {
throw new ApiException('订单状态不允许发货');
}
// 生成发货单
$deliverData = [
'order_id' => $orderId,
'express_code' => $expressData['code'],
'express_number' => $expressData['number'],
'deliver_time' => time()
];
// 更新订单状态
$this->updateOrderStatus($orderId, self::ORDER_STATUS_SHIPPED);
// 发送发货通知
$this->sendDeliverNotify($orderId);
}
```
## 🔄 售后处理
### 退款申请
```php
public function applyRefund($orderId, $reason, $amount) {
// 检查订单是否可退款
if (!$this->canRefund($orderId)) {
throw new ApiException('该订单不可退款');
}
// 创建退款记录
$refundData = [
'order_id' => $orderId,
'refund_amount' => $amount,
'refund_reason' => $reason,
'status' => self::REFUND_STATUS_APPLY
];
// 更新订单状态
$this->updateOrderStatus($orderId, self::ORDER_STATUS_REFUNDING);
}
```
### 退款审核
```php
public function auditRefund($refundId, $status, $remark = '') {
$refund = $this->getRefundInfo($refundId);
if ($status == self::REFUND_STATUS_APPROVED) {
// 执行退款
$this->doRefund($refund);
// 更新订单状态
$this->updateOrderStatus($refund['order_id'], self::ORDER_STATUS_REFUNDED);
} else {
// 拒绝退款
$this->updateRefundStatus($refundId, self::REFUND_STATUS_REJECTED, $remark);
// 恢复订单状态
$this->recoverOrderStatus($refund['order_id']);
}
}
```
## 📊 订单统计
### 常用统计方法
```php
// 今日订单统计
public function getTodayOrderStats() {
$todayStart = strtotime('today');
$todayEnd = strtotime('tomorrow') - 1;
return [
'total' => $this->dao->where('add_time', 'between', [$todayStart, $todayEnd])->count(),
'amount' => $this->dao->where('add_time', 'between', [$todayStart, $todayEnd])->sum('pay_price'),
'paid' => $this->dao->where('add_time', 'between', [$todayStart, $todayEnd])
->where('status', '>', 0)->count()
];
}
```
---
> **提示**：该文档由AI生成，仅供参考。

115
docs/phpapi/配置参数说明.md Normal file
View File

@ -0,0 +1,115 @@
# 配置参数说明
## ⚙️ 系统核心配置
### 数据库配置
```php
// config/database.php
'connections' => [
'mysql' => [
'hostname' => '127.0.0.1', // 数据库主机
'database' => 'crmeb', // 数据库名
'username' => 'root', // 用户名
'password' => '', // 密码
'hostport' => '3306', // 端口
'charset' => 'utf8mb4', // 字符集
]
]
```
### Redis缓存配置
```php
// config/cache.php
'redis' => [
'host' => '127.0.0.1', // Redis主机
'port' => 6379, // Redis端口
'password' => '', // 密码
'select' => 0, // 数据库索引
'timeout' => 0, // 超时时间
]
```
### 文件存储配置
```php
// config/filesystem.php
'disks' => [
'local' => [
'driver' => 'local', // 本地存储
'root' => app()->getRootPath() . 'public/uploads',
],
'qiniu' => [ // 七牛云存储
'driver' => 'qiniu',
'access_key' => env('qiniu.access_key'),
'secret_key' => env('qiniu.secret_key'),
'bucket' => env('qiniu.bucket'),
'domain' => env('qiniu.domain'),
]
]
```
## 🔧 业务相关配置
### 短信配置
```php
// 短信服务商配置
'sms' => [
'default' => 'aliyun', // 默认服务商
'aliyun' => [ // 阿里云短信
'access_key_id' => '',
'access_key_secret' => '',
'sign_name' => '', // 短信签名
]
]
```
### 支付配置
```php
// 微信支付配置
'wechat_pay' => [
'app_id' => '', // 应用ID
'mch_id' => '', // 商户号
'key' => '', // API密钥
'cert_path' => '', // 证书路径
'key_path' => '', // 密钥路径
]
```
### 第三方服务配置
```php
// 物流查询配置
'express' => [
'default' => 'kuaidi100', // 默认物流查询
'kuaidi100' => [ // 快递100
'customer' => '', // 客户编号
'key' => '', // 授权key
]
]
```
## 🌐 环境变量配置 (.env)
```ini
# 数据库配置
DATABASE_HOST=127.0.0.1
DATABASE_NAME=crmeb
DATABASE_USERNAME=root
DATABASE_PASSWORD=
# Redis配置
REDIS_HOST=127.0.0.1
REDIS_PORT=6379
REDIS_PASSWORD=
REDIS_SELECT=0
# 应用配置
APP_DEBUG=false
APP_URL=http://localhost
# 文件上传配置
UPLOAD_TYPE=local
UPLOAD_MAXSIZE=10485760
```
---
> **提示**：该文档由AI生成，仅供参考。

342
docs/phpapi/项目架构说明.md Normal file
View File

@ -0,0 +1,342 @@
# CRMEB 项目架构说明
## 🏗️ 整体架构概览
### 技术栈
```
前端：Vue.js 2 + ElementUI + UniApp
后端：ThinkPHP 6.0 + 多应用模式
数据库：MySQL 5.7+
缓存：Redis
消息队列：Workerman
```
### 架构模式
- **MVC 模式**：Model-View-Controller 分层架构
- **三层架构**：Controller → Service → DAO/Model
- **前后端分离**：API 接口与前端页面独立部署
- **多端适配**：支持小程序、H5、APP、PC 端
## 📂 项目目录结构
```
CRMEB/
├── app/ # 应用核心目录
│ ├── adminapi/ # 后台管理 API
│ │ ├── config/ # 配置文件（路由、中间件等）
│ │ ├── controller/ # 控制器层
│ │ │ ├── v1/ # API 版本 1
│ │ │ │ ├── agent/ # 代理相关
│ │ │ │ ├── marketing/ # 营销模块
│ │ │ │ ├── order/ # 订单模块
│ │ │ │ ├── product/ # 商品模块
│ │ │ │ ├── user/ # 用户模块
│ │ │ │ ├── ... # 其他功能模块
│ │ │ └── AuthController.php # 认证控制器
│ │ ├── middleware/ # 中间件
│ │ │ ├── AdminAuthTokenMiddleware.php # 后台 Token 认证
│ │ │ ├── AdminCheckRoleMiddleware.php # 角色权限检查
│ │ │ └── AdminLogMiddleware.php # 操作日志
│ │ ├── validate/ # 数据验证层
│ │ │ ├── marketing/ # 营销验证器
│ │ │ ├── order/ # 订单验证器
│ │ │ ├── product/ # 商品验证器
│ │ │ └── user/ # 用户验证器
│ │ └── route/ # 路由配置
│ │ ├── admin.php # 后台路由
│ │ ├── app.php # 前端路由
│ │ └── common.php # 公共路由
│ │
│ ├── api/ # 前端用户 API
│ │ ├── config/ # 配置文件
│ │ ├── controller/ # 控制器
│ │ │ ├── pc/ # PC 端接口
│ │ │ └── v1/ # 移动端接口
│ │ └── middleware/ # 中间件
│ │
│ ├── services/ # 业务服务层
│ │ ├── user/ # 用户服务
│ │ ├── order/ # 订单服务
│ │ ├── product/ # 商品服务
│ │ ├── payment/ # 支付服务
│ │ └── ...
│ │
│ ├── dao/ # 数据访问层
│ │ ├── UserDao.php
│ │ ├── OrderDao.php
│ │ └── ...
│ │
│ └── model/ # 数据模型层
│ ├── User.php
│ ├── Order.php
│ └── ...
│
├── crmeb/ # 核心库目录
│ ├── basic/ # 基础类库
│ │ ├── BaseController.php
│ │ ├── BaseServices.php
│ │ └── BaseDao.php
│ │
│ ├── services/ # 核心服务组件
│ │ ├── WechatServices.php # 微信服务
│ │ ├── SmsServices.php # 短信服务
│ │ ├── UploadServices.php # 文件上传服务
│ │ ├── CacheServices.php # 缓存服务
│ │ └── ...
│ │
│ ├── utils/ # 工具类
│ │ ├── Http.php # HTTP 请求工具
│ │ ├── Time.php # 时间处理工具
│ │ ├── Arr.php # 数组处理工具
│ │ └── ...
│ │
│ └── jobs/ # 队列任务
│
├── config/ # 系统配置
│ ├── app.php # 应用配置
│ ├── cache.php # 缓存配置
│ ├── database.php # 数据库配置
│ ├── filesystem.php # 文件存储配置
│ └── route.php # 路由配置
│
├── database/ # 数据库相关
│ ├── migrations/ # 数据库迁移
│ └── seeds/ # 数据填充
│
├── public/ # WEB 入口目录
│ ├── index.php # 入口文件
│ ├── router.php # 路由文件
│ ├── .htaccess # Apache 伪静态
│ └── uploads/ # 上传文件目录
│
├── extend/ # 扩展类库
│
├── runtime/ # 运行时目录
│ ├── cache/ # 缓存文件
│ ├── log/ # 日志文件
│ └── temp/ # 临时文件
│
├── docs/ # 项目文档
├── tests/ # 测试文件
└── composer.json # 依赖配置
```
## 🔄 请求处理流程
```
┌─────────────────────────────────────────────────────────────────┐
│ 客户端请求 │
└─────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────┐
│ Nginx / Apache │
│ 路由转发 │
└─────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────┐
│ public/index.php │
│ 应用入口文件 │
└─────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────┐
│ 应用中间件 (Middleware) │
│ 1. 全局中间件 │
│ 2. 路由中间件 │
│ 3. 控制器中间件 │
└─────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────┐
│ 路由分发 (Route) │
│ 根据 URL 映射到对应的控制器方法 │
└─────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────┐
│ 控制器层 (Controller) │
│ 1. 参数接收与初步验证 │
│ 2. 调用服务层处理业务 │
│ 3. 响应结果处理 │
└─────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────┐
│ 服务层 (Services) │
│ 1. 业务逻辑处理 │
│ 2. 数据组装与转换 │
│ 3. 调用 DAO 层操作数据 │
│ 4. 调用外部服务 │
└─────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────┐
│ 数据访问层 (DAO) │
│ 1. 基础 CRUD 操作 │
│ 2. 复杂查询封装 │
│ 3. 关联查询处理 │
└─────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────┐
│ 数据模型层 (Model) │
│ 1. 数据表映射 │
│ 2. 字段关联定义 │
│ 3. 模型事件处理 │
└─────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────┐
│ MySQL 数据库 │
└─────────────────────────────────────────────────────────────────┘
```
## 🔐 认证与授权机制
### JWT Token 认证
```
┌──────────────┐ 请求携带 Token ┌──────────────┐
│ 前端应用 │ ──────────────────→ │ 后端 API │
└──────────────┘ └──────────────┘
↓
┌──────────────┐
│ 解析 Token │
│ 验证有效性 │
└──────────────┘
↓
┌──────────────┐
│ 获取用户 ID │
│ 注入请求 │
└──────────────┘
```
### 权限控制
- **RBAC 权限模型**：用户 → 角色 → 权限
- **菜单权限**：控制后台菜单显示
- **按钮权限**：控制操作按钮显示
- **数据权限**：控制数据访问范围
## 📊 数据流转
### 订单数据流
```
用户下单 → 订单创建 → 库存预扣 → 支付处理 → 支付成功
↓
库存实际扣减 ← 发货处理 ← 订单发货
↓
订单完成 ← 收货确认 ← 物流更新
```
### 用户数据流
```
注册 → 信息完善 → 等级提升 → 积分获取 → 消费抵扣
↓
账户变动记录
```
## 🔧 核心服务组件
### 微信服务 (WechatServices)
- 公众号开发
- 小程序开发
- 微信支付
- 消息推送
### 短信服务 (SmsServices)
- 验证码发送
- 通知消息
- 营销短信
### 文件上传服务 (UploadServices)
- 本地存储
- 云存储（阿里云、七牛云、腾讯云）
- 图片处理
### 缓存服务 (CacheServices)
- 分布式缓存
- 页面缓存
- 数据缓存
## ?? 消息队列与定时任务
### 消息队列 (Workerman)
- 订单超时处理
- 异步通知发送
- 数据统计处理
- 批量数据操作
### 定时任务 (Timer)
- 订单自动取消
- 统计数据汇总
- 缓存自动清理
- 过期数据处理
## 📈 性能优化
### 缓存策略
- **接口缓存**：高频接口结果缓存
- **页面缓存**：减少页面渲染开销
- **数据缓存**：减少数据库查询
### 数据库优化
- **读写分离**：主从复制，读从写主
- **索引优化**：合理设计索引
- **慢查询分析**：定位性能瓶颈
### 代码优化
- **懒加载**：按需加载数据
- **预加载**：提前加载后续数据
- **批量处理**：减少循环操作
## 🛡️ 安全机制
### 接口安全
- **参数过滤**：防止 SQL 注入
- **频率限制**：防止恶意请求
- **签名验证**：防止数据篡改
### 数据安全
- **敏感加密**：密码、支付信息加密存储
- **日志记录**：操作全程记录
- **备份恢复**：数据定期备份
## 📱 多端适配
```
┌─────────────┐
│ 微信小程序 │ ← UniApp 编译
├─────────────┤
│ H5 页面 │ ← UniApp 编译
├─────────────┤
│ APP │ ← UniApp 编译（iOS/Android）
├─────────────┤
│ PC 端 │ ← Nuxt.js + Element
└─────────────┘
↓
统一后端 API
```
## 🔗 模块依赖关系
```
用户模块 (user)
├── 用户信息管理
├── 用户地址管理
├── 用户标签管理
└── 用户等级管理
↓
商品模块 (product)
├── 商品管理
├── 分类管理
├── 属性管理
└── 评价管理
↓
订单模块 (order)
├── 订单创建
├── 订单支付
├── 订单发货
└── 订单售后
↓
营销模块 (marketing)
├── 优惠券管理
├── 活动管理
├── 分销管理
└── 积分管理
```
---
> **提示**：该文档由AI生成，仅供参考。

219
docs/phpapi/项目目录文档.md Normal file
View File

@ -0,0 +1,219 @@
# CRMEB 项目目录文档
## 1. 引言
- **文档目的**: 详细说明 CRMEB 项目的目录结构和各目录功能
- **适用范围**: 项目开发人员、维护人员、新成员
- **术语定义**: 无特殊术语
## 2. 项目根目录结构
### 2.1 目录树
```
CRMEB/
├── .comate/ # Comate 工具配置
├── .env # 环境配置文件
├── .git/ # Git 版本控制
├── .gitignore # Git 忽略文件
├── .idea/ # IDEA 编辑器配置
├── .trae/ # Trae 工具配置
│ ├── rules/ # 规则配置
│ └── skills/ # 技能配置
├── crmeb/ # 核心应用目录
├── docker-compose/ # Docker 配置
├── docs/ # 文档目录
├── docs.zip # 文档压缩包
├── LICENSE # 许可证文件
├── readme/ # 说明文档
├── README.md # 项目说明
├── template/ # 模板文件
└── 安装必读.docx # 安装说明
```
### 2.2 根目录说明
- **.trae/**: Trae 工具配置目录，包含规则和技能配置
- **crmeb/**: 项目核心应用目录，包含所有业务逻辑
- **docker-compose/**: Docker 容器配置，用于快速部署
- **docs/**: 项目文档目录，存放各类说明文档
- **readme/**: 项目说明文档，包含功能介绍和截图
- **template/**: 模板文件目录，用于生成代码和配置
## 3. 核心应用目录结构 (crmeb/)
### 3.1 目录树
```
crmeb/
├── .constant # 常量定义
├── .env # 应用环境配置
├── .htaccess # Apache 配置
├── .phpstorm.meta.php # PHPStorm 元数据
├── .travis.yml # Travis CI 配置
├── .version # 版本信息
├── app/ # 应用核心目录
├── backup/ # 备份目录
├── build.example.php # 构建配置示例
├── composer.json # Composer 依赖配置
├── composer.lock # Composer 依赖锁定
├── config/ # 配置文件目录
├── crmeb/ # 核心库目录
├── filetree.txt # 文件树结构
├── index.html # 入口 HTML
├── install.lock # 安装锁定
├── LICENSE.txt # 许可证文件
├── public/ # 静态资源目录
├── README.md # 应用说明
├── route/ # 路由配置目录
├── runtime/ # 运行时目录
├── think # ThinkPHP 命令行工具
├── vendor/ # 依赖库目录
└── workerman.bat # Workerman 启动脚本
```
### 3.2 核心目录说明
- **app/**: 应用核心目录，包含所有业务逻辑
- **config/**: 配置文件目录，存放应用配置
- **crmeb/**: 核心库目录，提供基础功能
- **public/**: 静态资源目录，存放前端文件
- **route/**: 路由配置目录，定义 URL 路由
- **runtime/**: 运行时目录，存放缓存和日志
- **vendor/**: 依赖库目录，Composer 安装的依赖
## 4. 应用核心目录结构 (app/)
### 4.1 目录树
```
app/
├── adminapi/ # 后台 API 接口
├── api/ # 前端 API 接口
├── AppService.php # 应用服务
├── build.php # 构建配置
├── common.php # 公共函数
├── dao/ # 数据访问层
├── event.php # 事件配置
├── ExceptionHandle.php # 异常处理
├── filetree.txt # 文件树结构
├── http/ # HTTP 相关
├── jobs/ # 队列任务
├── kefuapi/ # 客服 API 接口
├── lang/ # 语言包
├── listener/ # 事件监听器
├── middleware.php # 中间件配置
├── model/ # 数据模型
├── outapi/ # 外部 API 接口
├── provider.php # 服务提供者
├── README.md # 目录说明
├── Request.php # 请求基类
├── service.php # 服务配置
└── services/ # 业务逻辑层
```
### 4.2 核心目录说明
- **adminapi/**: 后台管理系统 API 接口，处理后台请求
- **api/**: 前端应用 API 接口，处理客户端请求
- **dao/**: 数据访问层，封装数据库操作
- **jobs/**: 队列任务，处理异步操作
- **kefuapi/**: 客服系统 API 接口
- **model/**: 数据模型，定义数据结构
- **outapi/**: 外部系统 API 接口
- **services/**: 业务逻辑层，实现核心业务功能
## 5. 核心模块说明
### 5.1 控制器层 (api/, adminapi/, kefuapi/)
- 处理 HTTP 请求
- 路由分发
- 参数验证
- 返回响应
### 5.2 业务逻辑层 (services/)
- 实现核心业务逻辑
- 调用数据访问层
- 处理业务规则
### 5.3 数据访问层 (dao/)
- 封装数据库操作
- 提供数据查询方法
- 处理数据持久化
### 5.4 数据模型层 (model/)
- 定义数据结构
- 关联关系
- 数据验证
### 5.5 配置层 (config/)
- 应用配置
- 数据库配置
- 缓存配置
- 日志配置
## 6. 静态资源目录 (public/)
- **css/**: 样式文件
- **js/**: JavaScript 文件
- **images/**: 图片文件
- **fonts/**: 字体文件
- **uploads/**: 上传文件
## 7. 配置文件说明
### 7.1 核心配置文件
- **.env**: 环境变量配置
- **config/app.php**: 应用配置
- **config/database.php**: 数据库配置
- **config/cache.php**: 缓存配置
### 7.2 路由配置
- **route/api.php**: API 路由
- **route/adminapi.php**: 后台 API 路由
- **route/kefuapi.php**: 客服 API 路由
## 8. 核心文件说明
### 8.1 入口文件
- **public/index.php**: 应用入口文件
- **think**: 命令行工具
### 8.2 基础类
- **app/Request.php**: 请求基类
- **app/ExceptionHandle.php**: 异常处理类
- **app/AppService.php**: 应用服务类
### 8.3 配置文件
- **composer.json**: 依赖管理
- **.htaccess**: Apache 重写规则
## 9. 目录使用建议
### 9.1 开发规范
- **新增文件**: 按照对应模块目录结构存放
- **修改文件**: 保持原有目录结构
- **删除文件**: 确认无依赖后删除
### 9.2 命名规范
- **目录名**: 小写单词，无特殊字符
- **文件名**: 驼峰命名或小写下划线
- **类名**: PascalCase
- **方法名**: camelCase
## 10. 总结
### 10.1 目录结构特点
- **分层清晰**: 遵循 MVC 架构，分层明确
- **模块分离**: 按功能模块划分目录
- **配置集中**: 配置文件统一管理
- **资源分离**: 静态资源单独存放
### 10.2 后续计划
- 定期更新目录结构文档
- 根据项目演进调整目录结构
- 保持目录结构的合理性和可维护性
---
版本: 1.0
作者: 系统生成
更新日期: 2026-01-23
---
> **提示**：该文档由AI生成，仅供参考。

152
docs/uniapp/uniapp目录结构.md Normal file
View File

@ -0,0 +1,152 @@
# CRMEB 项目 uniapp 目录结构文档
## 1. 引言
- **文档目的**: 详细说明 CRMEB 项目中 uniapp 目录结构和各目录功能
- **适用范围**: 移动端开发人员、前端开发人员、项目维护人员
- **术语定义**: uniapp - 基于 Vue.js 的跨平台应用开发框架
## 2. 目录结构
### 2.1 目录树
```
uni-app/
├── androidPrivacy.json # Android 隐私政策配置
├── api/ # API 接口目录
├── App.vue # 应用入口组件
├── components/ # 公共组件目录
├── config/ # 配置文件目录
├── libs/ # 第三方库目录
├── main.js # 应用入口文件
├── manifest.json # 应用配置文件
├── mixins/ # 混入文件目录
├── package-lock.json # npm 依赖锁定文件
├── package.json # npm 依赖配置文件
├── pages/ # 页面目录
├── pages.json # 页面路由配置文件
├── plugin/ # 插件目录
├── static/ # 静态资源目录
├── store/ # 状态管理目录
├── uni.scss # 全局样式文件
├── utils/ # 工具函数目录
└── vue.config.js # Vue 配置文件
```
### 2.2 目录功能说明
#### 2.2.1 核心目录
- **api/**: 存放 API 接口定义，包含所有后端接口调用
- **components/**: 存放公共组件，可在多个页面复用
- **pages/**: 存放应用页面，每个页面对应一个子目录
- **static/**: 存放静态资源，如图片、字体、图标等
- **utils/**: 存放工具函数，如日期处理、请求封装等
#### 2.2.2 配置目录
- **config/**: 存放应用配置，如 API 地址、常量定义等
- **mixins/**: 存放混入文件，用于复用组件逻辑
- **store/**: 存放 Vuex 状态管理文件
- **libs/**: 存放第三方库，如 SDK、工具库等
#### 2.2.3 插件目录
- **plugin/**: 存放应用插件，如支付插件、分享插件等
## 3. 核心文件说明
### 3.1 入口文件
- **App.vue**: 应用根组件，全局配置和生命周期管理
- **main.js**: 应用入口文件，初始化 Vue 实例和全局配置
### 3.2 配置文件
- **manifest.json**: 应用配置文件，包含应用名称、版本、权限等
- **pages.json**: 页面路由配置文件，定义页面路径、导航栏等
- **vue.config.js**: Vue 项目配置文件，如代理配置、构建配置等
### 3.3 样式文件
- **uni.scss**: 全局样式文件，定义主题变量和通用样式
### 3.4 依赖文件
- **package.json**: npm 依赖配置文件，管理项目依赖
- **package-lock.json**: npm 依赖锁定文件，确保依赖版本一致
## 4. 页面目录结构
### 4.1 页面组织方式
```
pages/
├── index/ # 首页
│ ├── index.vue # 页面组件
│ └── main.js # 页面入口（可选）
├── goods/ # 商品相关页面
│ ├── list.vue # 商品列表
│ └── detail.vue # 商品详情
└── user/ # 用户相关页面
├── index.vue # 用户中心
└── login.vue # 登录页面
```
### 4.2 页面文件说明
- **页面组件 (.vue)**: 包含模板、脚本和样式
- **页面入口 (main.js)**: 页面级别的初始化配置（可选）
## 5. 开发规范
### 5.1 命名规范
- **目录名**: 小写单词，多个单词用连字符（-）分隔
- **文件名**: 小写单词，多个单词用连字符（-）分隔
- **组件名**: PascalCase 命名法
- **变量名**: camelCase 命名法
- **常量名**: 全大写，多个单词用下划线（_）分隔
### 5.2 代码规范
- 遵循 Vue 官方风格指南
- 使用 ES6+ 语法
- 组件化开发，提高代码复用性
- 合理使用 Vuex 管理全局状态
- 页面逻辑清晰，避免过度嵌套
### 5.3 性能优化
- 图片资源优化，使用适当尺寸和格式
- 减少 HTTP 请求，合理使用缓存
- 组件懒加载，减少初始包大小
- 避免在模板中使用复杂计算
- 合理使用 uni-app 提供的性能优化 API
## 6. 注意事项
### 6.1 跨平台兼容性
- 注意不同平台的 API 差异
- 避免使用平台特定的特性
- 测试时覆盖主要平台（iOS、Android、微信小程序等）
### 6.2 打包配置
- 根据不同平台配置相应的打包参数
- 注意应用权限配置
- 合理配置应用图标和启动页
### 6.3 调试技巧
- 使用 uni-app 开发者工具进行调试
- 利用 console.log 输出调试信息
- 关注控制台警告和错误信息
## 7. 总结
### 7.1 目录结构特点
- **结构清晰**: 遵循 uni-app 官方推荐的目录结构
- **模块化强**: 按功能模块化组织代码
- **易于维护**: 目录职责明确，代码结构合理
- **扩展性好**: 便于添加新功能和页面
### 7.2 后续计划
- 完善组件库，提高代码复用性
- 优化页面性能，提升用户体验
- 增加自动化测试，确保代码质量
- 持续更新依赖库，保持框架先进性
---
版本: 1.0
作者: 系统生成
更新日期: 2026-01-23
---
> **提示**：该文档由AI生成，仅供参考。

340
docs/uniapp/移动端前端架构说明.md Normal file
View File

@ -0,0 +1,340 @@
# CRMEB 移动端前端架构说明
## 📱 技术栈概览
| 技术 | 版本 | 说明 |
|------|------|------|
| UniApp | 2.x/3.x | 跨端开发框架 |
| Vue.js | 2.x/3.x | 核心框架 |
| Vuex | 3.x/4.x | 状态管理 |
| uView UI | 2.x | 移动端UI组件库 |
| Sass/Less | CSS预处理器 | |
| Axios | HTTP客户端 | 封装请求 |
## 🏗️ 整体架构
```
┌─────────────────────────────────────────────────────────────┐
│ UniApp 框架层 │
│ (跨端编译引擎) │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ Vue.js 核心层 │
│ (响应式数据驱动) │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ 状态管理层 │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ User模块 │ │ Cart模块 │ │ Order模块│ │ Config模块│ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ UI 组件层 │
│ ┌─────────────────────────────────────────────────────┐ │
│ │ 基础组件 │ 业务组件 │ 自定义组件 │ │
│ └─────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────┐
│ 多端适配层 │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ 微信小程序 │ │ H5页面 │ │ APP端 │ │ 其他平台 │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
└─────────────────────────────────────────────────────────────┘
```
## 🧩 核心功能模块
### 1. 商品模块
- 商品列表展示
- 商品详情页
- 商品搜索
- 商品分类
### 2. 购物车模块
- 添加商品到购物车
- 购物车管理
- 批量操作
### 3. 订单模块
- 订单创建
- 订单列表
- 订单详情
- 订单状态跟踪
### 4. 用户模块
- 用户登录注册
- 个人中心
- 地址管理
- 收藏管理
### 5. 支付模块
- 微信支付
- 支付宝支付
- 余额支付
## 🔧 开发最佳实践
### 1. 页面生命周期
```javascript
export default {
// 页面加载
onLoad(options) {
this.initPage(options)
},
// 页面显示
onShow() {
this.refreshData()
},
// 下拉刷新
onPullDownRefresh() {
this.loadData().finally(() => {
uni.stopPullDownRefresh()
})
},
// 上拉加载
onReachBottom() {
this.loadMore()
},
methods: {
async initPage(options) {
// 初始化页面数据
},
async refreshData() {
// 刷新数据
}
}
}
```
### 2. 组件通信
```javascript
// 父传子
<child-component :data="parentData" @custom-event="handleEvent" />
// 子组件
export default {
props: {
data: {
type: Object,
default: () => ({})
}
},
methods: {
emitEvent() {
this.$emit('custom-event', eventData)
}
}
}
```
### 3. 状态管理
```javascript
// 使用 Vuex
import { mapState, mapActions } from 'vuex'
export default {
computed: {
...mapState('user', ['userInfo']),
...mapState('cart', ['cartList'])
},
methods: {
...mapActions('user', ['login']),
...mapActions('cart', ['addToCart'])
}
}
```
## 🎯 性能优化
### 1. 图片优化
```javascript
// 使用懒加载
<image lazy-load src="image.jpg" />
// 使用webp格式
<image webp src="image.webp" />
// 使用合适的图片尺寸
<image :src="imageUrl + '?x-oss-process=image/resize,w_300'" />
```
### 2. 数据缓存
```javascript
// 使用本地存储
uni.setStorageSync('key', data)
const data = uni.getStorageSync('key')
// 使用内存缓存
const cache = new Map()
cache.set('key', data)
const data = cache.get('key')
```
### 3. 请求优化
```javascript
// 防抖处理
const debounce = (func, wait) => {
let timeout
return function() {
clearTimeout(timeout)
timeout = setTimeout(() => func.apply(this, arguments), wait)
}
}
// 使用
search: debounce(function(keyword) {
this.doSearch(keyword)
}, 300)
```
## 📦 多端适配
### 1. 条件编译
```javascript
// #ifdef H5
console.log('只在H5平台显示')
// #endif
// #ifdef MP-WEIXIN
console.log('只在微信小程序显示')
// #endif
// #ifdef APP-PLUS
console.log('只在App显示')
// #endif
```
### 2. 平台差异处理
```javascript
const platform = {
isH5: uni.getSystemInfoSync().platform === 'h5',
isWeapp: uni.getSystemInfoSync().platform === 'devtools',
isApp: uni.getSystemInfoSync().platform === 'app'
}
// 使用
if (platform.isH5) {
// H5特有逻辑
}
```
## 🚀 部署发布
### 1. 小程序发布
```bash
# 微信小程序
npm run build:mp-weixin
# 然后使用微信开发者工具上传
# 支付宝小程序
npm run build:mp-alipay
```
### 2. H5部署
```bash
# 构建H5
npm run build:h5
# 部署到服务器
scp -r dist/build/h5 user@server:/path/to/www
```
### 3. App发布
```bash
# 构建App
npm run build:app
# 使用HBuilderX进行打包和发布
```
## 🔍 调试技巧
### 1. 开发工具使用
```javascript
// 打印调试信息
console.log('调试信息', data)
// 使用debugger
debugger
// 性能监控
console.time('operation')
// 执行操作
console.timeEnd('operation')
```
### 2. 真机调试
```javascript
// 使用uni-app调试工具
// 1. 连接手机和电脑
// 2. 开启USB调试
// 3. 使用HBuilderX真机运行
```
## 📝 代码规范
### 1. 命名规范
```javascript
// 变量命名 - 小驼峰
const userName = 'John'
let isLoading = false
// 常量命名 - 全大写
const API_BASE_URL = 'https://api.example.com'
const MAX_COUNT = 100
// 组件命名 - 大驼峰
// MyComponent.vue
export default {
name: 'MyComponent'
}
```
### 2. 代码组织
```javascript
// 文件结构
export default {
// 1. 组件名
name: 'ComponentName',
// 2. 组件属性
props: {},
// 3. 数据
data() {
return {}
},
// 4. 计算属性
computed: {},
// 5. 监听器
watch: {},
// 6. 生命周期
mounted() {},
// 7. 方法
methods: {}
}
```
---
**文档版本**: v1.0
**更新日期**: 2024-01-17
**适用版本**: CRMEB 5.6.4+
💡 提示：移动端开发需要特别注意性能优化和多端适配，建议使用uni-app的Conditional Compile功能处理平台差异。
---
> **提示**：该文档由AI生成，仅供参考。

350
docs/uniapp/移动端前端目录结构详细说明.md Normal file
View File

@ -0,0 +1,350 @@
# CRMEB 移动端前端目录结构详细说明
## 📋 项目概览
**技术栈**: Vue.js 2.x + uni-app + Vuex + SCSS
**多端支持**: H5、微信小程序、支付宝小程序、百度小程序、头条小程序、App
**项目版本**: CRMEB标准版 5.6.2
**开发模式**: 组件化 + 模块化 + 分包加载
## 🏗️ 整体架构设计3
```
template/uni-app/
├── 📁 api/ # 接口服务层 (120+ API接口)
├── 📁 components/ # 组件层 (60+ 可复用组件)
├── 📁 config/ # 配置层
├── 📁 libs/ # 工具库层
├── 📁 mixins/ # 混入层
├── 📁 pages/ # 页面层 (分包架构)
├── 📁 plugin/ # 插件层
├── 📁 static/ # 静态资源层
├── 📁 store/ # 状态管理层
├── 📁 utils/ # 工具函数层
├── 🚀 App.vue # 应用根组件
├── 🎯 main.js # 应用入口
├── ⚙️ manifest.json # 应用配置文件
├── 📄 pages.json # 页面路由配置
└── 📦 package.json # 依赖配置
```
## 📊 详细目录结构解析
### 1. 📁 api/ - 接口服务层
按业务模块划分的API接口管理，采用Promise封装：
```javascript
// 文件结构
api/
├── activity.js # 营销活动接口 (砍价、拼团、秒杀等)
├── admin.js # 管理端接口
├── api.js # 基础API接口
├── kefu.js # 客服系统接口
├── lottery.js # 抽奖活动接口
├── order.js # 订单管理接口
├── points_mall.js # 积分商城接口
├── public.js # 公共接口 (配置获取等)
├── store.js # 门店相关接口
├── user.js # 用户中心接口
```
**接口设计特点**:
- 统一的错误处理机制
- 请求参数验证
- 响应数据格式化
- 支持多端环境适配
### 2. 📁 components/ - 组件层
丰富的组件库，采用原子化设计思想：
#### 2.1 基础组件
- `Authorize.vue` - 用户授权组件
- `BaseMoney.vue` - 金额显示组件（支持格式化）
- `BaseTag.vue` - 标签组件（多种样式）
- `emptyPage.vue` - 空状态页面组件
- `menuIcon.vue` - 菜单图标组件
#### 2.2 业务组件
- `addressWindow/` - 地址选择组件（三级联动）
- `cartList/` - 购物车商品列表
- `countDown/` - 倒计时组件（多种样式）
- `couponWindow/` - 优惠券选择组件
- `goodList/` - 商品列表组件（网格/列表布局）
- `home/` - 首页业务组件集合
- `orderGoods/` - 订单商品组件
- `payment/` - 支付组件（多支付方式）
#### 2.3 功能组件
- `easy-loadimage/` - 图片懒加载组件
- `jyf-parser/` - 富文本解析组件（支持HTML/Markdown）
- `Loading/` - 加载状态组件
- `skeleton/` - 骨架屏组件
- `swipers/` - 轮播图组件（可配置指示器）
- `update/` - 应用更新组件
- `WaterfallsFlow/` - 瀑布流布局组件
#### 2.4 特殊组件
- `parabolaBall/` - 抛物线动画组件（加入购物车动画）
- `shareRedPackets/` - 红包分享组件
- `tuiDrawer/` - 抽屉组件
- `uniNoticeBar/` - 通知栏组件
### 3. ?? config/ - 配置层
```javascript
config/
├── app.js # 应用基础配置
│ - HTTP_REQUEST_URL # API基础地址
│ - IMG_URL # 图片资源地址
│ - VERSION # 应用版本
│ - WS_URL # WebSocket地址
├── cache.js # 缓存配置
│ - 缓存键名定义
│ - 缓存策略配置
└── socket.js # Socket配置
```
### 4. 📁 libs/ - 工具库层
```javascript
libs/
├── chat.js # 聊天功能核心库
├── login.js # 登录认证工具
├── new_chat.js # 新版聊天服务
├── permission.js # 权限验证工具
├── routine.js # 小程序相关工具
├── uniApi.js # uni-app API增强
└── wechat.js # 微信SDK封装
```
### 5. 📁 mixins/ - 混入层
```javascript
mixins/
├── color.js # 颜色主题混入
├── debounce.js # 防抖函数混入
├── SendVerifyCode.js # 验证码发送混入
├── sharePoster.js # 分享海报生成混入
└── skuSelect.js # 商品SKU选择混入
```
### 6. 📁 pages/ - 页面层（分包架构）
#### 6.1 主包页面（核心页面）
- `guide/index` - 应用引导页
- `index/index` - 首页（TabBar）
- `order_addcart/order_addcart` - 购物车页（TabBar）
- `user/index` - 个人中心页（TabBar）
- `goods_cate/goods_cate` - 商品分类页（TabBar）
#### 6.2 商品模块分包 (goods)
```javascript
pages/goods/
├── goods_list/index # 商品列表
├── goods_search/index # 商品搜索
├── order_confirm/index # 订单确认
├── order_details/index # 订单详情
├── goods_details_store/index # 门店列表
├── goods_comment_con/index # 商品评价
├── cashier/index # 收银台
└── lottery/grids/index # 抽奖活动
```
#### 6.3 用户模块分包 (users)
```javascript
pages/users/
├── user_info/index # 用户信息
├── user_address/index # 地址管理
├── user_coupon/index # 优惠券
├── user_spread_user/index # 推广管理
├── user_money/index # 我的账户
├── login/index # 登录页面
└── message_center/index # 消息中心
```
#### 6.4 活动模块分包 (activity)
```javascript
pages/activity/
├── goods_bargain/index # 砍价活动
├── goods_combination/index # 拼团活动
├── goods_seckill/index # 秒杀活动
├── presell/index # 预售活动
└── bargain/index # 砍价记录
```
#### 6.5 管理模块分包 (admin)
```javascript
pages/admin/
├── order/index # 订单管理
├── orderList/index # 订单列表
├── statistics/index # 数据统计
├── delivery/index # 订单发货
└── order_cancellation/index # 订单核销
```
#### 6.6 其他分包
- `annex/` - 附件页面（Webview、会员等）
- `points_mall/` - 积分商城
- `extension/` - 扩展功能（客服、资讯等）
- `columnGoods/` - 专栏商品
- `goods_details/` - 商品详情（独立分包）
### 7. 📁 static/ - 静态资源层
#### 7.1 样式资源
```css
static/
├── css/
│ ├── base.css # 基础样式重置
│ ├── style.scss # 主要样式文件
│ ├── unocss.css # UnoCSS工具样式
│ └── guildford.css # 特定样式
├── fonts/ # 字体文件
│ └── D-DIN-PRO-*.ttf
└── iconfont/ # 图标字体
└── iconfont.css
```
#### 7.2 图片资源
```bash
static/images/
├── 1-001.png ~ 4-002.png # TabBar图标
├── def_avatar.png # 默认头像
├── vip.png # VIP标识
├── svip.png # SVIP标识
└── 各种功能图标和背景图片
```
#### 7.3 其他资源
- `app-plus/` - App特有资源
- `easy-loadimage/` - 图片加载相关资源
### 8. 📁 store/ - 状态管理层
Vuex模块化状态管理：
```javascript
store/
├── modules/ # 状态模块
│ ├── app.js # 应用状态
│ ├── hotWords.js # 搜索热词状态
│ └── indexData.js # 首页数据状态
├── getters.js # Getter函数
└── index.js # Store主入口
```
**状态管理特点**:
- 模块化状态划分
- 严格的mutations修改
- 支持状态持久化
- 多端状态同步
### 9. 📁 utils/ - 工具函数层
```javascript
utils/
├── cache.js # 缓存管理工具
├── emoji.js # 表情处理工具
├── index.js # 工具主入口
├── lang.js # 多语言工具
├── permission.js # 权限验证工具
├── request.js # 请求封装工具
├── util.js # 通用工具函数
├── validate.js # 数据验证工具
└── theme.js # 主题管理工具
```
## 🚀 核心技术特性
### 1. 多端适配机制
```javascript
// 条件编译示例
// #ifdef H5
// H5特有代码
// #endif
// #ifdef MP-WEIXIN
// 微信小程序特有代码
// #endif
// #ifdef APP-PLUS
// App特有代码
// #endif
```
### 2. 性能优化策略
- **分包加载**: 按业务模块分包，减少主包体积
- **图片懒加载**: 滚动可视区域加载
- **组件懒加载**: 路由级别的代码分割
- **数据缓存**: 合理的缓存策略
- **请求防抖**: 避免重复请求
### 3. 主题换肤系统
支持动态主题色切换，通过CSS变量实现：
```css
:root {
--view-theme: #e93323; /* 主要主题色 */
--view-assist: #ff9900; /* 辅助色 */
}
```
### 4. 国际化支持
基于Vue I18n的多语言支持，支持动态语言包加载。
## 📋 开发规范
### 1. 命名规范
- **目录命名**: 小写字母，使用连字符 `my-component`
- **文件命名**: Vue组件使用帕斯卡命名 `MyComponent.vue`
- **变量命名**: 驼峰命名 `userInfo`
- **常量命名**: 全大写加下划线 `API_BASE_URL`
### 2. 代码组织
- 单一职责原则
- 组件props验证
- 错误边界处理
- 合理的注释规范
### 3. 提交规范
- feat: 新功能
- fix: 修复bug
- docs: 文档更新
- style: 代码格式
- refactor: 代码重构
## 🛠️ 开发命令
```bash
# 开发环境
npm run dev:[platform]
# 生产构建
npm run build:[platform]
# 代码检查
npm run lint
# 示例
npm run dev:mp-weixin # 微信小程序开发
npm run build:h5 # H5生产构建
npm run build:app-plus # App生产构建
```
## 📝 注意事项
1. **环境配置**: 确保正确配置API地址和第三方服务密钥
2. **平台差异**: 注意不同平台的API兼容性
3. **图片资源**: 使用相对路径，注意多端适配
4. **权限申请**: 按需申请平台权限
5. **版本兼容**: 注意uni-app版本兼容性
---
*本文档基于CRMEB 5.6.2版本分析生成，最后更新: 2026-01-19*
*📧 如有疑问请联系开发团队: admin@crmeb.com*
---
> **提示**：该文档由AI生成，仅供参考。