diff --git a/.comate/specs/order_development_flow/doc.md b/.comate/specs/order_development_flow/doc.md new file mode 100644 index 000000000..7a905c959 --- /dev/null +++ b/.comate/specs/order_development_flow/doc.md @@ -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订单系统的完整开发流程，为开发团队提供了详细的指导。在实际开发中，请根据具体业务需求进行相应的调整和扩展。 \ No newline at end of file diff --git a/.comate/specs/order_development_flow/tasks.md b/.comate/specs/order_development_flow/tasks.md new file mode 100644 index 000000000..74059b8f3 --- /dev/null +++ b/.comate/specs/order_development_flow/tasks.md @@ -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: 添加数据迁移和清理脚本 \ No newline at end of file diff --git a/.comate/specs/order_flow/doc.md b/.comate/specs/order_flow/doc.md new file mode 100644 index 000000000..b65e6f43d --- /dev/null +++ b/.comate/specs/order_flow/doc.md @@ -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. **监控告警**: 关键指标监控和异常告警机制 + +该订单流程设计具备高可用性、高性能、高安全性的特点，能够满足大型电商平台的业务需求。 \ No newline at end of file diff --git a/.trae/rules/project_rules.md b/.trae/rules/project_rules.md new file mode 100644 index 000000000..76fae8afc --- /dev/null +++ b/.trae/rules/project_rules.md @@ -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 项目所有开发人员，确保代码一致性、可维护性和安全性。 \ No newline at end of file diff --git a/.trae/skills/docs规范/SKILL.md b/.trae/skills/docs规范/SKILL.md new file mode 100644 index 000000000..23ab3b2cd --- /dev/null +++ b/.trae/skills/docs规范/SKILL.md @@ -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 项目所有文档写作，确保文档质量和一致性。 + diff --git a/.trae/skills/uniapp说明/SKILL.md b/.trae/skills/uniapp说明/SKILL.md new file mode 100644 index 000000000..e4a3f1497 --- /dev/null +++ b/.trae/skills/uniapp说明/SKILL.md @@ -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**: 持续集成/持续部署 +- **文档协作**: 团队文档协作工具 \ No newline at end of file diff --git a/.trae/skills/目录结构/SKILL.md b/.trae/skills/目录结构/SKILL.md new file mode 100644 index 000000000..236a411eb --- /dev/null +++ b/.trae/skills/目录结构/SKILL.md @@ -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 关联查询 +- 使用队列处理耗时操作 +- 优化文件和目录结构，提高加载速度 \ No newline at end of file diff --git a/.trae/skills/管理端文档说明/SKILL.md b/.trae/skills/管理端文档说明/SKILL.md new file mode 100644 index 000000000..d96c55a7d --- /dev/null +++ b/.trae/skills/管理端文档说明/SKILL.md @@ -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**: 持续集成/持续部署 +- **文档协作**: 团队文档协作工具 \ No newline at end of file diff --git a/docs/AI代码理解指南.md b/docs/AI代码理解指南.md new file mode 100644 index 000000000..3a36d2384 --- /dev/null +++ b/docs/AI代码理解指南.md @@ -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生成，仅供参考。 diff --git a/docs/admin/后台管理前端架构说明.md b/docs/admin/后台管理前端架构说明.md new file mode 100644 index 000000000..f63a48323 --- /dev/null +++ b/docs/admin/后台管理前端架构说明.md @@ -0,0 +1,1129 @@ +# CRMEB 后台管理前端架构说明 + +## 📋 技术栈概览 + +| 技术 | 版本 | 说明 | +|------|------|------| +| Vue.js | 2.x | 前端核心框架 | +| Element UI | 2.x | UI组件库 | +| Vuex | 3.x | 状态管理 | +| Axios | 0.x | HTTP客户端 | +| VXE-Table | 高级表格组件 | | +| WangEditor | 富文本编辑器 | | +| Sass | CSS预处理器 | | +| Prettier | 代码格式化工具 | | +| Vue-Viewer | 图片查看器 | | + +## ??️ 整体架构 + +``` +┌─────────────────────────────────────────────────────────────┐ +│ Vue Router │ +│ (路由管理器) │ +└─────────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────────┐ +│ Vuex Store │ +│ (状态管理) │ +│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ +│ │ User模块 │ │ Order模块│ │ Product模块│ │ System模块│ │ +│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │ +└─────────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────────┐ +│ Vue Components │ +│ (视图组件层) │ +│ ┌─────────────────────────────────────────────────────┐ │ +│ │ Layout布局 │ Table表格 │ Form表单 │ │ +│ └─────────────────────────────────────────────────────┘ │ +└─────────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────────┐ +│ API Services │ +│ (接口服务层) │ +└─────────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────────┐ +│ Axios HTTP Client │ +│ (HTTP请求层) │ +└─────────────────────────────────────────────────────────────┘ +``` + +## 📂 目录结构 + +### 标准后台管理前端目录结构 + +``` +admin-web/ # 后台管理前端项目 +├── public/ # 公共资源 +│ ├── index.html # HTML模板 +│ └── favicon.ico # 网站图标 +│ +├── src/ # 源代码目录 +│ ├── api/ # API接口定义 +│ │ ├── user.js # 用户相关接口 +│ │ ├── order.js # 订单相关接口 +│ │ ├── product.js # 商品相关接口 +│ │ ├── system.js # 系统相关接口 +│ │ └── index.js # 接口入口 +│ │ +│ ├── assets/ # 静态资源 +│ │ ├── images/ # 图片资源 +│ │ ├── styles/ # 样式文件 +│ │ └── fonts/ # 字体文件 +│ │ +│ ├── components/ # 公共组件 +│ │ ├── Layout/ # 布局组件 +│ │ │ ├── Header.vue # 顶部导航 +│ │ │ ├── Sidebar.vue # 侧边菜单 +│ │ │ └── Breadcrumb.vue # 面包屑 +│ │ │ +│ │ ├── Table/ # 表格组件 +│ │ │ ├── TableColumn.vue # 表格列 +│ │ │ └── TablePage.vue # 分页组件 +│ │ │ +│ │ ├── Form/ # 表单组件 +│ │ │ ├── FormItem.vue # 表单项 +│ │ │ └── Upload.vue # 上传组件 +│ │ │ +│ │ └── Common/ # 通用组件 +│ │ ├── Dialog.vue # 弹窗 +│ │ ├── Select.vue # 选择器 +│ │ └── UploadImage.vue # 图片上传 +│ │ +│ ├── views/ # 页面视图 +│ │ ├── login/ # 登录页 +│ │ │ └── index.vue +│ │ │ +│ │ ├── dashboard/ # 控制台 +│ │ │ └── index.vue +│ │ │ +│ │ ├── user/ # 用户管理 +│ │ │ ├── list.vue # 用户列表 +│ │ │ ├── detail.vue # 用户详情 +│ │ │ └── edit.vue # 用户编辑 +│ │ │ +│ │ ├── order/ # 订单管理 +│ │ │ ├── list.vue # 订单列表 +│ │ │ ├── detail.vue # 订单详情 +│ │ │ └── export.vue # 订单导出 +│ │ │ +│ │ ├── product/ # 商品管理 +│ │ │ ├── list.vue # 商品列表 +│ │ │ ├── edit.vue # 商品编辑 +│ │ │ └── category.vue # 分类管理 +│ │ │ +│ │ ├── marketing/ # 营销管理 +│ │ │ ├── coupon.vue # 优惠券 +│ │ │ ├── seckill.vue # 秒杀活动 +│ │ │ └── combination.vue # 拼团活动 +│ │ │ +│ │ └── system/ # 系统管理 +│ │ ├── config.vue # 系统配置 +│ │ ├── admin.vue # 管理员 +│ │ └── role.vue # 角色权限 +│ │ +│ ├── router/ # 路由配置 +│ │ ├── index.js # 路由入口 +│ │ └── modules/ # 模块路由 +│ │ ├── user.js +│ │ ├── order.js +│ │ └── system.js +│ │ +│ ├── store/ # Vuex状态管理 +│ │ ├── index.js # Store入口 +│ │ ├── getters.js # Getters +│ │ └── modules/ # 状态模块 +│ │ ├── user.js # 用户状态 +│ │ ├── app.js # 应用状态 +│ │ └── permission.js # 权限状态 +│ │ +│ ├── utils/ # 工具函数 +│ │ ├── request.js # Axios封装 +│ │ ├── auth.js # 权限相关 +│ │ ├── validate.js # 表单验证 +│ │ └── format.js # 格式处理 +│ │ +│ ├── directive/ # 自定义指令 +│ │ ├── permission.js # 权限指令 +│ │ └── draggable.js # 拖拽指令 +│ │ +│ ├── filters/ # 过滤器 +│ │ ├── index.js # 过滤器入口 +│ │ ├── date.js # 日期格式化 +│ │ └── currency.js # 金额格式化 +│ │ +│ ├── App.vue # 根组件 +│ └── main.js # 入口文件 +│ +├── .env # 环境变量 +├── .env.development # 开发环境配置 +├── .env.production # 生产环境配置 +│ +├── package.json # 项目配置 +├── vue.config.js # Vue CLI配置 +└── README.md # 项目说明 +``` + +## 🔧 核心模块详解 + +### 1. 路由模块 (Router) + +#### 路由配置结构 +```javascript +// src/router/index.js +import Vue from 'vue' +import VueRouter from 'vue-router' +import { constantRoutes } from './modules' + +Vue.use(VueRouter) + +// 创建路由实例 +export const createRouter = () => new VueRouter({ + routes: constantRoutes, + mode: 'history', + scrollBehavior: () => ({ y: 0 }) +}) + +// 静态路由 +export const constantRoutes = [ + { + path: '/login', + component: () => import('@/views/login/index'), + meta: { title: '登录' } + }, + { + path: '/404', + component: () => import('@/views/error/404') + }, + { + path: '/', + component: Layout, + redirect: '/dashboard', + children: [ + { + path: 'dashboard', + name: 'Dashboard', + component: () => import('@/views/dashboard/index'), + meta: { title: '控制台', icon: 'dashboard' } + } + ] + } +] +``` + +#### 动态路由（权限控制） +```javascript +// src/router/modules/permission.js +export const asyncRoutes = [ + { + path: '/user', + component: Layout, + meta: { + title: '用户管理', + icon: 'user', + roles: ['admin', 'manager'] + }, + children: [ + { + path: 'list', + name: 'UserList', + component: () => import('@/views/user/list'), + meta: { + title: '用户列表', + roles: ['admin'] + } + } + ] + } +] +``` + +### 2. 状态管理 (Vuex) + +#### Store结构 +```javascript +// src/store/index.js +import Vue from 'vue' +import Vuex from 'vuex' +import user from './modules/user' +import app from './modules/app' +import permission from './modules/permission' + +Vue.use(Vuex) + +export default new Vuex.Store({ + modules: { + user, + app, + permission + }, + getters: { + token: state => state.user.token, + roles: state => state.user.roles, + sidebarOpened: state => app.sidebarOpened, + permissionRoutes: state => permission.routes + } +}) +``` + +#### 用户状态模块 +```javascript +// src/store/modules/user.js +const state = { + token: localStorage.getItem('token') || '', + userInfo: {}, + roles: [] +} + +const mutations = { + SET_TOKEN(state, token) { + state.token = token + localStorage.setItem('token', token) + }, + SET_USER_INFO(state, userInfo) { + state.userInfo = userInfo + }, + SET_ROLES(state, roles) { + state.roles = roles + } +} + +const actions = { + // 登录 + async login({ commit }, userInfo) { + const res = await login(userInfo) + commit('SET_TOKEN', res.data.token) + return res + }, + + // 获取用户信息 + async getInfo({ commit }) { + const res = await getUserInfo() + commit('SET_USER_INFO', res.data) + commit('SET_ROLES', res.data.roles) + return res + }, + + // 退出登录 + async logout({ commit }) { + await logout() + commit('SET_TOKEN', '') + commit('SET_USER_INFO', {}) + } +} + +export default { + namespaced: true, + state, + mutations, + actions +} +``` + +### 3. API服务层 + +#### Axios封装 +```javascript +// src/utils/request.js +import axios from 'axios' +import { Message, MessageBox } from 'element-ui' +import store from '@/store' +import router from '@/router' + +// 创建axios实例 +const service = axios.create({ + baseURL: process.env.VUE_APP_BASE_API, + timeout: 30000 +}) + +// 请求拦截器 +service.interceptors.request.use( + config => { + // 添加token + if (store.getters.token) { + config.headers['Authorization'] = `Bearer ${store.getters.token}` + } + return config + }, + error => { + return Promise.reject(error) + } +) + +// 响应拦截器 +service.interceptors.response.use( + response => { + const res = response.data + if (res.code === 200) { + return res + } + Message.error(res.msg || '请求失败') + return Promise.reject(new Error(res.msg || '请求失败')) + }, + error => { + if (error.response) { + const { status } = error.response + if (status === 401) { + MessageBox.confirm('登录状态已过期，请重新登录', '确认登录', { + confirmButtonText: '重新登录', + cancelButtonText: '取消', + type: 'warning' + }).then(() => { + store.dispatch('user/logout') + router.push('/login') + }) + } + } + return Promise.reject(error) + } +) + +export default service +``` + +#### API接口定义 +```javascript +// src/api/user.js +import request from '@/utils/request' + +// 获取用户列表 +export function getUserList(params) { + return request({ + url: '/adminapi/v1/user/list', + method: 'get', + params + }) +} + +// 获取用户详情 +export function getUserDetail(id) { + return request({ + url: `/adminapi/v1/user/${id}`, + method: 'get' + }) +} + +// 编辑用户 +export function editUser(data) { + return request({ + url: '/adminapi/v1/user/edit', + method: 'post', + data + }) +} + +// 删除用户 +export function deleteUser(id) { + return request({ + url: `/adminapi/v1/user/${id}`, + method: 'delete' + }) +} +``` + +### 4. 布局组件 (Layout) + +#### 主布局组件 +```vue + + + + + + +``` + +#### 侧边栏组件 +```vue + + + + +``` + +### 5. 列表页面组件 + +#### 通用列表页面模板 +```vue + + + + +``` + +### 6. 表单页面组件 + +#### 通用表单页面模板 +```vue + + + + +``` + +## 🎨 样式规范 + +### SCSS 变量定义 +```scss +// src/assets/styles/variables.scss + +// 主题色 +$primary-color: #409EFF; +$success-color: #67C23A; +$warning-color: #E6A23C; +$danger-color: #F56C6C; +$info-color: #909399; + +// 背景色 +$bg-color: #f0f2f5; +$white: #ffffff; + +// 文字颜色 +$text-primary: #303133; +$text-regular: #606266; +$text-secondary: #909399; +$text-placeholder: #c0c4cc; + +// 边框颜色 +$border-color: #dcdfe6; +$border-color-light: #e4e7ed; +$border-color-lighter: #ebeef5; + +// 字体 +$font-size-base: 14px; +$font-size-small: 12px; +$font-size-large: 16px; +``` + +### 通用样式 +```scss +// src/assets/styles/common.scss + +// 通用页面容器 +.app-container { + padding: 20px; +} + +// 卡片样式 +.card-header { + display: flex; + justify-content: space-between; + align-items: center; +} + +// 表格操作按钮 +.table-action-btn { + margin: 0 5px; +} + +// 表单样式 +.form-container { + max-width: 600px; + margin: 0 auto; +} +``` + +## 🔐 权限控制 + +### 权限指令 +```javascript +// src/directive/permission.js +import Vue from 'vue' + +// v-permission 指令 +Vue.directive('permission', { + inserted: function(el, binding) { + const { value } = binding + const permissions = Vue.prototype.$store.getters.permissions + + if (value && value instanceof Array) { + const hasPermission = value.some(permission => { + return permissions.includes(permission) + }) + + if (!hasPermission) { + el.parentNode && el.parentNode.removeChild(el) + } + } else { + throw new Error('v-permission value must be array') + } + } +}) +``` + +### 使用示例 +```vue + +``` + +## 📊 常用组件使用 + +### 表格组件 (VXE-Table) +```vue + +``` + +### 富文本编辑器 (WangEditor) +```vue + + + +``` + +## 🧪 测试配置 + +### Jest 测试配置 +```javascript +// jest.config.js +module.exports = { + testURL: 'http://localhost', + moduleFileExtensions: ['js', 'jsx', 'json', 'vue'], + transform: { + '^.+\\.vue$': 'vue-jest', + '^.+\\.js$': 'babel-jest' + }, + moduleNameMapper: { + '^@/(.*)$': '/src/$1' + }, + testMatch: ['/tests/**/*.spec.js'], + collectCoverageFrom: [ + 'src/**/*.{js,vue}', + '!src/main.js' + ] +} +``` + +### 测试示例 +```javascript +// tests/unit/user.spec.js +import { shallowMount } from '@vue/test-utils' +import UserList from '@/views/user/list.vue' + +describe('UserList', () => { + it('renders user list correctly', () => { + const wrapper = shallowMount(UserList, { + mocks: { + $route: { path: '/user/list' }, + $store: { + getters: { roles: ['admin'] } + } + } + }) + + expect(wrapper.find('.el-table').exists()).toBe(true) + expect(wrapper.find('.pagination').exists()).toBe(true) + }) +}) +``` + +## 🚀 构建部署 + +### 环境配置 +```bash +# .env.development +VUE_APP_BASE_API = 'http://localhost:8000' +VUE_APP_WS_API = 'ws://localhost:8000' + +# .env.production +VUE_APP_BASE_API = 'https://api.crmeb.com' +VUE_APP_WS_API = 'wss://api.crmeb.com' +``` + +### 构建命令 +```bash +# 安装依赖 +npm install + +# 开发环境 +npm run dev + +# 生产环境构建 +npm run build:prod + +# 代码检查 +npm run lint + +# 单元测试 +npm run test +``` + +### Nginx 配置 +```nginx +server { + listen 80; + server_name admin.crmeb.com; + + # 前端静态资源 + location / { + root /usr/share/nginx/html; + index index.html; + try_files $uri $uri/ /index.html; + } + + # API代理 + location /adminapi/ { + proxy_pass http://127.0.0.1:8000; + proxy_set_header Host $host; + proxy_set_header X-Real-IP $remote_addr; + } + + # WebSocket代理 + location /ws/ { + proxy_pass http://127.0.0.1:8000; + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection "upgrade"; + } +} +``` + +## 📝 开发规范 + +### 代码风格 +- 使用 ESLint + Prettier 进行代码格式化 +- Vue组件使用单文件组件 (.vue) +- 组件名使用 PascalCase 命名 +- 样式使用 SCSS 预处理器 + +### Git 提交规范 +``` +feat: 新增用户管理功能 +fix: 修复订单列表分页问题 +docs: 更新接口文档 +style: 代码格式调整 +refactor: 重构用户模块代码 +test: 添加单元测试 +chore: 更新构建配置 +``` + +--- +**文档版本**: v1.0 +**最后更新**: 2024-01-17 +**适用版本**: CRMEB 5.6.4+ +**维护团队**: 前端开发组 + +💡 提示：后台管理前端采用 Element UI 组件库，配合 Vuex 进行状态管理，通过 Axios 封装统一处理 HTTP 请求，实现了完整的权限控制和数据交互功能。 + +--- + +> **提示**：该文档由AI生成，仅供参考。 diff --git a/docs/admin/管理端前端目录结构详细说明.md b/docs/admin/管理端前端目录结构详细说明.md new file mode 100644 index 000000000..c3d2ae70f --- /dev/null +++ b/docs/admin/管理端前端目录结构详细说明.md @@ -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生成，仅供参考。 diff --git a/docs/docker安装说明文档.md b/docs/docker安装说明文档.md new file mode 100644 index 000000000..3d087c5a9 --- /dev/null +++ b/docs/docker安装说明文档.md @@ -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 +``` + +### 7.2 重启服务 + +```bash +# 重启所有服务 +docker-compose restart + +# 重启指定服务 +docker-compose restart +``` + +### 7.3 查看日志 + +```bash +# 查看所有服务日志 +docker-compose logs + +# 查看指定服务日志 +docker-compose logs + +# 实时查看日志 +docker-compose logs -f +``` + +## 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生成，仅供参考。 diff --git a/docs/phpapi/API接口文档.md b/docs/phpapi/API接口文档.md new file mode 100644 index 000000000..faa711ac6 --- /dev/null +++ b/docs/phpapi/API接口文档.md @@ -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生成，仅供参考。 diff --git a/docs/phpapi/业务流程说明.md b/docs/phpapi/业务流程说明.md new file mode 100644 index 000000000..c957147a7 --- /dev/null +++ b/docs/phpapi/业务流程说明.md @@ -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生成，仅供参考。 diff --git a/docs/phpapi/会员管理开发文档.md b/docs/phpapi/会员管理开发文档.md new file mode 100644 index 000000000..edfe0b4c1 --- /dev/null +++ b/docs/phpapi/会员管理开发文档.md @@ -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生成，仅供参考。 diff --git a/docs/phpapi/分销系统说明文档.md b/docs/phpapi/分销系统说明文档.md new file mode 100644 index 000000000..cf4d26d79 --- /dev/null +++ b/docs/phpapi/分销系统说明文档.md @@ -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生成，仅供参考。 diff --git a/docs/phpapi/后端代码目录结构说明.md b/docs/phpapi/后端代码目录结构说明.md new file mode 100644 index 000000000..bbe08b109 --- /dev/null +++ b/docs/phpapi/后端代码目录结构说明.md @@ -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生成，仅供参考。 diff --git a/docs/phpapi/后端系统事件文档说明.md b/docs/phpapi/后端系统事件文档说明.md new file mode 100644 index 000000000..0a25b2790 --- /dev/null +++ b/docs/phpapi/后端系统事件文档说明.md @@ -0,0 +1,398 @@ +# CRMEB 后端系统事件文档说明 + +## 1. 事件机制概述 + +CRMEB后端系统采用事件驱动架构，通过事件机制实现模块间的解耦和通信。事件系统允许在不直接依赖的情况下，实现不同模块间的交互和业务逻辑扩展。 + +### 1.1 核心概念 + +- **事件(Event)**：系统中发生的特定动作或状态变化，如订单创建、用户注册等。 +- **监听器(Listener)**：监听特定事件并执行相应处理逻辑的类。 +- **事件触发(Trigger)**：在特定业务逻辑点调用事件，通知相关监听器执行。 + +## 2. 监听器接口定义 + +所有监听器必须实现 `crmeb\interfaces\ListenerInterface` 接口，该接口定义了统一的事件处理方法。 + +```php + [], // 事件绑定 + '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 +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 +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 +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生成，仅供参考。 diff --git a/docs/phpapi/商品管理开发文档.md b/docs/phpapi/商品管理开发文档.md new file mode 100644 index 000000000..e2a923eb3 --- /dev/null +++ b/docs/phpapi/商品管理开发文档.md @@ -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生成，仅供参考。 diff --git a/docs/phpapi/客服系统开发文档.md b/docs/phpapi/客服系统开发文档.md new file mode 100644 index 000000000..0e13ceb6c --- /dev/null +++ b/docs/phpapi/客服系统开发文档.md @@ -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生成，仅供参考。 diff --git a/docs/phpapi/开发规范说明.md b/docs/phpapi/开发规范说明.md new file mode 100644 index 000000000..f309b7b77 --- /dev/null +++ b/docs/phpapi/开发规范说明.md @@ -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生成，仅供参考。 diff --git a/docs/phpapi/支付开发流程文档-V2.md b/docs/phpapi/支付开发流程文档-V2.md new file mode 100644 index 000000000..55f10efc3 --- /dev/null +++ b/docs/phpapi/支付开发流程文档-V2.md @@ -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生成，仅供参考。 diff --git a/docs/phpapi/支付开发流程文档.md b/docs/phpapi/支付开发流程文档.md new file mode 100644 index 000000000..9b332dc06 --- /dev/null +++ b/docs/phpapi/支付开发流程文档.md @@ -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 +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 +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 + 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 + '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 + +# 4. 启用备用支付通道 +php think payment:enable alipay +``` + +--- +**文档版本**: v1.0 +**最后更新**: 2024-01-17 +**维护人员**: 支付开发团队 + +💡 **提示**: 支付功能涉及资金安全，请严格遵循安全规范和审计要求。 + +--- + +> **提示**：该文档由AI生成，仅供参考。 diff --git a/docs/phpapi/数据库结构设计.md b/docs/phpapi/数据库结构设计.md new file mode 100644 index 000000000..1b7363861 --- /dev/null +++ b/docs/phpapi/数据库结构设计.md @@ -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生成，仅供参考。 diff --git a/docs/phpapi/服务管理开发文档.md b/docs/phpapi/服务管理开发文档.md new file mode 100644 index 000000000..a9b107762 --- /dev/null +++ b/docs/phpapi/服务管理开发文档.md @@ -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生成，仅供参考。 diff --git a/docs/phpapi/消息通知开发文档.md b/docs/phpapi/消息通知开发文档.md new file mode 100644 index 000000000..d72093c48 --- /dev/null +++ b/docs/phpapi/消息通知开发文档.md @@ -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生成，仅供参考。 diff --git a/docs/phpapi/物流管理开发文档.md b/docs/phpapi/物流管理开发文档.md new file mode 100644 index 000000000..639521f57 --- /dev/null +++ b/docs/phpapi/物流管理开发文档.md @@ -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生成，仅供参考。 diff --git a/docs/phpapi/系统分销开发文档.md b/docs/phpapi/系统分销开发文档.md new file mode 100644 index 000000000..6e4dedd41 --- /dev/null +++ b/docs/phpapi/系统分销开发文档.md @@ -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生成，仅供参考。 diff --git a/docs/phpapi/系统安装流程文档.md b/docs/phpapi/系统安装流程文档.md new file mode 100644 index 000000000..a1bfc473d --- /dev/null +++ b/docs/phpapi/系统安装流程文档.md @@ -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生成，仅供参考。 diff --git a/docs/phpapi/系统用户管理开发文档.md b/docs/phpapi/系统用户管理开发文档.md new file mode 100644 index 000000000..1273878a0 --- /dev/null +++ b/docs/phpapi/系统用户管理开发文档.md @@ -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生成，仅供参考。 diff --git a/docs/phpapi/系统设置开发文档.md b/docs/phpapi/系统设置开发文档.md new file mode 100644 index 000000000..d8c49ca66 --- /dev/null +++ b/docs/phpapi/系统设置开发文档.md @@ -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生成，仅供参考。 diff --git a/docs/phpapi/系统错误码说明.md b/docs/phpapi/系统错误码说明.md new file mode 100644 index 000000000..d86c45d5d --- /dev/null +++ b/docs/phpapi/系统错误码说明.md @@ -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生成，仅供参考。 diff --git a/docs/phpapi/系统队列任务开发文档.md b/docs/phpapi/系统队列任务开发文档.md new file mode 100644 index 000000000..b2984b733 --- /dev/null +++ b/docs/phpapi/系统队列任务开发文档.md @@ -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生成，仅供参考。 diff --git a/docs/phpapi/系统队列任务文档说明.md b/docs/phpapi/系统队列任务文档说明.md new file mode 100644 index 000000000..010b6473a --- /dev/null +++ b/docs/phpapi/系统队列任务文档说明.md @@ -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 +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生成，仅供参考。 diff --git a/docs/phpapi/统计分析开发文档.md b/docs/phpapi/统计分析开发文档.md new file mode 100644 index 000000000..dd4943bda --- /dev/null +++ b/docs/phpapi/统计分析开发文档.md @@ -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生成，仅供参考。 diff --git a/docs/phpapi/营销活动开发文档.md b/docs/phpapi/营销活动开发文档.md new file mode 100644 index 000000000..4226d6ef3 --- /dev/null +++ b/docs/phpapi/营销活动开发文档.md @@ -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生成，仅供参考。 diff --git a/docs/phpapi/订单模块说明.md b/docs/phpapi/订单模块说明.md new file mode 100644 index 000000000..125fb70b2 --- /dev/null +++ b/docs/phpapi/订单模块说明.md @@ -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生成，仅供参考。 diff --git a/docs/phpapi/配置参数说明.md b/docs/phpapi/配置参数说明.md new file mode 100644 index 000000000..d2179bc70 --- /dev/null +++ b/docs/phpapi/配置参数说明.md @@ -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生成，仅供参考。 diff --git a/docs/phpapi/项目架构说明.md b/docs/phpapi/项目架构说明.md new file mode 100644 index 000000000..32b959f83 --- /dev/null +++ b/docs/phpapi/项目架构说明.md @@ -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生成，仅供参考。 diff --git a/docs/phpapi/项目目录文档.md b/docs/phpapi/项目目录文档.md new file mode 100644 index 000000000..ae007f0ae --- /dev/null +++ b/docs/phpapi/项目目录文档.md @@ -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生成，仅供参考。 diff --git a/docs/uniapp/uniapp目录结构.md b/docs/uniapp/uniapp目录结构.md new file mode 100644 index 000000000..d0cb7281a --- /dev/null +++ b/docs/uniapp/uniapp目录结构.md @@ -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生成，仅供参考。 diff --git a/docs/uniapp/移动端前端架构说明.md b/docs/uniapp/移动端前端架构说明.md new file mode 100644 index 000000000..dc5b5d9c6 --- /dev/null +++ b/docs/uniapp/移动端前端架构说明.md @@ -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 +// 父传子 + + +// 子组件 +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 +// 使用懒加载 + + +// 使用webp格式 + + +// 使用合适的图片尺寸 + +``` + +### 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生成，仅供参考。 diff --git a/docs/uniapp/移动端前端目录结构详细说明.md b/docs/uniapp/移动端前端目录结构详细说明.md new file mode 100644 index 000000000..0730692d4 --- /dev/null +++ b/docs/uniapp/移动端前端目录结构详细说明.md @@ -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生成，仅供参考。