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

feat: 添加Git提交规范技能文件和相关文档

Browse Source 
docs: 更新开发文档生成规范和目录结构文档

refactor: 重构管理端前端和uniapp开发说明文档

chore: 删除旧的文档规范和目录结构文件
This commit is contained in:
sugar1569 2026-01-27 09:01:09 +08:00
parent 359911ef2c
commit eb73b84d9f
17 changed files with 3603 additions and 302 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

40
.trae/documents/生成Git提交规范技能文件.md Normal file
View File

@ -0,0 +1,40 @@
# 生成Git提交规范技能文件
## 目标
创建一个新的技能文件，用于规范git提交信息格式，确保不同目录下的文件提交时都能添加正确的前缀说明。
## 步骤
### 1. 创建技能目录
- 在 `.trae/skills/` 目录下创建 `git-commit/` 子目录
### 2. 生成SKILL.md文件
创建符合格式要求的SKILL.md文件，包含以下内容：
#### 2.1 基本信息
- 技能名称：Git提交规范
- 描述：规范git提交信息格式，确保不同目录下的文件提交时添加正确的前缀
#### 2.2 自动触发说明
- 触发条件：当浏览或操作git相关文件时自动调用
- 适用场景：git提交操作前的提示和规范检查
#### 2.3 核心内容
- 提交信息格式规范
- 不同目录的提交前缀说明
- 提交信息示例
- 最佳实践
#### 2.4 提交前缀规则
- **crmeb目录**：提交时添加前缀 `【程序目录】`
- **docker-compose目录**：提交时添加前缀 `【DOCKER】`
- **docs目录**：提交时添加前缀 `【开发文档】`
- **template目录**：提交时添加前缀 `【前端文件】`
#### 2.5 参考资源
- Git官方文档
- 常用git命令
- 提交信息规范指南
### 3. 验证文件结构
确保文件创建在正确的位置，格式符合技能文件的标准规范。

100
.trae/skills/SKLL.md Normal file
View File

@ -0,0 +1,100 @@
# CRMEB 技能说明文档
## 技能列表
### 1. 现有技能
| 技能名称 | 目录 | 描述 |
|---------|------|------|
| 管理端前端说明 | 管理端文档说明/ | 管理端前端开发skill说明 |
| docs规范 | docs规范/ | 文档写作规范 |
| uniapp说明 | uniapp说明/ | 移动端uniapp开发说明 |
| 目录结构 | 目录结构/ | 代码结构说明 |
| PHP后端说明 | php后端说明/ | PHP后端开发skill说明 |
| 数据库设计说明 | 数据库设计说明/ | 数据库设计skill说明 |
| API接口开发说明 | api接口开发说明/ | API接口开发skill说明 |
| 系统配置说明 | 系统配置说明/ | 系统配置skill说明 |
| 安全开发说明 | 安全开发说明/ | 安全开发skill说明 |
| 性能优化说明 | 性能优化说明/ | 性能优化skill说明 |
| 测试开发说明 | 测试开发说明/ | 测试开发skill说明 |
| 部署运维说明 | 部署运维说明/ | 部署运维skill说明 |
| 开发文档AI生成说明 | 开发文档AI生成说明/ | 开发文档AI生成skill说明 |
## 技能文档规范
### 1. 文件结构
```
.trae/skills/
├── 技能名称/
│ └── SKILL.md # 技能说明文档
└── SKLLmd # 技能列表文档
```
### 2. SKILL.md 格式规范
#### 2.1 文档头部
```yaml
---
name: 技能名称
description: 技能描述
---
```
#### 2.2 文档结构
1. **标题**：技能名称
2. **自动触发说明**：
- 触发条件（操作触发、内容触发、命令触发）
- 适用场景（核心场景、辅助场景）
- 触发机制（调用时机、频率、优先级）
- 触发后行为（自动分析、展示、建议）
3. **核心内容**：技能相关的技术文档
4. **最佳实践**：开发、使用建议
5. **常见问题**：常见问题及解决方案
6. **参考资源**：相关文档、工具等
### 3. 技能触发机制
#### 3.1 触发方式
- **操作触发**：文件/目录操作时触发
- **内容触发**：文件内容包含关键词时触发
- **命令触发**：执行特定命令时触发
#### 3.2 触发优先级
- **最高优先级**：系统核心技能
- **高优先级**：代码结构技能
- **中等优先级**：开发技能（前端、后端、移动端）
- **低优先级**：辅助工具技能
### 4. 技能开发流程
1. **需求分析**：确定技能的功能和范围
2. **文档编写**：按照规范编写SKILL.md文档
3. **目录创建**：创建技能目录结构
4. **测试验证**：测试技能触发和功能
5. **发布使用**：部署技能供开发人员使用
## 技能使用指南
### 1. 开发人员使用
1. **浏览触发**：浏览相关目录时自动触发对应技能
2. **编辑触发**：编辑相关文件时自动触发对应技能
3. **命令触发**：执行相关命令时自动触发对应技能
4. **手动调用**：通过IDE插件手动调用对应技能
### 2. 技能维护
1. **定期更新**：根据项目变化更新技能文档
2. **技能扩展**：根据新功能添加新技能
3. **技能优化**：优化技能触发机制和内容
## 总结
技能系统是CRMEB项目开发的重要辅助工具，通过规范的技能文档和触发机制，可以帮助开发人员更快地了解项目结构、开发规范和最佳实践，提高开发效率和代码质量。
建议定期维护和更新技能文档，确保其与项目发展保持同步，为开发人员提供持续的支持和指导。

10
.trae/skills/管理端文档说明/SKILL.md → .trae/skills/admin-element/SKILL.md
View File

@ -447,4 +447,12 @@ src/
- **项目管理**: 使用项目管理工具
- **代码托管**: 使用代码托管平台
- **CI/CD**: 持续集成/持续部署
- **文档协作**: 团队文档协作工具
- **文档协作**: 团队文档协作工具
### 14 其他资源
- 开发流程文档 /references/development_flow.md
- 代码规范文档 /references/code_style.md
- 项目部署文档 /references/deploy.md
- 目录结构文档 /references/directory_structure.md
- 接口请求流程文档 /references/api_flow.md
- 系统配置文档 /references/system_config.md

24
.trae/skills/docs规范/SKILL.md → .trae/skills/dev-docs-generate/SKILL.md
View File

@ -1,6 +1,6 @@
---
name: docs规范
description: 文档写作规范
name: dev-docs-generate
description: 开发文档生成规范，快速生成开发文档，自动放到docs目录下，方便技术快速了解项目，能快速入手开发
---
# CRMEB 项目文档写作规范
@ -10,11 +10,11 @@ description: 文档写作规范
### 0.1 触发条件
- **目录浏览时**：当浏览文档相关目录时自动调用
- 打开 `docs/` 目录时触发
- 打开 `docs/phpapi/` 目录时触发
- 打开 `docs/admin/` 目录时触发
- 打开 `docs/uniapp/` 目录时触发
- 打开 `docs/nuxt/` 目录时触发
- 打开 `dev-docs/` 目录时触发
- 打开 `dev-docs/phpapi/` 目录时触发
- 打开 `dev-docs/admin/` 目录时触发
- 打开 `dev-docs/uniapp/` 目录时触发
- 打开 `dev-docs/nuxt/` 目录时触发
- **文档创建时**：当创建新的 Markdown 文档文件时自动调用
- **文档编辑时**：当编辑现有文档文件时自动调用
- **关键词触发**：当文档内容包含以下关键词时自动调用
@ -87,11 +87,11 @@ description: 文档写作规范
### 2.5 文档存放目录
- 文档保存到 `docs` 目录中
- 后端接口文档存放 `docs/phpapi` 目录中
- 后端前端 ElementUI（Admin）文档存放 `docs/admin` 目录中
- 移动端前端 UniApp（移动端）文档存放 `docs/uniapp` 目录中
- PC 端 Nuxt（PC）文档存放 `docs/nuxt` 目录中
- 文档保存到 `dev-docs` 目录中
- 后端接口文档存放 `dev-docs/phpapi` 目录中
- 后端前端 ElementUI（Admin）文档存放 `dev-docs/admin` 目录中
- 移动端前端 UniApp（移动端）文档存放 `dev-docs/uniapp` 目录中
- PC 端 Nuxt（PC）文档存放 `dev-docs/nuxt` 目录中
## 3. 内容要求

240
.trae/skills/git-commit/SKILL.md Normal file
View File

