CRMEB Pro 二次开发指南

文档目标

• 面向技术读者的二次开发指南，覆盖架构认知、扩展切入点、标准范式与示例
• 兼顾推广：突出高可扩展性、事件机制、标准接口、微信生态能力与性能优势

项目概览

• 后端框架：ThinkPHP 8 + Swoole4，标准前后端分离，接口清晰（参考 README.md:160）
• 分层架构：Controller → Services → Dao/Model，职责明确、便于维护
• 核心能力：事件机制、Job 队列、权限中间件、FormBuilder 后台表单生成、WebSocket 推送
• 生态整合：微信公众号/小程序/企业微信，EasyWeChat 能力完备
• 快速安装：运行目录 /public（参考 README.md:195）

架构与技术栈

• 目录结构
  • app/controller 控制器层（admin/api/pc/erp 等）
  • app/services 业务服务层（统一业务入口），示例：app/services/BaseServices.php:1
  • app/dao 数据访问层（查询与分页封装）
  • app/model 模型层（数据结构与关系），示例：app/model/user/User.php:1
  • route/admin.php 后台路由集中注册，示例：route/admin.php:560
  • app/event.php 事件注册中心，示例：app/event.php:86
  • app/http/middleware 中间件与权限校验，示例：app/http/middleware/admin/AdminCkeckRoleMiddleware.php:20
  • config/*.php 配置系统（文件系统、支付、队列、上传、微信等），示例：config/filesystem.php:1
• 设计约定
  • Controller 轻业务、主导路由与参数校验
  • Service 承载业务流程与组合逻辑
  • Dao 聚焦查询与数据分页，不写业务
  • Model 定义数据结构与基础关系
  • 事件优先解耦，Job 异步削峰

二开原则

• 遵循分层：新增功能尽量落在 Services + Dao + Controller，对外暴露标准接口
• 先找现有能力：扩展前检索是否已有事件、服务、配置或组件可复用
• 配置驱动：系统参数统一走 sys_config('key') 与 SystemConfigServices
• 安全与权限：新增后台操作走权限中间件与角色校验
• 可观测：关键流程接入事件或日志，便于追踪与回滚

扩展切入点

• 路由扩展
  • 后台与 API 路由集中在 route/admin.php:560，可按模块分组并绑定统一中间件
• 事件系统
  • 事件注册：app/event.php:86（商品、门店、供应商、企业微信等）
  • 企业微信事件示例：app/event.php:100
• 中间件
  • 管理端权限：app/http/middleware/admin/AdminCkeckRoleMiddleware.php:20
  • API 开关：如社区开关 app/http/middleware/api/CommunityOpenMiddleware.php:1
• 配置中心
  • 使用 SystemConfigServices 增加配置项与界面呈现（参考 app/services/system/config/SystemConfigServices.php:2324）
• 表单构建
  • 使用 crmeb\services\FormBuilder 快速生成后台表单（参考 app/services/product/stock/StockRecordServices.php:27）
• 队列与异步
  • app/jobs/* 承接耗时与通知任务，事件驱动触发

快速示例：新增“用户扩展信息”模块

• 目标：为用户新增扩展字段（如会员偏好），支持后台列表与编辑
• 数据层
  • Model：app/model/user/UserExtend.php:1
  • Dao：app/dao/user/UserExtendDao.php:1
• 服务层
  • Service：app/services/user/UserExtendServices.php:23 已提供 getList 及基础方法
• 控制器与路由
  • 在 app/controller/admin/v1/user 下新增 Controller（继承 AuthController）
  • 在 route/admin.php:83 模块组下添加资源路由与中间件（AllowOriginMiddleware、AdminAuthTokenMiddleware、AdminCkeckRoleMiddleware、AdminLogMiddleware）
• 表单与配置
  • 使用 FormBuilder 生成新增/编辑表单（参考 app/services/system/SystemSignRewardServices.php:21）
  • 若需开关或枚举，添加系统配置并通过 sys_config('key') 获取
• 权限与展示
  • 走权限校验：app/http/middleware/admin/AdminCkeckRoleMiddleware.php:20
  • 在后台菜单配置中为新模块分配角色权限

事件与队列

• 内置事件示例
  • 商品、门店、供应商、企业微信欢迎语等，参考 app/event.php:86
• 用户注册监听示例
  • 权益发放与关系绑定：app/listener/user/Register.php:68
  • 触发消息通知：event('notice.notice', [...])
• 企业微信消息监听
  • 示例：app/listener/wechat/OffcialAccountListener.php:21
• 使用方式
  • 触发：event('key', $payload) 或 Event::trigger('key', $data)
  • 异步 Job：如 UserIntegralJob::dispatchDo('newcomerGiveIntegral', [$uid])（参考 app/listener/user/Register.php:68）

中间件与权限

• 管理端权限校验：app/http/middleware/admin/AdminCkeckRoleMiddleware.php:20
• API 开关控制：app/http/middleware/api/CommunityOpenMiddleware.php:1
• 路由绑定中间件：路由组统一绑定（参考 route/admin.php:560）

微信生态

• 小程序与公众号
  • 小程序服务入口：app/services/wechat/RoutineServices.php:49
  • API 控制器：app/controller/api/v1/wechat/Wechat.php:53
• 企业微信
  • Work 配置与客户端：crmeb/services/wechat/config/WorkConfig.php:1，crmeb/services/wechat/client/work/DepartmentClient.php:20
  • 管理端控制器：app/controller/admin/v1/work/Client.php:22
• 消息与二维码
  • 二维码服务：app/services/wechat/WechatQrcodeServices.php:31
  • 消息封装：crmeb/services/wechat/message/HasAttributes.php:19

配置与存储

• 文件系统扩展：config/filesystem.php:1 可新增磁盘（如 OSS、COS、Kodo）
• 管理端存储配置：app/controller/admin/v1/system/config/SystemStorage.php:19
• 配置界面构建：SystemConfigServices 表单化管理（参考 app/services/system/config/SystemConfigServices.php:2324）

WebSocket 推送

• 管理端推送处理：app/webscoket/handler/AdminHandler.php:19
• 用户端推送处理：app/webscoket/handler/UserHandler.php:21
• 用途：实时消息提醒、订单状态、客服消息等

开发与部署

• 安装与运行目录：参考 README.md:195
• 生成器与命令：crmeb/command 提供 Dao/Service 等生成；Swoole 与队列配置见 config/swoole.php、config/queue.php
• 环境建议：PHP 8.0，Redis 缓存，MySQL 5.7+，Nginx 静态与反向代理

常见二开场景速查

• 新增后台管理模块：建 Model/Dao/Service/Controller → 路由组注册 → 权限与菜单 → FormBuilder 表单
• 接入新支付或存储：在 config/pay.php/config/filesystem.php:1 扩展驱动 → 增加配置项 → 写适配 Service
• 订单流转自定义：在 app/event.php:86 挂载订单相关事件监听器（创建、支付、发货、核销）
• 增加开关与策略：配置新增 → 中间件校验（参考 app/http/middleware/api/CommunityOpenMiddleware.php:1）
• 企业微信自动化：通过 WorkConfig 与 Work*Services 打通客户标签、群发、欢迎语