From eb73b84d9f9fe01900bd656a3735a214ae893af4 Mon Sep 17 00:00:00 2001 From: sugar1569 Date: Tue, 27 Jan 2026 09:01:09 +0800 Subject: [PATCH] =?UTF-8?q?feat:=20=E6=B7=BB=E5=8A=A0Git=E6=8F=90=E4=BA=A4?= =?UTF-8?q?=E8=A7=84=E8=8C=83=E6=8A=80=E8=83=BD=E6=96=87=E4=BB=B6=E5=92=8C?= =?UTF-8?q?=E7=9B=B8=E5=85=B3=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit docs: 更新开发文档生成规范和目录结构文档 refactor: 重构管理端前端和uniapp开发说明文档 chore: 删除旧的文档规范和目录结构文件 --- .trae/documents/生成Git提交规范技能文件.md | 40 ++ .trae/skills/SKLL.md | 100 ++++ .../SKILL.md | 10 +- .../{docs规范 => dev-docs-generate}/SKILL.md | 24 +- .trae/skills/git-commit/SKILL.md | 240 ++++++++ .trae/skills/php-api/SKILL.md | 380 ++++++++++++ .trae/skills/php-api/references/api_create.md | 545 ++++++++++++++++++ .trae/skills/php-api/references/api_flow.md | 488 ++++++++++++++++ .trae/skills/php-api/references/code_style.md | 246 ++++++++ .trae/skills/php-api/references/db_design.md | 111 ++++ .trae/skills/php-api/references/deploy.md | 501 ++++++++++++++++ .../php-api/references/directory_structure.md | 275 +++++++++ .trae/skills/php-api/references/error_code.md | 273 +++++++++ .../php-api/references/system_config.md | 380 ++++++++++++ .trae/skills/{uniapp说明 => uniapp}/SKILL.md | 0 .trae/skills/目录结构/SKILL.md | 288 --------- crmeb/app/adminapi/controller/Test.php | 4 +- 17 files changed, 3603 insertions(+), 302 deletions(-) create mode 100644 .trae/documents/生成Git提交规范技能文件.md create mode 100644 .trae/skills/SKLL.md rename .trae/skills/{管理端文档说明 => admin-element}/SKILL.md (97%) rename .trae/skills/{docs规范 => dev-docs-generate}/SKILL.md (87%) create mode 100644 .trae/skills/git-commit/SKILL.md create mode 100644 .trae/skills/php-api/SKILL.md create mode 100644 .trae/skills/php-api/references/api_create.md create mode 100644 .trae/skills/php-api/references/api_flow.md create mode 100644 .trae/skills/php-api/references/code_style.md create mode 100644 .trae/skills/php-api/references/db_design.md create mode 100644 .trae/skills/php-api/references/deploy.md create mode 100644 .trae/skills/php-api/references/directory_structure.md create mode 100644 .trae/skills/php-api/references/error_code.md create mode 100644 .trae/skills/php-api/references/system_config.md rename .trae/skills/{uniapp说明 => uniapp}/SKILL.md (100%) delete mode 100644 .trae/skills/目录结构/SKILL.md diff --git a/.trae/documents/生成Git提交规范技能文件.md b/.trae/documents/生成Git提交规范技能文件.md new file mode 100644 index 000000000..f8c8ca413 --- /dev/null +++ b/.trae/documents/生成Git提交规范技能文件.md @@ -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. 验证文件结构 +确保文件创建在正确的位置，格式符合技能文件的标准规范。 \ No newline at end of file diff --git a/.trae/skills/SKLL.md b/.trae/skills/SKLL.md new file mode 100644 index 000000000..d053641e9 --- /dev/null +++ b/.trae/skills/SKLL.md @@ -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项目开发的重要辅助工具，通过规范的技能文档和触发机制，可以帮助开发人员更快地了解项目结构、开发规范和最佳实践，提高开发效率和代码质量。 + +建议定期维护和更新技能文档，确保其与项目发展保持同步，为开发人员提供持续的支持和指导。 \ No newline at end of file diff --git a/.trae/skills/管理端文档说明/SKILL.md b/.trae/skills/admin-element/SKILL.md similarity index 97% rename from .trae/skills/管理端文档说明/SKILL.md rename to .trae/skills/admin-element/SKILL.md index 2afc60754..620bc23e6 100644 --- a/.trae/skills/管理端文档说明/SKILL.md +++ b/.trae/skills/admin-element/SKILL.md @@ -447,4 +447,12 @@ src/ - **项目管理**: 使用项目管理工具 - **代码托管**: 使用代码托管平台 - **CI/CD**: 持续集成/持续部署 -- **文档协作**: 团队文档协作工具 \ No newline at end of file +- **文档协作**: 团队文档协作工具 + +### 14 其他资源 +- 开发流程文档 /references/development_flow.md +- 代码规范文档 /references/code_style.md +- 项目部署文档 /references/deploy.md +- 目录结构文档 /references/directory_structure.md +- 接口请求流程文档 /references/api_flow.md +- 系统配置文档 /references/system_config.md diff --git a/.trae/skills/docs规范/SKILL.md b/.trae/skills/dev-docs-generate/SKILL.md similarity index 87% rename from .trae/skills/docs规范/SKILL.md rename to .trae/skills/dev-docs-generate/SKILL.md index 23ab3b2cd..1d936ec8c 100644 --- a/.trae/skills/docs规范/SKILL.md +++ b/.trae/skills/dev-docs-generate/SKILL.md @@ -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. 内容要求 diff --git a/.trae/skills/git-commit/SKILL.md b/.trae/skills/git-commit/SKILL.md new file mode 100644 index 000000000..4e93ad1cd --- /dev/null +++ b/.trae/skills/git-commit/SKILL.md @@ -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 **: 添加文件到暂存区 +- **git commit -m "[前缀] 描述"**: 提交更改 +- **git push**: 推送更改到远程仓库 +- **git pull**: 从远程仓库拉取更改 + +### 5.2 分支命令 +- **git branch**: 查看分支 +- **git checkout **: 切换分支 +- **git checkout -b **: 创建并切换分支 +- **git merge **: 合并分支 + +### 5.3 历史命令 +- **git log**: 查看提交历史 +- **git show **: 查看提交详情 +- **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使用规范 +- 代码审查流程指南 \ No newline at end of file diff --git a/.trae/skills/php-api/SKILL.md b/.trae/skills/php-api/SKILL.md new file mode 100644 index 000000000..321fa648d --- /dev/null +++ b/.trae/skills/php-api/SKILL.md @@ -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 + success('获取用户列表成功', $data); + } + } + ``` + +### 2.2 服务模块 +- **功能**: 实现核心业务逻辑，封装业务规则 +- **特点**: 业务逻辑集中，可复用性高，易于测试 +- **关键文件**: 各业务服务类 +- **示例代码**: + ```php + where('id', $id)->find(); + } + } + ``` + +### 2.4 模型模块 +- **功能**: 定义数据模型，处理数据关系 +- **特点**: ORM 映射，自动表结构，关联查询 +- **关键文件**: `BaseModel.php` (模型基类) +- **示例代码**: + ```php + 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/) diff --git a/.trae/skills/php-api/references/api_flow.md b/.trae/skills/php-api/references/api_flow.md new file mode 100644 index 000000000..6a3e17b25 --- /dev/null +++ b/.trae/skills/php-api/references/api_flow.md @@ -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 格式 | test123456 | + +### 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/) \ No newline at end of file diff --git a/.trae/skills/php-api/references/code_style.md b/.trae/skills/php-api/references/code_style.md new file mode 100644 index 000000000..9471b3789 --- /dev/null +++ b/.trae/skills/php-api/references/code_style.md @@ -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 命名风格，如 `` +- **属性名**：使用 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 规范 + +- **标签名**：使用小写字母，如 `
` +- **属性名**：使用小写字母，如 `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) \ No newline at end of file diff --git a/.trae/skills/php-api/references/db_design.md b/.trae/skills/php-api/references/db_design.md new file mode 100644 index 000000000..bb34c0c6b --- /dev/null +++ b/.trae/skills/php-api/references/db_design.md @@ -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 \ No newline at end of file diff --git a/.trae/skills/php-api/references/deploy.md b/.trae/skills/php-api/references/deploy.md new file mode 100644 index 000000000..ad02463e7 --- /dev/null +++ b/.trae/skills/php-api/references/deploy.md @@ -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) \ No newline at end of file diff --git a/.trae/skills/php-api/references/directory_structure.md b/.trae/skills/php-api/references/directory_structure.md new file mode 100644 index 000000000..03f3924e7 --- /dev/null +++ b/.trae/skills/php-api/references/directory_structure.md @@ -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/模块化设计) \ No newline at end of file diff --git a/.trae/skills/php-api/references/error_code.md b/.trae/skills/php-api/references/error_code.md new file mode 100644 index 000000000..1d9fa89f9 --- /dev/null +++ b/.trae/skills/php-api/references/error_code.md @@ -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) \ No newline at end of file diff --git a/.trae/skills/php-api/references/system_config.md b/.trae/skills/php-api/references/system_config.md new file mode 100644 index 000000000..30a410b22 --- /dev/null +++ b/.trae/skills/php-api/references/system_config.md @@ -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) \ No newline at end of file diff --git a/.trae/skills/uniapp说明/SKILL.md b/.trae/skills/uniapp/SKILL.md similarity index 100% rename from .trae/skills/uniapp说明/SKILL.md rename to .trae/skills/uniapp/SKILL.md diff --git a/.trae/skills/目录结构/SKILL.md b/.trae/skills/目录结构/SKILL.md deleted file mode 100644 index 236a411eb..000000000 --- a/.trae/skills/目录结构/SKILL.md +++ /dev/null @@ -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 关联查询 -- 使用队列处理耗时操作 -- 优化文件和目录结构，提高加载速度 \ No newline at end of file diff --git a/crmeb/app/adminapi/controller/Test.php b/crmeb/app/adminapi/controller/Test.php index 9d0b051e4..70b91e8f8 100644 --- a/crmeb/app/adminapi/controller/Test.php +++ b/crmeb/app/adminapi/controller/Test.php @@ -10,7 +10,9 @@ class Test { public function index() { - + json(['code' => 0, 'msg' => '支付成功']); + app('json')->success('支付成功'); } } +