@ -0,0 +1,240 @@
---
name: Git提交规范
description: 规范git提交信息格式，确保不同目录下的文件提交时添加正确的前缀
---
# Git提交规范
## 0. 自动触发说明
### 0.1 触发条件
#### 0.1.1 操作触发
- **文件浏览时**: 当浏览以下目录时自动调用
- 打开 `crmeb/` 目录时触发
- 打开 `docker-compose/` 目录时触发
- 打开 `dev-docs/` 目录时触发
- 打开 `template/` 目录时触发
- **文件操作时**: 当对以下目录的文件进行操作时自动调用
- 修改 `crmeb/` 目录下文件时触发
- 修改 `docker-compose/` 目录下文件时触发
- 修改 `dev-docs/` 目录下文件时触发
- 修改 `template/` 目录下文件时触发
- **Git操作时**: 当执行以下Git命令时自动调用
- `git add` (添加文件到暂存区)
- `git commit` (提交更改)
- `git push` (推送更改)
#### 0.1.2 内容触发
- **关键词触发**: 当文件内容包含以下关键词时自动调用
- Git关键词: `git`、`commit`、`push`、`pull`、`branch`
- 提交关键词: `提交`、`更新`、`修复`、`添加`、`删除`
- 目录关键词: `crmeb`、`docker-compose`、`docs`、`template`
#### 0.1.3 命令触发
- **终端命令触发**: 当执行以下命令时自动调用
- `git` (Git相关命令)
- `git commit` (提交命令)
- `git add` (添加命令)
### 0.2 适用场景
#### 0.2.1 核心场景
- **代码提交**: 提交代码更改时
- **文件修改**: 修改项目文件时
- **目录操作**: 对项目目录进行操作时
#### 0.2.2 辅助场景
- **代码审查**: 审查代码提交时
- **版本管理**: 管理项目版本时
- **团队协作**: 团队成员协作开发时
### 0.3 触发机制
#### 0.3.1 调用时机
- **实时触发**: Git命令执行时立即触发
- **延迟触发**: 文件操作后延迟1秒触发
- **批量触发**: 批量文件操作时合并触发
#### 0.3.2 调用频率
- 文件浏览: 最多每10秒触发一次
- 文件操作: 最多每5秒触发一次
- Git命令: 最多每3秒触发一次
#### 0.3.3 调用优先级
- **优先级等级**: 中等优先级 (3/5)
- **竞争处理**: 当多个技能同时触发时
- 最高优先级: 系统核心技能
- 高优先级: 代码结构技能
- 中等优先级: Git提交技能、PHP后端技能、前端技能
- 低优先级: 辅助工具技能
### 0.4 触发后行为
#### 0.4.1 自动分析
- **目录分析**: 分析当前操作的文件所在目录
- **提交信息分析**: 分析提交信息格式是否符合规范
- **前缀检查**: 检查提交信息是否包含正确的目录前缀
#### 0.4.2 自动展示
- **提交规范**: 展示Git提交规范
- **目录前缀**: 展示当前目录对应的提交前缀
- **示例格式**: 展示正确的提交信息格式示例
#### 0.4.3 自动建议
- **前缀建议**: 提供当前目录对应的提交前缀建议
- **格式建议**: 提供提交信息格式建议
- **最佳实践**: 提供Git提交最佳实践建议
## 1. 提交信息格式规范
### 1.1 基本格式
```
[目录前缀] 提交描述
详细说明（可选）
```
### 1.2 目录前缀规则
| 目录 | 前缀 | 示例 |
|------|------|------|
| crmeb/ | 【程序目录】 | 【程序目录】修复登录功能bug |
| docker-compose/ | 【DOCKER】 | 【DOCKER】更新Docker配置文件 |
| dev-docs/ | 【开发文档】 | 【开发文档】完善API接口文档 |
| template/ | 【前端文件】 | 【前端文件】优化前端界面样式 |
### 1.3 提交描述规范
- **长度限制**: 不超过50个字符
- **内容要求**: 简洁明了，说明本次提交的主要内容
- **动词使用**: 使用现在时动词，如「添加」、「修复」、「更新」等
- **格式规范**: 首字母大写，结尾不加标点符号
### 1.4 详细说明规范
- **长度限制**: 不超过200个字符
- **内容要求**: 详细说明本次提交的原因、解决的问题等
- **格式规范**: 每行不超过72个字符，使用空行分隔不同段落
## 2. 提交信息示例
### 2.1 crmeb目录示例
```
【程序目录】添加用户注册功能
- 实现用户注册接口
- 添加注册参数验证
- 集成短信验证码功能
```
### 2.2 docker-compose目录示例
```
【DOCKER】优化Docker镜像构建
- 减少镜像体积
- 提高构建速度
- 修复容器启动问题
```
### 2.3 docs目录示例
```
【开发文档】更新API接口文档
- 补充新接口说明
- 修正参数描述错误
- 添加响应示例
```
### 2.4 template目录示例
```
【前端文件】优化登录页面样式
- 调整表单布局
- 美化按钮样式
- 优化响应式设计
```
## 3. 最佳实践
### 3.1 提交频率
- **合理拆分**: 每个提交只包含一个功能或修复
- **及时提交**: 完成一个功能或修复后及时提交
- **避免批量**: 避免一次提交大量不相关的更改
### 3.2 提交信息质量
- **清晰明了**: 提交信息应清晰说明本次更改的内容
- **准确描述**: 提交信息应准确反映代码更改
- **格式规范**: 严格遵循提交信息格式规范
### 3.3 分支管理
- **主分支**: 保持主分支稳定，只用于发布
- **开发分支**: 在开发分支上进行功能开发
- **特性分支**: 为大型功能创建专门的特性分支
- **修复分支**: 为紧急bug创建专门的修复分支
### 3.4 代码审查
- **自我审查**: 提交前自我审查代码
- **团队审查**: 重要更改应进行团队代码审查
- **审查标准**: 审查代码质量、安全性、性能等
## 4. 常见问题
### 4.1 提交信息问题
- **缺少前缀**: 忘记添加目录前缀
- 解决方法: 参考目录前缀规则，添加正确的前缀
- **描述过长**: 提交描述超过50个字符
- 解决方法: 精简描述，突出重点
- **格式不规范**: 提交信息格式不符合规范
- 解决方法: 参考提交信息格式规范，修正格式
### 4.2 分支管理问题
- **分支混乱**: 分支过多或命名不规范
- 解决方法: 定期清理无用分支，使用规范的分支命名
- **合并冲突**: 分支合并时产生冲突
- 解决方法: 及时同步主分支，减少冲突可能性
### 4.3 提交频率问题
- **提交过频**: 过于频繁的提交
- 解决方法: 合理组织提交，避免琐碎提交
- **提交过少**: 长时间不提交
- 解决方法: 及时提交更改，避免代码丢失
## 5. 常用Git命令
### 5.1 基本命令
- **git status**: 查看当前状态
- **git add <file>**: 添加文件到暂存区
- **git commit -m "[前缀] 描述"**: 提交更改
- **git push**: 推送更改到远程仓库
- **git pull**: 从远程仓库拉取更改
### 5.2 分支命令
- **git branch**: 查看分支
- **git checkout <branch>**: 切换分支
- **git checkout -b <branch>**: 创建并切换分支
- **git merge <branch>**: 合并分支
### 5.3 历史命令
- **git log**: 查看提交历史
- **git show <commit>**: 查看提交详情
- **git diff**: 查看更改内容
## 6. 参考资源
### 6.1 官方文档
- [Git官方文档](https://git-scm.com/doc)
- [GitHub Git教程](https://guides.github.com/introduction/git-handbook/)
### 6.2 学习资源
- [Pro Git](https://git-scm.com/book/zh/v2)
- [Git分支管理策略](https://nvie.com/posts/a-successful-git-branching-model/)
- [提交信息规范](https://chris.beams.io/posts/git-commit/)
### 6.3 工具推荐
- **Git GUI**: GitHub Desktop、SourceTree
- **Git客户端**: GitKraken、Tower
- **代码托管**: GitHub、GitLab、Gitee
### 6.4 其他资源
- Git工作流最佳实践
- 团队Git使用规范
- 代码审查流程指南

380
.trae/skills/php-api/SKILL.md Normal file
View File

@ -0,0 +1,380 @@
---
name: PHP后端开发说明
description: PHP后端开发skill说明
---
# PHP后端开发说明
## 0. 自动触发说明
### 0.1 触发条件
#### 0.1.1 操作触发
- **文件浏览时**: 当浏览 PHP 后端相关目录时自动调用
- 打开 `app/` 目录时触发
- 打开 `crmeb/` 核心库目录时触发
- 浏览控制器、模型、服务目录时触发
- 查看配置文件目录时触发
- **文件操作时**: 当对 PHP 后端文件进行操作时自动调用
- 创建新 PHP 文件时触发
- 修改后端代码时触发
- 删除 PHP 文件时触发
- **目录操作时**: 当对 PHP 后端目录进行操作时自动调用
- 创建新后端目录时触发
- 重命名后端目录时触发
- 删除后端目录时触发
#### 0.1.2 内容触发
- **关键词触发**: 当文件内容包含以下关键词时自动调用
- 后端关键词: `后端`、`PHP`、`服务器`、`API`、`接口`
- 框架关键词: `ThinkPHP`、`TP6`、`框架`、`路由`、`控制器`
- 功能关键词: `登录`、`注册`、`支付`、`订单`、`用户`
- **代码触发**: 当查看特定类型 PHP 代码时自动调用
- 控制器代码 (`Controller`)
- 模型代码 (`Model`)
- 服务代码 (`Service`)
- 配置代码 (`Config`)
- 路由代码 (`Route`)
#### 0.1.3 命令触发
- **终端命令触发**: 当执行以下命令时自动调用
- `php think` (ThinkPHP 命令)
- `composer` (依赖管理命令)
- `php` (PHP 执行命令)
- `artisan` (Laravel 命令，如需)
### 0.2 适用场景
#### 0.2.1 核心场景
- **后端开发**: 开发 PHP 后端功能时
- **API 开发**: 开发 RESTful API 接口时
- **业务逻辑实现**: 实现核心业务逻辑时
- **数据操作**: 进行数据库操作时
#### 0.2.2 辅助场景
- **代码调试**: 调试 PHP 后端代码时
- **性能优化**: 优化后端性能时
- **安全加固**: 增强后端安全性时
- **架构设计**: 设计后端架构时
### 0.3 触发机制
#### 0.3.1 调用时机
- **实时触发**: PHP 文件操作时立即触发
- **延迟触发**: 复杂目录操作时延迟1秒触发
- **批量触发**: 批量文件操作时合并触发
#### 0.3.2 调用频率
- 文件浏览: 最多每10秒触发一次
- 文件操作: 最多每5秒触发一次
- 命令执行: 最多每3秒触发一次
#### 0.3.3 调用优先级
- **优先级等级**: 中等优先级 (3/5)
- **竞争处理**: 当多个技能同时触发时
- 最高优先级: 系统核心技能
- 高优先级: 代码结构技能
- 中等优先级: PHP 后端技能、前端技能、移动端技能
- 低优先级: 辅助工具技能
- **触发限制**: 仅在 PHP 后端相关操作时被触发，不影响其他技能的正常使用
### 0.4 触发后行为
#### 0.4.1 自动分析
- **代码分析**: 分析 PHP 代码结构和质量
- **依赖分析**: 分析代码依赖关系
- **性能分析**: 分析代码性能瓶颈
- **安全分析**: 分析代码安全隐患
#### 0.4.2 自动展示
- **目录结构**: 展示 PHP 后端目录结构
- **代码说明**: 展示核心代码功能说明
- **技术栈**: 展示后端技术栈
- **开发规范**: 展示 PHP 开发规范
#### 0.4.3 自动建议
- **开发建议**: 提供 PHP 后端开发建议
- **优化建议**: 提供性能优化建议
- **规范建议**: 提供代码规范遵循建议
- **安全建议**: 提供安全防护建议
## 1. PHP 后端架构
### 1.1 整体架构
- **框架**: ThinkPHP 6.x
- **架构模式**: MVC + Service + DAO 分层架构
- **设计模式**: 单例、工厂、依赖注入等
- **数据库**: MySQL 5.7~8.0
- **缓存**: Redis (推荐)
- **队列**: ThinkPHP 内置队列
### 1.2 技术栈
- **PHP**: 7.1~7.4
- **ThinkPHP**: 6.x
- **MySQL**: 5.7+
- **Redis**: 5.0+
- **Composer**: 依赖管理
- **Workerman**: 长连接服务
### 1.3 目录结构
#### 1.3.1 核心目录
```
app/
├── api/ # API 接口层
├── controller/ # 控制器层
├── dao/ # 数据访问层
├── model/ # 模型层
├── services/ # 业务逻辑层
├── event/ # 事件处理层
├── middleware/ # 中间件层
└── validate/ # 数据验证层
```
#### 1.3.2 配置目录
```
config/
├── app.php # 应用配置
├── database.php # 数据库配置
├── route.php # 路由配置
├── cache.php # 缓存配置
└── queue.php # 队列配置
```
#### 1.3.3 核心库目录
```
crmeb/
├── basic/ # 基础类库
├── exception/ # 异常处理
└── services/ # 核心服务
```
## 2. 核心模块
### 2.1 控制器模块
- **功能**: 处理 HTTP 请求，路由分发，响应客户端
- **特点**: RESTful 风格，分层清晰，参数验证
- **关键文件**: `BaseController.php` (控制器基类)
- **示例代码**:
```php
<?php
namespace app\controller;
use app\BaseController;
class UserController extends BaseController
{
public function index()
{
return $this->success('获取用户列表成功', $data);
}
}
```
### 2.2 服务模块
- **功能**: 实现核心业务逻辑，封装业务规则
- **特点**: 业务逻辑集中，可复用性高，易于测试
- **关键文件**: 各业务服务类
- **示例代码**:
```php
<?php
namespace app\services;
use crmeb\basic\BaseServices;
class UserServices extends BaseServices
{
public function createUser($data)
{
// 业务逻辑实现
return $userId;
}
}
```
### 2.3 数据访问模块
- **功能**: 封装数据库操作，提供数据访问方法
- **特点**: SQL 集中管理，防止 SQL 注入，提高安全性
- **关键文件**: 各数据访问对象类
- **示例代码**:
```php
<?php
namespace app\dao;
use crmeb\basic\BaseDao;
class UserDao extends BaseDao
{
public function getUserById($id)
{
return $this->where('id', $id)->find();
}
}
```
### 2.4 模型模块
- **功能**: 定义数据模型，处理数据关系
- **特点**: ORM 映射，自动表结构，关联查询
- **关键文件**: `BaseModel.php` (模型基类)
- **示例代码**:
```php
<?php
namespace app\model;
use crmeb\basic\BaseModel;
class User extends BaseModel
{
protected $table = 'user';
protected $pk = 'id';
}
```
### 2.5 路由模块
- **功能**: 定义 URL 路由规则，分发请求
- **特点**: RESTful 风格，路由分组，中间件支持
- **关键文件**: `route/api.php`、`route/app.php`
- **示例代码**:
```php
<?php
use think\facade\Route;
Route::get('user/:id', 'User/read');
Route::post('user', 'User/save');
Route::put('user/:id', 'User/update');
Route::delete('user/:id', 'User/delete');
```
## 3. 开发规范
### 3.1 代码规范
- **PHP 规范**: 遵循 PSR-2 命名规范
- **命名规范**:
- 类名: PascalCase
- 方法/变量: camelCase
- 常量: 全大写，下划线分隔
- 文件名: 与类名一致，PascalCase
- **代码缩进**: 4空格缩进，禁止制表符
- **注释规范**: 方法注释、类注释、关键逻辑注释
### 3.2 目录规范
- **按功能模块组织**: 相同功能的代码放在同一目录
- **目录层次清晰**: 避免过深的目录嵌套
- **命名语义化**: 目录名应反映其功能
### 3.3 数据库规范
- **表名**: 小写下划线分隔
- **主键**: 统一命名为 `id`
- **外键**: 格式 `表名_id`
- **时间字段**: `create_time`/`update_time`
- **状态字段**: `status`，默认值 0
### 3.4 API 规范
- **RESTful 风格**: 使用标准 HTTP 方法
- **响应格式**: 统一 JSON 格式
- **错误处理**: 使用统一的错误码和错误信息
- **参数验证**: 严格的参数验证
## 4. 最佳实践
### 4.1 开发流程
1. **需求分析**: 明确功能需求和技术方案
2. **架构设计**: 设计模块结构和数据库结构
3. **代码实现**: 遵循开发规范编码
4. **测试验证**: 单元测试和功能测试
5. **代码审查**: 代码质量检查
6. **部署上线**: 构建和部署
### 4.2 性能优化
- **数据库优化**: 索引优化，SQL 优化
- **缓存策略**: 合理使用 Redis 缓存
- **代码优化**: 减少循环嵌套，优化算法
- **请求优化**: 合并请求，减少 HTTP 调用
### 4.3 安全防护
- **SQL 注入防护**: 使用参数绑定，避免直接拼接 SQL
- **XSS 防护**: 输入验证和输出编码
- **CSRF 防护**: 使用 Token 验证
- **权限控制**: 严格的权限验证机制
- **敏感信息保护**: 加密存储敏感信息
### 4.4 代码复用
- **抽象公共逻辑**: 将公共逻辑抽象为服务或工具类
- **使用 Traits**: 复用代码片段
- **继承基类**: 继承基础类获得通用功能
- **依赖注入**: 提高代码可测试性和可维护性
## 5. 常见问题
### 5.1 性能问题
- **数据库查询慢**: 检查索引，优化 SQL
- **内存占用高**: 检查大数组，优化内存使用
- **响应时间长**: 检查业务逻辑，使用缓存
### 5.2 安全问题
- **SQL 注入**: 使用参数绑定，避免直接拼接 SQL
- **XSS 攻击**: 对输入进行验证和过滤
- **CSRF 攻击**: 实现 CSRF Token 验证
- **权限绕过**: 严格检查权限，避免逻辑漏洞
### 5.3 部署问题
- **环境配置**: 确保生产环境配置正确
- **依赖管理**: 使用 Composer 管理依赖
- **缓存清理**: 部署后清理缓存
- **日志管理**: 配置合理的日志级别
### 5.4 代码问题
- **命名不规范**: 遵循命名规范
- **注释不足**: 添加必要的注释
- **逻辑混乱**: 重构代码，提高可读性
- **重复代码**: 抽象公共逻辑，减少重复
## 6. 开发工具推荐
### 6.1 IDE 推荐
- **PHPStorm**: 专业的 PHP IDE，功能强大
- **VS Code**: 轻量级编辑器，丰富的插件
- **Sublime Text**: 快速的代码编辑器
### 6.2 插件推荐
- **PHP Inspections**: PHP 代码检查插件
- **Laravel Idea**: Laravel 开发插件 (如需)
- **GitLens**: Git 增强插件
- **Debugger for Chrome**: 浏览器调试插件
### 6.3 工具推荐
- **Composer**: PHP 依赖管理工具
- **PHPUnit**: PHP 单元测试框架
- **Postman**: API 测试工具
- **MySQL Workbench**: 数据库设计工具
- **Redis Desktop Manager**: Redis 管理工具
## 7. 参考资源
### 7.1 官方文档
- [ThinkPHP 6 官方文档](https://www.kancloud.cn/manual/thinkphp6_0)
- [PHP 官方文档](https://www.php.net/docs.php)
- [MySQL 官方文档](https://dev.mysql.com/doc/)
- [Redis 官方文档](https://redis.io/documentation)
### 7.2 学习资源
- [Laravel 学院](https://learnku.com/laravel)
- [PHP 中文网](https://www.php.cn/)
- [ThinkPHP 社区](https://www.thinkphp.cn/)
- [Stack Overflow](https://stackoverflow.com/)
### 7.3 代码规范
- [PSR 标准](https://www.php-fig.org/psr/)
- [ThinkPHP 代码规范](https://www.thinkphp.cn/doc)
- [PHP 最佳实践](https://phpbestpractices.org/)
### 7.4 其他资源
- 接口开发流程文档 ./references/api_create.md
- 代码规范文档 ./references/code_style.md
- 数据库设计文档 ./references/db_design.md
- 项目部署文档 ./references/deploy.md
- 目录结构文档 ./references/directory_structure.md
- 错误码文档 ./references/error_code.md
- 系统配置文档 ./references/system_config.md
- 接口请求流程文档 ./references/api_flow.md

545
.trae/skills/php-api/references/api_create.md Normal file
View File

@ -0,0 +1,545 @@
# 接口开发流程文档
## 1. 概述
本文档描述了 CRMEB 项目中 API 接口的完整开发流程，包括需求分析、设计、开发、测试、文档编写、上线发布和监控维护等阶段。本流程旨在规范 API 开发过程，提高 API 的质量和可维护性。
## 2. 需求分析与设计
### 2.1 需求理解
1. **需求收集**: 收集业务部门或产品经理提出的 API 需求
2. **需求分析**: 分析需求的可行性、优先级和影响范围
3. **需求确认**: 与需求方确认需求细节，确保理解一致
4. **风险评估**: 评估需求实现过程中可能遇到的风险
### 2.2 资源设计
1. **数据模型设计**: 设计 API 涉及的数据模型和数据库表结构
2. **资源定义**: 定义 API 操作的资源和资源关系
3. **数据字段**: 确定资源包含的字段和数据类型
4. **关联关系**: 确定资源之间的关联关系
### 2.3 接口设计
1. **URL 设计**: 设计符合 RESTful 规范的 URL
- 使用复数形式，如 `/api/v1/users` 而不是 `/api/v1/user`
- 使用语义化名称，如 `/api/v1/orders` 而不是 `/api/v1/getOrders`
- 合理的 URL 层级，一般不超过 3 层
2. **请求方法设计**: 选择合适的 HTTP 请求方法
- `GET`: 获取资源
- `POST`: 创建资源
- `PUT`: 更新资源
- `DELETE`: 删除资源
- `PATCH`: 部分更新资源
3. **参数设计**: 设计请求参数
- **路径参数**: 用于标识资源，如 `/api/v1/users/:id`
- **查询参数**: 用于过滤、排序、分页，如 `?page=1&limit=10`
- **请求体参数**: 用于创建或更新资源，使用 JSON 格式
- **请求头参数**: 用于认证、授权等
4. **响应设计**: 设计统一的响应格式
- 使用 `app('json')->success()` 返回成功响应
- 使用 `app('json')->fail()` 返回错误响应
- 统一的响应字段：`status`、`msg`、`data`，错误响应额外包含 `code` 字段
- 分页响应包含 `total`、`page`、`limit`、`list` 字段
### 2.4 权限设计
1. **认证方式**: 选择合适的认证方式
- JWT 认证
- OAuth2 认证
- API Key 认证
2. **授权设计**: 设计 API 的访问权限
- 基于角色的访问控制 (RBAC)
- 基于资源的访问控制 (RBAC)
- 接口级别的权限控制
3. **访问控制**: 实现 API 的访问控制
- 使用中间件进行权限验证
- 接口白名单机制
- 接口速率限制
### 2.5 错误设计
1. **错误场景**: 定义 API 可能出现的错误场景
2. **错误码**: 从 `error_code.md` 文档中选择或申请合适的错误码
3. **错误信息**: 设计清晰、准确的错误信息
4. **错误处理**: 设计统一的错误处理机制
## 3. 开发实现
### 3.1 路由创建
1. **路由定义**: 在路由文件中定义 API 路由
2. **路由分组**: 使用路由分组组织相关 API
3. **中间件**: 为路由添加必要的中间件
4. **命名路由**: 为路由设置名称，便于生成 URL
**示例代码**:
```php
// api/v1/route.php
use think\facade\Route;
// API 版本分组
Route::group('v1', function () {
// 用户相关路由
Route::group('users', function () {
Route::get('', 'User/index'); // 获取用户列表
Route::post('', 'User/save'); // 创建用户
Route::get(':id', 'User/read'); // 获取用户详情
Route::put(':id', 'User/update'); // 更新用户
Route::delete(':id', 'User/delete'); // 删除用户
})->middleware(['auth', 'permission']);
})->middleware(['cors', 'jwt']);
```
### 3.2 控制器实现
1. **创建控制器**: 创建 API 控制器类
2. **继承基类**: 继承项目的控制器基类
3. **实现方法**: 实现 API 接口方法
4. **参数验证**: 使用验证器验证请求参数
5. **业务逻辑**: 实现 API 的业务逻辑
6. **响应返回**: 使用统一的响应方法返回响应
**示例代码**:
```php
// app/api/controller/v1/User.php
namespace app\api\controller\v1;
use app\BaseController;
use app\validate\User as UserValidate;
use app\services\UserServices;
class User extends BaseController
{
protected $userServices;
public function __construct(UserServices $userServices)
{
$this->userServices = $userServices;
}
/**
* 获取用户列表
*/
public function index()
{
$params = $this->request->param();
$list = $this->userServices->getUserList($params);
return app('json')->success('获取用户列表成功', $list);
}
/**
* 创建用户
*/
public function save()
{
$data = $this->request->post();
// 参数验证
$this->validate($data, UserValidate::class);
// 业务逻辑
$result = $this->userServices->createUser($data);
// 返回响应
return app('json')->success('创建用户成功', $result);
}
/**
* 获取用户详情
*/
public function read($id)
{
$user = $this->userServices->getUserById($id);
if (!$user) {
return app('json')->fail(400005); // 用户不存在
}
return app('json')->success('获取用户详情成功', $user);
}
}
```
### 3.3 参数验证
1. **创建验证器**: 创建 API 参数验证器
2. **定义规则**: 定义参数验证规则
3. **错误信息**: 定义验证错误信息，使用错误码
4. **验证调用**: 在控制器中调用验证器
**示例代码**:
```php
// app/validate/User.php
namespace app\validate;
use think\Validate;
class User extends Validate
{
protected $rule = [
'username' => 'require|length:3,20|unique:user',
'password' => 'require|length:6,20',
'email' => 'email|unique:user',
'mobile' => 'mobile|unique:user',
'status' => 'in:0,1',
];
protected $message = [
'username.require' => 400033, // 请填写管理员账号
'username.length' => 400762, // 账号密码必须是在6到32位之间
'username.unique' => 400001, // 用户名已存在
'password.require' => 400020, // 密码必须填写
'password.length' => 400762, // 账号密码必须是在6到32位之间
'email.email' => 400003, // 邮箱已被注册
'email.unique' => 400003, // 邮箱已被注册
'mobile.mobile' => 400319, // 请输入正确的身份证
'mobile.unique' => 400002, // 手机号已被注册
'status.in' => 400751, // 状态必须是0-1之间的整数
];
}
```
### 3.4 业务逻辑实现
1. **服务层**: 将业务逻辑封装到服务层
2. **模型层**: 数据访问封装到模型层
3. **事务处理**: 复杂业务使用事务处理
4. **错误处理**: 统一处理业务逻辑错误
**示例代码**:
```php
// app/services/UserServices.php
namespace app\services;
use app\model\User;
use crmeb\basic\BaseServices;
class UserServices extends BaseServices
{
protected $userModel;
public function __construct(User $userModel)
{
$this->userModel = $userModel;
}
/**
* 获取用户列表
*/
public function getUserList(array $params)
{
$page = $params['page'] ?? 1;
$limit = $params['limit'] ?? 10;
$keyword = $params['keyword'] ?? '';
$query = $this->userModel->where('is_deleted', 0);
if ($keyword) {
$query->where('username|nickname|email|mobile', 'like', "%$keyword%");
}
$list = $query->page($page, $limit)->select();
$total = $query->count();
return [
'total' => $total,
'page' => $page,
'limit' => $limit,
'list' => $list
];
}
/**
* 创建用户
*/
public function createUser(array $data)
{
// 密码加密
$data['password'] = password_hash($data['password'], PASSWORD_DEFAULT);
$data['create_time'] = time();
$data['update_time'] = time();
return $this->userModel->save($data);
}
}
```
### 3.5 错误处理
1. **使用错误码**: 优先使用 `error_code.md` 中定义的错误码
2. **统一错误返回**: 使用 `app('json')->fail()` 返回错误
3. **异常处理**: 使用 try-catch 处理异常
4. **日志记录**: 记录错误日志
**示例代码**:
```php
// 正确使用方式
return app('json')->fail(410025); // 账号或密码错误
// 不推荐的使用方式
return app('json')->fail('账号或密码错误');
// 使用错误码并传递额外数据
return app('json')->fail(400086, [], ['field' => 'username']);
// 异常处理
try {
// 业务逻辑
} catch (\Exception $e) {
// 记录日志
app('log')->error($e->getMessage());
// 返回错误
return app('json')->fail(500); // 系统错误
}
```
## 4. 测试验证
### 4.1 单元测试
1. **编写单元测试**: 为 API 编写单元测试
2. **测试框架**: 使用 PHPUnit 测试框架
3. **测试覆盖率**: 提高测试覆盖率
4. **CI/CD**: 集成到 CI/CD 流程
**示例代码**:
```php
// tests/api/UserTest.php
namespace tests\api;
use think\testing\TestCase;
class UserTest extends TestCase
{
public function testIndex()
{
$response = $this->get('/api/v1/users');
$response->assertStatus(200);
$response->assertJsonStructure([
'status',
'msg',
'data' => [
'total',
'page',
'limit',
'list' => [
'*' => [
'id',
'username',
'nickname',
'email',
'mobile',
'status'
]
]
]
]);
}
public function testSave()
{
$data = [
'username' => 'testuser',
'password' => '123456',
'email' => 'test@example.com',
'mobile' => '13800138000',
'status' => 1
];
$response = $this->post('/api/v1/users', $data);
$response->assertStatus(200);
$response->assertJson(['status' => 200, 'msg' => '创建用户成功']);
}
}
```
### 4.2 集成测试
1. **测试集成**: 测试 API 与其他模块的集成
2. **数据库测试**: 测试 API 对数据库的操作
3. **缓存测试**: 测试 API 的缓存机制
4. **队列测试**: 测试 API 与队列的集成
### 4.3 接口测试
1. **工具测试**: 使用 Postman、Apifox 等工具测试 API
2. **测试用例**: 编写完整的测试用例
3. **边界测试**: 测试边界情况
4. **性能测试**: 测试 API 的性能
### 4.4 安全测试
1. **认证测试**: 测试 API 的认证机制
2. **授权测试**: 测试 API 的授权机制
3. **注入测试**: 测试 SQL 注入、XSS 等安全问题
4. **速率限制测试**: 测试 API 的速率限制
## 5. 文档编写
### 5.1 接口文档
1. **编写接口文档**: 编写详细的接口文档
2. **文档工具**: 使用 Swagger、Apifox 等工具生成文档
3. **文档内容**: 包括 URL、请求方法、参数、响应、错误码等
4. **示例**: 提供请求和响应示例
### 5.2 错误码文档
1. **记录错误码**: 在 `error_code.md` 文档中记录 API 使用的错误码
2. **错误码规范**: 遵循项目的错误码规范
3. **错误码描述**: 清晰描述错误码的含义和使用场景
### 5.3 变更记录
1. **记录变更**: 记录 API 的变更历史
2. **变更类型**: 包括新增、修改、删除等
3. **影响范围**: 记录变更的影响范围
4. **版本管理**: 管理 API 的版本
## 6. 上线发布
### 6.1 代码审查
1. **代码审查**: 进行代码审查，确保代码质量
2. **审查标准**: 遵循项目的代码规范
3. **安全审查**: 审查代码的安全性
4. **性能审查**: 审查代码的性能
### 6.2 测试环境验证
1. **部署测试**: 在测试环境部署 API
2. **功能验证**: 验证 API 的功能
3. **性能验证**: 验证 API 的性能
4. **安全验证**: 验证 API 的安全性
### 6.3 灰度发布
1. **灰度策略**: 制定灰度发布策略
2. **灰度部署**: 灰度部署 API
3. **监控观察**: 监控 API 的运行情况
4. **逐步放量**: 逐步增加灰度流量
### 6.4 正式上线
1. **上线准备**: 准备上线所需的资源
2. **正式部署**: 正式部署 API
3. **上线验证**: 验证 API 的正常运行
4. **发布公告**: 发布 API 上线公告
## 7. 监控维护
### 7.1 监控
1. **性能监控**: 监控 API 的响应时间、QPS 等
2. **错误监控**: 监控 API 的错误率、错误类型等
3. **可用性监控**: 监控 API 的可用性
4. **日志监控**: 监控 API 的访问日志和错误日志
### 7.2 日志
1. **访问日志**: 记录 API 的访问日志
2. **错误日志**: 记录 API 的错误日志
3. **慢查询日志**: 记录 API 的慢查询日志
4. **日志分析**: 定期分析日志
### 7.3 优化
1. **性能优化**: 根据监控数据优化 API 性能
2. **安全优化**: 加强 API 的安全性
3. **功能优化**: 优化 API 的功能
4. **代码优化**: 优化 API 的代码
### 7.4 维护
1. **定期维护**: 定期维护 API
2. **版本更新**: 更新 API 的版本
3. **漏洞修复**: 修复 API 的漏洞
4. **文档更新**: 更新 API 的文档
## 8. 最佳实践
### 8.1 设计最佳实践
1. **遵循 RESTful 规范**: 使用 RESTful API 设计规范
2. **统一的命名规范**: 使用统一的命名规范
3. **合理的 URL 设计**: 设计简洁、语义化的 URL
4. **统一的响应格式**: 使用统一的响应格式
5. **明确的错误码**: 使用明确的错误码
### 8.2 开发最佳实践
1. **分层架构**: 遵循分层架构设计
2. **依赖注入**: 使用依赖注入
3. **参数验证**: 严格验证请求参数
4. **事务处理**: 合理使用事务
5. **缓存策略**: 合理使用缓存
### 8.3 测试最佳实践
1. **自动化测试**: 编写自动化测试
2. **测试覆盖率**: 提高测试覆盖率
3. **边界测试**: 测试边界情况
4. **性能测试**: 测试 API 的性能
5. **安全测试**: 测试 API 的安全性
### 8.4 上线最佳实践
1. **灰度发布**: 使用灰度发布策略
2. **监控观察**: 上线后密切监控
3. **回滚机制**: 准备回滚机制
4. **发布公告**: 及时发布公告
### 8.5 维护最佳实践
1. **监控预警**: 设置监控预警
2. **定期巡检**: 定期巡检 API
3. **日志分析**: 定期分析日志
4. **性能优化**: 持续优化性能
5. **文档更新**: 及时更新文档
## 9. 常见问题
### 9.1 跨域问题
- **问题**: 浏览器同源策略导致跨域请求失败
- **解决方案**: 实现 CORS（跨域资源共享），设置适当的响应头
### 9.2 认证授权问题
- **问题**: API 认证授权失败
- **解决方案**: 检查认证信息，确保令牌有效，权限正确
### 9.3 参数验证问题
- **问题**: 请求参数验证失败
- **解决方案**: 检查请求参数，确保格式正确，包含所有必填参数
### 9.4 性能问题
- **问题**: API 响应时间过长
- **解决方案**: 优化 API 实现，使用缓存，减少数据库查询次数
### 9.5 安全问题
- **问题**: API 存在安全漏洞
- **解决方案**: 加强 API 的安全性，如使用 HTTPS、参数验证、防止 SQL 注入等
## 10. 参考资源
- [RESTful API 设计指南](https://restfulapi.net/)
- [HTTP 状态码](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Status)
- [API 设计最佳实践](https://cloud.google.com/apis/design)
- [JSON API 规范](https://jsonapi.org/)
- [OpenAPI 规范](https://swagger.io/specification/)
- [API 安全性最佳实践](https://owasp.org/www-project-api-security/)
- [ThinkPHP 6 官方文档](https://www.kancloud.cn/manual/thinkphp6_0)
- [PHPUnit 官方文档](https://phpunit.de/)
- [Postman 官方文档](https://learning.postman.com/)

488
.trae/skills/php-api/references/api_flow.md Normal file
View File

@ -0,0 +1,488 @@
# 接口请求文档
## 1. 概述
本文档描述了 CRMEB 项目中 API 接口请求的流程、规范、参数设计和响应格式等，旨在统一 API 请求格式，提高 API 的一致性和可维护性。
## 2. 接口请求流程
### 2.1 基本流程
1. **客户端发起请求**: 客户端通过 HTTP/HTTPS 协议向服务器发送请求
2. **请求到达服务器**: 请求经过网络传输到达服务器
3. **请求解析**: 服务器解析请求，包括请求方法、路径、参数等
4. **认证授权**: 服务器对请求进行认证和授权
5. **业务处理**: 服务器执行相应的业务逻辑
6. **生成响应**: 服务器生成响应数据
7. **返回响应**: 服务器将响应返回给客户端
8. **客户端处理响应**: 客户端处理服务器返回的响应
### 2.2 详细流程
```
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ 客户端 │ │ 中间件 │ │ 控制器 │
│ 1. 发起请求 │────▶│ 2. 认证授权 │────▶│ 3. 业务处理 │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│
▼
┌─────────────────┐
│ 服务层 │
│ 4. 执行逻辑 │
└─────────────────┘
│
▼
┌─────────────────┐
│ 数据层 │
│ 5. 数据操作 │
└─────────────────┘
│
▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ 客户端 │ │ 中间件 │ │ 控制器 │
│ 8. 处理响应 │◀────│ 7. 响应处理 │◀────│ 6. 生成响应 │
└─────────────────┘ └─────────────────┘ └─────────────────┘
```
## 3. 请求方法
### 3.1 HTTP 方法
| 方法 | 描述 | 幂等性 | 安全性 |
|------|------|--------|--------|
| GET | 获取资源 | 是 | 是 |
| POST | 创建资源 | 否 | 否 |
| PUT | 更新资源 | 是 | 否 |
| DELETE | 删除资源 | 是 | 否 |
| PATCH | 部分更新资源 | 否 | 否 |
| OPTIONS | 获取资源的可用操作 | 是 | 是 |
| HEAD | 获取资源的元数据 | 是 | 是 |
### 3.2 方法使用规范
- **GET**: 用于获取资源，不应修改资源状态
- **POST**: 用于创建新资源
- **PUT**: 用于更新整个资源，应包含资源的完整表示
- **DELETE**: 用于删除资源
- **PATCH**: 用于部分更新资源，只包含需要更新的字段
- **OPTIONS**: 用于获取资源支持的 HTTP 方法
- **HEAD**: 用于获取资源的元数据，如 Content-Length、Last-Modified 等
## 4. 请求头
### 4.1 通用请求头
| 请求头 | 描述 | 示例 |
|-------|------|------|
| Accept | 客户端可接受的响应内容类型 | application/json |
| Accept-Encoding | 客户端可接受的编码方式 | gzip, deflate |
| Content-Type | 请求体的内容类型 | application/json |
| Authorization | 认证信息 | Bearer {token} |
| User-Agent | 客户端标识 | Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36 |
| X-Requested-With | 请求类型 | XMLHttpRequest |
| X-Token | 认证令牌（自定义） | your_token_here |
### 4.2 自定义请求头
自定义请求头应以 `X-` 为前缀，如 `X-Token`、`X-Request-ID` 等。
## 5. 请求参数
### 5.1 参数位置
| 位置 | 适用场景 | 示例 |
|------|----------|------|
| URL 路径 | 资源标识 | /api/v1/user/1 |
| 查询字符串 | 过滤、排序、分页 | /api/v1/user?page=1&limit=10&sort=create_time&order=desc |
| 请求体 | 复杂数据、创建/更新资源 | {"username": "test", "password": "123456"} |
| 请求头 | 认证信息、元数据 | Authorization: Bearer {token} |
| Cookie | 会话信息 | PHPSESSID=your_session_id |
### 5.2 参数命名规范
- **命名风格**: 使用 camelCase 命名风格，如 `userName`
- **语义化**: 参数名应具有明确的语义，如 `page`、`limit`、`sort`
- **简洁性**: 参数名应简洁明了，避免过长
- **一致性**: 相同类型的参数在不同接口中应保持一致
### 5.3 常用参数
| 参数名 | 类型 | 描述 | 示例 |
|-------|------|------|------|
| page | int | 页码，默认 1 | page=1 |
| limit | int | 每页数量，默认 10 | limit=20 |
| sort | string | 排序字段 | sort=create_time |
| order | string | 排序方式，asc 或 desc | order=desc |
| keyword | string | 搜索关键词 | keyword=test |
| status | int | 状态过滤 | status=1 |
| start_time | string | 开始时间 | start_time=2024-01-01 |
| end_time | string | 结束时间 | end_time=2024-01-31 |
## 6. 请求体
### 6.1 内容类型
| 内容类型 | 描述 | 示例 |
|---------|------|------|
| application/json | JSON 格式，最常用 | {"username": "test", "password": "123456"} |
| application/x-www-form-urlencoded | 表单格式 | username=test&password=123456 |
| multipart/form-data | 文件上传 | 包含文件和表单字段 |
| text/plain | 纯文本 | 简单的文本数据 |
| application/xml | XML 格式 | <user><username>test</username><password>123456</password></user> |
### 6.2 JSON 请求体规范
- **使用 camelCase 命名**: 字段名使用 camelCase 命名风格
- **明确的数据类型**: 使用适当的数据类型，如字符串、数字、布尔值、数组、对象
- **避免 null 值**: 非必要字段不应包含 null 值
- **嵌套结构**: 合理使用嵌套结构，避免过深的嵌套
- **数组格式**: 数组元素类型应一致
示例：
```json
{
"username": "test",
"password": "123456",
"nickname": "测试用户",
"age": 18,
"gender": 1,
"tags": ["tag1", "tag2"],
"address": {
"province": "北京",
"city": "北京",
"district": "朝阳区"
}
}
```
## 7. 响应格式
### 7.1 基本响应格式
所有 API 响应应使用统一的 JSON 格式，包含 `status`、`msg` 和可选的 `data` 字段。系统实际调用方式为 `app('json')->success()`。
#### 7.1.1 调用示例
```php
// 基本成功响应
return app('json')->success('操作成功', ['id' => 1, 'username' => 'test']);
// 只返回数据，不指定消息
return app('json')->success(['id' => 1, 'username' => 'test']);
// 使用系统内置成功码
return app('json')->success(100000); // 100000 是 "保存成功" 对应的系统内置成功码
```
#### 7.1.2 响应格式
```json
{
"status": 200,
"msg": "操作成功",
"data": {
"id": 1,
"username": "test",
"nickname": "测试用户"
}
}
```
### 7.2 分页响应格式
分页响应应包含 `total`、`page`、`limit` 和 `list` 字段，系统实际调用方式为 `app('json')->success()`。
#### 7.2.1 调用示例
```php
// 分页数据响应
$pageData = [
'total' => 100,
'page' => 1,
'limit' => 10,
'list' => [
['id' => 1, 'username' => 'test1', 'nickname' => '测试用户1'],
['id' => 2, 'username' => 'test2', 'nickname' => '测试用户2']
]
];
return app('json')->success('获取列表成功', $pageData);
```
#### 7.2.2 响应格式
```json
{
"status": 200,
"msg": "获取列表成功",
"data": {
"total": 100,
"page": 1,
"limit": 10,
"list": [
{
"id": 1,
"username": "test1",
"nickname": "测试用户1"
},
{
"id": 2,
"username": "test2",
"nickname": "测试用户2"
}
]
}
}
```
### 7.3 错误响应格式
系统使用统一的错误响应格式，所有错误响应通过 `app('json')->fail()` 方法返回。`fail()` 方法支持两种参数类型：
- **错误码**（推荐）：系统内置的数字错误码，如 `410025`
- **错误消息**：直接的字符串错误信息
#### 7.3.1 统一响应格式
无论使用哪种参数类型，系统都会返回统一的 JSON 格式，包含 `status`、`msg` 和可选的 `data` 字段。当使用错误码时，响应中还会包含 `code` 字段。
```json
{
"status": 400,
"msg": "账号或密码错误",
"code": 410025,
"data": null
}
```
#### 7.3.2 调用示例
```php
// 推荐：使用系统内置错误码
return app('json')->fail(410025);
// 不推荐：直接使用错误消息
return app('json')->fail('账号或密码错误');
// 使用错误码并传递额外数据
return app('json')->fail(410025, ['extra' => 'additional data']);
// 使用错误码并传递替换参数
return app('json')->fail(410025, [], ['field' => 'username']);
```
#### 7.3.3 最佳实践
- **优先使用错误码**：系统内置错误码经过统一规划，便于维护和国际化
- **避免直接使用字符串**：直接使用字符串错误信息不利于国际化和统一管理
- **传递必要的额外数据**：对于复杂错误，可以在 `data` 字段中提供详细信息
- **使用替换参数**：对于动态错误信息，使用替换参数提高灵活性
### 7.4 响应码规范
| 响应码范围 | 类型 | 描述 | 示例 |
|-----------|------|------|------|
| 200 | 成功 | 操作成功 | 200 |
| 1000-1999 | 系统级错误 | 系统核心错误 | 1001（参数错误） |
| 4000-4999 | 业务级错误 | 具体业务逻辑错误 | 410025（账号或密码错误） |
| 400 | 客户端错误 | 请求参数错误 | 400 |
| 401 | 认证错误 | 未认证或认证过期 | 401 |
| 403 | 权限错误 | 无权限访问 | 403 |
| 404 | 资源错误 | 资源不存在 | 404 |
| 500 | 服务器错误 | 服务器内部错误 | 500 |
## 8. 错误处理
### 8.1 错误响应设计
错误响应应遵循以下设计原则：
1. **统一格式**: 所有错误响应使用相同的 JSON 格式
2. **明确的错误码**: 使用唯一的错误码标识不同的错误类型
3. **清晰的错误信息**: 错误信息应简洁明了，便于理解
4. **可选的详细信息**: 对于复杂错误，可以在 `data` 字段中提供详细信息
5. **HTTP 状态码匹配**: 错误码应与 HTTP 状态码匹配
### 8.2 AI 自动提示系统内置错误码
CRMEB 系统集成了 AI 自动提示功能，当开发者在编写代码时使用 `fail()` 方法返回错误信息时，AI 会自动：
1. **识别错误信息**: 自动识别开发者输入的错误信息字符串
2. **匹配内置错误码**: 在系统内置错误码库中查找匹配的错误码
3. **自动转换**: 在运行时将错误信息自动转换为对应的系统内置错误码
4. **提供建议**: 对于未匹配到的错误信息，提供相似的错误码建议
5. **实时提示**: 在 IDE 中实时显示错误码建议
6. **错误码文档**: 在错误码文档 error_code.md，找到对应的错误码说明
#### 8.2.1 功能示例
```php
// 开发者输入
return $this->fail('登录失败');
// AI 自动提示并替换为
return $this->fail(410019); // 410019 是 "登录失败" 对应的系统内置错误码
```
#### 8.2.2 工作原理
1. **语言文件解析**: 系统在运行时解析语言文件，构建错误码到错误信息的映射表
2. **自动匹配**: 当调用 `fail()` 方法传入字符串错误信息时，系统自动在映射表中查找匹配的错误码
3. **运行时转换**: 如果找到匹配的错误码，系统会将错误信息替换为错误码，并在响应中包含 `code` 字段
4. **智能提示**: 在 IDE 中，AI 会实时提示开发者使用正确的系统内置错误码
#### 8.2.3 实际响应格式
当使用字符串错误信息时，系统会自动匹配并转换为错误码，最终响应格式为：
```json
{
"status": 400,
"msg": "登录失败",
"code": 410019
}
```
当直接使用错误码时，响应格式为：
```json
{
"status": 400,
"msg": "登录失败",
"code": 410019
}
```
### 8.3 错误处理最佳实践
1. **使用系统内置错误码**: 优先使用系统内置错误码，避免自定义错误信息
2. **错误信息本地化**: 使用 `getLang()` 函数获取本地化的错误信息
3. **详细的错误日志**: 记录详细的错误日志，包括错误码、错误信息、请求参数等
4. **友好的错误提示**: 对客户端返回友好的错误信息，避免暴露系统内部细节
5. **统一的错误处理**: 使用统一的错误处理中间件处理所有错误
6. **错误码文档化**: 定期更新错误码文档，确保与实际代码一致
### 8.4 自定义错误码
对于系统内置错误码无法覆盖的业务场景，可以自定义错误码，但应遵循以下规范：
1. **错误码范围**: 使用系统未占用的错误码范围
2. **命名规范**: 错误码应具有明确的语义
3. **文档化**: 自定义错误码应在文档中明确说明
4. **本地化**: 自定义错误码应在语言文件中定义对应的错误信息
## 9. 接口开发流程
### 9.1 需求分析与设计
1. **需求理解**: 明确接口的业务需求和功能要求
2. **资源设计**: 确定接口涉及的资源和数据模型
3. **接口设计**: 设计接口的 URL、请求方法、参数和响应格式
4. **权限设计**: 确定接口的访问权限和认证方式
5. **错误设计**: 定义接口可能出现的错误情况和错误码
### 9.2 开发实现
1. **创建路由**: 在路由文件中定义接口路由
2. **实现控制器**: 创建控制器并实现接口逻辑
3. **参数验证**: 使用验证器对请求参数进行验证
4. **业务逻辑**: 实现接口的业务逻辑
5. **错误处理**: 使用 `app('json')->fail()` 统一处理错误
6. **响应返回**: 使用 `app('json')->success()` 统一返回响应
### 9.3 测试验证
1. **单元测试**: 编写单元测试验证接口功能
2. **集成测试**: 测试接口与其他模块的集成
3. **接口测试**: 使用 Postman 或其他工具测试接口
4. **性能测试**: 测试接口的性能和响应时间
5. **安全测试**: 测试接口的安全性
### 9.4 文档编写
1. **接口文档**: 编写接口的详细文档
2. **错误码文档**: 在 `error_code.md` 中记录接口使用的错误码
3. **变更记录**: 记录接口的变更历史
### 9.5 上线发布
1. **代码审查**: 进行代码审查，确保代码质量
2. **测试环境验证**: 在测试环境验证接口功能
3. **灰度发布**: 灰度发布接口，观察运行情况
4. **正式上线**: 正式上线接口
### 9.6 监控维护
1. **监控**: 监控接口的运行状态和性能
2. **日志**: 记录接口的访问日志和错误日志
3. **优化**: 根据监控数据优化接口性能
4. **维护**: 定期维护和更新接口
## 10. 最佳实践
### 10.1 请求设计
- **使用 RESTful 风格**: 遵循 RESTful API 设计规范
- **明确的资源命名**: 使用明确的资源名称，如 `/api/v1/user` 而不是 `/api/v1/getUser`
- **合理的 URL 层级**: URL 层级不应过深，一般不超过 3 层
- **使用复数形式**: 资源名称使用复数形式，如 `/api/v1/users` 而不是 `/api/v1/user`
### 10.2 参数设计
- **必填参数**: 明确标识必填参数
- **默认值**: 为可选参数提供合理的默认值
- **参数验证**: 对所有参数进行验证
- **参数类型**: 明确参数类型和格式
### 10.3 响应设计
- **统一格式**: 使用统一的响应格式
- **明确的数据类型**: 响应数据类型应明确
- **避免冗余数据**: 只返回必要的数据
- **分页响应**: 列表接口应支持分页
- **错误信息**: 错误信息应清晰、准确
### 10.4 安全设计
- **认证授权**: 使用 JWT 或 OAuth2 进行认证授权
- **HTTPS**: 使用 HTTPS 加密传输
- **参数验证**: 严格验证所有输入参数
- **输出编码**: 对输出数据进行编码，防止 XSS 攻击
- **SQL 注入防护**: 使用参数绑定，避免直接拼接 SQL
- **CSRF 防护**: 实现 CSRF Token 验证
## 11. 常见问题
### 11.1 跨域问题
- **问题**: 浏览器同源策略导致跨域请求失败
- **解决方案**: 实现 CORS（跨域资源共享），设置适当的响应头
### 10.2 认证失败
- **问题**: 请求未携带认证信息或认证信息无效
- **解决方案**: 检查请求头中的认证信息，确保令牌有效
### 10.3 参数错误
- **问题**: 请求参数格式错误或缺少必填参数
- **解决方案**: 检查请求参数，确保格式正确且包含所有必填参数
### 10.4 响应数据不符合预期
- **问题**: 响应数据格式或内容不符合预期
- **解决方案**: 检查 API 文档，确保请求格式正确，或联系 API 提供者
### 10.5 性能问题
- **问题**: API 请求响应时间过长
- **解决方案**: 优化 API 实现，使用缓存，减少数据库查询次数
## 12. 参考资源
- [RESTful API 设计指南](https://restfulapi.net/)
- [HTTP 状态码](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Status)
- [API 设计最佳实践](https://cloud.google.com/apis/design)
- [JSON API 规范](https://jsonapi.org/)
- [OpenAPI 规范](https://swagger.io/specification/)
- [API 安全性最佳实践](https://owasp.org/www-project-api-security/)

246
.trae/skills/php-api/references/code_style.md Normal file
View File

@ -0,0 +1,246 @@
# 代码规范文档
## 1. 概述
本文档描述了 CRMEB 项目的代码规范，包括 PHP、Vue、JavaScript 等语言的编码标准，旨在统一代码风格，提高代码质量和可维护性。
## 2. PHP 代码规范
### 2.1 命名规范
- **类名**：使用 PascalCase 命名风格，如 `UserController`
- **方法名**：使用 camelCase 命名风格，如 `getUserList`
- **变量名**：使用 camelCase 命名风格，如 `$userName`
- **常量**：使用全大写字母和下划线分隔，如 `MAX_PAGE_SIZE`
- **属性名**：使用 camelCase 命名风格，如 `$userId`
- **文件名**：与类名一致，使用 PascalCase 命名风格，如 `UserController.php`
- **目录名**：使用小写字母，单词之间用下划线分隔，如 `user_service`
### 2.2 代码格式
- **缩进**：使用 4 个空格进行缩进，禁止使用制表符
- **行宽**：每行代码不超过 120 个字符
- **空行**：在类、方法、逻辑块之间使用空行分隔
- **空格**：
- 在操作符两边使用空格，如 `$a = $b + $c`
- 在逗号后使用空格，如 `function($a, $b, $c)`
- 在括号内不使用空格，如 `if($condition)`
### 2.3 注释规范
- **类注释**：使用 DocBlock 注释类的功能、作者和版本
- **方法注释**：使用 DocBlock 注释方法的功能、参数、返回值和异常
- **代码注释**：对复杂的代码逻辑添加注释
- **TODO 注释**：使用 `// TODO:` 标记待完成的任务
### 2.4 代码结构
- **类结构**：
- 类的声明
- 属性声明
- 构造方法
- 其他方法
- **方法结构**：
- 参数声明
- 变量声明
- 业务逻辑
- 返回语句
### 2.5 最佳实践
- **单一职责**：每个类和方法只负责一个功能
- **代码复用**：抽取公共代码为方法或类
- **异常处理**：使用 try-catch 处理异常
- **类型提示**：使用类型提示增强代码可读性
- **魔术方法**：谨慎使用魔术方法
## 3. Vue 代码规范
### 3.1 命名规范
- **组件名**：使用 PascalCase 命名风格，如 `UserList`
- **props**：使用 camelCase 命名风格，如 `userName`
- **data 属性**：使用 camelCase 命名风格，如 `userList`
- **methods**：使用 camelCase 命名风格，如 `getUserList`
- **事件名**：使用 kebab-case 命名风格，如 `user-clicked`
- **插槽名**：使用 kebab-case 命名风格，如 `header-content`
### 3.2 代码格式
- **缩进**：使用 2 个空格进行缩进
- **行宽**：每行代码不超过 120 个字符
- **空行**：在不同逻辑块之间使用空行分隔
- **空格**：
- 在操作符两边使用空格
- 在逗号后使用空格
- 在括号内不使用空格
### 3.3 模板规范
- **标签名**：使用 kebab-case 命名风格，如 `<user-list>`
- **属性名**：使用 kebab-case 命名风格，如 `:user-name="userName"`
- **指令缩写**：使用 `:` 代替 `v-bind:`，使用 `@` 代替 `v-on:`
- **模板表达式**：保持模板表达式简洁，复杂逻辑应在计算属性或方法中处理
### 3.4 组件结构
- **template**：模板部分
- **script**：脚本部分
- **style**：样式部分
### 3.5 最佳实践
- **组件拆分**：将复杂组件拆分为多个子组件
- **计算属性**：使用计算属性处理复杂的响应式数据
- **监听器**：使用监听器监听数据变化
- **混入**：使用混入复用组件逻辑
- **指令**：使用自定义指令封装 DOM 操作
## 4. JavaScript 代码规范
### 4.1 命名规范
- **变量名**：使用 camelCase 命名风格，如 `userName`
- **函数名**：使用 camelCase 命名风格，如 `getUserList`
- **常量**：使用全大写字母和下划线分隔，如 `MAX_PAGE_SIZE`
- **对象属性**：使用 camelCase 命名风格，如 `userName`
- **类名**：使用 PascalCase 命名风格，如 `UserService`
### 4.2 代码格式
- **缩进**：使用 2 个空格进行缩进
- **行宽**：每行代码不超过 120 个字符
- **空行**：在不同逻辑块之间使用空行分隔
- **空格**：
- 在操作符两边使用空格
- 在逗号后使用空格
- 在括号内不使用空格
### 4.3 代码结构
- **函数声明**：使用函数表达式或箭头函数
- **对象字面量**：使用简洁的对象字面量语法
- **数组字面量**：使用简洁的数组字面量语法
- **条件语句**：使用简洁的条件语句语法
- **循环语句**：使用简洁的循环语句语法
### 4.4 最佳实践
- **变量声明**：使用 `let` 和 `const` 声明变量，避免使用 `var`
- **箭头函数**：在适当的场景使用箭头函数
- **模板字符串**：使用模板字符串代替字符串拼接
- **解构赋值**：使用解构赋值简化代码
- **展开运算符**：使用展开运算符简化代码
- **异步编程**：使用 `async/await` 处理异步操作
## 5. HTML/CSS 代码规范
### 5.1 HTML 规范
- **标签名**：使用小写字母，如 `<div>`
- **属性名**：使用小写字母，如 `class="container"`
- **属性值**：使用双引号包围，如 `class="container"`
- **缩进**：使用 2 个空格进行缩进
- **嵌套**：保持标签嵌套层次清晰
- **注释**：对复杂的 HTML 结构添加注释
### 5.2 CSS 规范
- **选择器**：使用小写字母和连字符分隔，如 `.user-list`
- **属性名**：使用小写字母，如 `font-size`
- **属性值**：使用小写字母，如 `color: #333`
- **缩进**：使用 2 个空格进行缩进
- **分号**：每个属性声明后添加分号
- **空行**：在不同选择器之间使用空行分隔
- **注释**：对复杂的 CSS 规则添加注释
### 5.3 最佳实践
- **语义化标签**：使用语义化的 HTML 标签
- **CSS 预处理器**：使用 SCSS 或 Less 等 CSS 预处理器
- **BEM 命名**：使用 BEM 命名规范组织 CSS 类名
- **响应式设计**：使用媒体查询实现响应式设计
- **CSS 变量**：使用 CSS 变量管理样式值
## 6. 数据库规范
### 6.1 命名规范
- **数据库名**：使用小写字母和下划线分隔，如 `crmeb_db`
- **表名**：使用小写字母和下划线分隔，如 `user`
- **字段名**：使用小写字母和下划线分隔，如 `user_name`
- **索引名**：使用小写字母和下划线分隔，如 `idx_user_name`
### 6.2 设计规范
- **主键**：使用 `id` 作为主键，自增整数类型
- **外键**：使用 `表名_id` 作为外键，如 `user_id`
- **时间字段**：使用 `create_time` 和 `update_time` 作为时间字段
- **状态字段**：使用 `status` 作为状态字段，默认值为 0
- **软删除**：使用 `delete_time` 作为软删除字段
### 6.3 最佳实践
- **范式设计**：遵循数据库设计范式
- **索引优化**：为经常查询的字段添加索引
- **分区表**：对大表进行分区
- **事务处理**：使用事务保证数据一致性
- **备份策略**：定期备份数据库
## 7. 代码审查
### 7.1 审查内容
- **代码风格**：是否符合代码规范
- **代码质量**：是否存在代码异味
- **安全性**：是否存在安全漏洞
- **性能**：是否存在性能问题
- **功能**：是否实现了需求功能
### 7.2 审查流程
1. **提交代码**：开发者提交代码到版本控制系统
2. **代码审查**：审查者审查代码
3. **反馈修改**：审查者提供反馈，开发者修改代码
4. **合并代码**：代码审查通过后合并代码
### 7.3 审查工具
- **ESLint**：JavaScript 代码审查工具
- **PHP CodeSniffer**：PHP 代码审查工具
- **Prettier**：代码格式化工具
- **SonarQube**：代码质量分析工具
## 8. 版本控制规范
### 8.1 Git 规范
- **分支命名**：使用小写字母和连字符分隔，如 `feature/user-auth`
- **提交信息**：使用中文描述，格式为 `[模块名] 操作描述`，如 `[用户] 添加用户登录功能`
- **提交频率**：每个功能或 bug 修复单独提交
- **代码冲突**：及时解决代码冲突
### 8.2 版本号规范
使用语义化版本号，格式为 `主版本号.次版本号.修订号`，如 `5.6.4`：
- **主版本号**：不兼容的 API 变更
- **次版本号**：向下兼容的功能新增
- **修订号**：向下兼容的问题修正
## 9. 最佳实践
1. **代码可读性**：编写易于理解的代码
2. **代码可维护性**：编写易于维护的代码
3. **代码可测试性**：编写易于测试的代码
4. **代码可扩展性**：编写易于扩展的代码
5. **代码安全性**：编写安全的代码
6. **代码性能**：编写高性能的代码
## 10. 参考资源
- [PSR-1: 基本编码规范](https://www.php-fig.org/psr/psr-1/)
- [PSR-2: 编码风格规范](https://www.php-fig.org/psr/psr-2/)
- [Vue 官方风格指南](https://cn.vuejs.org/v2/style-guide/)
- [JavaScript 标准风格](https://standardjs.com/)
- [Google HTML/CSS 风格指南](https://google.github.io/styleguide/htmlcssguide.html)

111
.trae/skills/php-api/references/db_design.md Normal file
View File

@ -0,0 +1,111 @@
# 数据库设计文档
## 1. 概述
本文档描述了 CRMEB 项目的数据库设计，包括数据库架构、表结构、索引设计、关系设计等，旨在规范数据库设计，提高数据库性能和可维护性。
## 2. 数据库架构
### 2.1 整体架构
- **数据库系统**: MySQL 5.7~8.0
- **存储引擎**: InnoDB (默认)
- **字符集**: utf8mb4
- **排序规则**: utf8mb4_general_ci
- **连接池**: 建议使用
### 2.2 技术栈
- **MySQL**: 5.7+
- **Redis**: 用于缓存
- **ThinkPHP ORM**: 用于模型操作
- **数据库迁移**: 用于版本控制
- **数据库备份**: 用于数据安全
### 2.3 配置说明
#### 2.3.1 数据库配置
```php
// config/database.php
return [
'default' => env('database.driver', 'mysql'),
'connections' => [
'mysql' => [
'type' => 'mysql',
'hostname' => env('database.hostname', '127.0.0.1'),
'database' => env('database.database', ''),
'username' => env('database.username', ''),
'password' => env('database.password', ''),
'hostport' => env('database.hostport', '3306'),
'charset' => 'utf8mb4',
'prefix' => env('database.prefix', ''),
'debug' => env('app_debug', true),
],
],
];
```
## 3. 数据库设计规范
### 3.1 命名规范
- **数据库名**: 小写字母，下划线分隔
- **表名**: 小写字母，下划线分隔，前缀统一
- **字段名**: 小写字母，下划线分隔
- **索引名**: 小写字母，下划线分隔，类型前缀
- 主键: `PRIMARY`
- 唯一索引: `uk_字段名`
- 普通索引: `idx_字段名`
### 3.2 表结构规范
- **主键**: 统一命名为 `id`，自增整数
- **外键**: 格式 `表名_id`，如 `user_id`
- **时间字段**: `create_time`/`update_time`
- **状态字段**: `status`，默认值 0
- **软删除字段**: `delete_time`，默认值 NULL
### 3.3 字段类型规范
- **整数类型**: 根据实际范围选择
- `TINYINT`: 1字节，范围 -128~127
- `SMALLINT`: 2字节，范围 -32768~32767
- `INT`: 4字节，范围 -2147483648~2147483647
- `BIGINT`: 8字节，范围更大
- **字符串类型**:
- 固定长度: `CHAR`
- 可变长度: `VARCHAR`
- 长文本: `TEXT`
- 大文本: `LONGTEXT`
- **日期时间类型**:
- 日期: `DATE`
- 时间: `TIME`
- 日期时间: `DATETIME`
- 时间戳: `TIMESTAMP`
- **数值类型**:
- 小数: `DECIMAL`
- 浮点数: `FLOAT`, `DOUBLE`
- **布尔类型**: 使用 `TINYINT(1)`，0 表示 false，1 表示 true
### 3.4 索引规范
- **主键索引**: 每个表必须有主键
- **唯一索引**: 用于唯一标识的字段
- **普通索引**: 用于经常查询的字段
- **复合索引**: 用于多字段查询
- **外键索引**: 用于关联查询
- **索引数量**: 每个表索引数量不宜过多，一般不超过 5 个
## 4. 核心表结构
### 4.1 用户表 (`user`)
| 字段名 | 数据类型 | 长度 | 约束 | 描述 |
|-------|---------|------|------|------|
| `id` | `INT` | 11 | `PRIMARY KEY AUTO_INCREMENT` | 用户ID |
| `username

501
.trae/skills/php-api/references/deploy.md Normal file
View File

@ -0,0 +1,501 @@
# 项目部署文档
## 1. 概述
本文档描述了 CRMEB 项目的部署流程，包括环境配置、部署步骤、服务管理等，旨在规范项目部署，确保项目能够稳定运行。
## 2. 部署架构
### 2.1 系统架构
#### 2.1.1 基础架构
- **Web 服务器**: Nginx/Apache
- **应用服务器**: PHP-FPM
- **数据库服务器**: MySQL
- **缓存服务器**: Redis
- **队列服务器**: ThinkPHP 内置队列
- **长连接服务器**: Workerman
#### 2.1.2 部署模式
##### 2.1.2.1 单机部署
```
┌─────────────────────────────────────────────────────┐
│ 服务器 │
├──────────────┬──────────────┬──────────────┬─────────┤
│ Nginx/Apache│ PHP-FPM │ MySQL │ Redis │
└──────────────┴──────────────┴──────────────┴─────────┘
```
##### 2.1.2.2 分布式部署
```
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ Web 服务器 │────>│ 应用服务器 │────>│ 数据库服务器 │
├──────────────┤ ├──────────────┤ ├──────────────┤
│ Nginx │ │ PHP-FPM │ │ MySQL │
└──────────────┘ └──────────────┘ └──────────────┘
│ │ │
└──────────────────┼──────────────────┘
▼
┌──────────────┐
│ 缓存服务器 │
├──────────────┤
│ Redis │
└──────────────┘
```
### 2.2 网络架构
#### 2.2.1 网络拓扑
- **公网**: 外部访问
- **内网**: 内部服务通信
- **DMZ**: 边界区域
#### 2.2.2 端口规划
- **HTTP**: 80
- **HTTPS**: 443
- **SSH**: 22
- **MySQL**: 3306
- **Redis**: 6379
- **PHP-FPM**: 9000
- **Workerman**: 8282
## 3. 环境配置
### 3.1 操作系统
#### 3.1.1 系统要求
- **Linux**: CentOS 7+/Ubuntu 18.04+
- **Windows**: Windows Server 2016+
- **macOS**: macOS 10.15+
#### 3.1.2 系统优化
```bash
# 关闭 SELinux
setenforce 0
sed -i 's/SELINUX=enforcing/SELINUX=disabled/g' /etc/selinux/config
# 关闭防火墙（生产环境建议配置规则）
systemctl stop firewalld
systemctl disable firewalld
# 调整文件描述符
cat >> /etc/security/limits.conf << EOF
* soft nofile 65536
* hard nofile 65536
EOF
# 调整内核参数
cat >> /etc/sysctl.conf << EOF
net.core.somaxconn = 65535
net.ipv4.tcp_max_syn_backlog = 65535
net.ipv4.tcp_fin_timeout = 30
net.ipv4.tcp_keepalive_time = 1200
net.ipv4.tcp_max_tw_buckets = 5000
EOF
sysctl -p
```
### 3.2 PHP 环境
#### 3.2.1 版本要求
- **PHP**: 7.1~7.4
#### 3.2.2 安装步骤
```bash
# CentOS 安装 PHP 7.4
rpm -Uvh https://mirror.webtatic.com/yum/el7/epel-release.rpm
rpm -Uvh https://mirror.webtatic.com/yum/el7/webtatic-release.rpm
yum install -y php74w php74w-fpm php74w-cli php74w-mysql php74w-redis php74w-gd php74w-mbstring php74w-xml php74w-zip php74w-opcache
# Ubuntu 安装 PHP 7.4
apt update
apt install -y php7.4 php7.4-fpm php7.4-cli php7.4-mysql php7.4-redis php7.4-gd php7.4-mbstring php7.4-xml php7.4-zip php7.4-opcache
```
#### 3.2.3 配置优化
```php
// php.ini 配置
memory_limit = 512M
upload_max_filesize = 20M
post_max_size = 20M
max_execution_time = 300
date.timezone = Asia/Shanghai
opcache.enable = 1
opcache.enable_cli = 1
opcache.memory_consumption = 128
opcache.interned_strings_buffer = 8
opcache.max_accelerated_files = 4000
opcache.revalidate_freq = 60
// www.conf 配置
pm.max_children = 50
pm.start_servers = 10
pm.min_spare_servers = 5
pm.max_spare_servers = 20
pm.process_idle_timeout = 10s
pm.max_requests = 1000
```
### 3.3 Web 服务器
#### 3.3.1 Nginx 配置
```nginx
# crmeb.conf
server {
listen 80;
server_name example.com;
root /data/www/crmeb/public;
index index.php index.html;
location / {
try_files $uri $uri/ /index.php?$query_string;
}
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;
}
location ~* \.(js|css|png|jpg|jpeg|gif|ico)$ {
expires 30d;
add_header Cache-Control "public, no-transform";
}
access_log /data/logs/nginx/crmeb.access.log;
error_log /data/logs/nginx/crmeb.error.log;
}
```
### 3.4 数据库配置
#### 3.4.1 MySQL 安装
```bash
# CentOS 安装 MySQL 5.7
yum localinstall -y https://dev.mysql.com/get/mysql57-community-release-el7-11.noarch.rpm
yum install -y mysql-community-server
systemctl start mysqld
systemctl enable mysqld
# 获取初始密码
grep 'temporary password' /var/log/mysqld.log
# 安全配置
mysql_secure_installation
# Ubuntu 安装 MySQL 5.7
apt update
apt install -y mysql-server
mysql_secure_installation
```
#### 3.4.2 MySQL 配置优化
```ini
# my.cnf 配置
[mysqld]
bind-address = 127.0.0.1
port = 3306
datadir = /var/lib/mysql
socket = /var/lib/mysql/mysql.sock
user = mysql
# 性能优化
max_connections = 1000
wait_timeout = 60
interactive_timeout = 28800
key_buffer_size = 64M
table_open_cache = 256
sort_buffer_size = 1M
read_buffer_size = 1M
read_rnd_buffer_size = 4M
myisam_sort_buffer_size = 64M
thread_cache_size = 8
query_cache_size = 16M
# InnoDB 优化
innodb_buffer_pool_size = 1G
innodb_file_per_table = 1
innodb_log_file_size = 256M
innodb_log_buffer_size = 8M
innodb_flush_method = O_DIRECT
```
### 3.5 缓存配置
#### 3.5.1 Redis 安装
```bash
# CentOS 安装 Redis
yum install -y epel-release
yum install -y redis
systemctl start redis
systemctl enable redis
# Ubuntu 安装 Redis
apt update
apt install -y redis-server
systemctl start redis
systemctl enable redis
```
#### 3.5.2 Redis 配置优化
```conf
# redis.conf 配置
bind 127.0.0.1
port 6379
databases 16
dir /var/lib/redis
requirepass your_password
maxmemory 512mb
maxmemory-policy allkeys-lru
save 900 1
save 300 10
save 60 10000
```
## 4. 部署流程
### 4.1 代码部署
#### 4.1.1 Git 部署
```bash
# 克隆代码
git clone https://github.com/crmeb/CRMEB.git /data/www/crmeb
cd /data/www/crmeb
# 切换版本
git checkout tags/v5.6.4
# 安装依赖
composer install --no-dev
# 配置环境变量
cp .env.example .env
# 编辑 .env 文件，配置数据库、Redis 等信息
# 生成密钥
php think key:generate
# 数据库迁移
php think migrate:run
# 生成数据表
php think crmeb:install
# 清除缓存
php think clear
```
#### 4.1.2 手动部署
1. **下载代码**: 从官方网站下载最新版本
2. **上传代码**: 上传到服务器 `/data/www/` 目录
3. **解压代码**: `unzip CRMEB_v5.6.4.zip -d /data/www/crmeb`
4. **安装依赖**: `composer install --no-dev`
5. **配置环境**: 同 Git 部署步骤
### 4.2 服务启动
#### 4.2.1 Web 服务
```bash
# Nginx 启动
systemctl start nginx
systemctl enable nginx
# Apache 启动
systemctl start httpd
systemctl enable httpd
```
#### 4.2.2 PHP-FPM 服务
```bash
systemctl start php-fpm
systemctl enable php-fpm
```
#### 4.2.3 队列服务
```bash
# 启动队列（推荐使用 Supervisor 管理）
supervisorctl start crmeb-queue
# Supervisor 配置
[program:crmeb-queue]
command=php /data/www/crmeb/think queue:listen --queue=default --timeout=60
process_name=%(program_name)s_%(process_num)02d
autostart=true
autorestart=true
user=www
numprocs=2
directory=/data/www/crmeb
stdout_logfile=/data/logs/supervisor/crmeb-queue-stdout.log
stderr_logfile=/data/logs/supervisor/crmeb-queue-stderr.log
```
#### 4.2.4 长连接服务
```bash
# 启动长连接服务
php think workerman start --d
# 停止长连接服务
php think workerman stop
```
#### 4.2.5 定时任务
```bash
# 添加定时任务
crontab -e
# 定时任务配置
* * * * * php /data/www/crmeb/think timer run
0 0 * * * php /data/www/crmeb/think crmeb:backup
```
### 4.3 部署验证
#### 4.3.1 健康检查
- **访问首页**: `http://example.com`
- **访问后台**: `http://example.com/admin`
- **API 测试**: `http://example.com/api/ping`
- **数据库连接**: 检查数据库连接状态
- **Redis 连接**: 检查缓存连接状态
#### 4.3.2 日志检查
```bash
# 检查 Nginx 日志
tail -f /data/logs/nginx/crmeb.error.log
# 检查 PHP 错误日志
tail -f /var/log/php-fpm/error.log
# 检查应用日志
tail -f /data/www/crmeb/runtime/log/*.log
```
## 5. 服务管理
### 5.1 日常运维
#### 5.1.1 监控检查
- **服务状态**: 检查所有服务是否正常运行
- **系统负载**: 监控 CPU、内存、磁盘使用情况
- **网络状态**: 监控网络连接和带宽使用
- **应用状态**: 监控应用响应时间和错误率
#### 5.1.2 日志管理
- **日志收集**: 集中收集所有服务日志
- **日志分析**: 分析日志中的错误和异常
- **日志清理**: 定期清理过期日志
- **日志备份**: 重要日志备份到远程存储
#### 5.1.3 备份恢复
##### 5.1.3.1 数据备份
```bash
# 数据库备份
mysqldump -u username -p database_name > /data/backup/data/$(date +%Y%m%d)_backup.sql
# 代码备份
tar -czf /data/backup/code/$(date +%Y%m%d)_crmeb.tar.gz /data/www/crmeb
# 配置文件备份
tar -czf /data/backup/config/$(date +%Y%m%d)_config.tar.gz /data/www/crmeb/config
```
##### 5.1.3.2 数据恢复
```bash
# 数据库恢复
mysql -u username -p database_name < /data/backup/data/20240101_backup.sql
# 代码恢复
tar -xzf /data/backup/code/20240101_crmeb.tar.gz -C /data/www/
# 配置文件恢复
tar -xzf /data/backup/config/20240101_config.tar.gz -C /data/www/crmeb/
```
## 6. 常见问题
### 6.1 部署问题
#### 6.1.1 依赖安装失败
- **问题**: Composer 安装依赖失败
- **原因**: 网络问题，PHP 版本不兼容
- **解决方案**: 使用国内镜像，检查 PHP 版本
#### 6.1.2 数据库连接失败
- **问题**: 应用无法连接数据库
- **原因**: 数据库服务未启动，用户名密码错误，网络连接问题
- **解决方案**: 检查 MySQL 服务，验证用户名密码，检查网络连接
#### 6.1.3 权限错误
- **问题**: 文件或目录权限错误
- **原因**: 权限设置不正确，用户组不匹配
- **解决方案**: 设置正确的文件权限，确保 PHP-FPM 用户有访问权限
#### 6.1.4 端口占用
- **问题**: 服务启动失败，端口被占用
- **原因**: 其他服务占用了相同端口
- **解决方案**: 查找并停止占用端口的服务，或修改服务端口
### 6.2 运行问题
#### 6.2.1 应用响应缓慢
- **问题**: 应用响应时间长
- **原因**: 数据库查询慢，PHP 代码效率低，服务器资源不足
- **解决方案**: 优化 SQL 查询，优化 PHP 代码，增加服务器资源
#### 6.2.2 内存溢出
- **问题**: PHP 内存溢出
- **原因**: 内存限制过小，代码中存在内存泄漏
- **解决方案**: 增加 PHP 内存限制，优化代码中的内存使用
#### 6.2.3 队列堆积
- **问题**: 队列任务堆积
- **原因**: 队列处理速度慢，任务量过大
- **解决方案**: 增加队列进程数，优化队列任务处理逻辑
## 7. 参考资源
- [CRMEB 官方文档](https://doc.crmeb.com/single_open)
- [ThinkPHP 6 官方文档](https://www.kancloud.cn/manual/thinkphp6_0)
- [Nginx 官方文档](https://nginx.org/en/docs/)
- [PHP 官方文档](https://www.php.net/docs.php)
- [MySQL 官方文档](https://dev.mysql.com/doc/)
- [Redis 官方文档](https://redis.io/documentation)

275
.trae/skills/php-api/references/directory_structure.md Normal file
View File

@ -0,0 +1,275 @@
# 目录结构文档
## 1. 概述
本文档描述了 CRMEB 项目的目录结构，包括各目录的功能、文件组织方式等，旨在帮助开发者理解项目结构，提高开发效率。
## 2. 项目根目录结构
```
CRMEB/
├── app/ # 应用目录
├── config/ # 配置目录
├── crmeb/ # 核心库目录
├── database/ # 数据库目录
├── extend/ # 扩展目录
├── public/ # 公共资源目录
├── runtime/ # 运行时目录
├── thinkphp/ # ThinkPHP 核心目录
├── vendor/ # 第三方依赖目录
├── .env # 环境变量文件
├── .env.example # 环境变量示例文件
├── composer.json # Composer 配置文件
├── composer.lock # Composer 锁定文件
├── LICENSE # 许可证文件
├── README.md # 项目说明文档
├── think # ThinkPHP 命令行工具
```
## 3. 应用目录结构 (app/)
```
app/
├── api/ # API 接口层
│ ├── v1/ # API 版本 1
│ ├── v2/ # API 版本 2
│ └── BaseApi.php # API 基类
├── controller/ # 控制器层
│ ├── admin/ # 管理端控制器
│ ├── api/ # API 控制器
│ └── BaseController.php # 控制器基类
├── dao/ # 数据访问层
│ └── BaseDao.php # DAO 基类
├── event/ # 事件层
├── exception/ # 异常处理层
├── middleware/ # 中间件层
├── model/ # 模型层
│ └── BaseModel.php # 模型基类
├── services/ # 业务逻辑层
│ └── BaseServices.php # 服务基类
├── subscribe/ # 事件订阅层
├── validate/ # 验证层
│ └── BaseValidate.php # 验证器基类
└── common.php # 公共函数文件
```
### 3.1 API 目录 (app/api/)
- **功能**: 处理 API 接口请求
- **结构**: 按 API 版本划分目录
- **基类**: `BaseApi.php`，提供 API 基础功能
- **版本控制**: 通过目录结构实现 API 版本管理
### 3.2 控制器目录 (app/controller/)
- **功能**: 处理 HTTP 请求，路由分发
- **结构**: 按模块划分控制器
- **基类**: `BaseController.php`，提供控制器基础功能
- **类型**: 管理端控制器、API 控制器
### 3.3 DAO 目录 (app/dao/)
- **功能**: 数据访问对象，封装数据库操作
- **结构**: 按业务模块划分 DAO 类
- **基类**: `BaseDao.php`，提供 DAO 基础功能
- **职责**: 处理数据库查询、插入、更新、删除等操作
### 3.4 模型目录 (app/model/)
- **功能**: 数据模型，定义数据结构和关系
- **结构**: 按业务模块划分模型类
- **基类**: `BaseModel.php`，提供模型基础功能
- **特性**: 支持 ORM、关联查询、软删除等
### 3.5 服务目录 (app/services/)
- **功能**: 业务逻辑层，封装核心业务逻辑
- **结构**: 按业务模块划分服务类
- **基类**: `BaseServices.php`，提供服务基础功能
- **职责**: 实现业务规则，协调多个 DAO 和模型
### 3.6 验证目录 (app/validate/)
- **功能**: 数据验证，验证请求参数
- **结构**: 按业务模块划分验证器类
- **基类**: `BaseValidate.php`，提供验证器基础功能
- **特性**: 支持规则验证、场景验证等
## 4. 配置目录结构 (config/)
```
config/
├── app.php # 应用配置
├── cache.php # 缓存配置
├── captcha.php # 验证码配置
├── console.php # 控制台配置
├── cookie.php # Cookie 配置
├── database.php # 数据库配置
├── filesystem.php # 文件系统配置
├── lang.php # 语言配置
├── log.php # 日志配置
├── queue.php # 队列配置
├── route.php # 路由配置
├── session.php # Session 配置
├── template.php # 模板配置
└── trace.php # 调试配置
```
- **功能**: 存储项目的所有配置文件
- **结构**: 按功能模块划分配置文件
- **特性**: 支持环境变量配置、配置缓存等
- **加载顺序**: 框架配置 → 应用配置 → 环境配置
## 5. 核心库目录结构 (crmeb/)
```
crmeb/
├── basic/ # 基础类库
├── exception/ # 核心异常类
├── services/ # 核心服务类
├── utils/ # 工具类
└── version.php # 版本信息
```
- **功能**: 存储 CRMEB 核心库代码
- **结构**: 按功能模块划分目录
- **特性**: 独立于应用代码，便于维护和升级
- **作用**: 提供核心功能和基础服务
## 6. 数据库目录结构 (database/)
```
database/
├── migrations/ # 数据库迁移文件
└── seeders/ # 数据库种子文件
```
- **功能**: 存储数据库相关文件
- **迁移文件**: 用于版本控制数据库结构
- **种子文件**: 用于初始化数据库数据
- **工具**: 使用 ThinkPHP 迁移工具管理
## 7. 公共资源目录结构 (public/)
```
public/
├── admin/ # 管理端资源
├── api/ # API 资源
├── assets/ # 静态资源
│ ├── css/ # CSS 文件
│ ├── images/ # 图片文件
│ └── js/ # JavaScript 文件
├── index.php # 应用入口文件
├── robots.txt # 机器人协议文件
└── router.php # URL 重写文件
```
- **功能**: 存储可直接访问的公共资源
- **结构**: 按功能模块划分目录
- **特性**: 可通过 URL 直接访问
- **安全**: 敏感文件不应放在此目录
## 8. 运行时目录结构 (runtime/)
```
runtime/
├── cache/ # 缓存目录
├── log/ # 日志目录
│ └── app/ # 应用日志
├── session/ # Session 目录
├── temp/ # 临时文件目录
└── think/ # ThinkPHP 运行时目录
```
- **功能**: 存储运行时生成的文件
- **结构**: 按功能模块划分目录
- **特性**: 自动生成，无需手动维护
- **权限**: 需要可写权限
## 9. 核心目录结构 (thinkphp/)
```
thinkphp/
├── lang/ # 语言包目录
├── library/ # 核心类库目录
├── tpl/ # 模板目录
├── base.php # 基础定义文件
├── composer.json # Composer 配置文件
└── helper.php # 助手函数文件
```
- **功能**: 存储 ThinkPHP 框架核心代码
- **结构**: 框架默认结构
- **特性**: 独立于应用代码
- **升级**: 通过 Composer 升级
## 10. 第三方依赖目录结构 (vendor/)
```
vendor/
├── autoload.php # 自动加载文件
├── composer/ # Composer 核心目录
├── symfony/ # Symfony 组件
├── topthink/ # ThinkPHP 组件
└── ... # 其他第三方依赖
```
- **功能**: 存储第三方依赖库
- **管理**: 通过 Composer 管理
- **结构**: 按依赖包名称划分目录
- **自动加载**: 通过 `autoload.php` 自动加载
## 11. 目录结构最佳实践
### 11.1 命名规范
- **目录名**: 小写字母，单词之间用下划线分隔
- **文件名**: 与类名一致，使用 PascalCase 命名风格
- **类名**: 使用 PascalCase 命名风格
- **方法名**: 使用 camelCase 命名风格
- **变量名**: 使用 camelCase 命名风格
### 11.2 组织原则
- **模块化**: 按功能模块组织目录结构
- **分层架构**: 遵循 MVC + Service + DAO 分层架构
- **单一职责**: 每个目录和文件只负责一个功能
- **可扩展性**: 便于添加新功能和模块
- **易维护性**: 便于理解和维护
### 11.3 开发建议
- **遵循框架规范**: 遵循 ThinkPHP 框架目录结构规范
- **合理划分模块**: 根据业务功能合理划分模块
- **避免目录过深**: 目录层级不宜过深，一般不超过 4 层
- **保持目录整洁**: 及时清理无用文件和目录
- **文档化**: 为重要目录添加说明文档
## 12. 常见问题
### 12.1 目录权限问题
- **问题**: 运行时目录没有写权限
- **解决方案**: 执行 `chmod -R 777 runtime/` 赋予写权限
### 12.2 自动加载问题
- **问题**: 新增类无法自动加载
- **解决方案**: 执行 `composer dump-autoload` 更新自动加载
### 12.3 配置文件不生效
- **问题**: 修改配置文件后不生效
- **解决方案**: 清除配置缓存，执行 `php think clear`
### 12.4 目录结构混乱
- **问题**: 目录结构不清晰，难以维护
- **解决方案**: 重新组织目录结构，遵循模块化原则
## 13. 参考资源
- [ThinkPHP 6 目录结构](https://www.kancloud.cn/manual/thinkphp6_0/1037487)
- [MVC 架构设计](https://zh.wikipedia.org/wiki/MVC)
- [分层架构设计](https://zh.wikipedia.org/wiki/分层架构)
- [模块化设计](https://zh.wikipedia.org/wiki/模块化设计)

273
.trae/skills/php-api/references/error_code.md Normal file
View File

@ -0,0 +1,273 @@
# 错误码文档
## 1. 概述
本文档描述了 CRMEB 项目的错误码规范，包括错误码的分类、定义、使用方法等，旨在统一错误码格式，提高错误处理的一致性和可维护性。
## 2. 错误码分类
### 2.1 HTTP 状态码
- **1xx**: 信息性状态码，表示请求已接收，继续处理
- **2xx**: 成功状态码，表示请求已成功处理
- **3xx**: 重定向状态码，表示需要进一步操作以完成请求
- **4xx**: 客户端错误状态码，表示请求包含语法错误或无法完成请求
- **5xx**: 服务器错误状态码，表示服务器在处理请求时发生错误
### 2.2 业务错误码
业务错误码由 5 位数字组成，格式为 `XXXXX`，其中：
- **第一位**: 错误类型标识
- `1`: 系统错误
- `2`: 业务错误
- `3`: 参数错误
- `4`: 权限错误
- `5`: 资源错误
- `6`: 数据库错误
- `7`: 第三方服务错误
- `8`: 其他错误
- **后四位**: 具体错误编码，从 0000 开始递增
## 3. 系统错误码
### 3.1 系统错误 (1xxxxx)
| 错误码 | 描述 | HTTP 状态码 |
|-------|------|-------------|
| 10001 | 系统内部错误 | 500 |
| 10002 | 系统维护中 | 503 |
| 10003 | 系统繁忙 | 503 |
| 10004 | 服务不可用 | 503 |
| 10005 | 网关错误 | 502 |
### 3.2 业务错误 (2xxxxx)
| 错误码 | 描述 | HTTP 状态码 |
|-------|------|-------------|
| 20001 | 操作失败 | 400 |
| 20002 | 业务逻辑错误 | 400 |
| 20003 | 数据已存在 | 400 |
| 20004 | 数据不存在 | 404 |
| 20005 | 操作不允许 | 403 |
### 3.3 参数错误 (3xxxxx)
| 错误码 | 描述 | HTTP 状态码 |
|-------|------|-------------|
| 30001 | 参数不能为空 | 400 |
| 30002 | 参数格式错误 | 400 |
| 30003 | 参数类型错误 | 400 |
| 30004 | 参数超出范围 | 400 |
| 30005 | 参数验证失败 | 422 |
### 3.4 权限错误 (4xxxxx)
| 错误码 | 描述 | HTTP 状态码 |
|-------|------|-------------|
| 40001 | 未登录 | 401 |
| 40002 | 登录已过期 | 401 |
| 40003 | 无权限访问 | 403 |
| 40004 | 权限不足 | 403 |
| 40005 | 令牌无效 | 401 |
### 3.5 资源错误 (5xxxxx)
| 错误码 | 描述 | HTTP 状态码 |
|-------|------|-------------|
| 50001 | 资源不存在 | 404 |
| 50002 | 资源已删除 | 404 |
| 50003 | 资源已锁定 | 400 |
| 50004 | 资源不足 | 400 |
| 50005 | 资源已过期 | 400 |
### 3.6 数据库错误 (6xxxxx)
| 错误码 | 描述 | HTTP 状态码 |
|-------|------|-------------|
| 60001 | 数据库连接失败 | 500 |
| 60002 | 数据库查询失败 | 500 |
| 60003 | 数据库更新失败 | 500 |
| 60004 | 数据库插入失败 | 500 |
| 60005 | 数据库删除失败 | 500 |
| 60006 | 数据库事务失败 | 500 |
### 3.7 第三方服务错误 (7xxxxx)
| 错误码 | 描述 | HTTP 状态码 |
|-------|------|-------------|
| 70001 | 第三方服务连接失败 | 500 |
| 70002 | 第三方服务超时 | 504 |
| 70003 | 第三方服务返回错误 | 500 |
| 70004 | 第三方服务认证失败 | 401 |
| 70005 | 第三方服务限流 | 429 |
## 4. 模块错误码
### 4.1 用户模块 (801xx)
| 错误码 | 描述 | HTTP 状态码 |
|-------|------|-------------|
| 80101 | 用户名或密码错误 | 401 |
| 80102 | 用户不存在 | 404 |
| 80103 | 用户已存在 | 400 |
| 80104 | 用户状态异常 | 400 |
| 80105 | 验证码错误 | 400 |
| 80106 | 验证码已过期 | 400 |
| 80107 | 手机号格式错误 | 400 |
| 80108 | 邮箱格式错误 | 400 |
### 4.2 商品模块 (802xx)
| 错误码 | 描述 | HTTP 状态码 |
|-------|------|-------------|
| 80201 | 商品不存在 | 404 |
| 80202 | 商品已下架 | 400 |
| 80203 | 商品库存不足 | 400 |
| 80204 | 商品价格异常 | 400 |
| 80205 | 商品分类不存在 | 404 |
### 4.3 订单模块 (803xx)
| 错误码 | 描述 | HTTP 状态码 |
|-------|------|-------------|
| 80301 | 订单不存在 | 404 |
| 80302 | 订单状态异常 | 400 |
| 80303 | 订单已取消 | 400 |
| 80304 | 订单已完成 | 400 |
| 80305 | 订单支付失败 | 400 |
| 80306 | 订单支付超时 | 400 |
### 4.4 支付模块 (804xx)
| 错误码 | 描述 | HTTP 状态码 |
|-------|------|-------------|
| 80401 | 支付方式不支持 | 400 |
| 80402 | 支付金额异常 | 400 |
| 80403 | 支付参数错误 | 400 |
| 80404 | 支付失败 | 400 |
| 80405 | 支付超时 | 400 |
| 80406 | 支付已完成 | 400 |
## 5. 错误码使用规范
### 5.1 错误响应格式
```json
{
"code": 20001,
"msg": "操作失败",
"data": []
}
```
### 5.2 成功响应格式
```json
{
"code": 200,
"msg": "操作成功",
"data": {...}
}
```
### 5.3 错误处理流程
1. **捕获异常**: 在控制器或中间件中捕获异常
2. **确定错误码**: 根据异常类型确定对应的错误码
3. **构建响应**: 按照统一格式构建错误响应
4. **返回响应**: 返回错误响应给客户端
### 5.4 错误日志记录
- **记录内容**: 错误码、错误信息、请求参数、请求路径、用户信息、时间戳等
- **记录级别**: 根据错误严重程度选择合适的日志级别
- **记录位置**: 系统日志文件
- **监控告警**: 对于严重错误，触发告警机制
## 6. 错误码管理
### 6.1 错误码定义
错误码定义在配置文件中，便于统一管理和维护：
```php
// config/error_code.php
return [
// 系统错误
10001 => '系统内部错误',
10002 => '系统维护中',
// 业务错误
20001 => '操作失败',
20002 => '业务逻辑错误',
// 参数错误
30001 => '参数不能为空',
30002 => '参数格式错误',
// ...
];
```
### 6.2 错误码使用
在代码中使用错误码时，应直接引用配置文件中的定义：
```php
// 控制器中使用
return $this->fail(config('error_code.20001'));
// 或直接使用错误码
return $this->fail('操作失败', [], 20001);
```
### 6.3 错误码更新
当需要添加新的错误码时，应遵循以下流程：
1. **确定错误类型**: 根据错误性质确定错误类型
2. **分配错误码**: 从对应类型的错误码范围中分配一个未使用的错误码
3. **更新配置**: 在 `error_code.php` 配置文件中添加错误码定义
4. **更新文档**: 更新错误码文档
5. **通知团队**: 通知团队成员新添加的错误码
## 7. 错误码最佳实践
### 7.1 设计原则
- **唯一性**: 每个错误码唯一对应一种错误情况
- **可读性**: 错误码应易于理解和记忆
- **可扩展性**: 错误码应具有良好的扩展性，便于添加新的错误码
- **一致性**: 错误码格式和使用方法应保持一致
- **详细性**: 错误信息应清晰、准确，便于调试和定位问题
### 7.2 使用建议
- **避免硬编码**: 错误码应定义在配置文件中，避免直接硬编码在代码中
- **统一处理**: 使用统一的错误处理中间件处理错误
- **详细日志**: 记录详细的错误日志，便于调试和分析
- **友好提示**: 向客户端返回友好的错误信息，避免暴露系统内部细节
- **定期清理**: 定期清理不再使用的错误码，保持错误码的简洁性
### 7.3 常见问题
#### 7.3.1 错误码冲突
- **问题**: 不同模块使用了相同的错误码
- **解决方案**: 严格按照模块划分错误码范围，避免冲突
#### 7.3.2 错误信息不明确
- **问题**: 错误信息过于简洁，无法定位问题
- **解决方案**: 提供详细的错误信息，包含必要的上下文
#### 7.3.3 错误码未及时更新
- **问题**: 新增功能时未及时添加对应的错误码
- **解决方案**: 在开发新功能时，同步更新错误码定义和文档
## 8. 参考资源
- [HTTP 状态码](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Status)
- [RESTful API 错误处理](https://restfulapi.net/http-status-codes/)
- [错误码设计最佳实践](https://www.thoughtworks.com/insights/blog/error-handling-microservices)
- [API 错误码规范](https://cloud.google.com/apis/design/errors)

380
.trae/skills/php-api/references/system_config.md Normal file
View File

@ -0,0 +1,380 @@
# 系统配置文档
## 1. 概述
本文档描述了 CRMEB 项目的系统配置，包括配置文件、环境变量、配置项说明等，旨在帮助开发者理解和配置项目，确保项目能够正常运行。
## 2. 配置文件结构
### 2.1 配置目录结构
```
config/
├── app.php # 应用配置
├── cache.php # 缓存配置
├── captcha.php # 验证码配置
├── console.php # 控制台配置
├── cookie.php # Cookie 配置
├── database.php # 数据库配置
├── filesystem.php # 文件系统配置
├── lang.php # 语言配置
├── log.php # 日志配置
├── queue.php # 队列配置
├── route.php # 路由配置
├── session.php # Session 配置
├── template.php # 模板配置
└── trace.php # 调试配置
```
### 2.2 配置加载顺序
1. **框架默认配置**：ThinkPHP 框架自带的默认配置
2. **应用配置**：项目根目录下的 `config/` 目录中的配置文件
3. **环境配置**：根据当前环境加载对应的环境配置文件
4. **动态配置**：运行时动态设置的配置
5. **环境变量**：通过 `.env` 文件或系统环境变量设置的配置
## 3. 环境变量配置
### 3.1 环境变量文件 (.env)
环境变量文件 `.env` 用于存储敏感配置信息，如数据库密码、API 密钥等。该文件不应提交到版本控制系统。
```ini
# 应用配置
APP_NAME=CRMEB
APP_ENV=local
APP_KEY=base64:your_app_key
APP_DEBUG=true
APP_URL=http://localhost
# 数据库配置
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=crmeb
DB_USERNAME=root
DB_PASSWORD=your_password
# Redis 配置
REDIS_HOST=127.0.0.1
REDIS_PASSWORD=null
REDIS_PORT=6379
REDIS_DB=0
# 缓存配置
CACHE_DRIVER=file
# 队列配置
QUEUE_CONNECTION=sync
# 邮件配置
MAIL_MAILER=smtp
MAIL_HOST=smtp.example.com
MAIL_PORT=587
MAIL_USERNAME=your_email@example.com
MAIL_PASSWORD=your_email_password
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=your_email@example.com
MAIL_FROM_NAME="CRMEB"
# 阿里云配置
ALIYUN_ACCESS_KEY_ID=your_access_key_id
ALIYUN_ACCESS_KEY_SECRET=your_access_key_secret
# 腾讯云配置
TENCENTCLOUD_SECRET_ID=your_secret_id
TENCENTCLOUD_SECRET_KEY=your_secret_key
```
### 3.2 环境变量加载
环境变量可以通过以下方式加载：
1. **.env 文件**：在项目根目录下创建 `.env` 文件，根据环境需要配置相关变量
2. **系统环境变量**：在服务器上设置系统环境变量
3. **命令行参数**：在运行命令时通过参数设置环境变量
### 3.3 环境变量使用
在配置文件中可以使用 `env()` 函数获取环境变量：
```php
// config/database.php
return [
'default' => env('database.driver', 'mysql'),
'connections' => [
'mysql' => [
'type' => 'mysql',
'hostname' => env('database.hostname', '127.0.0.1'),
'database' => env('database.database', ''),
'username' => env('database.username', ''),
'password' => env('database.password', ''),
'hostport' => env('database.hostport', '3306'),
'charset' => 'utf8mb4',
'prefix' => env('database.prefix', ''),
'debug' => env('app_debug', true),
],
],
];
```
## 4. 核心配置项
### 4.1 应用配置 (app.php)
| 配置项 | 类型 | 默认值 | 描述 |
|-------|------|--------|------|
| app_debug | bool | true | 应用调试模式 |
| app_trace | bool | false | 应用跟踪模式 |
| app_status | string | 'dev' | 应用状态 |
| app_namespace | string | 'app' | 应用命名空间 |
| default_return_type | string | 'json' | 默认返回类型 |
| default_timezone | string | 'Asia/Shanghai' | 默认时区 |
| lang_switch_on | bool | false | 语言切换开关 |
| default_lang | string | 'zh-cn' | 默认语言 |
| auto_bind_module | bool | true | 自动绑定模块 |
| controller_suffix | bool | false | 控制器后缀 |
| url_route_on | bool | true | URL 路由开关 |
| url_route_must | bool | false | URL 路由必须 |
| var_pathinfo | string | 's' | PATH_INFO 变量名 |
| pathinfo_depr | string | '/' | PATH_INFO 分隔符 |
| url_html_suffix | string | '' | URL HTML 后缀 |
| url_common_param | bool | false | URL 普通参数模式 |
| url_param_type | int | 1 | URL 参数类型 |
| request_cache_on | bool | false | 请求缓存开关 |
| request_cache_expire | int | null | 请求缓存有效期 |
### 4.2 数据库配置 (database.php)
| 配置项 | 类型 | 默认值 | 描述 |
|-------|------|--------|------|
| default | string | 'mysql' | 默认数据库连接 |
| connections | array | [] | 数据库连接配置 |
| connections.mysql.type | string | 'mysql' | 数据库类型 |
| connections.mysql.hostname | string | '127.0.0.1' | 数据库主机名 |
| connections.mysql.database | string | '' | 数据库名 |
| connections.mysql.username | string | '' | 数据库用户名 |
| connections.mysql.password | string | '' | 数据库密码 |
| connections.mysql.hostport | string | '3306' | 数据库端口 |
| connections.mysql.charset | string | 'utf8mb4' | 数据库字符集 |
| connections.mysql.prefix | string | '' | 数据库表前缀 |
| connections.mysql.debug | bool | true | 数据库调试模式 |
| connections.mysql.deploy | array | [] | 数据库部署方式 |
| connections.mysql.rw_separate | bool | false | 数据库读写分离 |
| connections.mysql.master_num | int | 1 | 主数据库数量 |
| connections.mysql.slave_no | int | '' | 从数据库编号 |
| connections.mysql.read_master | bool | false | 是否从主服务器读取 |
| connections.mysql.deploy_type | int | 0 | 数据库部署类型 |
| connections.mysql.failover | array | [] | 数据库故障转移 |
| connections.mysql.break_reconnect | bool | false | 断开重连 |
| connections.mysql.pdo_type | string | '' | PDO 类型 |
| connections.mysql.max_conn | int | 0 | 最大连接数 |
| connections.mysql.strict_type | bool | false | 严格模式 |
| connections.mysql.auto_timestamp | bool | false | 自动时间戳 |
| connections.mysql.datetime_format | string | 'Y-m-d H:i:s' | 日期时间格式 |
| connections.mysql.date_format | string | 'Y-m-d' | 日期格式 |
| connections.mysql.time_format | string | 'H:i:s' | 时间格式 |
| connections.mysql.sql_build_cache | bool | false | SQL 构建缓存 |
| connections.mysql.builder | string | '' | 查询构建器 |
| connections.mysql.query | string | '' | 查询类 |
| connections.mysql.break_match_str | string | '' | 断开匹配字符串 |
| connections.mysql.params | array | [] | 连接参数 |
| connections.mysql.pk_convert | bool | false | 主键转换 |
| connections.mysql.resultset_type | string | 'array' | 结果集类型 |
| connections.mysql.return_collection | bool | false | 返回集合 |
| connections.mysql.identifier_quote | string | '' | 标识符引号 |
| connections.mysql.cache | array | [] | 缓存配置 |
| connections.mysql.trace_sql | bool | false | SQL 跟踪 |
### 4.3 缓存配置 (cache.php)
| 配置项 | 类型 | 默认值 | 描述 |
|-------|------|--------|------|
| default | string | 'file' | 默认缓存驱动 |
| stores | array | [] | 缓存驱动配置 |
| stores.file.type | string | 'file' | 文件缓存驱动 |
| stores.file.path | string | '' | 文件缓存路径 |
| stores.file.prefix | string | '' | 文件缓存前缀 |
| stores.file.expire | int | 0 | 文件缓存有效期 |
| stores.redis.type | string | 'redis' | Redis 缓存驱动 |
| stores.redis.host | string | '127.0.0.1' | Redis 主机名 |
| stores.redis.port | int | 6379 | Redis 端口 |
| stores.redis.password | string | '' | Redis 密码 |
| stores.redis.select | int | 0 | Redis 数据库 |
| stores.redis.timeout | int | 0 | Redis 超时时间 |
| stores.redis.persistent | bool | false | Redis 持久连接 |
| stores.redis.prefix | string | '' | Redis 缓存前缀 |
| stores.redis.serializer | int | 0 | Redis 序列化方式 |
| stores.memcache.type | string | 'memcache' | Memcache 缓存驱动 |
| stores.memcache.host | string | '127.0.0.1' | Memcache 主机名 |
| stores.memcache.port | int | 11211 | Memcache 端口 |
| stores.memcache.persistent | bool | false | Memcache 持久连接 |
| stores.memcache.timeout | int | 0 | Memcache 超时时间 |
| stores.memcache.prefix | string | '' | Memcache 缓存前缀 |
| stores.wincache.type | string | 'wincache' | WinCache 缓存驱动 |
| stores.wincache.prefix | string | '' | WinCache 缓存前缀 |
| stores.xcache.type | string | 'xcache' | XCache 缓存驱动 |
| stores.xcache.prefix | string | '' | XCache 缓存前缀 |
| stores.apc.type | string | 'apc' | APC 缓存驱动 |
| stores.apc.prefix | string | '' | APC 缓存前缀 |
| prefix | string | '' | 缓存前缀 |
### 4.4 队列配置 (queue.php)
| 配置项 | 类型 | 默认值 | 描述 |
|-------|------|--------|------|
| default | string | 'sync' | 默认队列驱动 |
| connections | array | [] | 队列连接配置 |
| connections.sync.driver | string | 'sync' | 同步队列驱动 |
| connections.database.driver | string | 'database' | 数据库队列驱动 |
| connections.database.table | string | 'jobs' | 队列表名 |
| connections.database.queue | string | 'default' | 默认队列名 |
| connections.database.expire | int | 60 | 任务过期时间 |
| connections.redis.driver | string | 'redis' | Redis 队列驱动 |
| connections.redis.connection | string | 'default' | Redis 连接名 |
| connections.redis.queue | string | 'default' | 默认队列名 |
| connections.redis.expire | int | 60 | 任务过期时间 |
| failed | array | [] | 失败队列配置 |
| failed.driver | string | 'database' | 失败队列驱动 |
| failed.table | string | 'failed_jobs' | 失败队列表名 |
### 4.5 日志配置 (log.php)
| 配置项 | 类型 | 默认值 | 描述 |
|-------|------|--------|------|
| default | array | ['file'] | 默认日志通道 |
| channels | array | [] | 日志通道配置 |
| channels.file.type | string | 'file' | 文件日志驱动 |
| channels.file.path | string | '' | 文件日志路径 |
| channels.file.level | string | 'debug' | 日志级别 |
| channels.file.days | int | 15 | 日志保留天数 |
| channels.file.json | bool | false | 是否 JSON 格式 |
| channels.syslog.type | string | 'syslog' | Syslog 日志驱动 |
| channels.syslog.ident | string | 'think' | Syslog 标识 |
| channels.syslog.facility | int | 8 | Syslog 设备 |
| channels.syslog.level | string | 'debug' | 日志级别 |
| channels.mail.type | string | 'mail' | 邮件日志驱动 |
| channels.mail.to | string | '' | 邮件接收地址 |
| channels.mail.subject | string | 'Log message' | 邮件主题 |
| channels.mail.level | string | 'error' | 日志级别 |
## 4. 核心配置说明
### 4.1 应用配置 (app.php)
- **app_debug**: 应用调试模式，开发环境设置为 `true`，生产环境设置为 `false`
- **app_trace**: 应用跟踪模式，用于调试，开发环境设置为 `true`，生产环境设置为 `false`
- **app_status**: 应用状态，用于加载不同的配置文件
- **default_return_type**: 默认返回类型，API 应用通常设置为 `json`
- **default_timezone**: 默认时区，中国地区设置为 `Asia/Shanghai`
### 4.2 数据库配置 (database.php)
- **default**: 默认数据库连接，通常使用 `mysql`
- **connections.mysql.hostname**: 数据库主机名，通常为 `127.0.0.1` 或数据库服务器 IP 地址
- **connections.mysql.database**: 数据库名，根据实际情况设置
- **connections.mysql.username**: 数据库用户名，根据实际情况设置
- **connections.mysql.password**: 数据库密码，根据实际情况设置
- **connections.mysql.charset**: 数据库字符集，通常使用 `utf8mb4`
- **connections.mysql.prefix**: 数据库表前缀，根据实际情况设置
### 4.3 缓存配置 (cache.php)
- **default**: 默认缓存驱动，开发环境通常使用 `file`，生产环境通常使用 `redis`
- **stores.redis.host**: Redis 主机名，通常为 `127.0.0.1` 或 Redis 服务器 IP 地址
- **stores.redis.password**: Redis 密码，根据实际情况设置
- **stores.redis.port**: Redis 端口，默认为 `6379`
- **stores.redis.select**: Redis 数据库编号，默认使用 `0`
### 4.4 队列配置 (queue.php)
- **default**: 默认队列驱动，开发环境通常使用 `sync`，生产环境通常使用 `redis` 或 `database`
- **connections.redis.queue**: 默认队列名，根据实际情况设置
- **failed.table**: 失败队列表名，默认为 `failed_jobs`
### 4.5 日志配置 (log.php)
- **default**: 默认日志通道，通常使用 `file`
- **channels.file.path**: 文件日志路径，默认使用 `runtime/log`
- **channels.file.level**: 日志级别，开发环境通常使用 `debug`，生产环境通常使用 `info` 或 `error`
- **channels.file.days**: 日志保留天数，根据实际情况设置
## 5. 配置最佳实践
### 5.1 开发环境配置
- **app_debug**: `true`
- **app_trace**: `true`
- **default_return_type**: `json`
- **database.connections.mysql.hostname**: `127.0.0.1`
- **database.connections.mysql.database**: `crmeb_dev`
- **cache.default**: `file`
- **queue.default**: `sync`
- **log.channels.file.level**: `debug`
### 5.2 测试环境配置
- **app_debug**: `false`
- **app_trace**: `false`
- **default_return_type**: `json`
- **database.connections.mysql.hostname**: `127.0.0.1`
- **database.connections.mysql.database**: `crmeb_test`
- **cache.default**: `redis`
- **queue.default**: `redis`
- **log.channels.file.level**: `info`
### 5.3 生产环境配置
- **app_debug**: `false`
- **app_trace**: `false`
- **default_return_type**: `json`
- **database.connections.mysql.hostname**: `your_db_host`
- **database.connections.mysql.database**: `crmeb_prod`
- **database.connections.mysql.username**: `your_db_user`
- **database.connections.mysql.password**: `your_db_password`
- **cache.default**: `redis`
- **queue.default**: `redis`
- **log.channels.file.level**: `error`
- **log.channels.file.days**: `30`
## 6. 常见配置问题
### 6.1 数据库连接失败
- **问题**: 无法连接到数据库
- **原因**: 数据库配置错误，如主机名、端口、用户名或密码错误
- **解决方案**: 检查数据库配置，确保配置正确
### 6.2 缓存无法使用
- **问题**: 缓存无法正常使用
- **原因**: 缓存配置错误，如 Redis 主机名、端口或密码错误
- **解决方案**: 检查缓存配置，确保配置正确
### 6.3 队列无法正常工作
- **问题**: 队列任务无法执行
- **原因**: 队列配置错误，如 Redis 连接错误或队列驱动配置错误
- **解决方案**: 检查队列配置，确保配置正确
### 6.4 日志无法写入
- **问题**: 日志无法写入到文件
- **原因**: 日志目录没有写权限
- **解决方案**: 为日志目录添加写权限
### 6.5 环境变量不生效
- **问题**: 环境变量配置不生效
- **原因**: 环境变量文件 `.env` 不存在或配置错误
- **解决方案**: 创建 `.env` 文件，确保配置正确
## 7. 参考资源
- [ThinkPHP 6 配置](https://www.kancloud.cn/manual/thinkphp6_0/1037478)
- [环境变量配置](https://www.kancloud.cn/manual/thinkphp6_0/1037479)
- [数据库配置](https://www.kancloud.cn/manual/thinkphp6_0/1037480)
- [缓存配置](https://www.kancloud.cn/manual/thinkphp6_0/1037481)
- [队列配置](https://www.kancloud.cn/manual/thinkphp6_0/1037482)
- [日志配置](https://www.kancloud.cn/manual/thinkphp6_0/1037483)

0
.trae/skills/uniapp说明/SKILL.md → .trae/skills/uniapp/SKILL.md
View File

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

@ -1,288 +0,0 @@
---
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 关联查询
- 使用队列处理耗时操作
- 优化文件和目录结构，提高加载速度

4
crmeb/app/adminapi/controller/Test.php
View File

@ -10,7 +10,9 @@ class Test
{
public function index()
{
json(['code' => 0, 'msg' => '支付成功']);
app('json')->success('支付成功');
}
}