mirror of
https://github.com/crmeb/CRMEB.git
synced 2026-10-28 21:40:50 +00:00
3b5bd37bfb
为所有 MCP 内置工具实现 category() 分类方法，支持管理后台按业务分组展示；优化订单列表关键词搜索逻辑，使用闭包显式 OR 条件匹配订单号和商品标题，避免管道字段静默丢弃问题；新增优惠券库存调整原子方法，提升并发安全性；同步更新相关文档和注释，完善分类展示规则说明。
290 lines
9.8 KiB
Markdown
290 lines
9.8 KiB
Markdown
# CRMEB v8 电商系统
|
||
|
||
> 基于 ThinkPHP 8.0 的三端一体电商 CRM 系统：后端 + 管理端（Vue 3）+ 移动端（uni-app），支持 PC / H5 / 小程序 / APP。
|
||
|
||
**后端运行环境**：PHP 8.2-8.4 + MySQL 8.0 + Redis ｜ **前端构建**：Node >= 18.20
|
||
**主开发分支**：`v8.0.dev`，正式发布以 Release / Tag 为准
|
||
|
||
> 本仓库提供统一的 AI 开发入口（AGENTS.md 标准）。使用 Claude Code、Cursor、Codex、Copilot 等 AI 工具开发本项目前，请让 AI 先读取 [AGENTS.md](AGENTS.md) → [.crmeb/AGENTS.md](.crmeb/AGENTS.md)。详见下文[用 AI 开发本项目](#用-ai-开发本项目)。
|
||
|
||
---
|
||
|
||
## 快速开始（宿主机，默认）
|
||
|
||
```bash
|
||
cd backend
|
||
composer install
|
||
|
||
# 配置 backend/.env 并确保 MySQL 8、Redis 已在宿主机运行后启动
|
||
php think run --host 127.0.0.1 --port 8011
|
||
```
|
||
|
||
数据库和 Redis 连接以 `backend/.env` 为准，宿主机常见端口为 MySQL `3306`、Redis `6379`。首次启动后访问 **http://localhost:8011** 进入安装向导。
|
||
|
||
## 前端一键命令
|
||
|
||
```bash
|
||
./run.sh admin:dev # 管理端开发测试启动（端口 1619）
|
||
./run.sh admin:build # 管理端编译打包并发布到 backend/public/admin
|
||
./run.sh uni:dev # 移动端 H5 开发测试启动
|
||
./run.sh uni:build # 移动端 H5 编译打包并发布到 backend/public
|
||
```
|
||
|
||
也可直接执行 `./run.sh` 打开交互式菜单（前端命令对应编号 11/12/21/22）。
|
||
|
||
## 可选 Docker Compose
|
||
|
||
只有明确选择容器环境时使用：
|
||
|
||
```bash
|
||
# 首次且允许清空本地数据时才执行
|
||
./run.sh install
|
||
|
||
# 日常启停和检查
|
||
./run.sh start
|
||
./run.sh stop
|
||
./run.sh restart
|
||
|
||
./run.sh ps
|
||
./run.sh logs
|
||
```
|
||
|
||
### 容器说明
|
||
|
||
| 服务 | 端口 |
|
||
|------|------|
|
||
| Nginx（Web 入口） | `8011` |
|
||
| MySQL 8.0 | `33061` |
|
||
| Redis | `63791` |
|
||
| Workerman（WebSocket） | `40001` |
|
||
|
||
另有 `phpfpm`、`timer`（定时任务）、`queue`（队列消费）为内部服务，无需对外访问。
|
||
|
||
Dev Containers 配置（`.devcontainer/`）不在仓库内，已在 `.gitignore` 中忽略。需要容器化开发环境者可在仓库根自建，编辑器即可「Reopen in Container」，无需入库。
|
||
|
||
---
|
||
|
||
## 首次安装配置
|
||
|
||
1. 创建数据库，导入 `backend/public/install/crmeb_table.sql`（表结构）与 `backend/public/install/data/` 下的基础数据（推荐直接访问安装向导自动完成）
|
||
2. 复制 `backend/.env.example` 为 `backend/.env`，按实际环境修改（文件内有逐项注释）
|
||
3. 设置 `backend/runtime`、`backend/public` 目录权限为 777
|
||
4. 访问 `http://域名/admin`，默认账号 `admin` / 密码 `crmeb.com`
|
||
|
||
### .env 配置参考
|
||
|
||
```ini
|
||
APP_DEBUG = true
|
||
|
||
[APP]
|
||
DEFAULT_TIMEZONE = Asia/Shanghai
|
||
APP_KEY = your_app_key
|
||
|
||
[DATABASE]
|
||
TYPE = mysql
|
||
HOSTNAME = 127.0.0.1
|
||
HOSTPORT = 3306
|
||
DATABASE = crmeb
|
||
USERNAME = root
|
||
PASSWORD = root
|
||
PREFIX = eb_
|
||
CHARSET = utf8mb4
|
||
|
||
[LANG]
|
||
default_lang = zh-cn
|
||
|
||
[CACHE]
|
||
DRIVER = redis
|
||
CACHE_PREFIX = cache_xxx:
|
||
CACHE_TAG_PREFIX = cache_tag_xxx:
|
||
|
||
[REDIS]
|
||
REDIS_HOSTNAME = 127.0.0.1
|
||
PORT = 6379
|
||
REDIS_PASSWORD =
|
||
SELECT = 0
|
||
|
||
[QUEUE]
|
||
QUEUE_NAME = your_queue_prefix
|
||
```
|
||
|
||
> 完整配置模板与逐项注释见 [backend/.env.example](backend/.env.example)。
|
||
|
||
---
|
||
|
||
## 管理端（frontend/admin）
|
||
|
||
```bash
|
||
cd frontend/admin
|
||
npm install
|
||
npm run dev # 开发模式，自动打开浏览器
|
||
```
|
||
|
||
- 开发地址 **http://localhost:1619**；Vite 已把 `/adminapi` 代理到 `http://localhost:8011`（见 [vite.config.js](frontend/admin/vite.config.js)），需先启动后端
|
||
- 生产构建：`npm run build`，产物部署到后端 `public/admin/`
|
||
- 接口地址由 `VITE_APP_API_URL` 控制，留空 = 同源 `/adminapi`
|
||
|
||
## 移动端（frontend/uni-app）
|
||
|
||
```bash
|
||
cd frontend/uni-app
|
||
npm install
|
||
npm run dev:h5 # H5 开发模式
|
||
```
|
||
|
||
- H5 开发地址默认 **http://localhost:5173**；接口地址 `UNI_APP_API_URL` 已在 `.env.development` 默认指向 `http://localhost:8011`
|
||
- 微信小程序：`npm run dev:mp-weixin`，再用微信开发者工具导入 `dist/dev/mp-weixin`；支付宝小程序用 `dev:mp-alipay`；APP 用 `dev:app`
|
||
- 生产构建：`npm run build:h5` / `build:mp-weixin` / `build:app`
|
||
|
||
---
|
||
|
||
## 后台服务
|
||
|
||
### 消息队列
|
||
```bash
|
||
cd backend
|
||
php think queue:listen --queue
|
||
```
|
||
|
||
### 定时任务
|
||
（自动收货、库存预警等）
|
||
```bash
|
||
php think timer start --d # 启动
|
||
php think timer stop # 停止
|
||
php think timer restart # 重启
|
||
```
|
||
|
||
### 长连接服务（WebSocket）
|
||
（H5 聊天、管理员消息通知）
|
||
```bash
|
||
php think workerman start --d
|
||
php think workerman stop
|
||
php think workerman restart
|
||
```
|
||
|
||
---
|
||
|
||
## 项目文档
|
||
|
||
| 文档 | 说明 |
|
||
|------|------|
|
||
| [文档索引](help/docs/文档索引.md) | 项目、功能、开发、部署与运维阅读导航 |
|
||
| [架构设计](help/docs/项目架构.md) | 系统架构、技术栈、目录结构 |
|
||
| [模块与驱动](help/docs/模块与驱动.md) | 默认安装清单与各业务模块功能说明 |
|
||
| [管理端 API](help/docs/api/管理端接口.md) | AdminAPI 接口文档 |
|
||
| [用户端 API](help/docs/api/用户端接口.md) | 用户端 API 接口文档 |
|
||
| [MCP 接口](help/docs/api/MCP接口.md) | 独立 MCP 服务的接入、认证、工具与排障说明 |
|
||
| [数据库设计](help/docs/数据库设计.md) | 数据库表结构设计 |
|
||
| [开发指南](help/docs/开发指南.md) | 开发环境、规范、流程 |
|
||
|
||
外部资源：
|
||
- [CRMEB 使用手册](https://doc.crmeb.com)
|
||
- [ThinkPHP 8.0 开发手册](https://doc.thinkphp.cn/v8_0/)
|
||
|
||
---
|
||
|
||
## 多应用结构
|
||
|
||
URL 前缀自动路由到对应应用：
|
||
|
||
| 前缀 | 应用 | 说明 |
|
||
|------|------|------|
|
||
| `/admin` | 管理端静态页面 | Vue 管理后台入口，不是 API 前缀 |
|
||
| `/adminapi` | `app/adminapi/` + 模块 `route/admin.php` | 管理后台 API |
|
||
| `/api` | `app/api/` + 模块 `route/user.php` | 商城用户 API、模块用户端接口 |
|
||
|
||
---
|
||
|
||
## 开发规范
|
||
|
||
### 命名规范（PSR-2 + PSR-4）
|
||
|
||
| 元素 | 规范 | 示例 |
|
||
|------|------|------|
|
||
| 类名 / 接口 / Trait | 大驼峰 | `User`, `UserType` |
|
||
| 方法（控制器除外） | 小驼峰 | `getUserName()` |
|
||
| 属性 / 变量 | 小驼峰 | `tableName` |
|
||
| 控制器方法 | 小写+下划线 | `get_client_ip` |
|
||
| 目录 | 小写+下划线 | `store_product/` |
|
||
| 常量 / 环境变量 | 大写+下划线 | `APP_DEBUG` |
|
||
| 数据表 / 字段 | 小写+下划线，`eb_` 前缀 | `eb_user`, `user_name` |
|
||
|
||
### CRMEB 核心规范
|
||
|
||
- **验证**：数据验证放在模块的 `validates/` 目录下
|
||
- **JSON 响应**：统一使用 `app('json')->success()` / `app('json')->fail()`
|
||
- **错误处理**：抛异常统一控制输出 —— `throw new AuthException('错误信息', 400)`
|
||
- **数据库**：统一使用模型操作，**禁止 `Db::table()`**
|
||
- **请求参数**：使用 `$request->getMore([...])` 获取表单数据
|
||
- **分层职责**：
|
||
- Model 层 —— 仅写搜索条件和关联关系
|
||
- Services 层 —— 数据组合查询、业务逻辑（创建命令：`php make:services api@user/User`）
|
||
- **代码风格**：使用 PHP 8 新语法，严格类型声明
|
||
|
||
---
|
||
|
||
## 用 AI 开发本项目
|
||
|
||
本仓库为所有 AI 编码工具提供统一约定：规则、技能、子智能体唯一真源在 [.crmeb/](.crmeb/AGENTS.md)，各工具入口只做指引、不承载正文。
|
||
|
||
| 工具 | 使用方式 |
|
||
|------|------|
|
||
| Codex / Cursor / Gemini CLI 等支持 AGENTS.md 标准的工具 | 自动读取根 [AGENTS.md](AGENTS.md)，无需配置 |
|
||
| Claude Code | 自动读取 [CLAUDE.md](CLAUDE.md) |
|
||
| 支持 llms.txt 的工具 / 网页抓取类 AI | 读取 [llms.txt](llms.txt) |
|
||
|
||
所有入口最终指向 [.crmeb/AGENTS.md](.crmeb/AGENTS.md)：其中定义了项目硬约束（依赖方向、分层、插件零侵入红线）、16 条开发规则、8 个开发技能与 3 个专项子智能体，AI 按索引按需加载即可获得与内部开发者一致的约定。
|
||
|
||
### 连接本项目的 MCP 开发工具
|
||
|
||
内置 MCP 服务（`service_mcp` 模块，默认安装）向任意支持 MCP 的 AI 工具开放实时项目知识：
|
||
|
||
完整的安装启用、认证、业务工具、写入授权和排障说明见 [MCP 接口文档](help/docs/api/MCP接口.md)。
|
||
|
||
| 工具 | 用途 |
|
||
|------|------|
|
||
| `crmeb_dev_docs_search` | 检索开发规则 / 技能手册 / 项目文档（架构铁律、插件规范、事件规范等） |
|
||
| `crmeb_dev_route_search` | 按关键词 / 应用检索接口路由定义（定位「接口在哪、控制器是谁」） |
|
||
| `crmeb_dev_table_schema` | 查询运行库真实表结构：字段、注释、索引（含已安装插件表） |
|
||
|
||
接入步骤：
|
||
|
||
1. 启动后端后，登录管理后台「设置 → MCP 服务」，开启开关并复制访问密钥（appkey）；
|
||
2. 在 AI 工具的 MCP 配置中添加（Claude Code 写入 `.mcp.json`，Cursor / Trae 等在各自 MCP 设置中填写）：
|
||
|
||
```json
|
||
{
|
||
"mcpServers": {
|
||
"crmeb": {
|
||
"type": "http",
|
||
"name": "CRMEB 商城",
|
||
"url": "http://localhost:8011/api/mcp",
|
||
"headers": { "X-Mcp-Key": "你的appkey" },
|
||
"timeout": 15,
|
||
"description": "CRMEB 商城管理工具集：查询/管理商城数据（商品、订单、售后、配置等，以账号已授权工具为准）。",
|
||
"disabled": false
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
3. Docker 部署无需额外配置（`docker-compose.yml` 已为容器只读挂载文档目录）；文档检索工具定位仓库根依赖 `CRMEB_REPO_ROOT` 环境变量，默认取 `backend/` 的父目录。
|
||
|
||
工具的返回为检索摘要，正文以仓库文件为准；工具实现位于 `backend/modules/service/mcp/tools/`，按约定新增 `*Tool.php` 即自动注册。
|
||
|
||
---
|
||
|
||
## 参与开发
|
||
|
||
提交流程、检查清单与规范入口见 [CONTRIBUTING.md](CONTRIBUTING.md)；上游项目参阅 [CRMEB](https://github.com/crmeb/CRMEB)。
|
||
|
||
---
|
||
|
||
## 版权信息
|
||
|
||
版权所有 Copyright © 2016~2026 by CRMEB (http://www.crmeb.com)
|
||
|
||
All rights reserved.
|
||
|
||
CRMEB® 商标和著作权所有者为西安众邦网络科技有限公司。
|