`、`

` ### 3.6 分号 - **语句结束**: 每个语句结束都应该加分号 - **示例**: `const name = '张三';`、`function() {};` ### 3.7 空行 - **代码块之间**: 代码块之间应该有空行 - **示例**: ```javascript function first() { // 代码 } function second() { // 代码 } ``` - **逻辑块之间**: 逻辑块之间应该有空行 - **示例**: ```javascript if (condition) { // 代码 } while (loop) { // 代码 } ``` ## 4. 文件结构 ### 4.1 组件文件结构 ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ### 4.2 页面文件结构 ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ### 4.3 JS 文件结构 ```javascript // 导入依赖 import axios from 'axios'; import { Message } from 'element-ui'; // 常量定义 const BASE_URL = process.env.VUE_APP_API_BASE_URL; const TIMEOUT = 10000; // 创建 axios 实例 const service = axios.create({ baseURL: BASE_URL, timeout: TIMEOUT }); // 请求拦截器 service.interceptors.request.use( config => { // 添加 token const token = localStorage.getItem('token'); if (token) { config.headers['Authorization'] = `Bearer ${token}`; } return config; }, error => { console.error('请求错误:', error); return Promise.reject(error); } ); // 响应拦截器 service.interceptors.response.use( response => { const { data } = response; if (data.code !== 200) { Message.error(data.message || '请求失败'); return Promise.reject(data); } return data; }, error => { console.error('响应错误:', error); Message.error('网络错误，请稍后重试'); return Promise.reject(error); } ); // 工具函数 function formatDate(date) { const d = new Date(date); return d.toLocaleString(); } function deepClone(obj) { return JSON.parse(JSON.stringify(obj)); } // 导出 export { service, formatDate, deepClone }; // 默认导出 export default service; ``` ## 5. 组件开发规范 ### 5.1 组件设计 - **单一职责**: 每个组件只负责一个功能 - **可复用性**: 设计通用的、可复用的组件 - **可配置性**: 通过 props 提供配置选项 - **事件通信**: 通过事件与父组件通信 - **插槽支持**: 提供插槽，增强组件灵活性 ### 5.2 组件使用 - **组件导入**: 使用 import 导入组件 - **示例**: `import Button from '@/components/Button.vue'` - **组件注册**: 在 components 中注册组件 - **示例**: ```javascript components: { Button } ``` - **组件使用**: 使用组件标签 - **示例**: `` - **组件传值**: 通过 props 传递数据 - **示例**: `` - **事件监听**: 监听组件事件 - **示例**: `` ### 5.3 组件通信 - **props 向下传递**: 父组件通过 props 向子组件传递数据 - **events 向上传递**: 子组件通过 events 向父组件传递事件 - **refs 引用**: 通过 refs 引用子组件实例 - **provide/inject**: 祖先组件向后代组件传递数据 - **Vuex 全局状态**: 使用 Vuex 管理全局状态 - **EventBus**: 组件间事件总线 ### 5.4 组件生命周期 - **created**: 初始化数据，发送请求 - **mounted**: 操作 DOM，初始化第三方库 - **beforeUpdate**: 更新前的准备工作 - **updated**: 数据更新后的操作 - **beforeDestroy**: 清理定时器，取消订阅 - **destroyed**: 组件销毁后的清理工作 ### 5.5 组件命名规范 - **组件名**: PascalCase 命名风格 - **组件文件名**: 与组件名一致 - **组件目录**: 按功能分类存放 - **组件前缀**: 通用组件使用统一前缀 ## 6. 页面开发规范 ### 6.1 页面结构 - **模板结构**: 清晰明了，层次分明 - **脚本结构**: 按照 Vue 规范组织代码 - **样式结构**: 模块化，可维护 - **布局规范**: 遵循统一的布局规范 ### 6.2 数据管理 - **本地数据**: 使用 data 管理组件内部数据 - **计算数据**: 使用 computed 计算衍生数据 - **监听数据**: 使用 watch 监听数据变化 - **全局数据**: 使用 Vuex 管理全局数据 ### 6.3 路由管理 - **路由配置**: 在 router 目录中配置路由 - **路由跳转**: 使用 router.push、router.replace 等方法 - **路由参数**: 通过 $route.params 获取路由参数 - **路由守卫**: 使用全局/局部路由守卫 ### 6.4 API 调用 - **API 封装**: 统一封装 API 调用 - **异步处理**: 使用 async/await 处理异步请求 - **错误处理**: 使用 try/catch 捕获错误 - **加载状态**: 显示加载状态，提升用户体验 ### 6.5 用户体验 - **响应式设计**: 适配不同屏幕尺寸 - **加载状态**: 显示加载中提示 - **错误提示**: 显示错误信息 - **成功提示**: 显示操作成功提示 - **表单验证**: 实时表单验证 - **防抖节流**: 优化频繁触发的事件 ## 7. 性能优化 ### 7.1 代码优化 - **减少冗余代码**: 避免重复的代码 - **使用计算属性**: 对于复杂的计算，使用 computed - **使用 v-if 和 v-show 合理**: 根据场景选择合适的指令 - **使用 key**: 在 v-for 中使用 key，提高渲染性能 - **避免频繁更新**: 使用防抖和节流 ### 7.2 网络优化 - **合理使用缓存**: 缓存不经常变化的数据 - **减少请求次数**: 合并请求，批量操作 - **使用 CDN**: 静态资源使用 CDN - **压缩传输**: 使用 gzip 压缩传输数据 ### 7.3 构建优化 - **Tree Shaking**: 移除未使用的代码 - **代码分割**: 按路由分割代码 - **懒加载**: 路由懒加载，组件懒加载 - **预加载**: 预加载关键资源 ### 7.4 其他优化 - **减少 DOM 节点**: 简化 DOM 结构 - **优化图片**: 使用合适的图片格式和大小 - **使用虚拟列表**: 对于长列表，使用虚拟列表 - **避免内存泄漏**: 及时清理定时器、事件监听器等 ## 8. 常见问题 ### 8.1 代码风格问题 - **问题**: 代码风格不一致 - **解决方案**: 使用 ESLint 和 Prettier 统一代码风格 ### 8.2 性能问题 - **问题**: 页面加载慢，卡顿 - **解决方案**: 优化代码，减少 DOM 操作，使用虚拟列表等 ### 8.3 兼容性问题 - **问题**: 在不同浏览器上表现不一致 - **解决方案**: 遵循 Web 标准，使用 polyfill ### 8.4 维护性问题 - **问题**: 代码难以维护 - **解决方案**: 模块化开发，添加注释，遵循代码规范 ### 8.5 命名冲突问题 - **问题**: 命名冲突 - **解决方案**: 使用命名空间，避免全局变量 ## 9. 参考资源 - [Vue 官方风格指南](https://v2.vuejs.org/v2/style-guide/) - [Element UI 官方文档](https://element.eleme.io/#/zh-CN) - [ESLint 官方文档](https://eslint.org/docs/user-guide/) - [Prettier 官方文档](https://prettier.io/docs/en/) - [JavaScript 代码规范](https://github.com/airbnb/javascript) - [CSS 代码规范](https://github.com/airbnb/css) ## 10. 总结本文档描述了 CRMEB 项目中管理端前端的代码规范，包括命名规范、代码风格、文件结构、组件开发等方面的规范。遵循本文档的规范，可以提高代码的可读性、可维护性和可扩展性，确保项目的质量和稳定性。代码规范是团队协作的基础，建议开发团队成员严格遵循本文档的规范，共同维护一个高质量的代码库。 --- ### .Codebuddy/Skills/Admin Element/References/Deploy (.codebuddy/skills/admin-element/references/deploy.md) # 管理端前端部署文档 ## 1. 概述本文档描述了 CRMEB 项目中管理端前端的部署流程，包括构建、部署、配置等环节，旨在规范前端部署流程，确保部署过程的顺利进行和系统的稳定运行。 ## 2. 部署环境 ### 2.1 服务器要求 - **操作系统**: Linux (Ubuntu 18.04+、CentOS 7+) - **Web 服务器**: Nginx 1.14+ 或 Apache 2.4+ - **Node.js**: v12.0.0+ (仅构建时需要) - **npm/yarn**: v6.0.0+ (仅构建时需要) - **内存**: 至少 2GB RAM - **CPU**: 至少 2 核 CPU - **磁盘空间**: 至少 20GB 可用空间 ### 2.2 环境准备 - **Web 服务器配置**: 配置虚拟主机，指向前端构建产物目录 - **SSL 证书**: 配置 HTTPS，使用 SSL 证书 - **防火墙**: 开放 80/443 端口 - **域名**: 配置域名解析，指向服务器 IP ## 3. 构建流程 ### 3.1 开发环境构建 - **命令**: `npm run dev` - **用途**: 本地开发，启动开发服务器 - **访问地址**: `http://localhost:8080` ### 3.2 测试环境构建 - **命令**: `npm run build:test` - **用途**: 测试环境部署 - **构建产物**: `dist/` 目录 ### 3.3 生产环境构建 - **命令**: `npm run build:prod` - **用途**: 生产环境部署 - **构建产物**: `dist/` 目录 ### 3.4 构建优化 - **代码压缩**: 压缩 JS/CSS/HTML 文件 - **资源压缩**: 压缩图片等静态资源 - **Tree Shaking**: 移除未使用的代码 - **代码分割**: 按路由分割代码 - **预加载**: 预加载关键资源 ## 4. 部署方式 ### 4.1 静态部署 #### 4.1.1 Nginx 配置 ```nginx server { listen 80; server_name admin.example.com; return 301 https://$server_name$request_uri; } server { listen 443 ssl http2; server_name admin.example.com; # SSL 配置 ssl_certificate /path/to/ssl/cert.pem; ssl_certificate_key /path/to/ssl/key.pem; ssl_protocols TLSv1.2 TLSv1.3; ssl_ciphers ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384; ssl_prefer_server_ciphers on; # 静态文件配置 root /path/to/admin/dist; index index.html; # 路由重写，解决单页应用刷新 404 问题 location / { try_files $uri $uri/ /index.html; } # 静态资源缓存 location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ { expires 30d; add_header Cache-Control "public, max-age=2592000"; } # 日志配置 access_log /var/log/nginx/admin_access.log; error_log /var/log/nginx/admin_error.log; } ``` #### 4.1.2 Apache 配置 ```apache ServerName admin.example.com Redirect permanent / https://admin.example.com/ ServerName admin.example.com # SSL 配置 SSLEngine on SSLCertificateFile /path/to/ssl/cert.pem SSLCertificateKeyFile /path/to/ssl/key.pem # 静态文件配置 DocumentRoot /path/to/admin/dist AllowOverride All Require all granted # 路由重写，解决单页应用刷新 404 问题 RewriteEngine On RewriteBase / RewriteRule ^index\.html$ - [L] RewriteCond %{REQUEST_FILENAME} !-f RewriteCond %{REQUEST_FILENAME} !-d RewriteRule . /index.html [L] # 日志配置 ErrorLog ${APACHE_LOG_DIR}/admin_error.log CustomLog ${APACHE_LOG_DIR}/admin_access.log combined ``` ### 4.2 容器部署 #### 4.2.1 Dockerfile ```dockerfile # 基础镜像 FROM node:12-alpine as build # 设置工作目录 WORKDIR /app # 复制依赖文件 COPY package*.json ./ # 安装依赖 RUN npm install # 复制源代码 COPY . . # 构建生产版本 RUN npm run build:prod # 生产镜像 FROM nginx:1.19-alpine # 复制构建产物 COPY --from=build /app/dist /usr/share/nginx/html # 复制 Nginx 配置 COPY nginx.conf /etc/nginx/conf.d/default.conf # 暴露端口 EXPOSE 80 # 启动 Nginx CMD ["nginx", "-g", "daemon off;"] ``` #### 4.2.2 Docker Compose ```yaml version: '3' services: admin: build: . ports: - "80:80" restart: always volumes: - ./ssl:/etc/nginx/ssl environment: - TZ=Asia/Shanghai ``` #### 4.2.3 部署命令 ```bash # 构建镜像 docker build -t crmeb-admin . # 运行容器 docker run -d --name crmeb-admin -p 80:80 crmeb-admin # 使用 Docker Compose docker-compose up -d ``` ### 4.3 CDN 部署 #### 4.3.1 配置 CDN - **源站设置**: 指向静态文件服务器 - **缓存策略**: 配置静态资源缓存时间 - **HTTPS**: 开启 HTTPS - **HTTP/2**: 开启 HTTP/2 #### 4.3.2 部署流程 1. 构建前端项目 2. 上传构建产物到 CDN 3. 配置 CDN 缓存策略 4. 验证部署结果 ## 5. 配置管理 ### 5.1 环境变量配置 - **开发环境**: `.env.development` - **测试环境**: `.env.test` - **生产环境**: `.env.production` ### 5.2 配置示例 ```env # API 基础地址 VUE_APP_API_BASE_URL=https://api.example.com # 静态资源 CDN 地址 VUE_APP_CDN_BASE_URL=https://cdn.example.com # 应用名称 VUE_APP_TITLE=CRMEB 管理后台 # 构建环境 NODE_ENV=production # 构建版本 VUE_APP_VERSION=1.0.0 ``` ### 5.3 运行时配置 - **API 地址**: 可通过环境变量或配置文件修改 - **主题配置**: 可通过配置文件修改 - **权限配置**: 可通过后端 API 动态获取 ## 6. 部署流程 ### 6.1 手动部署 1. **拉取代码**: `git pull origin master` 2. **安装依赖**: `npm install` 3. **构建项目**: `npm run build:prod` 4. **部署文件**: 将 `dist/` 目录复制到服务器 5. **配置 Web 服务器**: 配置虚拟主机 6. **重启服务**: 重启 Web 服务器 7. **验证部署**: 访问管理端地址 ### 6.2 自动化部署 #### 6.2.1 CI/CD 配置 - **Jenkins**: 配置 Jenkins 任务，实现自动构建和部署 - **GitLab CI**: 配置 `.gitlab-ci.yml`，实现自动构建和部署 - **GitHub Actions**: 配置 `.github/workflows/deploy.yml`，实现自动构建和部署 #### 6.2.2 GitHub Actions 示例 ```yaml name: Deploy Admin Frontend on: push: branches: - master jobs: deploy: runs-on: ubuntu-latest steps: - name: Checkout code uses: actions/checkout@v2 - name: Setup Node.js uses: actions/setup-node@v2 with: node-version: '12' - name: Install dependencies run: npm install - name: Build project run: npm run build:prod - name: Deploy to server uses: easingthemes/ssh-deploy@v2.1.5 env: SSH_PRIVATE_KEY: ${{ secrets.SSH_PRIVATE_KEY }} ARGS: '-rltgoDzvO --delete' SOURCE: 'dist/' REMOTE_HOST: ${{ secrets.REMOTE_HOST }} REMOTE_USER: ${{ secrets.REMOTE_USER }} REMOTE_PORT: ${{ secrets.REMOTE_PORT }} TARGET: ${{ secrets.REMOTE_TARGET }} - name: Restart Nginx uses: appleboy/ssh-action@master with: host: ${{ secrets.REMOTE_HOST }} username: ${{ secrets.REMOTE_USER }} key: ${{ secrets.SSH_PRIVATE_KEY }} port: ${{ secrets.REMOTE_PORT }} script: sudo systemctl restart nginx ``` ## 7. 监控与维护 ### 7.1 监控 - **访问日志**: 分析 Web 服务器访问日志 - **错误日志**: 监控 Web 服务器错误日志 - **性能监控**: 监控页面加载速度、响应时间 - **可用性监控**: 监控服务可用性，设置告警 ### 7.2 维护 - **定期更新**: 定期更新前端代码，修复漏洞 - **缓存清理**: 定期清理 CDN 缓存 - **日志清理**: 定期清理日志文件 - **备份**: 定期备份构建产物和配置文件 ### 7.3 常见问题 #### 7.3.1 404 问题 - **问题**: 刷新页面出现 404 错误 - **解决方案**: 配置 Web 服务器，将所有请求重定向到 index.html #### 7.3.2 静态资源加载失败 - **问题**: 静态资源（JS/CSS/图片）加载失败 - **解决方案**: 检查静态资源路径，确保 CDN 配置正确 #### 7.3.3 API 调用失败 - **问题**: 前端无法调用后端 API - **解决方案**: 检查 API 地址配置，确保后端服务正常运行 #### 7.3.4 性能问题 - **问题**: 页面加载慢，卡顿 - **解决方案**: 优化前端代码，使用 CDN，启用 HTTP/2 ## 8. 回滚策略 ### 8.1 版本管理 - **版本号**: 遵循语义化版本规范 - **发布记录**: 记录每次发布的版本和变更内容 - **备份**: 备份每次发布的构建产物 ### 8.2 回滚流程 1. **停止服务**: 停止当前版本的服务 2. **恢复备份**: 恢复到上一个稳定版本 3. **重启服务**: 启动恢复后的服务 4. **验证回滚**: 验证服务是否正常运行 ### 8.3 回滚方案 - **手动回滚**: 手动复制备份文件到部署目录 - **自动化回滚**: 通过 CI/CD 工具实现自动回滚 - **容器回滚**: 通过 Docker 镜像版本回滚 ## 9. 安全部署 ### 9.1 HTTPS 配置 - **SSL 证书**: 使用正规 CA 签发的 SSL 证书 - **证书续期**: 定期续期 SSL 证书 - **HTTP 重定向**: 将 HTTP 请求重定向到 HTTPS ### 9.2 安全头部 - **Content-Security-Policy**: 配置内容安全策略 - **X-Content-Type-Options**: 防止 MIME 类型嗅探 - **X-Frame-Options**: 防止点击劫持 - **X-XSS-Protection**: 启用 XSS 过滤 ### 9.3 访问控制 - **IP 白名单**: 限制管理端访问 IP - **登录验证**: 强制登录验证 - **权限控制**: 基于角色的权限控制 - **会话管理**: 安全的会话管理 ### 9.4 漏洞防护 - **依赖扫描**: 定期扫描依赖包漏洞 - **代码审计**: 定期进行代码安全审计 - **渗透测试**: 定期进行渗透测试 ## 10. 最佳实践 ### 10.1 构建优化 - **使用缓存**: 缓存依赖包和构建产物 - **并行构建**: 使用多线程并行构建 - **增量构建**: 只构建变更的文件 - **构建日志**: 保存构建日志，便于排查问题 ### 10.2 部署优化 - **灰度发布**: 采用灰度发布策略 - **蓝绿部署**: 采用蓝绿部署策略 - **滚动部署**: 采用滚动部署策略 - **金丝雀发布**: 采用金丝雀发布策略 ### 10.3 监控优化 - **实时监控**: 实时监控系统运行状态 - **告警机制**: 设置合理的告警阈值 - **日志聚合**: 聚合多服务器日志 - **性能分析**: 定期分析系统性能 ### 10.4 安全优化 - **最小权限**: 遵循最小权限原则 - **定期更新**: 定期更新依赖和系统 - **安全扫描**: 定期进行安全扫描 - **应急响应**: 建立安全应急响应机制 ## 11. 总结本文档描述了 CRMEB 项目中管理端前端的部署流程，包括构建、部署、配置等环节，以及相关的最佳实践和常见问题解决方案。遵循本文档的部署流程和规范，可以确保前端部署的顺利进行和系统的稳定运行，同时提高部署效率和系统安全性。随着项目的发展和技术的演进，部署流程也需要不断优化和调整，以适应新的业务需求和技术挑战。 --- ### .Codebuddy/Skills/Admin Element/References/Development Flow (.codebuddy/skills/admin-element/references/development_flow.md) # 管理端前端开发流程文档 ## 1. 概述本文档描述了 CRMEB 项目中管理端前端的开发流程，包括需求分析、设计、编码、测试、部署等环节，旨在规范前端开发流程，提高开发效率和代码质量。 ## 2. 开发流程 ### 2.1 需求分析 #### 2.1.1 需求获取 - **需求来源**: 产品经理、业务方、后端开发、测试人员 - **需求形式**: PRD 文档、需求评审会议、邮件、即时通讯工具 - **需求内容**: 功能需求、非功能需求、UI/UX 需求 #### 2.1.2 需求评审 - **评审人员**: 前端开发、后端开发、产品经理、测试人员 - **评审内容**: 需求可行性、技术实现方案、时间评估、风险评估 - **评审输出**: 评审纪要、任务分解、时间计划 #### 2.1.3 需求确认 - **确认内容**: 需求细节、技术方案、交付标准 - **确认形式**: 需求确认邮件、需求确认会议 - **确认输出**: 需求确认文档 ### 2.2 设计阶段 #### 2.2.1 UI 设计 - **设计工具**: Figma、Sketch、Adobe XD - **设计内容**: 页面布局、组件样式、交互设计、色彩方案 - **设计输出**: UI 设计稿、设计规范文档 #### 2.2.2 技术设计 - **设计内容**: 技术选型、架构设计、目录结构、组件设计、API 设计 - **设计输出**: 技术设计文档、架构图、组件设计图 #### 2.2.3 原型设计 - **原型工具**: Axure、Figma、Sketch - **原型内容**: 页面原型、交互原型、流程原型 - **原型输出**: 交互式原型、流程图 ### 2.3 编码实现 #### 2.3.1 环境搭建 - **开发环境**: Node.js、npm/yarn、VS Code、Git - **依赖安装**: `npm install` 或 `yarn install` - **开发工具**: Vue DevTools、Chrome DevTools #### 2.3.2 代码开发 - **开发顺序**: 基础组件 → 页面组件 → 业务逻辑 → 测试 - **开发规范**: 遵循代码规范、命名规范、文档规范 - **代码质量**: 代码可读性、可维护性、可扩展性 #### 2.3.3 代码审查 - **审查人员**: 前端团队成员 - **审查内容**: 代码质量、功能实现、性能优化、安全防护 - **审查工具**: GitLab/GitHub Code Review、ESLint、Prettier ### 2.4 测试验证 #### 2.4.1 单元测试 - **测试工具**: Jest、Vue Test Utils - **测试内容**: 组件测试、工具函数测试、状态管理测试 - **测试覆盖率**: 关键功能测试覆盖率 ≥ 80% #### 2.4.2 功能测试 - **测试人员**: 前端开发、测试人员 - **测试内容**: 功能实现、交互体验、页面布局、响应式设计 - **测试工具**: 浏览器、测试管理工具 #### 2.4.3 性能测试 - **测试工具**: Chrome DevTools、Lighthouse、WebPageTest - **测试内容**: 首屏加载速度、页面渲染性能、内存使用、网络请求 - **测试指标**: FCP、LCP、TTI、CLS、FID #### 2.4.4 兼容性测试 - **测试浏览器**: Chrome、Firefox、Safari、Edge - **测试分辨率**: 1024x768、1366x768、1920x1080 - **测试内容**: 页面显示、功能实现、交互体验 ### 2.5 部署上线 #### 2.5.1 构建打包 - **构建命令**: `npm run build:prod` - **构建产物**: 静态资源文件 - **构建优化**: 代码压缩、资源压缩、Tree Shaking #### 2.5.2 部署配置 - **部署环境**: 测试环境、预发布环境、生产环境 - **部署工具**: Nginx、Apache、CDN - **配置内容**: 服务器配置、域名配置、HTTPS 配置 #### 2.5.3 上线发布 - **发布流程**: 测试环境 → 预发布环境 → 生产环境 - **发布时间**: 非业务高峰期 - **发布监控**: 实时监控系统运行状态 #### 2.5.4 上线后验证 - **验证内容**: 功能验证、性能验证、兼容性验证 - **验证人员**: 前端开发、测试人员、产品经理 - **验证输出**: 上线验证报告 ## 3. 开发规范 ### 3.1 代码规范 - **ESLint 规则**: 遵循 Vue 官方推荐的 ESLint 规则 - **Prettier 配置**: 统一代码格式化规则 - **代码缩进**: 4 空格缩进 - **命名规范**: 组件名 PascalCase，变量/方法名 camelCase，常量全大写 ### 3.2 提交规范 - **提交信息格式**: `[类型] 描述` - **类型**: feat（新功能）、fix（修复）、docs（文档）、style（样式）、refactor（重构）、test（测试）、chore（构建/依赖） - **提交频率**: 小步提交，每个功能或修复一个提交 - **提交内容**: 只提交相关代码，不提交无关文件 ### 3.3 分支规范 - **主分支**: master（生产环境）、develop（开发环境） - **功能分支**: feature/功能名称 - **修复分支**: fix/修复内容 - **发布分支**: release/版本号 - **分支管理**: 定期清理无用分支 ### 3.4 文档规范 - **README.md**: 项目说明、安装说明、开发说明 - **组件文档**: 组件使用说明、Props、Events、Slots - **API 文档**: API 接口说明、请求参数、响应格式 - **开发文档**: 开发流程、编码规范、部署流程 ## 4. 开发工具 ### 4.1 开发环境 - **Node.js**: v12.0.0+ - **npm**: v6.0.0+ 或 **yarn**: v1.22.0+ - **VS Code**: 最新版本 - **Git**: 最新版本 ### 4.2 编辑器插件 - **Vetur**: Vue 开发插件 - **ESLint**: 代码检查插件 - **Prettier**: 代码格式化插件 - **GitLens**: Git 增强插件 - **Debugger for Chrome**: 浏览器调试插件 - **Auto Close Tag**: 自动闭合标签 - **Auto Rename Tag**: 自动重命名标签 ### 4.3 开发工具 - **Vue DevTools**: Vue 开发调试工具 - **Chrome DevTools**: 浏览器调试工具 - **Postman**: API 测试工具 - **Charles**: 网络调试工具 - **Figma/Sketch**: UI 设计工具 - **Zeplin**: 设计协作工具 ### 4.4 构建工具 - **Webpack**: 模块打包工具 - **Babel**: JavaScript 编译器 - **Sass/Less**: CSS 预处理器 - **ESLint**: 代码检查工具 - **Prettier**: 代码格式化工具 ## 5. 常见问题及解决方案 ### 5.1 需求变更 - **问题**: 开发过程中需求发生变更 - **解决方案**: 1. 记录需求变更内容 2. 评估变更影响范围 3. 与产品经理确认变更可行性 4. 调整开发计划和时间评估 5. 通知相关团队成员 ### 5.2 技术难题 - **问题**: 遇到技术难题无法解决 - **解决方案**: 1. 查阅相关文档和资料 2. 寻求团队成员帮助 3. 咨询外部专家 4. 尝试替代方案 5. 记录解决方案，形成知识库 ### 5.3 时间紧张 - **问题**: 开发时间紧张，任务无法按时完成 - **解决方案**: 1. 评估任务优先级 2. 与产品经理沟通，调整需求优先级 3. 寻求团队成员协助 4. 优化开发流程，提高开发效率 5. 加班完成（作为最后手段） ### 5.4 代码冲突 - **问题**: Git 代码冲突 - **解决方案**: 1. 拉取最新代码 2. 手动解决冲突 3. 测试冲突解决后的代码 4. 提交解决冲突后的代码 5. 通知相关团队成员 ### 5.5 线上问题 - **问题**: 线上出现问题 - **解决方案**: 1. 快速定位问题原因 2. 制定解决方案 3. 紧急修复并部署 4. 验证修复效果 5. 分析问题原因，避免类似问题再次发生 ## 6. 最佳实践 ### 6.1 开发前准备 - **需求确认**: 确保需求理解正确 - **技术方案**: 制定详细的技术实现方案 - **环境搭建**: 确保开发环境配置正确 - **依赖安装**: 安装必要的依赖包 ### 6.2 编码实现 - **组件化开发**: 封装可复用组件 - **模块化开发**: 按功能模块组织代码 - **代码复用**: 提取公共逻辑，避免重复代码 - **性能优化**: 考虑代码性能，避免性能瓶颈 - **安全性**: 考虑代码安全性，避免安全漏洞 ### 6.3 测试验证 - **单元测试**: 编写关键功能的单元测试 - **功能测试**: 全面测试功能实现 - **性能测试**: 测试页面性能 - **兼容性测试**: 测试不同浏览器兼容性 - **用户体验测试**: 测试页面交互体验 ### 6.4 部署上线 - **构建优化**: 优化构建产物 - **部署策略**: 采用灰度发布策略 - **监控告警**: 配置系统监控和告警 - **回滚方案**: 准备系统回滚方案 - **上线验证**: 上线后及时验证系统状态 ### 6.5 维护迭代 - **问题跟踪**: 及时跟踪和解决线上问题 - **代码维护**: 定期维护和优化代码 - **文档更新**: 及时更新相关文档 - **技术债务**: 定期清理技术债务 - **知识共享**: 分享开发经验和解决方案 ## 7. 团队协作 ### 7.1 协作模式 - **敏捷开发**: 采用 Scrum 或 Kanban 敏捷开发模式 - **每日站会**: 每日 15 分钟站会，同步开发进度 - **迭代周期**: 2-4 周一个迭代周期 - **迭代回顾**: 迭代结束后进行回顾，总结经验教训 ### 7.2 沟通工具 - **即时通讯**: 企业微信、钉钉、Slack - **项目管理**: Jira、Trello、GitHub Issues - **代码托管**: GitLab、GitHub、Gitee - **文档协作**: 语雀、Confluence、Google Docs ### 7.3 知识共享 - **技术分享**: 定期组织技术分享会议 - **代码审查**: 相互代码审查，分享编码经验 - **问题讨论**: 定期组织问题讨论会议 - **知识库**: 建立团队知识库，积累技术经验 ## 8. 总结本文档描述了 CRMEB 项目中管理端前端的开发流程，包括需求分析、设计、编码、测试、部署等环节，以及相关的开发规范和最佳实践。遵循本文档的开发流程和规范，可以提高前端开发效率和代码质量，减少开发过程中的问题和风险，确保项目的顺利进行。同时，开发流程也需要根据项目的实际情况进行调整和优化，以适应不同项目的需求和特点。 --- ### .Codebuddy/Skills/Admin Element/References/Directory Structure (.codebuddy/skills/admin-element/references/directory_structure.md) # Admin-Element 目录结构文档 ## 1 项目根目录结构 ``` template/ # 前端项目目录 ├── admin-element/ # 管理端前端项目 │ ├── public/ # 静态资源目录 │ │ ├── favicon.ico # 网站图标 │ │ ├── index.html # 入口HTML文件 │ │ └── static/ # 静态资源文件 │ ├── src/ # 源代码目录 │ │ ├── api/ # API接口定义 │ │ ├── assets/ # 静态资源 │ │ ├── components/ # 通用组件 │ │ ├── config/ # 配置文件 │ │ ├── directive/ # 自定义指令 │ │ ├── filters/ # 过滤器 │ │ ├── layout/ # 布局组件 │ │ ├── router/ # 路由配置 │ │ ├── store/ # 状态管理 │ │ ├── styles/ # 样式文件 │ │ ├── utils/ # 工具函数 │ │ ├── views/ # 页面组件 │ │ ├── App.vue # 根组件 │ │ └── main.js # 入口文件 │ ├── tests/ # 测试文件 │ ├── .env.* # 环境变量配置 │ ├── babel.config.js # Babel配置 │ ├── package.json # 项目依赖 │ ├── vue.config.js # Vue配置 │ └── README.md # 项目说明 ``` ## 2 主要目录说明 ### 2.1 public/ 目录 - **favicon.ico**: 网站图标文件 - **index.html**: 应用入口HTML文件，Vue应用将挂载到这个文件中 - **static/**: 静态资源目录，存放不需要经过webpack处理的静态文件 ### 2.2 src/ 目录 #### 2.2.1 api/ 目录 - 定义所有API接口请求 - 按模块组织API文件 - 包含接口调用方法和参数配置 #### 2.2.2 assets/ 目录 - **images/**: 图片资源 - **icons/**: 图标资源 - **styles/**: 全局样式文件 - 其他静态资源文件 #### 2.2.3 components/ 目录 - **base/**: 基础组件 - **business/**: 业务组件 - **common/**: 通用组件 - 可复用的Vue组件 #### 2.2.4 config/ 目录 - **index.js**: 主配置文件 - **router.config.js**: 路由配置 - **menu.config.js**: 菜单配置 - **theme.config.js**: 主题配置 - 其他系统配置文件 #### 2.2.5 directive/ 目录 - 自定义Vue指令 - 如权限控制、表单验证等指令 #### 2.2.6 filters/ 目录 - 自定义Vue过滤器 - 如日期格式化、数字格式化等 #### 2.2.7 layout/ 目录 - **components/**: 布局组件 - **index.vue**: 主布局文件 - **AppMain.vue**: 内容区域组件 - **Navbar.vue**: 导航栏组件 - **Sidebar.vue**: 侧边栏组件 #### 2.2.8 router/ 目录 - **index.js**: 路由配置主文件 - **modules/**: 按模块组织的路由配置 - 路由守卫配置 #### 2.2.9 store/ 目录 - **index.js**: 状态管理主文件 - **modules/**: 按模块组织的状态管理 - **getters.js**: 全局计算属性 #### 2.2.10 styles/ 目录 - **index.scss**: 全局样式入口 - **variables.scss**: 全局变量 - **mixins.scss**: 混合器 - **reset.scss**: 重置样式 #### 2.2.11 utils/ 目录 - **request.js**: 网络请求封装 - **auth.js**: 认证相关工具 - **tools.js**: 通用工具函数 - **storage.js**: 存储工具 #### 2.2.12 views/ 目录 - 按业务模块组织页面组件 - 每个模块一个目录 - 包含页面组件和相关子组件 #### 2.2.13 App.vue - 应用根组件 - 包含全局布局结构 #### 2.2.14 main.js - 应用入口文件 - 初始化Vue实例 - 加载插件和全局配置 ### 2.3 配置文件 #### 2.3.1 package.json - 项目依赖配置 - 脚本命令配置 - 项目信息配置 #### 2.3.2 vue.config.js - Vue CLI配置 - 构建配置 - 代理配置 #### 2.3.3 babel.config.js - Babel转译配置 #### 2.3.4 .env.* - 环境变量配置文件 - **.env.development**: 开发环境 - **.env.production**: 生产环境 - **.env.staging**: 测试环境 ## 3 目录规范 ### 3.1 命名规范 - 目录名使用小写字母，多单词用连字符(-)分隔 - 文件名使用小写字母，多单词用连字符(-)分隔 - 组件名使用 PascalCase 命名法 ### 3.2 目录组织原则 1. **按功能模块组织**: 相关功能的文件放在同一目录 2. **模块化**: 每个模块保持相对独立 3. **可扩展性**: 目录结构应易于扩展和维护 4. **一致性**: 保持目录结构的一致性 ### 3.3 特殊目录处理 - **components/**: 只存放可复用组件 - **views/**: 存放页面级组件 - **api/**: 按模块组织API接口 - **store/modules/**: 按模块组织状态管理 ## 4 最佳实践 ### 4.1 目录使用建议 - 新增业务模块时，在 views/ 下创建对应的目录 - 新增可复用组件时，放在 components/ 下的对应子目录 - 新增API接口时，在 api/ 下按模块组织 - 新增状态管理时，在 store/modules/ 下创建对应模块 ### 4.2 目录结构维护 - 定期清理无用文件和目录 - 保持目录结构的清晰和整洁 - 遵循统一的命名规范 - 文档及时更新，反映目录结构的变化 ## 5 常见问题 ### 5.1 目录权限问题 - 确保目录权限正确，避免构建时出现权限错误 ### 5.2 路径引用问题 - 使用相对路径或别名路径引用文件 - 避免使用绝对路径 ### 5.3 目录结构优化 - 随着项目规模增大，适时调整目录结构 - 保持目录层级合理，避免过深的嵌套 ## 6 总结 Admin-Element 项目采用标准的 Vue + ElementUI 项目结构，通过清晰的目录组织和命名规范，提高了代码的可维护性和可扩展性。开发者应遵循目录结构规范，合理组织代码，确保项目的长期可维护性。 --- ### .Codebuddy/Skills/Crmeb Agent/SKILL (.codebuddy/skills/crmeb-agent/SKILL.md) --- name: CRMEB电商系统Agent description: 专为CRMEB电商系统设计的智能开发助手,帮助开发者理解架构、快速开发功能、解决问题 --- # CRMEB电商系统Agent ## 0. 自动触发说明 ### 0.1 触发条件 #### 0.1.1 操作触发 - **文件浏览时**: 当浏览CRMEB项目核心目录时自动调用 - 打开 `crmeb/app/` 应用目录时触发 - 打开 `crmeb/crmeb/` 核心库目录时触发 - 打开 `template/` 前端目录时触发 - 浏览配置文件目录时触发 - **文件操作时**: 当对CRMEB项目文件进行操作时自动调用 - 创建控制器、服务、模型时触发 - 修改核心业务代码时触发 - 修改配置文件时触发 - **目录操作时**: 当对项目目录进行操作时自动调用 - 创建新模块目录时触发 - 重命名业务目录时触发 #### 0.1.2 内容触发 - **关键词触发**: 当文件内容包含以下关键词时自动调用 - 电商关键词: `订单`、`商品`、`用户`、`支付`、`购物车` - 营销关键词: `优惠券`、`拼团`、`砍价`、`秒杀`、`积分` - 系统关键词: `CRMEB`、`ThinkPHP`、`后台管理`、`移动端` - **代码触发**: 当查看特定类型代码时自动调用 - 控制器代码 (`Controller`) - 服务层代码 (`Services`) - 模型代码 (`Model`) - 前端Vue组件 (`*.vue`) #### 0.1.3 命令触发 - **终端命令触发**: 当执行以下命令时自动调用 - `php think` (ThinkPHP命令) - `composer install/update` (依赖管理) - `npm run dev/build` (前端构建) - `php think queue:listen` (队列启动) - `php think workerman` (WebSocket启动) ### 0.2 适用场景 #### 0.2.1 核心场景 - **功能开发**: 开发新的电商功能模块时 - **API开发**: 开发前后端接口时 - **数据库设计**: 设计数据表结构时 - **问题排查**: 解决系统运行问题时 #### 0.2.2 辅助场景 - **代码审查**: 审查代码质量时 - **性能优化**: 优化系统性能时 - **安全加固**: 增强系统安全性时 - **部署运维**: 部署和维护系统时 ## 1. CRMEB系统架构 ### 1.1 整体架构 - **框架**: ThinkPHP 6.x (PHP后端) + Vue 2.x (前端) - **架构模式**: 前后端分离 + MVC + Service + DAO分层架构 - **数据库**: MySQL 5.7-8.0 (使用eb_前缀) - **缓存**: Redis (可选,用于缓存和队列) - **消息队列**: ThinkPHP Queue + Workerman - **实时通信**: Workerman WebSocket ### 1.2 技术栈 #### 后端技术栈 ``` - PHP: 7.1-7.4 - ThinkPHP: 6.x - Composer: 依赖管理 - Workerman: 长连接服务 - PHPUnit: 单元测试(可选) ``` #### 前端技术栈 ``` 管理端: - Vue.js 2.x - Element UI 2.15.6 - Vuex 3.0 - Vue Router 3.0 - Axios - ECharts 4.8.0 移动端: - UniApp - uView UI ``` #### 第三方服务 ``` - 支付: 微信支付、支付宝支付 - 存储: 阿里云OSS、腾讯云COS、七牛云 - 短信: 阿里云短信 - 微信: 公众号、小程序 ``` ### 1.3 目录结构 #### 1.3.1 后端目录结构 ``` /* Detailed source-code truncated for AI context efficiency. */ ``` #### 1.3.2 前端目录结构 ``` template/ ├── admin/ # 管理后台 (Vue + ElementUI) │ ├── src/ │ │ ├── api/ # API接口定义 │ │ ├── components/ # 通用组件 │ │ ├── pages/ # 页面组件 │ │ ├── router/ # 路由配置 │ │ ├── store/ # Vuex状态管理 │ │ └── utils/ # 工具函数 │ ├── package.json │ └── vue.config.js └── uni-app/ # 移动端 (UniApp) ├── api/ # API接口 ├── components/ # 组件 ├── pages/ # 页面 ├── manifest.json # 应用配置 └── pages.json # 页面路由配置 ``` ## 2. 核心业务模块 ### 2.1 用户模块 (`app/services/user/`) #### 核心服务 - **UserServices**: 用户主服务,管理用户基础信息 - **LoginServices**: 登录服务,处理多种登录方式 - **UserLevelServices**: 用户等级管理 - **UserMoneyServices**: 用户余额管理 - **UserBillServices**: 账单流水管理 - **UserExtractServices**: 提现管理 - **UserRechargeServices**: 充值管理 - **UserGroupServices**: 用户分组 - **UserLabelServices**: 用户标签 #### 数据表 ```sql eb_user # 用户表 eb_user_bill # 账单表 eb_user_extract # 提现表 eb_user_recharge # 充值表 eb_user_level # 用户等级表 eb_user_group # 用户分组表 eb_user_label # 用户标签表 ``` #### 开发要点 - 用户登录支持多种方式: 账号密码、手机验证码、微信授权 - 用户余额变动必须记录到账单表 - 用户等级可以设置升级条件 - 用户分组和标签用于精准营销 ### 2.2 商品模块 (`app/services/product/`) #### 核心服务 - **StoreProductServices**: 商品主服务 - **StoreCategoryServices**: 商品分类 - **StoreProductAttrServices**: 商品属性 - **StoreProductReplyServices**: 商品评价 - **CopyTaobaoServices**: 淘宝商品采集 #### 数据表 ```sql eb_store_product # 商品表 eb_store_category # 商品分类表 eb_store_product_attr # 商品属性表 eb_store_product_reply # 商品评价表 eb_store_product_description # 商品详情表 ``` #### 开发要点 - 商品支持多规格(SKU),需要处理库存和价格 - 商品可以设置为普通商品、积分商品、预售商品等 - 商品分类支持多级分类 - 商品属性支持自定义规格 ### 2.3 订单模块 (`app/services/order/`) #### 核心服务 - **StoreOrderServices**: 订单主服务 - **StoreOrderCreateServices**: 订单创建 - **StoreOrderDeliveryServices**: 订单发货 - **StoreOrderRefundServices**: 订单退款 - **StoreCartServices**: 购物车 - **OtherOrderServices**: 其他订单(积分订单等) - **OutStoreOrderServices**: 外部订单 #### 数据表 ```sql eb_store_order # 订单表 eb_store_order_cart # 订单商品表 eb_store_order_status # 订单状态变更记录 eb_store_refund # 退款表 eb_store_cart # 购物车表 ``` #### 开发要点 - 订单状态流转: 未支付 → 待发货 → 待收货 → 已完成 (或取消/退款) - 订单创建时需要扣减库存 - 支付成功后触发后续流程(发货通知、积分增加等) - 订单退款需要恢复库存 - 订单相关操作建议使用队列异步处理 #### 订单状态流转图 ``` 未支付 (status=0) ↓ 支付成功待发货 (status=1) ↓ 发货待收货 (status=2) ↓ 确认收货已完成 (status=3) 分支流程: - 未支付 → 已取消 (status=-1) - 待发货 → 申请退款 → 退款中 (status=-2) → 已退款 (status=-3) - 待收货 → 申请退款 → 退款中 (status=-2) → 已退款 (status=-3) ``` ### 2.4 支付模块 (`app/services/pay/`) #### 核心服务 - **PayServices**: 支付服务 - **WechatPayServices**: 微信支付 - **AlipayServices**: 支付宝支付 #### 数据表 ```sql eb_pay # 支付记录表 ``` #### 开发要点 - 支付方式: 微信支付(公众号/小程序/H5)、支付宝支付、余额支付 - 支付流程: 创建订单 → 调起支付 → 支付回调 → 更新订单状态 - 支付回调需要验证签名防止伪造 - 支付成功后触发事件,可以扩展后续业务逻辑 ### 2.5 营销模块 (`app/services/activity/`) #### 核心服务 - **拼团**: StoreCombinationServices, StorePinkServices - **砍价**: StoreBargainServices - **秒杀**: StoreSeckillServices - **优惠券**: StoreCouponService, StoreCouponUserServices - **积分**: StoreIntegralServices - **直播**: LiveRoomServices, LiveGoodsServices - **抽奖**: LuckLotteryServices #### 数据表 ```sql eb_store_combination # 拼团商品表 eb_store_pink # 拼团记录表 eb_store_bargain # 砍价商品表 eb_store_bargain_user # 砍价记录表 eb_store_seckill # 秒杀商品表 eb_store_coupon # 优惠券表 eb_store_coupon_user # 用户优惠券表 eb_integral_product # 积分商品表 ``` #### 开发要点 - 营销活动都需要设置时间范围 - 优惠券可以设置使用条件和适用商品 - 拼团需要处理拼团成功/失败的逻辑 - 砍价需要处理砍价进度和完成时间 - 秒杀商品需要限制库存和购买数量 ### 2.6 分销模块 (`app/services/agent/`) #### 核心服务 - **AgentLevelServices**: 分销等级管理 - **AgentLevelTaskServices**: 分销任务系统 - **DivisionServices**: 事业部/代理管理 - **SpreadApplyServices**: 分销申请 #### 数据表 ```sql eb_agent_level # 分销等级表 eb_agent_level_task # 分销任务表 eb_division # 事业部表 eb_spread_apply # 分销申请表 ``` #### 开发要点 - 分销系统支持多级分销 - 分销员等级通过完成任务自动升级 - 分销佣金结算需要计算各级佣金 - 分销申请需要管理员审核 ### 2.7 系统管理模块 (`app/services/system/`) #### 核心服务 - **SystemCrudServices**: CRUD代码生成器 - **SystemConfigServices**: 系统配置 - **SystemEventServices**: 系统事件管理 - **SystemCrontabServices**: 定时任务管理 - **SystemMenusServices**: 菜单管理 - **SystemAdminServices**: 管理员管理 - **SystemLogServices**: 操作日志 - **SystemFileServices**: 文件管理 - **SystemUpgradeServices**: 系统升级 #### 开发要点 - **代码生成器**: 可以快速生成Controller、Service、DAO、Model、Validate - **系统配置**: 支持后台动态配置,存储在数据库中 - **事件系统**: 定义了30+系统事件锚点,可以扩展业务逻辑 - **定时任务**: 基于Workerman,支持Cron表达式 - **权限管理**: 基于RBAC模型,可以控制到菜单和按钮级别 ## 3. 开发规范 ### 3.1 命名规范 #### 类命名 - **控制器**: 模块名 + Controller,如 `UserController` - **服务**: 模块名 + Services,如 `UserServices` - **DAO**: 模块名 + Dao,如 `UserDao` - **模型**: 模块名,如 `User` - **验证器**: 模块名 + Validate,如 `UserValidate` #### 方法命名 - **控制器方法**: 小写+下划线,如 `get_list`, `save_data` - **服务方法**: 驼峰法,如 `getUserList`, `saveData` - **DAO方法**: 数据库操作相关,如 `selectList`, `insert`, `update`, `delete` #### 变量命名 - **普通变量**: 驼峰法,如 `$userName`, `$orderId` - **数组变量**: 复数形式,如 `$users`, `$products` - **布尔变量**: is/has/can开头,如 `$isPaid`, `$hasStock` ### 3.2 代码规范 #### 控制器层 ```php services = $services; } /** * 获取管理员列表 * @return mixed */ public function get_list() { $where = $this->request->getMore([ ['keywords', ''], ['status', ''] ]); $list = $this->services->getAdminList($where); return app('json')->success($list); } /** * 保存管理员 * @return mixed */ public function save() { $data = $this->request->postMore([ ['account', ''], ['real_name', ''], ['pwd', ''], ['roles', []], ['status', 1] ]); $this->services->saveAdmin($data); return app('json')->success('保存成功'); } } ``` #### 服务层 ```php dao->search($where); // 获取列表 $list = $query->select()->toArray(); // 处理数据 foreach ($list as &$item) { $item['role_names'] = $this->getRoleNames($item['roles']); } return $list; } /** * 保存管理员 * @param array $data * @return int */ public function saveAdmin(array $data): int { // 验证数据 if (empty($data['account'])) { throw new AdminException('账号不能为空'); } // 密码加密 if (!empty($data['pwd'])) { $data['pwd'] = password_hash($data['pwd'], PASSWORD_DEFAULT); } else { unset($data['pwd']); } // 保存数据 if (isset($data['id']) && $data['id']) { // 更新 $id = $data['id']; unset($data['id']); $this->dao->update($id, $data); } else { // 新增 $id = $this->dao->save($data); } return $id; } } ``` #### DAO层 ```php getModel() ->where('is_del', 0); // 账号搜索 if (!empty($where['keywords'])) { $query = $query->whereLike('account|real_name', "%{$where['keywords']}%"); } // 状态筛选 if ($where['status'] !== '') { $query = $query->where('status', $where['status']); } return $query; } } ``` #### 模型层 ```php belongsToMany(SystemRole::class, 'system_admin_role', 'role_id', 'admin_id'); } /** * 密码修改器 * @param $value * @return string */ public function setPwdAttr($value) { return password_hash($value, PASSWORD_DEFAULT); } /** * 状态获取器 * @param $value * @return string */ public function getStatusTextAttr($value, $data) { $status = [ 0 => '禁用', 1 => '启用' ]; return $status[$data['status']] ?? ''; } } ``` ### 3.3 数据库规范 #### 表命名 - 使用小写字母和下划线 - 统一使用 `eb_` 前缀 - 表名使用复数形式或明确含义 #### 字段命名 - 使用小写字母和下划线 - 字段名不以下划线开头 - 主键统一命名为 `id` - 外键命名为 `表名_id`,如 `user_id` - 时间字段命名为 `create_time`, `update_time` - 状态字段命名为 `status`,默认值0 - 删除标记命名为 `is_del`,0未删除1已删除 #### 字段类型 - 整型: 使用 `int`,如 `tinyint`, `smallint`, `int`, `bigint` - 字符串: 使用 `varchar`,如 `varchar(255)` - 文本: 使用 `text` - 金额: 使用 `decimal(10,2)` - 时间: 使用 `int`(时间戳)或 `datetime` ### 3.4 API规范 #### 请求方式 - **GET**: 查询数据 - **POST**: 创建数据 - **PUT**: 更新数据 - **DELETE**: 删除数据 #### 响应格式 ```json { "code": 200, "msg": "操作成功", "data": {} } ``` #### 错误响应 ```json { "code": 400, "msg": "错误信息", "data": null } ``` #### 分页响应 ```json { "code": 200, "msg": "操作成功", "data": { "list": [], "count": 100, "page": 1, "limit": 10 } } ``` ## 4. 自动化功能 ### 4.1 代码生成器 #### 使用方式 1. 在后台管理中进入"系统管理" > "代码生成" 2. 选择数据表 3. 配置生成参数(字段类型、搜索类型、表单类型等) 4. 生成代码 #### 支持的表单类型 - **input**: 普通输入框 - **textarea**: 文本域 - **select**: 下拉选择 - **radio**: 单选框 - **checkbox**: 复选框 - **date**: 日期选择 - **datetime**: 日期时间选择 - **image**: 图片上传 - **file**: 文件上传 - **editor**: 富文本编辑器 - **number**: 数字输入 - **switch**: 开关 - 等等 #### 支持的搜索类型 - **普通搜索**: 普通文本搜索 - **日期范围**: 日期区间搜索 - **时间范围**: 时间区间搜索 - **下拉选择**: 下拉筛选 ### 4.2 定时任务 #### 启动命令 ```bash # 启动定时任务(守护进程) php think timer start --d # 停止定时任务 php think timer stop # 重启定时任务 php think timer restart # 查看定时任务状态 php think timer status ``` #### 系统预置定时任务 1. 自动取消未支付订单 2. 自动确认收货 3. 自动评价 4. 自动关闭拼团 5. 自动关闭砍价 6. 积分到期处理 7. 优惠券过期处理 8. 分销佣金结算 9. 统计数据汇总 10. 系统日志清理 ### 4.3 队列任务 #### 启动命令 ```bash # 启动队列消费者 php think queue:listen --queue # 或者使用Workerman php think queue:work --queue ``` #### 主要队列任务 - **OrderJob**: 订单相关任务(创建、支付、发货等) - **PinkJob**: 拼团任务 - **BargainJob**: 砍价任务 - **SeckillJob**: 秒杀任务 - **AutoCommentJob**: 自动评价 - **PosterJob**: 海报生成 - **AgentJob**: 分销等级升级检测 - **UnpaidOrderCancelJob**: 未支付订单取消 - 等等 ### 4.4 事件系统 #### 系统事件锚点 **用户事件**: - 用户注册 (user.register) - 用户登录 (user.login) - 用户注销 (user.logout) - 用户修改信息 (user.update) - 用户绑定推广 (user.bind_spread) - 用户签到 (user.sign) - 用户充值 (user.recharge) **订单事件**: - 订单创建 (order.create) - 订单支付成功 (order.pay_success) - 订单发货 (order.delivery) - 订单收货 (order.confirm) - 订单取消 (order.cancel) - 订单退款 (order.refund) **商品事件**: - 商品上架 (product.on_shelf) - 商品下架 (product.off_shelf) - 商品评价 (product.comment) **支付事件**: - 支付成功 (pay.success) - 支付失败 (pay.fail) **营销事件**: - 领取优惠券 (coupon.receive) - 参与拼团 (combination.join) - 参与砍价 (bargain.join) #### 事件监听器开发 ```php [ 'protocol' => 'websocket', 'port' => 40001, 'ip' => '0.0.0.0', ], // 客服消息 'chat' => [ 'protocol' => 'websocket', 'port' => 40002, 'ip' => '0.0.0.0', ], // 内部通讯 'channel' => [ 'port' => 40003, 'ip' => '127.0.0.1', ], ]; ``` #### 使用场景 - 新订单实时通知 - 客服在线聊天 - 系统消息推送 - 实时数据统计 ## 5. 常见开发场景 ### 5.1 创建新功能模块 #### 步骤1: 创建数据表 ```sql CREATE TABLE `eb_example` ( `id` int(11) NOT NULL AUTO_INCREMENT, `name` varchar(255) NOT NULL DEFAULT '' COMMENT '名称', `status` tinyint(1) NOT NULL DEFAULT '1' COMMENT '状态 0禁用 1启用', `create_time` int(11) NOT NULL DEFAULT '0' COMMENT '创建时间', `update_time` int(11) NOT NULL DEFAULT '0' COMMENT '更新时间', `is_del` tinyint(1) NOT NULL DEFAULT '0' COMMENT '是否删除', PRIMARY KEY (`id`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='示例表'; ``` #### 步骤2: 创建模型 ```bash # 使用命令行生成模型 php think make:model Example ``` #### 步骤3: 创建DAO ```php dao = $dao; } public function getList(array $where): array { return $this->dao->getList($where); } public function save(array $data): int { return $this->dao->save($data); } } ``` #### 步骤5: 创建控制器 ```php services = $services; } public function get_list() { $where = $this->request->getMore([ ['name', ''], ['status', ''] ]); $list = $this->services->getList($where); return app('json')->success($list); } public function save() { $data = $this->request->postMore([ ['name', ''], ['status', 1] ]); $this->services->save($data); return app('json')->success('保存成功'); } } ``` #### 步骤6: 创建路由 ```php // route/app.php 或 route/adminapi.php use think\facade\Route; Route::group('example', function () { Route::get('list', 'Example/get_list'); Route::post('save', 'Example/save'); }); ``` #### 步骤7: 使用代码生成器(可选) 直接在后台管理系统配置代码生成,自动生成前后端代码 ### 5.2 开发订单功能 #### 订单创建流程 1. 校验商品库存和状态 2. 计算订单金额 3. 创建订单记录 4. 创建订单商品记录 5. 扣减商品库存 6. 清空购物车 7. 触发订单创建事件 #### 订单支付流程 1. 调起支付(微信/支付宝/余额) 2. 接收支付回调 3. 验证签名 4. 更新订单状态为"待发货" 5. 扣减优惠券 6. 增加用户积分 7. 触发支付成功事件(分销、通知等) #### 订单发货流程 1. 获取订单信息 2. 填写物流信息 3. 更新订单状态为"待收货" 4. 发送发货通知 5. 触发发货事件 #### 订单收货流程 1. 用户确认收货或系统自动收货(7天未收货) 2. 更新订单状态为"已完成" 3. 结算分销佣金 4. 增加用户积分 5. 触发收货事件 ### 5.3 开发营销活动 #### 优惠券功能开发要点 1. 创建优惠券模板(面额、门槛、使用条件等) 2. 用户领取优惠券 3. 下单时选择优惠券 4. 计算优惠金额 5. 支付后核销优惠券 6. 过期自动失效 #### 拼团功能开发要点 1. 创建拼团商品(拼团价、成团人数、拼团时长) 2. 用户发起拼团 3. 其他人参与拼团 4. 拼团成功/失败判断 5. 成团后按拼团价计算订单 6. 失败后退款 #### 秒杀功能开发要点 1. 创建秒杀活动(时间、商品、库存、限购) 2. 用户参与秒杀 3. 检查库存和限购 4. 创建秒杀订单 5. 未支付订单自动取消 6. 活动结束后更新库存 ### 5.4 开发分销功能 #### 分销流程 1. 用户申请成为分销员 2. 管理员审核通过 3. 分销员分享推广链接 4. 新用户通过链接注册成为下级 5. 下级用户下单 6. 系统计算分销佣金 7. 佣金结算到分销员余额 #### 分销等级升级 1. 创建分销等级(等级名称、佣金比例) 2. 设置升级任务(订单数、金额等) 3. 定时任务检测分销员任务完成情况 4. 达到条件自动升级 ## 6. 问题排查指南 ### 6.1 常见错误 #### 数据库连接错误 ```php // 错误信息 SQLSTATE[HY000] [2002] Connection refused // 排查步骤 1. 检查数据库服务是否启动 2. 检查 .env 配置文件中的数据库配置 3. 检查数据库用户权限 4. 检查防火墙设置 ``` #### 队列任务不执行 ```php // 排查步骤 1. 检查队列消费者是否启动: php think queue:work 2. 检查队列配置: config/queue.php 3. 检查Redis连接: redis-cli ping 4. 查看队列日志: runtime/log/ ``` #### 定时任务不执行 ```bash # 排查步骤 1. 检查定时任务是否启动: php think timer status 2. 检查定时任务配置 3. 检查Cron表达式是否正确 4. 查看定时任务日志 ``` #### WebSocket连接失败 ```bash # 排查步骤 1. 检查WebSocket服务是否启动: php think workerman status 2. 检查端口是否被占用: netstat -tlnp | grep 40001 3. 检查防火墙设置 4. 检查客户端连接地址是否正确 ``` ### 6.2 性能优化 #### 数据库优化 - 为常用查询字段添加索引 - 避免使用 `SELECT *`,只查询需要的字段 - 使用 `EXPLAIN` 分析SQL执行计划 - 合理使用缓存减少数据库查询 #### 缓存优化 - 使用Redis缓存热点数据 - 设置合理的缓存过期时间 - 使用缓存前缀防止冲突 #### 代码优化 - 减少循环嵌套 - 优化算法复杂度 - 使用队列处理耗时操作 - 异步处理非关键业务 ### 6.3 安全加固 #### SQL注入防护 - 使用参数绑定,不要直接拼接SQL - 使用ThinkPHP的查询构造器 - 对用户输入进行验证 #### XSS防护 - 对用户输入进行过滤 - 输出时进行HTML转义 - 使用CSP(内容安全策略) #### CSRF防护 - 使用CSRF Token - 验证请求来源 - 重要操作二次确认 #### 权限控制 - 严格的权限验证 - 基于RBAC的权限模型 - 敏感操作记录日志 ## 7. 部署与运维 ### 7.1 环境要求 - PHP >= 7.1 - MySQL >= 5.7 - Redis >= 5.0 (可选) - Nginx/Apache - Composer ### 7.2 部署步骤 #### 1. 安装依赖 ```bash composer install ``` #### 2. 配置环境 ```bash cp .env.example .env # 修改 .env 文件中的配置 ``` #### 3. 数据库初始化 ```bash # 导入数据库 mysql -u root -p crmeb < database.sql ``` #### 4. 设置目录权限 ```bash chmod -R 755 runtime chmod -R 755 public/uploads ``` #### 5. 启动服务 ```bash # 启动队列 php think queue:listen --queue # 启动定时任务 php think timer start --d # 启动WebSocket php think workerman start --d ``` #### 6. 前端构建 ```bash cd template/admin npm install npm run build ``` ### 7.3 Docker部署 #### 使用docker-compose ```bash cd docker-compose docker-compose up -d ``` ### 7.4 监控与日志 #### 日志位置 - 应用日志: `runtime/log/` - 错误日志: `runtime/log/error/` - SQL日志: 开启数据库SQL日志记录 #### 监控指标 - 服务器资源: CPU、内存、磁盘 - 应用性能: 响应时间、吞吐量 - 数据库: 慢查询、连接数 - 队列: 队列长度、处理速度 ## 8. 参考资源 ### 8.1 官方文档 - [ThinkPHP 6 官方文档](https://www.kancloud.cn/manual/thinkphp6_0) - [Vue 2 官方文档](https://v2.vuejs.org/) - [Element UI 官方文档](https://element.eleme.io/) - [UniApp 官方文档](https://uniapp.dcloud.net.cn/) ### 8.2 项目文档 - `/dev-docs/AI代码理解指南.md` - 代码理解指南 - `/dev-docs/错误码说明文档.md` - 错误码说明 - `.codebuddy/skills/php-api/SKILL.md` - 后端开发规范 - `.codebuddy/skills/admin-element/SKILL.md` - 前端开发规范 ### 8.3 工具推荐 - **IDE**: PhpStorm / VS Code - **API测试**: Postman / Apifox - **数据库**: Navicat / phpMyAdmin - **Redis**: Redis Desktop Manager ## 9. 常用命令速查 ### 9.1 ThinkPHP命令 ```bash php think # 查看所有命令 php think make:controller # 创建控制器 php think make:model # 创建模型 php think make:middleware # 创建中间件 php think make:validate # 创建验证器 php think clear # 清除缓存 php think run # 启动内置服务器 ``` ### 9.2 队列命令 ```bash php think queue:listen # 监听队列 php think queue:work # 处理队列任务 php think queue:restart # 重启队列 php think queue:fail # 查看失败任务 php think queue:retry # 重试失败任务 ``` ### 9.3 定时任务命令 ```bash php think timer start # 启动定时任务 php think timer stop # 停止定时任务 php think timer restart # 重启定时任务 php think timer status # 查看状态 ``` ### 9.4 Workerman命令 ```bash php think workerman start # 启动 php think workerman stop # 停止 php think workerman restart # 重启 php think workerman reload # 平滑重启 php think workerman status # 查看状态 ``` --- > **提示**: 本Agent专为CRMEB电商系统设计,帮助您快速开发和理解系统。如有疑问,请参考官方文档或查看项目源码。 --- ### .Codebuddy/Skills/Php Api/References/Api Flow (.codebuddy/skills/php-api/references/api_flow.md) # 接口请求文档 ## 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/) --- ### .Codebuddy/Skills/Php Api/References/Db Design (.codebuddy/skills/php-api/references/db_design.md) # 数据库设计文档 ## 1. 概述本文档描述了 CRMEB 项目的数据库设计，包括数据库架构、表结构、索引设计、关系设计等，旨在规范数据库设计，提高数据库性能和可维护性。 ## 2. 数据库架构 ### 2.1 整体架构 - **数据库系统**: MySQL 5.7~8.0 - **存储引擎**: InnoDB (默认) - **字符集**: utf8mb4 - **排序规则**: utf8mb4_general_ci - **连接池**: 建议使用 - **SQL文件位置**: `public/install/crmeb.sql` ### 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` | `VARCHAR` | 50 | `NOT NULL` | 用户名 | | `password` | `VARCHAR` | 255 | `NOT NULL` | 密码 | | `nickname` | `VARCHAR` | 50 | `NOT NULL` | 昵称 | | `avatar` | `VARCHAR` | 255 | | 头像 | | `mobile` | `VARCHAR` | 20 | | 手机号 | | `email` | `VARCHAR` | 100 | | 邮箱 | | `status` | `TINYINT` | 1 | `DEFAULT 1` | 状态 | | `create_time` | `DATETIME` | | `DEFAULT CURRENT_TIMESTAMP` | 创建时间 | | `update_time` | `DATETIME` | | `DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP` | 更新时间 | | `delete_time` | `DATETIME` | | | 删除时间 | ### 4.2 商品表 (`product`) | 字段名 | 数据类型 | 长度 | 约束 | 描述 | |-------|---------|------|------|------| | `id` | `INT` | 11 | `PRIMARY KEY AUTO_INCREMENT` | 商品ID | | `name` | `VARCHAR` | 255 | `NOT NULL` | 商品名称 | | `category_id` | `INT` | 11 | `NOT NULL` | 分类ID | | `price` | `DECIMAL` | 10,2 | `NOT NULL` | 价格 | | `stock` | `INT` | 11 | `NOT NULL` | 库存 | | `status` | `TINYINT` | 1 | `DEFAULT 1` | 状态 | | `create_time` | `DATETIME` | | `DEFAULT CURRENT_TIMESTAMP` | 创建时间 | | `update_time` | `DATETIME` | | `DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP` | 更新时间 | | `delete_time` | `DATETIME` | | | 删除时间 | ### 4.3 订单表 (`order`) | 字段名 | 数据类型 | 长度 | 约束 | 描述 | |-------|---------|------|------|------| | `id` | `INT` | 11 | `PRIMARY KEY AUTO_INCREMENT` | 订单ID | | `order_sn` | `VARCHAR` | 32 | `NOT NULL UNIQUE` | 订单号 | | `user_id` | `INT` | 11 | `NOT NULL` | 用户ID | | `total_price` | `DECIMAL` | 10,2 | `NOT NULL` | 总价 | | `status` | `TINYINT` | 1 | `DEFAULT 0` | 状态 | | `create_time` | `DATETIME` | | `DEFAULT CURRENT_TIMESTAMP` | 创建时间 | | `update_time` | `DATETIME` | | `DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP` | 更新时间 | | `delete_time` | `DATETIME` | | | 删除时间 | ### 4.4 分类表 (`category`) | 字段名 | 数据类型 | 长度 | 约束 | 描述 | |-------|---------|------|------|------| | `id` | `INT` | 11 | `PRIMARY KEY AUTO_INCREMENT` | 分类ID | | `name` | `VARCHAR` | 50 | `NOT NULL` | 分类名称 | | `parent_id` | `INT` | 11 | `DEFAULT 0` | 父分类ID | | `sort` | `INT` | 11 | `DEFAULT 0` | 排序 | | `status` | `TINYINT` | 1 | `DEFAULT 1` | 状态 | | `create_time` | `DATETIME` | | `DEFAULT CURRENT_TIMESTAMP` | 创建时间 | | `update_time` | `DATETIME` | | `DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP` | 更新时间 | | `delete_time` | `DATETIME` | | | 删除时间 | ### 4.5 地址表 (`address`) | 字段名 | 数据类型 | 长度 | 约束 | 描述 | |-------|---------|------|------|------| | `id` | `INT` | 11 | `PRIMARY KEY AUTO_INCREMENT` | 地址ID | | `user_id` | `INT` | 11 | `NOT NULL` | 用户ID | | `name` | `VARCHAR` | 50 | `NOT NULL` | 收货人姓名 | | `mobile` | `VARCHAR` | 20 | `NOT NULL` | 手机号 | | `province` | `VARCHAR` | 50 | `NOT NULL` | 省份 | | `city` | `VARCHAR` | 50 | `NOT NULL` | 城市 | | `district` | `VARCHAR` | 50 | `NOT NULL` | 区县 | | `detail` | `VARCHAR` | 255 | `NOT NULL` | 详细地址 | | `is_default` | `TINYINT` | 1 | `DEFAULT 0` | 是否默认 | | `create_time` | `DATETIME` | | `DEFAULT CURRENT_TIMESTAMP` | 创建时间 | | `update_time` | `DATETIME` | | `DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP` | 更新时间 | | `delete_time` | `DATETIME` | | | 删除时间 | ## 5. 索引设计 ### 5.1 用户表索引 | 索引名 | 类型 | 字段 | 描述 | |-------|------|------|------| | `PRIMARY` | 主键 | `id` | 主键索引 | | `uk_username` | 唯一 | `username` | 用户名唯一索引 | | `idx_mobile` | 普通 | `mobile` | 手机号索引 | | `idx_email` | 普通 | `email` | 邮箱索引 | | `idx_status` | 普通 | `status` | 状态索引 | ### 5.2 商品表索引 | 索引名 | 类型 | 字段 | 描述 | |-------|------|------|------| | `PRIMARY` | 主键 | `id` | 主键索引 | | `idx_category_id` | 普通 | `category_id` | 分类ID索引 | | `idx_price` | 普通 | `price` | 价格索引 | | `idx_status` | 普通 | `status` | 状态索引 | ### 5.3 订单表索引 | 索引名 | 类型 | 字段 | 描述 | |-------|------|------|------| | `PRIMARY` | 主键 | `id` | 主键索引 | | `uk_order_sn` | 唯一 | `order_sn` | 订单号唯一索引 | | `idx_user_id` | 普通 | `user_id` | 用户ID索引 | | `idx_status` | 普通 | `status` | 状态索引 | | `idx_create_time` | 普通 | `create_time` | 创建时间索引 | ### 5.4 分类表索引 | 索引名 | 类型 | 字段 | 描述 | |-------|------|------|------| | `PRIMARY` | 主键 | `id` | 主键索引 | | `idx_parent_id` | 普通 | `parent_id` | 父分类ID索引 | | `idx_sort` | 普通 | `sort` | 排序索引 | | `idx_status` | 普通 | `status` | 状态索引 | ### 5.5 地址表索引 | 索引名 | 类型 | 字段 | 描述 | |-------|------|------|------| | `PRIMARY` | 主键 | `id` | 主键索引 | | `idx_user_id` | 普通 | `user_id` | 用户ID索引 | | `idx_is_default` | 普通 | `is_default` | 是否默认索引 | ## 6. 关系设计 ### 6.1 表关系图 ``` user ----------------- order | | | | | | address product | | | category ``` ### 6.2 关系说明 - **用户与订单**: 一对多关系，一个用户可以有多个订单 - **用户与地址**: 一对多关系，一个用户可以有多个地址 - **商品与分类**: 多对一关系，多个商品属于一个分类 - **订单与商品**: 多对多关系，一个订单可以包含多个商品，一个商品可以出现在多个订单中 ### 6.3 外键关系 | 主表 | 主键 | 从表 | 外键 | 描述 | |------|------|------|------|------| | `user` | `id` | `order` | `user_id` | 订单所属用户 | | `user` | `id` | `address` | `user_id` | 地址所属用户 | | `category` | `id` | `product` | `category_id` | 商品所属分类 | ## 7. 性能优化 ### 7.1 索引优化 - **选择合适的索引类型**: 根据查询场景选择合适的索引类型 - **避免过度索引**: 只在需要的字段上创建索引 - **使用复合索引**: 对于多字段查询，使用复合索引 - **定期维护索引**: 定期重建碎片化的索引 ### 7.2 查询优化 - **避免全表扫描**: 使用索引覆盖查询 - **减少查询字段**: 只查询需要的字段 - **使用连接查询**: 合理使用连接查询，避免子查询 - **限制查询结果**: 使用 LIMIT 限制查询结果数量 ### 7.3 存储优化 - **选择合适的字段类型**: 根据实际需求选择合适的字段类型 - **使用分区表**: 对于大表，使用分区表提高查询性能 - **定期清理数据**: 定期清理无用数据，减少表大小 - **使用缓存**: 对于频繁查询的数据，使用 Redis 缓存 ### 7.4 配置优化 - **调整 innodb_buffer_pool_size**: 根据服务器内存大小调整 - **调整 max_connections**: 根据并发量调整 - **启用查询缓存**: 对于读多写少的场景 - **优化日志配置**: 合理配置二进制日志和慢查询日志 ## 8. 安全设计 ### 8.1 数据安全 - **加密存储**: 敏感数据（如密码）加密存储 - **数据备份**: 定期备份数据库 - **数据恢复**: 建立数据恢复机制 - **访问控制**: 严格控制数据库访问权限 ### 8.2 SQL 注入防护 - **使用参数化查询**: 避免直接拼接 SQL - **使用 ORM**: 使用 ThinkPHP ORM 框架 - **输入验证**: 对用户输入进行验证 - **转义特殊字符**: 对特殊字符进行转义 ### 8.3 权限管理 - **最小权限原则**: 只授予必要的权限 - **角色分离**: 不同角色拥有不同权限 - **定期审计**: 定期审计数据库访问日志 ## 9. 备份与恢复 ### 9.1 备份策略 - **全量备份**: 定期进行全量备份 - **增量备份**: 每天进行增量备份 - **日志备份**: 备份二进制日志 ### 9.2 恢复策略 - **全量恢复**: 使用全量备份恢复 - **增量恢复**: 使用增量备份恢复 - **点恢复**: 使用二进制日志进行点恢复 ### 9.3 备份工具 - **mysqldump**: MySQL 自带备份工具 - **xtrabackup**: Percona 提供的备份工具 - **第三方工具**: 如 Navicat 等 ## 10. 版本控制 ### 10.1 数据库迁移 - **使用迁移工具**: 使用 ThinkPHP 数据库迁移工具 - **版本管理**: 对数据库结构变更进行版本管理 - **回滚机制**: 支持数据库结构回滚 ### 10.2 迁移文件命名规范 - **格式**: `YYYYMMDDHHMMSS_描述.php` - **示例**: `20230101000000_create_user_table.php` ### 10.3 迁移文件结构 ```php table('user'); $table->addColumn('username', 'string', ['limit' => 50, 'comment' => '用户名']) ->addColumn('password', 'string', ['limit' => 255, 'comment' => '密码']) ->addColumn('nickname', 'string', ['limit' => 50, 'comment' => '昵称']) ->addColumn('avatar', 'string', ['limit' => 255, 'comment' => '头像']) ->addColumn('mobile', 'string', ['limit' => 20, 'comment' => '手机号']) ->addColumn('email', 'string', ['limit' => 100, 'comment' => '邮箱']) ->addColumn('status', 'tinyint', ['default' => 1, 'comment' => '状态']) ->addColumn('create_time', 'datetime', ['default' => 'CURRENT_TIMESTAMP', 'comment' => '创建时间']) ->addColumn('update_time', 'datetime', ['default' => 'CURRENT_TIMESTAMP', 'update' => 'CURRENT_TIMESTAMP', 'comment' => '更新时间']) ->addColumn('delete_time', 'datetime', ['comment' => '删除时间']) ->addIndex('username', ['unique' => true]) ->addIndex('mobile') ->addIndex('email') ->addIndex('status') ->create(); } } ``` ## 11. 维护与监控 ### 11.1 日常维护 - **定期优化表**: 定期执行 OPTIMIZE TABLE 命令 - **监控表大小**: 监控表大小变化 - **检查慢查询**: 定期分析慢查询日志 - **更新统计信息**: 定期更新表统计信息 ### 11.2 监控指标 - **查询性能**: 监控查询响应时间 - **连接数**: 监控数据库连接数 - **缓存命中率**: 监控缓存命中率 - **磁盘使用率**: 监控磁盘空间使用情况 - **CPU 使用率**: 监控数据库服务器 CPU 使用率 ### 11.3 监控工具 - **MySQL Enterprise Monitor**: MySQL 企业版监控工具 - **Percona Monitoring and Management**: 开源监控工具 - **Zabbix**: 通用监控工具 - **Prometheus + Grafana**: 现代化监控方案 ## 12. 总结本文档描述了 CRMEB 项目的数据库设计规范和最佳实践，包括数据库架构、表结构、索引设计、关系设计、性能优化、安全设计、备份与恢复、版本控制、维护与监控等方面。遵循本文档的设计规范，可以提高数据库性能和可维护性，确保系统的稳定运行。同时，定期对数据库进行维护和监控，可以及时发现和解决潜在问题，保障系统的安全性和可靠性。随着业务的发展和系统的演进，数据库设计也需要不断优化和调整，以适应新的业务需求和技术挑战。 --- ### .Codebuddy/Skills/Php Api/References/Directory Structure (.codebuddy/skills/php-api/references/directory_structure.md) # 目录结构文档 ## 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/模块化设计) --- ### .Codebuddy/Skills/Php Api/References/Error Code (.codebuddy/skills/php-api/references/error_code.md) # 错误码文档 ## 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) --- ### .Codebuddy/Skills/Uniapp/References/Api Flow (.codebuddy/skills/uniapp/references/api_flow.md) # UniApp API 开发流程文档 ## 1. 概述本文档描述了 CRMEB 项目中 UniApp 移动端的 API 开发流程，包括 API 接口设计、请求流程、响应处理、错误处理等，旨在规范 API 开发，提高开发效率和代码质量。 ## 2. API 目录结构 ``` template/uni-app/api/ ├── activity.js # 活动相关接口 ├── admin.js # 管理相关接口 ├── api.js # 基础 API 配置 ├── kefu.js # 客服相关接口 ├── lottery.js # 抽奖相关接口 ├── order.js # 订单相关接口 ├── public.js # 公共接口 ├── store.js # 商城相关接口 └── user.js # 用户相关接口 ``` ## 3. 基础 API 配置 (api.js) ```javascript // 基础 API 配置 const baseURL = 'https://api.crmeb.net'; // 请求超时时间 const timeout = 10000; // 请求拦截器 const requestInterceptor = (config) => { // 添加 token const token = uni.getStorageSync('token'); if (token) { config.header['Authorization'] = `Bearer ${token}`; } // 添加设备信息 config.header['X-Device-Type'] = uni.getSystemInfoSync().platform; return config; }; // 响应拦截器 const responseInterceptor = (response) => { const { data } = response; // 统一处理错误 if (data.code !== 200) { uni.showToast({ title: data.message || '请求失败', icon: 'none' }); // 处理登录过期 if (data.code === 401) { uni.redirectTo({ url: '/pages/login/index' }); } return Promise.reject(data); } return data; }; // 错误处理 const errorHandler = (error) => { uni.showToast({ title: '网络错误，请稍后重试', icon: 'none' }); return Promise.reject(error); }; // 导出配置 export default { baseURL, timeout, requestInterceptor, responseInterceptor, errorHandler }; ``` ## 4. API 接口封装 ### 4.1 通用请求方法 ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ### 4.2 业务接口封装 ```javascript // api/user.js import request from '../utils/request'; // 用户相关接口 export default { // 登录 login: (data) => request.post('/api/user/login', data), // 注册 register: (data) => request.post('/api/user/register', data), // 获取用户信息 getUserInfo: () => request.get('/api/user/info'), // 更新用户信息 updateUserInfo: (data) => request.put('/api/user/info', data), // 修改密码 changePassword: (data) => request.post('/api/user/password', data), // 获取地址列表 getAddressList: () => request.get('/api/user/address'), // 添加地址 addAddress: (data) => request.post('/api/user/address', data), // 更新地址 updateAddress: (id, data) => request.put(`/api/user/address/${id}`, data), // 删除地址 deleteAddress: (id) => request.delete(`/api/user/address/${id}`), // 设置默认地址 setDefaultAddress: (id) => request.put(`/api/user/address/${id}/default`) }; ``` ## 5. API 调用示例 ### 5.1 页面中调用 API ```vue ``` ### 5.2 组件中调用 API ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ## 6. API 开发最佳实践 ### 6.1 命名规范 - **文件命名**: 小写字母，单词之间用下划线分隔，如 `user.js` - **方法命名**: 驼峰命名法，如 `getUserInfo` - **URL 命名**: 小写字母，单词之间用连字符分隔，如 `/api/user/info` - **参数命名**: 驼峰命名法，与后端保持一致 ### 6.2 接口设计规范 - **RESTful 风格**: 遵循 RESTful API 设计规范 - **版本控制**: 在 URL 中包含版本号，如 `/api/v1/user/info` - **统一响应格式**: 所有接口返回统一的响应格式 - **错误处理**: 统一的错误码和错误信息 ### 6.3 请求规范 - **请求方法**: 根据操作类型选择合适的 HTTP 方法 - GET: 获取资源 - POST: 创建资源 - PUT: 更新资源 - DELETE: 删除资源 - **请求头**: 统一添加必要的请求头，如 Authorization、Content-Type 等 - **参数传递**: 根据请求方法选择合适的参数传递方式 - GET: 查询参数 - POST/PUT: 请求体 - DELETE: 查询参数或路径参数 ### 6.4 响应规范 - **成功响应**: ```json { "code": 200, "message": "请求成功", "data": {} } ``` - **失败响应**: ```json { "code": 400, "message": "请求失败", "data": {} } ``` ### 6.5 错误处理规范 - **网络错误**: 统一处理网络错误，如超时、断网等 - **业务错误**: 根据错误码处理不同的业务错误 - **登录过期**: 统一处理登录过期，跳转到登录页面 - **错误提示**: 统一的错误提示方式，使用 uni.showToast ## 7. API 性能优化 ### 7.1 请求优化 - **合并请求**: 多个相关请求合并为一个 - **缓存策略**: 对不经常变化的数据使用缓存 - **请求防抖**: 避免频繁发送相同的请求 - **批量操作**: 支持批量操作，减少请求次数 ### 7.2 响应优化 - **数据结构优化**: 优化响应数据结构，减少数据传输量 - **分页处理**: 对列表数据使用分页 - **字段筛选**: 支持字段筛选，只返回需要的字段 - **压缩传输**: 使用 gzip 压缩传输数据 ### 7.3 代码优化 - **模块化**: 按业务模块划分 API 文件 - **复用代码**: 提取通用的请求逻辑 - **减少冗余**: 避免重复的 API 调用 - **代码可读性**: 保持代码清晰易读 ## 8. 常见问题 ### 8.1 跨域问题 - **问题**: 开发环境中遇到跨域问题 - **解决方案**: 在本地开发服务器中配置跨域代理 ### 8.2 Token 过期问题 - **问题**: Token 过期后请求失败 - **解决方案**: 在响应拦截器中处理 Token 过期，跳转到登录页面 ### 8.3 请求超时问题 - **问题**: 网络不稳定时请求超时 - **解决方案**: 设置合理的超时时间，添加网络状态检测 ### 8.4 重复请求问题 - **问题**: 快速点击按钮导致重复请求 - **解决方案**: 添加请求防抖或锁机制 ### 8.5 数据缓存问题 - **问题**: 缓存数据与服务器数据不一致 - **解决方案**: 合理设置缓存过期时间，提供手动刷新机制 ## 9. 参考资源 - [UniApp 网络请求文档](https://uniapp.dcloud.io/api/request/request) - [RESTful API 设计指南](https://restfulapi.cn/) - [Axios 文档](https://axios-http.com/zh/docs/intro) - [HTTP 方法](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Methods) ## 10. 总结本文档描述了 CRMEB 项目中 UniApp 移动端的 API 开发流程，包括 API 接口设计、请求流程、响应处理、错误处理等。遵循本文档的开发规范，可以提高 API 开发的效率和质量，确保应用的稳定性和可靠性。随着业务的发展和技术的演进，API 开发流程也需要不断优化和调整，以适应新的业务需求和技术挑战。 --- ### .Codebuddy/Skills/Uniapp/References/Code Style (.codebuddy/skills/uniapp/references/code_style.md) # UniApp 代码规范文档 ## 1. 概述本文档描述了 CRMEB 项目中 UniApp 移动端的代码规范，包括命名规范、代码风格、文件结构、组件开发等，旨在统一代码风格，提高代码质量和可维护性。 ## 2. 命名规范 ### 2.1 目录命名 - **目录名**: 小写字母，单词之间用下划线分隔 - **示例**: `pages/index/`、`components/common/`、`utils/` - **规范**: 简洁明了，反映目录的功能 ### 2.2 文件命名 - **页面文件**: 小写字母，单词之间用下划线分隔 - **示例**: `index.vue`、`login.vue`、`user_info.vue` - **组件文件**: 大写字母开头的 PascalCase 命名风格 - **示例**: `Button.vue`、`NavBar.vue`、`GoodsList.vue` - **JS 文件**: 小写字母，单词之间用下划线分隔 - **示例**: `user.js`、`request.js`、`util.js` - **CSS/SCSS 文件**: 小写字母，单词之间用下划线分隔 - **示例**: `common.scss`、`theme.scss` ### 2.3 变量命名 - **普通变量**: 驼峰命名法 - **示例**: `userInfo`、`goodsList`、`isLoading` - **常量**: 全大写，单词之间用下划线分隔 - **示例**: `BASE_URL`、`MAX_COUNT`、`DEFAULT_PAGE_SIZE` - **布尔变量**: 以 `is` 开头的驼峰命名法 - **示例**: `isShow`、`isLoading`、`isLogin` ### 2.4 函数命名 - **函数名**: 驼峰命名法，动词开头 - **示例**: `getUserInfo`、`submitForm`、`handleClick` - **方法名**: 驼峰命名法 - **示例**: `data`、`methods`、`computed`、`watch` - **生命周期函数**: 按照 Vue 规范命名 - **示例**: `created`、`mounted`、`beforeDestroy` ### 2.5 组件命名 - **组件名**: PascalCase 命名风格 - **示例**: `Button`、`NavBar`、`GoodsList` - **组件标签**: 小写字母，单词之间用连字符分隔 - **示例**: ``、``、`` ### 2.6 其他命名 - **路由命名**: 小写字母，单词之间用连字符分隔 - **示例**: `/pages/index/index`、`/pages/user/login` - **CSS 类名**: 小写字母，单词之间用连字符分隔 - **示例**: `.user-info`、`.goods-list`、`.btn-primary` - **ID 命名**: 小写字母，单词之间用连字符分隔 - **示例**: `#app`、`#header`、`#footer` ## 3. 代码风格 ### 3.1 缩进 - **缩进方式**: 4 个空格 - **示例**: ```vue ``` ### 3.2 换行 - **标签换行**: 多个属性的标签应该换行 - **示例**: ```vue {{ message }} ``` - **代码块换行**: 逻辑代码块应该换行 - **示例**: ```javascript if (condition) { // 代码块 } else { // 代码块 } ``` ### 3.3 空格 - **运算符空格**: 运算符两侧应该有空格 - **示例**: `a + b`、`x = y`、`i < 10` - **逗号空格**: 逗号后面应该有空格 - **示例**: `[1, 2, 3]`、`{ name: '张三', age: 18 }` - **括号空格**: 括号内侧不应该有空格 - **示例**: `if (condition)`、`function (param)` ### 3.4 注释 - **单行注释**: 使用 `//` 注释 - **示例**: `// 这是单行注释` - **多行注释**: 使用 `/* */` 注释 - **示例**: ```javascript /* * 这是多行注释 * 第二行 */ ``` - **文档注释**: 使用 JSDoc 风格的注释 - **示例**: ```javascript /** * 获取用户信息 * @param {number} id - 用户ID * @returns {Promise} 用户信息 */ async function getUserInfo(id) { // 代码 } ``` ### 3.5 引号 - **字符串**: 使用单引号 `''` - **示例**: `const name = '张三'`、`Hello` - **模板字符串**: 使用反引号 `` ` `` - **示例**: `` const url = `${baseUrl}/api/user` `` - **HTML 属性**: 使用双引号 `""` - **示例**: ``、`

` ## 4. 文件结构 ### 4.1 页面文件结构 ```vue ``` ### 4.2 组件文件结构 ```vue ``` ### 4.3 JS 文件结构 ```javascript // 导入依赖 import request from './request'; // 常量定义 const BASE_URL = 'https://api.crmeb.net'; const TIMEOUT = 10000; // 工具函数 function formatTime(time) { const date = new Date(time); return date.toLocaleString(); } function getRandomNum(min, max) { return Math.floor(Math.random() * (max - min + 1)) + min; } // 导出 export { formatTime, getRandomNum }; // 默认导出 export default { BASE_URL, TIMEOUT }; ``` ## 5. 组件开发规范 ### 5.1 组件设计 - **单一职责**: 每个组件只负责一个功能 - **可复用性**: 设计通用的、可复用的组件 - **可配置性**: 通过 props 提供配置选项 - **事件通信**: 通过事件与父组件通信 ### 5.2 组件使用 - **组件导入**: 使用 import 导入组件 - **示例**: `import Button from '../../components/Button.vue'` - **组件注册**: 在 components 中注册组件 - **示例**: ```javascript components: { Button } ``` - **组件使用**: 使用组件标签 - **示例**: `` ### 5.3 组件通信 - **props 向下传递**: 父组件通过 props 向子组件传递数据 - **events 向上传递**: 子组件通过 events 向父组件传递事件 - **refs 引用**: 通过 refs 引用子组件实例 - **provide/inject**: 祖先组件向后代组件传递数据 ## 6. 页面开发规范 ### 6.1 页面结构 - **模板结构**: 清晰明了，层次分明 - **脚本结构**: 按照 Vue 规范组织代码 - **样式结构**: 模块化，可维护 ### 6.2 数据管理 - **本地数据**: 使用 data 管理组件内部数据 - **计算数据**: 使用 computed 计算衍生数据 - **监听数据**: 使用 watch 监听数据变化 - **全局数据**: 使用 Vuex 管理全局数据 ### 6.3 生命周期管理 - **created**: 初始化数据，发送请求 - **mounted**: 操作 DOM，初始化第三方库 - **beforeDestroy**: 清理定时器，取消订阅 ### 6.4 路由管理 - **路由配置**: 在 pages.json 中配置路由 - **路由跳转**: 使用 uni.navigateTo、uni.redirectTo 等方法 - **路由参数**: 通过 options 或 $route.params 获取路由参数 ## 7. API 调用规范 ### 7.1 API 封装 - **模块化**: 按业务模块封装 API - **统一处理**: 统一处理请求头、响应拦截、错误处理 - **Promise 化**: 使用 Promise 处理异步请求 ### 7.2 API 调用 - **异步处理**: 使用 async/await 处理异步请求 - **错误处理**: 使用 try/catch 捕获错误 - **加载状态**: 显示加载状态，提升用户体验 - **错误提示**: 统一处理错误提示 ### 7.3 示例代码 ```javascript async function getUserInfo() { try { this.loading = true; const res = await userApi.getUserInfo(); this.userInfo = res.data; } catch (error) { console.error('获取用户信息失败:', error); uni.showToast({ title: '获取用户信息失败', icon: 'none' }); } finally { this.loading = false; } } ``` ## 8. 性能优化 ### 8.1 代码优化 - **减少冗余代码**: 避免重复的代码 - **使用计算属性**: 对于复杂的计算，使用 computed - **使用 v-if 和 v-show 合理**: 根据场景选择合适的指令 - **使用 key**: 在 v-for 中使用 key，提高渲染性能 ### 8.2 网络优化 - **合理使用缓存**: 缓存不经常变化的数据 - **减少请求次数**: 合并请求，批量操作 - **使用防抖和节流**: 避免频繁的事件触发 - **延迟加载**: 对于非首屏内容，使用延迟加载 ### 8.3 其他优化 - **减少 DOM 节点**: 简化 DOM 结构 - **优化图片**: 使用合适的图片格式和大小 - **使用虚拟列表**: 对于长列表，使用虚拟列表 - **避免内存泄漏**: 及时清理定时器、事件监听器等 ## 9. 常见问题 ### 9.1 代码风格问题 - **问题**: 代码风格不一致 - **解决方案**: 使用 ESLint 等工具进行代码检查 ### 9.2 性能问题 - **问题**: 页面加载慢，卡顿 - **解决方案**: 优化代码，减少 DOM 操作，使用虚拟列表等 ### 9.3 兼容性问题 - **问题**: 在不同平台上表现不一致 - **解决方案**: 遵循 UniApp 规范，使用条件编译 ### 9.4 维护性问题 - **问题**: 代码难以维护 - **解决方案**: 模块化开发，添加注释，遵循代码规范 ## 10. 参考资源 - [Vue 官方文档](https://cn.vuejs.org/) - [UniApp 官方文档](https://uniapp.dcloud.io/) - [ESLint 官方文档](https://eslint.org/docs/user-guide/) - [Prettier 官方文档](https://prettier.io/docs/en/) - [前端代码规范指南](https://github.com/ecomfe/spec) ## 11. 总结本文档描述了 CRMEB 项目中 UniApp 移动端的代码规范，包括命名规范、代码风格、文件结构、组件开发等。遵循本文档的规范，可以提高代码的可读性、可维护性和可扩展性，确保项目的质量和稳定性。代码规范是团队协作的基础，建议开发团队成员严格遵循本文档的规范，共同维护一个高质量的代码库。 --- ### .Codebuddy/Skills/Uniapp/References/Directory Structure (.codebuddy/skills/uniapp/references/directory_structure.md) # UniApp 目录结构文档 ## 1. 概述本文档描述了 CRMEB 项目中 UniApp 移动端的目录结构，包括各目录的功能、文件组织方式等，旨在帮助开发者理解项目结构，提高开发效率。 ## 2. 项目根目录结构 ``` template/uni-app/ ├── api/ # API 接口目录 ├── config/ # 配置目录 ├── libs/ # 库文件目录 ├── mixins/ # 混入目录 ├── store/ # 状态管理目录 ├── utils/ # 工具类目录 ├── App.vue # 应用入口组件 ├── main.js # 应用入口文件 ├── manifest.json # 应用配置文件 ├── package.json # 项目配置文件 ├── pages.json # 页面路由配置文件 ├── uni.scss # UniApp 全局样式文件 └── vue.config.js # Vue 配置文件 ``` ## 3. API 目录结构 (api/) ``` api/ ├── activity.js # 活动相关接口 ├── admin.js # 管理相关接口 ├── api.js # 基础 API 配置 ├── kefu.js # 客服相关接口 ├── lottery.js # 抽奖相关接口 ├── order.js # 订单相关接口 ├── public.js # 公共接口 ├── store.js # 商城相关接口 └── user.js # 用户相关接口 ``` - **功能**: 封装与后端交互的 API 接口 - **结构**: 按业务模块划分接口文件 - **特性**: 统一处理请求头、响应拦截、错误处理等 - **调用方式**: 通过 `import` 导入使用 ## 4. 配置目录结构 (config/) ``` config/ ├── app.js # 应用配置 ├── cache.js # 缓存配置 └── socket.js # WebSocket 配置 ``` - **功能**: 存储项目的所有配置文件 - **结构**: 按功能模块划分配置文件 - **特性**: 集中管理配置，便于维护和修改 - **加载顺序**: 应用启动时加载 ## 5. 库文件目录结构 (libs/) ``` libs/ ├── chat.js # 聊天相关功能 ├── login.js # 登录相关功能 ├── new_chat.js # 新聊天功能 ├── order.js # 订单相关功能 ├── routine.js # 小程序相关功能 ├── uniApi.js # UniApp API 封装 └── wechat.js # 微信相关功能 ``` - **功能**: 存储通用库文件和功能模块 - **结构**: 按功能划分库文件 - **特性**: 独立于页面代码，便于复用 - **作用**: 提供通用功能和服务 ## 6. 混入目录结构 (mixins/) ``` mixins/ └── color.js # 颜色相关混入 ``` - **功能**: 存储 Vue 混入对象 - **结构**: 按功能划分混入文件 - **特性**: 实现代码复用，避免重复逻辑 - **作用**: 为组件提供共享的方法和数据 ## 7. 状态管理目录结构 (store/) ``` store/ ├── getters.js # 状态获取器 └── index.js # 状态管理入口 ``` - **功能**: 存储 Vuex 状态管理相关文件 - **结构**: 按 Vuex 规范划分文件 - **特性**: 集中管理应用状态，实现组件间通信 - **作用**: 管理全局状态，如用户信息、购物车数据等 ## 8. 工具类目录结构 (utils/) ``` utils/ ├── cache.js # 缓存工具 ├── emoji.js # 表情工具 ├── index.js # 工具类入口 ├── lang.js # 语言工具 ├── request.js # 网络请求工具 ├── theme.js # 主题工具 ├── util.js # 通用工具 └── validate.js # 验证工具 ``` - **功能**: 存储通用工具类 - **结构**: 按功能划分工具文件 - **特性**: 提供通用功能，便于复用 - **作用**: 处理缓存、网络请求、验证等通用操作 ## 9. 页面目录结构 ### 9.1 页面配置 (pages.json) ```json { "pages": [ { "path": "pages/index/index", "style": { "navigationBarTitleText": "首页" } }, { "path": "pages/user/index", "style": { "navigationBarTitleText": "个人中心" } } ], "subPackages": [ { "root": "pages/order", "pages": [ { "path": "index", "style": { "navigationBarTitleText": "订单列表" } } ] } ] } ``` - **功能**: 配置页面路由、导航栏样式等 - **结构**: 按页面层级配置 - **特性**: 支持分包加载，优化应用体积 - **作用**: 定义应用的页面结构和导航样式 ## 10. 应用配置文件 ### 10.1 manifest.json ```json { "name": "CRMEB商城", "appid": "__UNI__APPID__", "description": "CRMEB商城移动端", "versionName": "1.0.0", "versionCode": "100", "transformPx": true, "uniStatistics": { "enable": true }, "app-plus": { "usingComponents": true, "nvueStyleCompiler": "uni-app" }, "mp-weixin": { "appid": "wx_appid", "setting": { "urlCheck": false }, "usingComponents": true } } ``` - **功能**: 配置应用的基本信息、平台配置等 - **结构**: 按平台划分配置 - **特性**: 支持多平台配置，如微信小程序、App 等 - **作用**: 定义应用的全局配置信息 ### 10.2 package.json ```json { "name": "crmeb-uni-app", "version": "1.0.0", "description": "CRMEB商城移动端", "main": "main.js", "scripts": { "dev": "npm run dev:mp-weixin", "dev:mp-weixin": "cross-env NODE_ENV=development UNI_PLATFORM=mp-weixin vue-cli-service uni-build --watch", "build": "npm run build:mp-weixin", "build:mp-weixin": "cross-env NODE_ENV=production UNI_PLATFORM=mp-weixin vue-cli-service uni-build" }, "dependencies": { "vue": "^2.6.11", "vuex": "^3.4.0" } } ``` - **功能**: 配置项目的依赖、脚本等 - **结构**: 标准 npm 配置格式 - **特性**: 管理项目依赖，定义构建脚本 - **作用**: 管理项目的依赖和构建流程 ## 11. 目录结构最佳实践 ### 11.1 命名规范 - **目录名**: 小写字母，单词之间用下划线分隔 - **文件名**: 小写字母，单词之间用下划线分隔 - **组件名**: 使用 PascalCase 命名风格 - **方法名**: 使用 camelCase 命名风格 - **变量名**: 使用 camelCase 命名风格 ### 11.2 组织原则 - **模块化**: 按功能模块组织目录结构 - **分层架构**: 遵循 Vue 组件化开发架构 - **单一职责**: 每个目录和文件只负责一个功能 - **可扩展性**: 便于添加新功能和模块 - **易维护性**: 便于理解和维护 ### 11.3 开发建议 - **遵循 UniApp 规范**: 遵循 UniApp 官方目录结构规范 - **合理划分模块**: 根据业务功能合理划分模块 - **避免目录过深**: 目录层级不宜过深，一般不超过 4 层 - **保持目录整洁**: 及时清理无用文件和目录 - **文档化**: 为重要目录添加说明文档 ## 12. 常见问题 ### 12.1 目录权限问题 - **问题**: 某些目录没有读写权限 - **解决方案**: 确保项目目录有正确的读写权限 ### 12.2 页面路由配置问题 - **问题**: 新增页面后无法访问 - **解决方案**: 在 pages.json 中添加页面路由配置 ### 12.3 分包加载问题 - **问题**: 应用体积过大，无法上传到小程序平台 - **解决方案**: 使用分包加载，将页面划分到不同的分包中 ### 12.4 目录结构混乱 - **问题**: 目录结构不清晰，难以维护 - **解决方案**: 重新组织目录结构，遵循模块化原则 ## 13. 参考资源 - [UniApp 官方文档](https://uniapp.dcloud.io/) - [Vue 官方文档](https://cn.vuejs.org/) - [Vuex 官方文档](https://vuex.vuejs.org/zh/) - [微信小程序开发文档](https://developers.weixin.qq.com/miniprogram/dev/framework/) ## 14. 总结本文档描述了 CRMEB 项目中 UniApp 移动端的目录结构，包括各目录的功能、文件组织方式等。遵循本文档的目录结构规范，可以提高项目的可维护性和可扩展性，便于团队协作开发。随着业务的发展和技术的演进，目录结构也可能需要不断优化和调整，以适应新的业务需求和技术挑战。 --- ### .Trae/Documents/生成Git提交规范技能文件 (.trae/documents/生成Git提交规范技能文件.md) # 生成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】` - **dev-docs目录**：提交时添加前缀 `【开发文档】` - **template目录**：提交时添加前缀 `【前端文件】` #### 2.5 参考资源 - Git官方文档 - 常用git命令 - 提交信息规范指南 ### 3. 验证文件结构确保文件创建在正确的位置，格式符合技能文件的标准规范。 --- ### .Trae/Rules/Project Rules (.trae/rules/project_rules.md) # CRMEB 项目专属 Chat 规则 ## 1. 项目概述 - **名称**: CRMEB 开源商城系统（PHP版） - **技术栈**: ThinkPHP 6 + ElementUI + UniApp - **版本**: 5.6.4 - **许可证**: Apache-2.0 ## 2. 代码风格规范 ### 2.1 PHP 规范 - 遵循 PSR-2 命名规范 - 使用 Restful 接口设计 - 代码分层清晰，注释简洁 - 类名 PascalCase，方法/变量 camelCase - 常量全大写，下划线分隔 - 4空格缩进，禁止制表符 ### 2.2 Vue 规范 - 组件名 PascalCase - 方法/变量 camelCase - 模板使用 kebab-case - 遵循 Vue 官方风格指南 ### 2.3 数据库规范 - 表名小写下划线分隔 - 主键统一命名为 `id` - 外键格式 `表名_id` - 时间字段 `create_time`/`update_time` - 状态字段 `status`，默认值 0 ## 3. 技术选择限制 - **后端**: ThinkPHP 6.x（禁止升级到 7.x） - **前端**: Vue 2.x + ElementUI（Admin）、UniApp（移动端）、Nuxt（PC） - **数据库**: MySQL 5.7~8.0（InnoDB） - **缓存**: Redis（推荐） - **队列**: ThinkPHP 内置队列 - **长连接**: Workerman ## 4. 开发流程规范 ### 4.1 开发环境 - PHP 7.1~7.4 - 开发工具：PHPStorm/VS Code - 版本控制：Git ### 4.2 代码提交 - 提交信息清晰，中文描述 - 格式：`[模块名] 操作描述` - 禁止一次提交多个不相关功能 ### 4.3 二开流程 1. 阅读项目文档和代码注释 2. 使用代码生成工具创建基础功能 3. 遵循系统架构，不破坏原有结构 4. 使用系统事件扩展功能 5. 测试通过后提交 ## 5. 安全规范 - 操作必须记录系统日志 - 敏感数据加密存储 - 禁止直接拼接 SQL，使用参数绑定 - 验证用户输入，防止 XSS/CSRF 攻击 - 使用内置权限管理系统，禁止硬编码权限 - 合理使用缓存，减少数据库查询 - 高并发场景使用队列处理 ## 6. 部署规范 ### 6.1 运行环境 - 操作系统：Linux/Windows - Web 服务器：Nginx/Apache/IIS - PHP 扩展：fileinfo（可选）、redis（可选） - 禁用危险函数：`proc_open`、`pcntl_signal` 等 ### 6.2 启动命令 - 消息队列：`php think queue:listen --queue`（Supervisor 管理） - 长连接：`sudo -u www php think workerman start --d` - 定时任务：`php think timer start --d` ## 7. 常用开发命令 - 代码生成：`php think crmeb:build` - 数据库迁移：`php think migrate:run` - 查看路由：`php think route:list` - 清除缓存：`php think clear` ## 8. 文档与支持 - 官方文档：https://doc.crmeb.com/single_open - 技术社区：https://www.crmeb.com/ask/thread/list/147 ## 9. 注意事项 - 确保代码兼容 PHP 7.1~7.4 - 前端兼容主流浏览器和移动端系统 - 避免复杂 SQL 关联查询 - 大数组分批处理 - 保持代码简洁，注释适当 - 遵循单一职责原则 ## 10. 违规处理 - 违反规范的提交将被拒绝 - 影响系统稳定性的代码将被回滚 - 多次违规者禁止提交代码 --- 以上规则适用于 CRMEB 项目所有开发人员，确保代码一致性、可维护性和安全性。 --- ### .Trae/Skills/Admin Element/References/Api Flow (.trae/skills/admin-element/references/api_flow.md) # Admin-Element 接口请求流程文档 ## 1 API 请求流程概述 Admin-Element 项目的 API 请求流程遵循以下步骤： 1. **接口定义**: 在 `src/api/` 目录下按模块定义 API 接口 2. **请求封装**: 使用 `axios` 封装网络请求，添加拦截器 3. **接口调用**: 在组件或业务逻辑中调用 API 接口 4. **响应处理**: 统一处理 API 响应，包括成功和失败情况 5. **错误处理**: 统一处理网络错误、业务错误等异常情况 6. **数据管理**: 将获取的数据存储到状态管理或组件中 ## 2 网络请求封装 ### 2.1 axios 实例创建在 `src/utils/request.js` 中创建 axios 实例并配置： ```javascript import axios from 'axios' import { Message, Loading } from 'element-ui' import store from '@/store' import { getToken } from '@/utils/auth' // 创建 axios 实例 const service = axios.create({ baseURL: process.env.VUE_APP_BASE_API, // API 基础路径 timeout: 10000, // 请求超时时间 headers: { 'Content-Type': 'application/json;charset=utf-8' } }) ``` ### 2.2 请求拦截器 ```javascript // 请求拦截器 service.interceptors.request.use( config => { // 显示加载动画 if (config.loading !== false) { store.dispatch('app/showLoading') } // 自动添加 token if (store.getters.token) { config.headers['Authorization'] = `Bearer ${getToken()}` } return config }, error => { // 隐藏加载动画 store.dispatch('app/hideLoading') console.error('请求错误:', error) return Promise.reject(error) } ) ``` ### 2.3 响应拦截器 ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ## 3 API 接口定义 ### 3.1 接口文件组织 API 接口按模块组织，存放在 `src/api/` 目录下： ``` src/api/ ├── index.js # API 入口文件 ├── user.js # 用户相关接口 ├── goods.js # 商品相关接口 ├── order.js # 订单相关接口 └── ... # 其他模块接口 ``` ### 3.2 接口定义示例在 `src/api/user.js` 中定义用户相关接口： ```javascript import request from '@/utils/request' export default { // 登录 login(data) { return request({ url: '/admin/login', method: 'post', data }) }, // 获取用户信息 getUserInfo() { return request({ url: '/admin/user/info', method: 'get' }) }, // 获取用户列表 getUserList(params) { return request({ url: '/admin/user/list', method: 'get', params }) }, // 修改用户信息 updateUser(data) { return request({ url: '/admin/user/update', method: 'put', data }) }, // 删除用户 deleteUser(id) { return request({ url: `/admin/user/delete/${id}`, method: 'delete' }) } } ``` ### 3.3 API 入口文件在 `src/api/index.js` 中导出所有 API 模块： ```javascript import user from './user' import goods from './goods' import order from './order' // 导出 API 模块 export default { user, goods, order } ``` ## 4 请求和响应处理 ### 4.1 请求参数处理 #### 4.1.1 GET 请求 ```javascript // 带查询参数的 GET 请求 api.user.getUserList({ page: 1, limit: 10, keyword: 'test' }) ``` #### 4.1.2 POST 请求 ```javascript // 带请求体的 POST 请求 api.user.login({ username: 'admin', password: '123456' }) ``` #### 4.1.3 PUT 请求 ```javascript // 带请求体的 PUT 请求 api.user.updateUser({ id: 1, username: 'newadmin', nickname: '新管理员' }) ``` #### 4.1.4 DELETE 请求 ```javascript // 路径参数的 DELETE 请求 api.user.deleteUser(1) ``` ### 4.2 响应数据结构后端 API 响应数据结构应遵循以下规范： ```javascript { "code": 200, // 状态码，200 表示成功 "message": "操作成功", // 响应消息 "data": { ... } // 响应数据 } ``` ### 4.3 响应处理示例 ```javascript // 在组件中调用 API import api from '@/api' export default { methods: { async fetchUserList() { try { const res = await api.user.getUserList({ page: this.page, limit: this.limit }) // 处理成功响应 this.userList = res.data.list this.total = res.data.total } catch (error) { // 错误已在拦截器中处理，这里可以做额外处理 console.error('获取用户列表失败:', error) } } } } ``` ## 5 错误处理机制 ### 5.1 网络错误 - 网络连接失败 - 请求超时 - 服务器无响应 ### 5.2 业务错误 - 参数错误 (400) - 未授权 (401) - 拒绝访问 (403) - 请求地址不存在 (404) - 服务器内部错误 (500) ### 5.3 业务逻辑错误 - 状态码非 200 的响应 - 业务规则验证失败 ### 5.4 错误处理最佳实践 1. **统一错误处理**: 在响应拦截器中统一处理错误 2. **友好的错误提示**: 向用户显示清晰的错误消息 3. **错误日志记录**: 记录错误信息，便于排查问题 4. **特殊错误处理**: 对 token 过期等特殊情况进行处理 5. **降级处理**: 网络错误时提供合理的降级方案 ## 6 接口调用最佳实践 ### 6.1 使用 async/await ```javascript async fetchData() { try { const res = await api.goods.getGoodsList(this.queryParams) this.goodsList = res.data.list this.total = res.data.total } catch (error) { // 错误处理 } } ``` ### 6.2 加载状态管理 ```javascript export default { data() { return { loading: false, goodsList: [] } }, methods: { async fetchData() { this.loading = true try { const res = await api.goods.getGoodsList(this.queryParams) this.goodsList = res.data.list } catch (error) { // 错误处理 } finally { this.loading = false } } } } ``` ### 6.3 防抖和节流对于频繁触发的请求，使用防抖或节流优化： ```javascript import { debounce } from 'lodash' export default { methods: { // 使用防抖优化搜索请求 search: debounce(async function(query) { try { const res = await api.goods.searchGoods({ keyword: query }) this.searchResults = res.data } catch (error) { // 错误处理 } }, 300) } } ``` ### 6.4 请求取消对于可能重复触发的请求，使用取消令牌避免重复请求： ```javascript import axios from 'axios' export default { data() { return { cancelToken: null } }, methods: { async fetchData() { // 取消之前的请求 if (this.cancelToken) { this.cancelToken.cancel('取消重复请求') } // 创建新的取消令牌 this.cancelToken = axios.CancelToken.source() try { const res = await api.goods.getGoodsList({ page: this.page, limit: this.limit }, { cancelToken: this.cancelToken.token }) this.goodsList = res.data.list } catch (error) { if (axios.isCancel(error)) { console.log('请求已取消:', error.message) } else { // 错误处理 } } } } } ``` ## 7 接口安全 ### 7.1 认证与授权 - 使用 JWT 令牌进行身份认证 - 请求头中携带 Authorization 字段 - 定期刷新令牌，避免过期 ### 7.2 数据加密 - 敏感数据传输加密 - 密码等敏感信息使用 HTTPS 传输 ### 7.3 防止 CSRF 攻击 - 使用 CSRF Token - 验证请求来源 ### 7.4 接口速率限制 - 后端实现接口速率限制 - 前端避免频繁请求 ## 8 性能优化 ### 8.1 请求合并对于多个相同类型的请求，合并为一个请求： ```javascript // 批量获取数据 api.goods.batchGetGoodsInfo(ids) ``` ### 8.2 缓存策略 - 对不常变化的数据进行缓存 - 使用 localStorage 或 sessionStorage 缓存数据 ### 8.3 懒加载 - 按需加载数据 - 滚动到底部加载更多数据 ### 8.4 预加载 - 预加载可能需要的数据 - 提升用户体验 ## 9 调试技巧 ### 9.1 接口调试工具 - 使用 Chrome DevTools 的 Network 面板 - 使用 Postman 等 API 调试工具 ### 9.2 日志记录 - 在开发环境下打印详细的请求和响应信息 - 在生产环境下只记录错误信息 ### 9.3 模拟数据 - 使用 Mock 数据进行前端开发 - 减少对后端接口的依赖 ## 10 总结 Admin-Element 项目的 API 请求流程采用了统一的封装和处理机制，通过 axios 拦截器实现了请求和响应的统一处理，提高了代码的可维护性和可扩展性。开发者应遵循接口定义规范和最佳实践，确保 API 调用的安全性、可靠性和性能。 --- ### .Trae/Skills/Admin Element/References/Code Style (.trae/skills/admin-element/references/code_style.md) # 管理端前端代码规范文档 ## 1. 概述本文档描述了 CRMEB 项目中管理端前端的代码规范，包括命名规范、代码风格、文件结构、组件开发等方面的规范，旨在统一代码风格，提高代码质量和可维护性。 ## 2. 命名规范 ### 2.1 目录命名 - **目录名**: 小写字母，单词之间用连字符分隔 - **示例**: `components/common/`、`pages/user-management/`、`utils/` - **规范**: 简洁明了，反映目录的功能 ### 2.2 文件命名 - **组件文件**: 大写字母开头的 PascalCase 命名风格 - **示例**: `Button.vue`、`UserList.vue`、`Navbar.vue` - **页面文件**: 小写字母，单词之间用连字符分隔 - **示例**: `login.vue`、`user-list.vue`、`dashboard.vue` - **JS 文件**: 小写字母，单词之间用连字符分隔 - **示例**: `api.js`、`request.js`、`util.js` - **CSS/SCSS 文件**: 小写字母，单词之间用连字符分隔 - **示例**: `common.scss`、`theme.scss`、`variables.scss` ### 2.3 变量命名 - **普通变量**: 驼峰命名法 - **示例**: `userInfo`、`goodsList`、`isLoading` - **常量**: 全大写，单词之间用下划线分隔 - **示例**: `BASE_URL`、`MAX_COUNT`、`DEFAULT_PAGE_SIZE` - **布尔变量**: 以 `is` 开头的驼峰命名法 - **示例**: `isShow`、`isLoading`、`isLogin` - **数组变量**: 以复数形式命名 - **示例**: `users`、`goods`、`orders` - **对象变量**: 以单数形式命名 - **示例**: `user`、`good`、`order` ### 2.4 函数命名 - **函数名**: 驼峰命名法，动词开头 - **示例**: `getUserInfo`、`submitForm`、`handleClick` - **方法名**: 驼峰命名法 - **示例**: `data`、`methods`、`computed`、`watch` - **生命周期函数**: 按照 Vue 规范命名 - **示例**: `created`、`mounted`、`beforeDestroy` - **事件处理函数**: 以 `handle` 开头 - **示例**: `handleSubmit`、`handleClick`、`handleChange` ### 2.5 组件命名 - **组件名**: PascalCase 命名风格 - **示例**: `Button`、`UserList`、`Navbar` - **组件标签**: 小写字母，单词之间用连字符分隔 - **示例**: ``、``、`` - **组件文件名**: 与组件名一致，PascalCase 命名 - **示例**: `Button.vue`、`UserList.vue`、`Navbar.vue` ### 2.6 其他命名 - **路由命名**: 小写字母，单词之间用连字符分隔 - **示例**: `/login`、`/user/list`、`/dashboard` - **CSS 类名**: 小写字母，单词之间用连字符分隔 - **示例**: `.user-info`、`.goods-list`、`.btn-primary` - **ID 命名**: 小写字母，单词之间用连字符分隔 - **示例**: `#app`、`#header`、`#footer` - **Vuex 模块命名**: 小写字母，单词之间用连字符分隔 - **示例**: `user`、`goods`、`orders` ## 3. 代码风格 ### 3.1 缩进 - **缩进方式**: 4 个空格 - **示例**: ```vue ``` ### 3.2 换行 - **标签换行**: 多个属性的标签应该换行 - **示例**: ```vue 提交 ``` - **代码块换行**: 逻辑代码块应该换行 - **示例**: ```javascript if (condition) { // 代码块 } else { // 代码块 } ``` ### 3.3 空格 - **运算符空格**: 运算符两侧应该有空格 - **示例**: `a + b`、`x = y`、`i < 10` - **逗号空格**: 逗号后面应该有空格 - **示例**: `[1, 2, 3]`、`{ name: '张三', age: 18 }` - **括号空格**: 括号内侧不应该有空格 - **示例**: `if (condition)`、`function (param)` - **冒号空格**: 对象字面量中冒号后面应该有空格 - **示例**: `{ name: '张三', age: 18 }` ### 3.4 注释 - **单行注释**: 使用 `//` 注释 - **示例**: `// 这是单行注释` - **多行注释**: 使用 `/* */` 注释 - **示例**: ```javascript /* * 这是多行注释 * 第二行 */ ``` - **文档注释**: 使用 JSDoc 风格的注释 - **示例**: ```javascript /** * 获取用户信息 * @param {number} id - 用户ID * @returns {Promise} 用户信息 */ async function getUserInfo(id) { // 代码 } ``` - **组件注释**: 组件使用文档注释 - **示例**: ```vue /** * 用户列表组件 * @props {Array} users - 用户列表数据 * @props {Boolean} loading - 是否加载中 * @events {Function} select - 选择用户时触发 */ ``` ### 3.5 引号 - **字符串**: 使用单引号 `''` - **示例**: `const name = '张三'`、`Hello` - **模板字符串**: 使用反引号 `` ` `` - **示例**: `` const url = `${baseUrl}/api/user` `` - **HTML 属性**: 使用双引号 `""` - **示例**: `

`、`

` ### 3.6 分号 - **语句结束**: 每个语句结束都应该加分号 - **示例**: `const name = '张三';`、`function() {};` ### 3.7 空行 - **代码块之间**: 代码块之间应该有空行 - **示例**: ```javascript function first() { // 代码 } function second() { // 代码 } ``` - **逻辑块之间**: 逻辑块之间应该有空行 - **示例**: ```javascript if (condition) { // 代码 } while (loop) { // 代码 } ``` ## 4. 文件结构 ### 4.1 组件文件结构 ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ### 4.2 页面文件结构 ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ### 4.3 JS 文件结构 ```javascript // 导入依赖 import axios from 'axios'; import { Message } from 'element-ui'; // 常量定义 const BASE_URL = process.env.VUE_APP_API_BASE_URL; const TIMEOUT = 10000; // 创建 axios 实例 const service = axios.create({ baseURL: BASE_URL, timeout: TIMEOUT }); // 请求拦截器 service.interceptors.request.use( config => { // 添加 token const token = localStorage.getItem('token'); if (token) { config.headers['Authorization'] = `Bearer ${token}`; } return config; }, error => { console.error('请求错误:', error); return Promise.reject(error); } ); // 响应拦截器 service.interceptors.response.use( response => { const { data } = response; if (data.code !== 200) { Message.error(data.message || '请求失败'); return Promise.reject(data); } return data; }, error => { console.error('响应错误:', error); Message.error('网络错误，请稍后重试'); return Promise.reject(error); } ); // 工具函数 function formatDate(date) { const d = new Date(date); return d.toLocaleString(); } function deepClone(obj) { return JSON.parse(JSON.stringify(obj)); } // 导出 export { service, formatDate, deepClone }; // 默认导出 export default service; ``` ## 5. 组件开发规范 ### 5.1 组件设计 - **单一职责**: 每个组件只负责一个功能 - **可复用性**: 设计通用的、可复用的组件 - **可配置性**: 通过 props 提供配置选项 - **事件通信**: 通过事件与父组件通信 - **插槽支持**: 提供插槽，增强组件灵活性 ### 5.2 组件使用 - **组件导入**: 使用 import 导入组件 - **示例**: `import Button from '@/components/Button.vue'` - **组件注册**: 在 components 中注册组件 - **示例**: ```javascript components: { Button } ``` - **组件使用**: 使用组件标签 - **示例**: `` - **组件传值**: 通过 props 传递数据 - **示例**: `` - **事件监听**: 监听组件事件 - **示例**: `` ### 5.3 组件通信 - **props 向下传递**: 父组件通过 props 向子组件传递数据 - **events 向上传递**: 子组件通过 events 向父组件传递事件 - **refs 引用**: 通过 refs 引用子组件实例 - **provide/inject**: 祖先组件向后代组件传递数据 - **Vuex 全局状态**: 使用 Vuex 管理全局状态 - **EventBus**: 组件间事件总线 ### 5.4 组件生命周期 - **created**: 初始化数据，发送请求 - **mounted**: 操作 DOM，初始化第三方库 - **beforeUpdate**: 更新前的准备工作 - **updated**: 数据更新后的操作 - **beforeDestroy**: 清理定时器，取消订阅 - **destroyed**: 组件销毁后的清理工作 ### 5.5 组件命名规范 - **组件名**: PascalCase 命名风格 - **组件文件名**: 与组件名一致 - **组件目录**: 按功能分类存放 - **组件前缀**: 通用组件使用统一前缀 ## 6. 页面开发规范 ### 6.1 页面结构 - **模板结构**: 清晰明了，层次分明 - **脚本结构**: 按照 Vue 规范组织代码 - **样式结构**: 模块化，可维护 - **布局规范**: 遵循统一的布局规范 ### 6.2 数据管理 - **本地数据**: 使用 data 管理组件内部数据 - **计算数据**: 使用 computed 计算衍生数据 - **监听数据**: 使用 watch 监听数据变化 - **全局数据**: 使用 Vuex 管理全局数据 ### 6.3 路由管理 - **路由配置**: 在 router 目录中配置路由 - **路由跳转**: 使用 router.push、router.replace 等方法 - **路由参数**: 通过 $route.params 获取路由参数 - **路由守卫**: 使用全局/局部路由守卫 ### 6.4 API 调用 - **API 封装**: 统一封装 API 调用 - **异步处理**: 使用 async/await 处理异步请求 - **错误处理**: 使用 try/catch 捕获错误 - **加载状态**: 显示加载状态，提升用户体验 ### 6.5 用户体验 - **响应式设计**: 适配不同屏幕尺寸 - **加载状态**: 显示加载中提示 - **错误提示**: 显示错误信息 - **成功提示**: 显示操作成功提示 - **表单验证**: 实时表单验证 - **防抖节流**: 优化频繁触发的事件 ## 7. 性能优化 ### 7.1 代码优化 - **减少冗余代码**: 避免重复的代码 - **使用计算属性**: 对于复杂的计算，使用 computed - **使用 v-if 和 v-show 合理**: 根据场景选择合适的指令 - **使用 key**: 在 v-for 中使用 key，提高渲染性能 - **避免频繁更新**: 使用防抖和节流 ### 7.2 网络优化 - **合理使用缓存**: 缓存不经常变化的数据 - **减少请求次数**: 合并请求，批量操作 - **使用 CDN**: 静态资源使用 CDN - **压缩传输**: 使用 gzip 压缩传输数据 ### 7.3 构建优化 - **Tree Shaking**: 移除未使用的代码 - **代码分割**: 按路由分割代码 - **懒加载**: 路由懒加载，组件懒加载 - **预加载**: 预加载关键资源 ### 7.4 其他优化 - **减少 DOM 节点**: 简化 DOM 结构 - **优化图片**: 使用合适的图片格式和大小 - **使用虚拟列表**: 对于长列表，使用虚拟列表 - **避免内存泄漏**: 及时清理定时器、事件监听器等 ## 8. 常见问题 ### 8.1 代码风格问题 - **问题**: 代码风格不一致 - **解决方案**: 使用 ESLint 和 Prettier 统一代码风格 ### 8.2 性能问题 - **问题**: 页面加载慢，卡顿 - **解决方案**: 优化代码，减少 DOM 操作，使用虚拟列表等 ### 8.3 兼容性问题 - **问题**: 在不同浏览器上表现不一致 - **解决方案**: 遵循 Web 标准，使用 polyfill ### 8.4 维护性问题 - **问题**: 代码难以维护 - **解决方案**: 模块化开发，添加注释，遵循代码规范 ### 8.5 命名冲突问题 - **问题**: 命名冲突 - **解决方案**: 使用命名空间，避免全局变量 ## 9. 参考资源 - [Vue 官方风格指南](https://v2.vuejs.org/v2/style-guide/) - [Element UI 官方文档](https://element.eleme.io/#/zh-CN) - [ESLint 官方文档](https://eslint.org/docs/user-guide/) - [Prettier 官方文档](https://prettier.io/docs/en/) - [JavaScript 代码规范](https://github.com/airbnb/javascript) - [CSS 代码规范](https://github.com/airbnb/css) ## 10. 总结本文档描述了 CRMEB 项目中管理端前端的代码规范，包括命名规范、代码风格、文件结构、组件开发等方面的规范。遵循本文档的规范，可以提高代码的可读性、可维护性和可扩展性，确保项目的质量和稳定性。代码规范是团队协作的基础，建议开发团队成员严格遵循本文档的规范，共同维护一个高质量的代码库。 --- ### .Trae/Skills/Admin Element/References/Deploy (.trae/skills/admin-element/references/deploy.md) # 管理端前端部署文档 ## 1. 概述本文档描述了 CRMEB 项目中管理端前端的部署流程，包括构建、部署、配置等环节，旨在规范前端部署流程，确保部署过程的顺利进行和系统的稳定运行。 ## 2. 部署环境 ### 2.1 服务器要求 - **操作系统**: Linux (Ubuntu 18.04+、CentOS 7+) - **Web 服务器**: Nginx 1.14+ 或 Apache 2.4+ - **Node.js**: v12.0.0+ (仅构建时需要) - **npm/yarn**: v6.0.0+ (仅构建时需要) - **内存**: 至少 2GB RAM - **CPU**: 至少 2 核 CPU - **磁盘空间**: 至少 20GB 可用空间 ### 2.2 环境准备 - **Web 服务器配置**: 配置虚拟主机，指向前端构建产物目录 - **SSL 证书**: 配置 HTTPS，使用 SSL 证书 - **防火墙**: 开放 80/443 端口 - **域名**: 配置域名解析，指向服务器 IP ## 3. 构建流程 ### 3.1 开发环境构建 - **命令**: `npm run dev` - **用途**: 本地开发，启动开发服务器 - **访问地址**: `http://localhost:8080` ### 3.2 测试环境构建 - **命令**: `npm run build:test` - **用途**: 测试环境部署 - **构建产物**: `dist/` 目录 ### 3.3 生产环境构建 - **命令**: `npm run build:prod` - **用途**: 生产环境部署 - **构建产物**: `dist/` 目录 ### 3.4 构建优化 - **代码压缩**: 压缩 JS/CSS/HTML 文件 - **资源压缩**: 压缩图片等静态资源 - **Tree Shaking**: 移除未使用的代码 - **代码分割**: 按路由分割代码 - **预加载**: 预加载关键资源 ## 4. 部署方式 ### 4.1 静态部署 #### 4.1.1 Nginx 配置 ```nginx server { listen 80; server_name admin.example.com; return 301 https://$server_name$request_uri; } server { listen 443 ssl http2; server_name admin.example.com; # SSL 配置 ssl_certificate /path/to/ssl/cert.pem; ssl_certificate_key /path/to/ssl/key.pem; ssl_protocols TLSv1.2 TLSv1.3; ssl_ciphers ECDHE-RSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384; ssl_prefer_server_ciphers on; # 静态文件配置 root /path/to/admin/dist; index index.html; # 路由重写，解决单页应用刷新 404 问题 location / { try_files $uri $uri/ /index.html; } # 静态资源缓存 location ~* \.(js|css|png|jpg|jpeg|gif|ico|svg)$ { expires 30d; add_header Cache-Control "public, max-age=2592000"; } # 日志配置 access_log /var/log/nginx/admin_access.log; error_log /var/log/nginx/admin_error.log; } ``` #### 4.1.2 Apache 配置 ```apache ServerName admin.example.com Redirect permanent / https://admin.example.com/ ServerName admin.example.com # SSL 配置 SSLEngine on SSLCertificateFile /path/to/ssl/cert.pem SSLCertificateKeyFile /path/to/ssl/key.pem # 静态文件配置 DocumentRoot /path/to/admin/dist AllowOverride All Require all granted # 路由重写，解决单页应用刷新 404 问题 RewriteEngine On RewriteBase / RewriteRule ^index\.html$ - [L] RewriteCond %{REQUEST_FILENAME} !-f RewriteCond %{REQUEST_FILENAME} !-d RewriteRule . /index.html [L] # 日志配置 ErrorLog ${APACHE_LOG_DIR}/admin_error.log CustomLog ${APACHE_LOG_DIR}/admin_access.log combined ``` ### 4.2 容器部署 #### 4.2.1 Dockerfile ```dockerfile # 基础镜像 FROM node:12-alpine as build # 设置工作目录 WORKDIR /app # 复制依赖文件 COPY package*.json ./ # 安装依赖 RUN npm install # 复制源代码 COPY . . # 构建生产版本 RUN npm run build:prod # 生产镜像 FROM nginx:1.19-alpine # 复制构建产物 COPY --from=build /app/dist /usr/share/nginx/html # 复制 Nginx 配置 COPY nginx.conf /etc/nginx/conf.d/default.conf # 暴露端口 EXPOSE 80 # 启动 Nginx CMD ["nginx", "-g", "daemon off;"] ``` #### 4.2.2 Docker Compose ```yaml version: '3' services: admin: build: . ports: - "80:80" restart: always volumes: - ./ssl:/etc/nginx/ssl environment: - TZ=Asia/Shanghai ``` #### 4.2.3 部署命令 ```bash # 构建镜像 docker build -t crmeb-admin . # 运行容器 docker run -d --name crmeb-admin -p 80:80 crmeb-admin # 使用 Docker Compose docker-compose up -d ``` ### 4.3 CDN 部署 #### 4.3.1 配置 CDN - **源站设置**: 指向静态文件服务器 - **缓存策略**: 配置静态资源缓存时间 - **HTTPS**: 开启 HTTPS - **HTTP/2**: 开启 HTTP/2 #### 4.3.2 部署流程 1. 构建前端项目 2. 上传构建产物到 CDN 3. 配置 CDN 缓存策略 4. 验证部署结果 ## 5. 配置管理 ### 5.1 环境变量配置 - **开发环境**: `.env.development` - **测试环境**: `.env.test` - **生产环境**: `.env.production` ### 5.2 配置示例 ```env # API 基础地址 VUE_APP_API_BASE_URL=https://api.example.com # 静态资源 CDN 地址 VUE_APP_CDN_BASE_URL=https://cdn.example.com # 应用名称 VUE_APP_TITLE=CRMEB 管理后台 # 构建环境 NODE_ENV=production # 构建版本 VUE_APP_VERSION=1.0.0 ``` ### 5.3 运行时配置 - **API 地址**: 可通过环境变量或配置文件修改 - **主题配置**: 可通过配置文件修改 - **权限配置**: 可通过后端 API 动态获取 ## 6. 部署流程 ### 6.1 手动部署 1. **拉取代码**: `git pull origin master` 2. **安装依赖**: `npm install` 3. **构建项目**: `npm run build:prod` 4. **部署文件**: 将 `dist/` 目录复制到服务器 5. **配置 Web 服务器**: 配置虚拟主机 6. **重启服务**: 重启 Web 服务器 7. **验证部署**: 访问管理端地址 ### 6.2 自动化部署 #### 6.2.1 CI/CD 配置 - **Jenkins**: 配置 Jenkins 任务，实现自动构建和部署 - **GitLab CI**: 配置 `.gitlab-ci.yml`，实现自动构建和部署 - **GitHub Actions**: 配置 `.github/workflows/deploy.yml`，实现自动构建和部署 #### 6.2.2 GitHub Actions 示例 ```yaml name: Deploy Admin Frontend on: push: branches: - master jobs: deploy: runs-on: ubuntu-latest steps: - name: Checkout code uses: actions/checkout@v2 - name: Setup Node.js uses: actions/setup-node@v2 with: node-version: '12' - name: Install dependencies run: npm install - name: Build project run: npm run build:prod - name: Deploy to server uses: easingthemes/ssh-deploy@v2.1.5 env: SSH_PRIVATE_KEY: ${{ secrets.SSH_PRIVATE_KEY }} ARGS: '-rltgoDzvO --delete' SOURCE: 'dist/' REMOTE_HOST: ${{ secrets.REMOTE_HOST }} REMOTE_USER: ${{ secrets.REMOTE_USER }} REMOTE_PORT: ${{ secrets.REMOTE_PORT }} TARGET: ${{ secrets.REMOTE_TARGET }} - name: Restart Nginx uses: appleboy/ssh-action@master with: host: ${{ secrets.REMOTE_HOST }} username: ${{ secrets.REMOTE_USER }} key: ${{ secrets.SSH_PRIVATE_KEY }} port: ${{ secrets.REMOTE_PORT }} script: sudo systemctl restart nginx ``` ## 7. 监控与维护 ### 7.1 监控 - **访问日志**: 分析 Web 服务器访问日志 - **错误日志**: 监控 Web 服务器错误日志 - **性能监控**: 监控页面加载速度、响应时间 - **可用性监控**: 监控服务可用性，设置告警 ### 7.2 维护 - **定期更新**: 定期更新前端代码，修复漏洞 - **缓存清理**: 定期清理 CDN 缓存 - **日志清理**: 定期清理日志文件 - **备份**: 定期备份构建产物和配置文件 ### 7.3 常见问题 #### 7.3.1 404 问题 - **问题**: 刷新页面出现 404 错误 - **解决方案**: 配置 Web 服务器，将所有请求重定向到 index.html #### 7.3.2 静态资源加载失败 - **问题**: 静态资源（JS/CSS/图片）加载失败 - **解决方案**: 检查静态资源路径，确保 CDN 配置正确 #### 7.3.3 API 调用失败 - **问题**: 前端无法调用后端 API - **解决方案**: 检查 API 地址配置，确保后端服务正常运行 #### 7.3.4 性能问题 - **问题**: 页面加载慢，卡顿 - **解决方案**: 优化前端代码，使用 CDN，启用 HTTP/2 ## 8. 回滚策略 ### 8.1 版本管理 - **版本号**: 遵循语义化版本规范 - **发布记录**: 记录每次发布的版本和变更内容 - **备份**: 备份每次发布的构建产物 ### 8.2 回滚流程 1. **停止服务**: 停止当前版本的服务 2. **恢复备份**: 恢复到上一个稳定版本 3. **重启服务**: 启动恢复后的服务 4. **验证回滚**: 验证服务是否正常运行 ### 8.3 回滚方案 - **手动回滚**: 手动复制备份文件到部署目录 - **自动化回滚**: 通过 CI/CD 工具实现自动回滚 - **容器回滚**: 通过 Docker 镜像版本回滚 ## 9. 安全部署 ### 9.1 HTTPS 配置 - **SSL 证书**: 使用正规 CA 签发的 SSL 证书 - **证书续期**: 定期续期 SSL 证书 - **HTTP 重定向**: 将 HTTP 请求重定向到 HTTPS ### 9.2 安全头部 - **Content-Security-Policy**: 配置内容安全策略 - **X-Content-Type-Options**: 防止 MIME 类型嗅探 - **X-Frame-Options**: 防止点击劫持 - **X-XSS-Protection**: 启用 XSS 过滤 ### 9.3 访问控制 - **IP 白名单**: 限制管理端访问 IP - **登录验证**: 强制登录验证 - **权限控制**: 基于角色的权限控制 - **会话管理**: 安全的会话管理 ### 9.4 漏洞防护 - **依赖扫描**: 定期扫描依赖包漏洞 - **代码审计**: 定期进行代码安全审计 - **渗透测试**: 定期进行渗透测试 ## 10. 最佳实践 ### 10.1 构建优化 - **使用缓存**: 缓存依赖包和构建产物 - **并行构建**: 使用多线程并行构建 - **增量构建**: 只构建变更的文件 - **构建日志**: 保存构建日志，便于排查问题 ### 10.2 部署优化 - **灰度发布**: 采用灰度发布策略 - **蓝绿部署**: 采用蓝绿部署策略 - **滚动部署**: 采用滚动部署策略 - **金丝雀发布**: 采用金丝雀发布策略 ### 10.3 监控优化 - **实时监控**: 实时监控系统运行状态 - **告警机制**: 设置合理的告警阈值 - **日志聚合**: 聚合多服务器日志 - **性能分析**: 定期分析系统性能 ### 10.4 安全优化 - **最小权限**: 遵循最小权限原则 - **定期更新**: 定期更新依赖和系统 - **安全扫描**: 定期进行安全扫描 - **应急响应**: 建立安全应急响应机制 ## 11. 总结本文档描述了 CRMEB 项目中管理端前端的部署流程，包括构建、部署、配置等环节，以及相关的最佳实践和常见问题解决方案。遵循本文档的部署流程和规范，可以确保前端部署的顺利进行和系统的稳定运行，同时提高部署效率和系统安全性。随着项目的发展和技术的演进，部署流程也需要不断优化和调整，以适应新的业务需求和技术挑战。 --- ### .Trae/Skills/Admin Element/References/Development Flow (.trae/skills/admin-element/references/development_flow.md) # 管理端前端开发流程文档 ## 1. 概述本文档描述了 CRMEB 项目中管理端前端的开发流程，包括需求分析、设计、编码、测试、部署等环节，旨在规范前端开发流程，提高开发效率和代码质量。 ## 2. 开发流程 ### 2.1 需求分析 #### 2.1.1 需求获取 - **需求来源**: 产品经理、业务方、后端开发、测试人员 - **需求形式**: PRD 文档、需求评审会议、邮件、即时通讯工具 - **需求内容**: 功能需求、非功能需求、UI/UX 需求 #### 2.1.2 需求评审 - **评审人员**: 前端开发、后端开发、产品经理、测试人员 - **评审内容**: 需求可行性、技术实现方案、时间评估、风险评估 - **评审输出**: 评审纪要、任务分解、时间计划 #### 2.1.3 需求确认 - **确认内容**: 需求细节、技术方案、交付标准 - **确认形式**: 需求确认邮件、需求确认会议 - **确认输出**: 需求确认文档 ### 2.2 设计阶段 #### 2.2.1 UI 设计 - **设计工具**: Figma、Sketch、Adobe XD - **设计内容**: 页面布局、组件样式、交互设计、色彩方案 - **设计输出**: UI 设计稿、设计规范文档 #### 2.2.2 技术设计 - **设计内容**: 技术选型、架构设计、目录结构、组件设计、API 设计 - **设计输出**: 技术设计文档、架构图、组件设计图 #### 2.2.3 原型设计 - **原型工具**: Axure、Figma、Sketch - **原型内容**: 页面原型、交互原型、流程原型 - **原型输出**: 交互式原型、流程图 ### 2.3 编码实现 #### 2.3.1 环境搭建 - **开发环境**: Node.js、npm/yarn、VS Code、Git - **依赖安装**: `npm install` 或 `yarn install` - **开发工具**: Vue DevTools、Chrome DevTools #### 2.3.2 代码开发 - **开发顺序**: 基础组件 → 页面组件 → 业务逻辑 → 测试 - **开发规范**: 遵循代码规范、命名规范、文档规范 - **代码质量**: 代码可读性、可维护性、可扩展性 #### 2.3.3 代码审查 - **审查人员**: 前端团队成员 - **审查内容**: 代码质量、功能实现、性能优化、安全防护 - **审查工具**: GitLab/GitHub Code Review、ESLint、Prettier ### 2.4 测试验证 #### 2.4.1 单元测试 - **测试工具**: Jest、Vue Test Utils - **测试内容**: 组件测试、工具函数测试、状态管理测试 - **测试覆盖率**: 关键功能测试覆盖率 ≥ 80% #### 2.4.2 功能测试 - **测试人员**: 前端开发、测试人员 - **测试内容**: 功能实现、交互体验、页面布局、响应式设计 - **测试工具**: 浏览器、测试管理工具 #### 2.4.3 性能测试 - **测试工具**: Chrome DevTools、Lighthouse、WebPageTest - **测试内容**: 首屏加载速度、页面渲染性能、内存使用、网络请求 - **测试指标**: FCP、LCP、TTI、CLS、FID #### 2.4.4 兼容性测试 - **测试浏览器**: Chrome、Firefox、Safari、Edge - **测试分辨率**: 1024x768、1366x768、1920x1080 - **测试内容**: 页面显示、功能实现、交互体验 ### 2.5 部署上线 #### 2.5.1 构建打包 - **构建命令**: `npm run build:prod` - **构建产物**: 静态资源文件 - **构建优化**: 代码压缩、资源压缩、Tree Shaking #### 2.5.2 部署配置 - **部署环境**: 测试环境、预发布环境、生产环境 - **部署工具**: Nginx、Apache、CDN - **配置内容**: 服务器配置、域名配置、HTTPS 配置 #### 2.5.3 上线发布 - **发布流程**: 测试环境 → 预发布环境 → 生产环境 - **发布时间**: 非业务高峰期 - **发布监控**: 实时监控系统运行状态 #### 2.5.4 上线后验证 - **验证内容**: 功能验证、性能验证、兼容性验证 - **验证人员**: 前端开发、测试人员、产品经理 - **验证输出**: 上线验证报告 ## 3. 开发规范 ### 3.1 代码规范 - **ESLint 规则**: 遵循 Vue 官方推荐的 ESLint 规则 - **Prettier 配置**: 统一代码格式化规则 - **代码缩进**: 4 空格缩进 - **命名规范**: 组件名 PascalCase，变量/方法名 camelCase，常量全大写 ### 3.2 提交规范 - **提交信息格式**: `[类型] 描述` - **类型**: feat（新功能）、fix（修复）、docs（文档）、style（样式）、refactor（重构）、test（测试）、chore（构建/依赖） - **提交频率**: 小步提交，每个功能或修复一个提交 - **提交内容**: 只提交相关代码，不提交无关文件 ### 3.3 分支规范 - **主分支**: master（生产环境）、develop（开发环境） - **功能分支**: feature/功能名称 - **修复分支**: fix/修复内容 - **发布分支**: release/版本号 - **分支管理**: 定期清理无用分支 ### 3.4 文档规范 - **README.md**: 项目说明、安装说明、开发说明 - **组件文档**: 组件使用说明、Props、Events、Slots - **API 文档**: API 接口说明、请求参数、响应格式 - **开发文档**: 开发流程、编码规范、部署流程 ## 4. 开发工具 ### 4.1 开发环境 - **Node.js**: v12.0.0+ - **npm**: v6.0.0+ 或 **yarn**: v1.22.0+ - **VS Code**: 最新版本 - **Git**: 最新版本 ### 4.2 编辑器插件 - **Vetur**: Vue 开发插件 - **ESLint**: 代码检查插件 - **Prettier**: 代码格式化插件 - **GitLens**: Git 增强插件 - **Debugger for Chrome**: 浏览器调试插件 - **Auto Close Tag**: 自动闭合标签 - **Auto Rename Tag**: 自动重命名标签 ### 4.3 开发工具 - **Vue DevTools**: Vue 开发调试工具 - **Chrome DevTools**: 浏览器调试工具 - **Postman**: API 测试工具 - **Charles**: 网络调试工具 - **Figma/Sketch**: UI 设计工具 - **Zeplin**: 设计协作工具 ### 4.4 构建工具 - **Webpack**: 模块打包工具 - **Babel**: JavaScript 编译器 - **Sass/Less**: CSS 预处理器 - **ESLint**: 代码检查工具 - **Prettier**: 代码格式化工具 ## 5. 常见问题及解决方案 ### 5.1 需求变更 - **问题**: 开发过程中需求发生变更 - **解决方案**: 1. 记录需求变更内容 2. 评估变更影响范围 3. 与产品经理确认变更可行性 4. 调整开发计划和时间评估 5. 通知相关团队成员 ### 5.2 技术难题 - **问题**: 遇到技术难题无法解决 - **解决方案**: 1. 查阅相关文档和资料 2. 寻求团队成员帮助 3. 咨询外部专家 4. 尝试替代方案 5. 记录解决方案，形成知识库 ### 5.3 时间紧张 - **问题**: 开发时间紧张，任务无法按时完成 - **解决方案**: 1. 评估任务优先级 2. 与产品经理沟通，调整需求优先级 3. 寻求团队成员协助 4. 优化开发流程，提高开发效率 5. 加班完成（作为最后手段） ### 5.4 代码冲突 - **问题**: Git 代码冲突 - **解决方案**: 1. 拉取最新代码 2. 手动解决冲突 3. 测试冲突解决后的代码 4. 提交解决冲突后的代码 5. 通知相关团队成员 ### 5.5 线上问题 - **问题**: 线上出现问题 - **解决方案**: 1. 快速定位问题原因 2. 制定解决方案 3. 紧急修复并部署 4. 验证修复效果 5. 分析问题原因，避免类似问题再次发生 ## 6. 最佳实践 ### 6.1 开发前准备 - **需求确认**: 确保需求理解正确 - **技术方案**: 制定详细的技术实现方案 - **环境搭建**: 确保开发环境配置正确 - **依赖安装**: 安装必要的依赖包 ### 6.2 编码实现 - **组件化开发**: 封装可复用组件 - **模块化开发**: 按功能模块组织代码 - **代码复用**: 提取公共逻辑，避免重复代码 - **性能优化**: 考虑代码性能，避免性能瓶颈 - **安全性**: 考虑代码安全性，避免安全漏洞 ### 6.3 测试验证 - **单元测试**: 编写关键功能的单元测试 - **功能测试**: 全面测试功能实现 - **性能测试**: 测试页面性能 - **兼容性测试**: 测试不同浏览器兼容性 - **用户体验测试**: 测试页面交互体验 ### 6.4 部署上线 - **构建优化**: 优化构建产物 - **部署策略**: 采用灰度发布策略 - **监控告警**: 配置系统监控和告警 - **回滚方案**: 准备系统回滚方案 - **上线验证**: 上线后及时验证系统状态 ### 6.5 维护迭代 - **问题跟踪**: 及时跟踪和解决线上问题 - **代码维护**: 定期维护和优化代码 - **文档更新**: 及时更新相关文档 - **技术债务**: 定期清理技术债务 - **知识共享**: 分享开发经验和解决方案 ## 7. 团队协作 ### 7.1 协作模式 - **敏捷开发**: 采用 Scrum 或 Kanban 敏捷开发模式 - **每日站会**: 每日 15 分钟站会，同步开发进度 - **迭代周期**: 2-4 周一个迭代周期 - **迭代回顾**: 迭代结束后进行回顾，总结经验教训 ### 7.2 沟通工具 - **即时通讯**: 企业微信、钉钉、Slack - **项目管理**: Jira、Trello、GitHub Issues - **代码托管**: GitLab、GitHub、Gitee - **文档协作**: 语雀、Confluence、Google Docs ### 7.3 知识共享 - **技术分享**: 定期组织技术分享会议 - **代码审查**: 相互代码审查，分享编码经验 - **问题讨论**: 定期组织问题讨论会议 - **知识库**: 建立团队知识库，积累技术经验 ## 8. 总结本文档描述了 CRMEB 项目中管理端前端的开发流程，包括需求分析、设计、编码、测试、部署等环节，以及相关的开发规范和最佳实践。遵循本文档的开发流程和规范，可以提高前端开发效率和代码质量，减少开发过程中的问题和风险，确保项目的顺利进行。同时，开发流程也需要根据项目的实际情况进行调整和优化，以适应不同项目的需求和特点。 --- ### .Trae/Skills/Admin Element/References/Directory Structure (.trae/skills/admin-element/references/directory_structure.md) # Admin-Element 目录结构文档 ## 1 项目根目录结构 ``` template/ # 前端项目目录 ├── admin-element/ # 管理端前端项目 │ ├── public/ # 静态资源目录 │ │ ├── favicon.ico # 网站图标 │ │ ├── index.html # 入口HTML文件 │ │ └── static/ # 静态资源文件 │ ├── src/ # 源代码目录 │ │ ├── api/ # API接口定义 │ │ ├── assets/ # 静态资源 │ │ ├── components/ # 通用组件 │ │ ├── config/ # 配置文件 │ │ ├── directive/ # 自定义指令 │ │ ├── filters/ # 过滤器 │ │ ├── layout/ # 布局组件 │ │ ├── router/ # 路由配置 │ │ ├── store/ # 状态管理 │ │ ├── styles/ # 样式文件 │ │ ├── utils/ # 工具函数 │ │ ├── views/ # 页面组件 │ │ ├── App.vue # 根组件 │ │ └── main.js # 入口文件 │ ├── tests/ # 测试文件 │ ├── .env.* # 环境变量配置 │ ├── babel.config.js # Babel配置 │ ├── package.json # 项目依赖 │ ├── vue.config.js # Vue配置 │ └── README.md # 项目说明 ``` ## 2 主要目录说明 ### 2.1 public/ 目录 - **favicon.ico**: 网站图标文件 - **index.html**: 应用入口HTML文件，Vue应用将挂载到这个文件中 - **static/**: 静态资源目录，存放不需要经过webpack处理的静态文件 ### 2.2 src/ 目录 #### 2.2.1 api/ 目录 - 定义所有API接口请求 - 按模块组织API文件 - 包含接口调用方法和参数配置 #### 2.2.2 assets/ 目录 - **images/**: 图片资源 - **icons/**: 图标资源 - **styles/**: 全局样式文件 - 其他静态资源文件 #### 2.2.3 components/ 目录 - **base/**: 基础组件 - **business/**: 业务组件 - **common/**: 通用组件 - 可复用的Vue组件 #### 2.2.4 config/ 目录 - **index.js**: 主配置文件 - **router.config.js**: 路由配置 - **menu.config.js**: 菜单配置 - **theme.config.js**: 主题配置 - 其他系统配置文件 #### 2.2.5 directive/ 目录 - 自定义Vue指令 - 如权限控制、表单验证等指令 #### 2.2.6 filters/ 目录 - 自定义Vue过滤器 - 如日期格式化、数字格式化等 #### 2.2.7 layout/ 目录 - **components/**: 布局组件 - **index.vue**: 主布局文件 - **AppMain.vue**: 内容区域组件 - **Navbar.vue**: 导航栏组件 - **Sidebar.vue**: 侧边栏组件 #### 2.2.8 router/ 目录 - **index.js**: 路由配置主文件 - **modules/**: 按模块组织的路由配置 - 路由守卫配置 #### 2.2.9 store/ 目录 - **index.js**: 状态管理主文件 - **modules/**: 按模块组织的状态管理 - **getters.js**: 全局计算属性 #### 2.2.10 styles/ 目录 - **index.scss**: 全局样式入口 - **variables.scss**: 全局变量 - **mixins.scss**: 混合器 - **reset.scss**: 重置样式 #### 2.2.11 utils/ 目录 - **request.js**: 网络请求封装 - **auth.js**: 认证相关工具 - **tools.js**: 通用工具函数 - **storage.js**: 存储工具 #### 2.2.12 views/ 目录 - 按业务模块组织页面组件 - 每个模块一个目录 - 包含页面组件和相关子组件 #### 2.2.13 App.vue - 应用根组件 - 包含全局布局结构 #### 2.2.14 main.js - 应用入口文件 - 初始化Vue实例 - 加载插件和全局配置 ### 2.3 配置文件 #### 2.3.1 package.json - 项目依赖配置 - 脚本命令配置 - 项目信息配置 #### 2.3.2 vue.config.js - Vue CLI配置 - 构建配置 - 代理配置 #### 2.3.3 babel.config.js - Babel转译配置 #### 2.3.4 .env.* - 环境变量配置文件 - **.env.development**: 开发环境 - **.env.production**: 生产环境 - **.env.staging**: 测试环境 ## 3 目录规范 ### 3.1 命名规范 - 目录名使用小写字母，多单词用连字符(-)分隔 - 文件名使用小写字母，多单词用连字符(-)分隔 - 组件名使用 PascalCase 命名法 ### 3.2 目录组织原则 1. **按功能模块组织**: 相关功能的文件放在同一目录 2. **模块化**: 每个模块保持相对独立 3. **可扩展性**: 目录结构应易于扩展和维护 4. **一致性**: 保持目录结构的一致性 ### 3.3 特殊目录处理 - **components/**: 只存放可复用组件 - **views/**: 存放页面级组件 - **api/**: 按模块组织API接口 - **store/modules/**: 按模块组织状态管理 ## 4 最佳实践 ### 4.1 目录使用建议 - 新增业务模块时，在 views/ 下创建对应的目录 - 新增可复用组件时，放在 components/ 下的对应子目录 - 新增API接口时，在 api/ 下按模块组织 - 新增状态管理时，在 store/modules/ 下创建对应模块 ### 4.2 目录结构维护 - 定期清理无用文件和目录 - 保持目录结构的清晰和整洁 - 遵循统一的命名规范 - 文档及时更新，反映目录结构的变化 ## 5 常见问题 ### 5.1 目录权限问题 - 确保目录权限正确，避免构建时出现权限错误 ### 5.2 路径引用问题 - 使用相对路径或别名路径引用文件 - 避免使用绝对路径 ### 5.3 目录结构优化 - 随着项目规模增大，适时调整目录结构 - 保持目录层级合理，避免过深的嵌套 ## 6 总结 Admin-Element 项目采用标准的 Vue + ElementUI 项目结构，通过清晰的目录组织和命名规范，提高了代码的可维护性和可扩展性。开发者应遵循目录结构规范，合理组织代码，确保项目的长期可维护性。 --- ### .Trae/Skills/Dev Docs Generate/SKILL (.trae/skills/dev-docs-generate/SKILL.md) --- name: dev-docs-generate description: 开发文档生成规范，快速生成开发文档，自动放到docs目录下，方便技术快速了解项目，能快速入手开发 --- # CRMEB 项目文档写作规范 ## 0. 自动调用场景 ### 0.1 触发条件 - **目录浏览时**：当浏览文档相关目录时自动调用 - 打开 `dev-docs/` 目录时触发 - 打开 `dev-docs/phpapi/` 目录时触发 - 打开 `dev-docs/admin/` 目录时触发 - 打开 `dev-docs/uniapp/` 目录时触发 - 打开 `dev-docs/nuxt/` 目录时触发 - **文档创建时**：当创建新的 Markdown 文档文件时自动调用 - **文档编辑时**：当编辑现有文档文件时自动调用 - **关键词触发**：当文档内容包含以下关键词时自动调用 - `文档`、`说明`、`指南`、`手册`、`规范` - `API`、`接口`、`部署`、`开发`、`需求` ### 0.2 适用文件类型 - `.md` (Markdown 文件) - `.txt` (文本文件) - `.doc`/`.docx` (Word 文档) - `.pdf` (PDF 文档) ### 0.3 调用优先级 - 当多个技能同时触发时，文档规范技能优先级中等 - 仅在文档相关操作时被触发 - 不影响其他技能的正常使用 ## 1. 文档类型 ### 1.1 技术文档 - **API 文档**：接口设计、参数说明、返回格式 - **开发文档**：架构设计、模块说明、开发流程 - **部署文档**：环境要求、安装步骤、配置说明 - **接口文档**：接口列表、请求参数、返回示例 ### 1.2 业务文档 - **需求文档**：功能描述、业务流程、数据结构 - **测试文档**：测试用例、测试结果、缺陷报告 - **用户手册**：功能介绍、操作指南、常见问题 ## 2. 格式规范 ### 2.1 文件名规范 - 使用小写下划线分隔 - 清晰描述文档内容 - 示例：`api接口文档.md`、`部署指南.md` ### 2.2 标题层级 - 使用 `#` 表示标题层级 - 一级标题：文档主题 - 二级标题：主要章节 - 三级标题：细分内容 - 最多使用四级标题 ### 2.3 文本格式 - 正文使用宋体/无衬线字体，14px - 代码块使用 ``` 包裹，指定语言 - 列表使用 `-` 或 `1.` 表示 - 强调内容使用 `**加粗**` 或 `*斜体*` ### 2.4 代码规范 - 代码块必须指定语言 - 缩进一致，格式清晰 - 关键代码添加注释 - 示例： ```php // 获取用户信息 public function getUserInfo($id) { return $this->where('id', $id)->find(); } ``` ### 2.5 文档存放目录 - 文档保存到 `dev-docs` 目录中 - 后端接口文档存放 `dev-docs/phpapi` 目录中 - 后端前端 ElementUI（Admin）文档存放 `dev-docs/admin` 目录中 - 移动端前端 UniApp（移动端）文档存放 `dev-docs/uniapp` 目录中 - PC 端 Nuxt（PC）文档存放 `dev-docs/nuxt` 目录中 ## 3. 内容要求 ### 3.1 结构清晰 - 引言：文档目的、适用范围 - 主体：详细内容，逻辑连贯 - 结论：总结、后续计划 - 附录：参考资料、术语表 ### 3.2 语言要求 - 使用简洁、准确的语言 - 避免歧义，术语统一 - 中文文档使用规范汉字 - 英文文档语法正确 ### 3.3 内容完整性 - 包含必要的背景信息 - 步骤清晰，可操作 - 提供示例和截图 - 注明版本和更新日期 ### 3.4 可维护性 - 定期更新，保持时效性 - 使用版本控制管理文档 - 注明作者和联系方式 - 便于搜索和导航 ## 4. 文档工具 ### 4.1 编辑工具 - 推荐使用 Markdown 格式 - 支持工具：VS Code、Typora、语雀 - 图片存储：项目内部或图床 ### 4.2 版本管理 - 与代码一同纳入 Git 管理 - 提交信息清晰，说明文档变更 - 定期备份，防止丢失 ## 5. 审核与发布 ### 5.1 审核流程 1. 编写完成后进行自我检查 2. 提交给相关人员审核 3. 根据反馈修改完善 4. 最终确认发布 ### 5.2 发布规范 - 发布前检查格式和内容 - 明确文档版本号 - 通知相关人员文档更新 - 确保文档可访问 ## 6. Markdown 文档模板 ```markdown # 文档标题 ## 1. 引言 ### 1.1 文档目的 - 说明文档的编写目的 ### 1.2 适用范围 - 说明文档的适用范围 ### 1.3 术语定义 - 解释文档中使用的专业术语 ## 2. 主体内容 ### 2.1 功能描述 - 详细描述功能特性 ### 2.2 实现方案 - 说明技术实现方案 ### 2.3 代码示例 ```php // 代码示例 function example() { return true; } ``` ### 2.4 操作步骤 1. 第一步操作 2. 第二步操作 3. 第三步操作 ## 3. 结论 ### 3.1 总结 - 总结文档的主要内容 ### 3.2 后续计划 - 说明后续的工作计划 ## 4. 附录 ### 4.1 参考资料 - 列出参考的文档和资源 ### 4.2 联系方式 - 提供联系人信息 --- **版本**: 1.0 **作者**: 文档作者 **更新日期**: YYYY-MM-DD ``` ## 7. Markdown 语法指南 ### 7.1 标题 ```markdown # 一级标题 ## 二级标题 ### 三级标题 #### 四级标题 ``` ### 7.2 列表 - 无序列表项 1 - 无序列表项 2 - 嵌套列表项 1. 有序列表项 1 2. 有序列表项 2 ### 7.3 链接和图片 - [链接文本](https://example.com) - ### 7.4 代码块 ```javascript // JavaScript 代码 console.log('Hello World'); ``` ### 7.5 表格 | 表头 1 | 表头 2 | | ------ | ------ | | 单元格 1 | 单元格 2 | | 单元格 3 | 单元格 4 | ### 7.6 引用 > 这是一段引用文本 ## 8. 注意事项 - 避免冗长，重点突出 - 保持格式统一 - 定期更新文档 - 确保内容准确无误 - 便于他人理解和使用 - 生成文档最后说明由AI生成 --- 以上规范适用于 CRMEB 项目所有文档写作，确保文档质量和一致性。 --- ### .Trae/Skills/Git Commit/SKILL (.trae/skills/git-commit/SKILL.md) --- 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使用规范 - 代码审查流程指南 --- ### .Trae/Skills/Php Api/References/Api Flow (.trae/skills/php-api/references/api_flow.md) # 接口请求文档 ## 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/) --- ### .Trae/Skills/Php Api/References/Db Design (.trae/skills/php-api/references/db_design.md) # 数据库设计文档 ## 1. 概述本文档描述了 CRMEB 项目的数据库设计，包括数据库架构、表结构、索引设计、关系设计等，旨在规范数据库设计，提高数据库性能和可维护性。 ## 2. 数据库架构 ### 2.1 整体架构 - **数据库系统**: MySQL 5.7~8.0 - **存储引擎**: InnoDB (默认) - **字符集**: utf8mb4 - **排序规则**: utf8mb4_general_ci - **连接池**: 建议使用 - **SQL文件位置**: `public/install/crmeb.sql` ### 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` | `VARCHAR` | 50 | `NOT NULL` | 用户名 | | `password` | `VARCHAR` | 255 | `NOT NULL` | 密码 | | `nickname` | `VARCHAR` | 50 | `NOT NULL` | 昵称 | | `avatar` | `VARCHAR` | 255 | | 头像 | | `mobile` | `VARCHAR` | 20 | | 手机号 | | `email` | `VARCHAR` | 100 | | 邮箱 | | `status` | `TINYINT` | 1 | `DEFAULT 1` | 状态 | | `create_time` | `DATETIME` | | `DEFAULT CURRENT_TIMESTAMP` | 创建时间 | | `update_time` | `DATETIME` | | `DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP` | 更新时间 | | `delete_time` | `DATETIME` | | | 删除时间 | ### 4.2 商品表 (`product`) | 字段名 | 数据类型 | 长度 | 约束 | 描述 | |-------|---------|------|------|------| | `id` | `INT` | 11 | `PRIMARY KEY AUTO_INCREMENT` | 商品ID | | `name` | `VARCHAR` | 255 | `NOT NULL` | 商品名称 | | `category_id` | `INT` | 11 | `NOT NULL` | 分类ID | | `price` | `DECIMAL` | 10,2 | `NOT NULL` | 价格 | | `stock` | `INT` | 11 | `NOT NULL` | 库存 | | `status` | `TINYINT` | 1 | `DEFAULT 1` | 状态 | | `create_time` | `DATETIME` | | `DEFAULT CURRENT_TIMESTAMP` | 创建时间 | | `update_time` | `DATETIME` | | `DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP` | 更新时间 | | `delete_time` | `DATETIME` | | | 删除时间 | ### 4.3 订单表 (`order`) | 字段名 | 数据类型 | 长度 | 约束 | 描述 | |-------|---------|------|------|------| | `id` | `INT` | 11 | `PRIMARY KEY AUTO_INCREMENT` | 订单ID | | `order_sn` | `VARCHAR` | 32 | `NOT NULL UNIQUE` | 订单号 | | `user_id` | `INT` | 11 | `NOT NULL` | 用户ID | | `total_price` | `DECIMAL` | 10,2 | `NOT NULL` | 总价 | | `status` | `TINYINT` | 1 | `DEFAULT 0` | 状态 | | `create_time` | `DATETIME` | | `DEFAULT CURRENT_TIMESTAMP` | 创建时间 | | `update_time` | `DATETIME` | | `DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP` | 更新时间 | | `delete_time` | `DATETIME` | | | 删除时间 | ### 4.4 分类表 (`category`) | 字段名 | 数据类型 | 长度 | 约束 | 描述 | |-------|---------|------|------|------| | `id` | `INT` | 11 | `PRIMARY KEY AUTO_INCREMENT` | 分类ID | | `name` | `VARCHAR` | 50 | `NOT NULL` | 分类名称 | | `parent_id` | `INT` | 11 | `DEFAULT 0` | 父分类ID | | `sort` | `INT` | 11 | `DEFAULT 0` | 排序 | | `status` | `TINYINT` | 1 | `DEFAULT 1` | 状态 | | `create_time` | `DATETIME` | | `DEFAULT CURRENT_TIMESTAMP` | 创建时间 | | `update_time` | `DATETIME` | | `DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP` | 更新时间 | | `delete_time` | `DATETIME` | | | 删除时间 | ### 4.5 地址表 (`address`) | 字段名 | 数据类型 | 长度 | 约束 | 描述 | |-------|---------|------|------|------| | `id` | `INT` | 11 | `PRIMARY KEY AUTO_INCREMENT` | 地址ID | | `user_id` | `INT` | 11 | `NOT NULL` | 用户ID | | `name` | `VARCHAR` | 50 | `NOT NULL` | 收货人姓名 | | `mobile` | `VARCHAR` | 20 | `NOT NULL` | 手机号 | | `province` | `VARCHAR` | 50 | `NOT NULL` | 省份 | | `city` | `VARCHAR` | 50 | `NOT NULL` | 城市 | | `district` | `VARCHAR` | 50 | `NOT NULL` | 区县 | | `detail` | `VARCHAR` | 255 | `NOT NULL` | 详细地址 | | `is_default` | `TINYINT` | 1 | `DEFAULT 0` | 是否默认 | | `create_time` | `DATETIME` | | `DEFAULT CURRENT_TIMESTAMP` | 创建时间 | | `update_time` | `DATETIME` | | `DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP` | 更新时间 | | `delete_time` | `DATETIME` | | | 删除时间 | ## 5. 索引设计 ### 5.1 用户表索引 | 索引名 | 类型 | 字段 | 描述 | |-------|------|------|------| | `PRIMARY` | 主键 | `id` | 主键索引 | | `uk_username` | 唯一 | `username` | 用户名唯一索引 | | `idx_mobile` | 普通 | `mobile` | 手机号索引 | | `idx_email` | 普通 | `email` | 邮箱索引 | | `idx_status` | 普通 | `status` | 状态索引 | ### 5.2 商品表索引 | 索引名 | 类型 | 字段 | 描述 | |-------|------|------|------| | `PRIMARY` | 主键 | `id` | 主键索引 | | `idx_category_id` | 普通 | `category_id` | 分类ID索引 | | `idx_price` | 普通 | `price` | 价格索引 | | `idx_status` | 普通 | `status` | 状态索引 | ### 5.3 订单表索引 | 索引名 | 类型 | 字段 | 描述 | |-------|------|------|------| | `PRIMARY` | 主键 | `id` | 主键索引 | | `uk_order_sn` | 唯一 | `order_sn` | 订单号唯一索引 | | `idx_user_id` | 普通 | `user_id` | 用户ID索引 | | `idx_status` | 普通 | `status` | 状态索引 | | `idx_create_time` | 普通 | `create_time` | 创建时间索引 | ### 5.4 分类表索引 | 索引名 | 类型 | 字段 | 描述 | |-------|------|------|------| | `PRIMARY` | 主键 | `id` | 主键索引 | | `idx_parent_id` | 普通 | `parent_id` | 父分类ID索引 | | `idx_sort` | 普通 | `sort` | 排序索引 | | `idx_status` | 普通 | `status` | 状态索引 | ### 5.5 地址表索引 | 索引名 | 类型 | 字段 | 描述 | |-------|------|------|------| | `PRIMARY` | 主键 | `id` | 主键索引 | | `idx_user_id` | 普通 | `user_id` | 用户ID索引 | | `idx_is_default` | 普通 | `is_default` | 是否默认索引 | ## 6. 关系设计 ### 6.1 表关系图 ``` user ----------------- order | | | | | | address product | | | category ``` ### 6.2 关系说明 - **用户与订单**: 一对多关系，一个用户可以有多个订单 - **用户与地址**: 一对多关系，一个用户可以有多个地址 - **商品与分类**: 多对一关系，多个商品属于一个分类 - **订单与商品**: 多对多关系，一个订单可以包含多个商品，一个商品可以出现在多个订单中 ### 6.3 外键关系 | 主表 | 主键 | 从表 | 外键 | 描述 | |------|------|------|------|------| | `user` | `id` | `order` | `user_id` | 订单所属用户 | | `user` | `id` | `address` | `user_id` | 地址所属用户 | | `category` | `id` | `product` | `category_id` | 商品所属分类 | ## 7. 性能优化 ### 7.1 索引优化 - **选择合适的索引类型**: 根据查询场景选择合适的索引类型 - **避免过度索引**: 只在需要的字段上创建索引 - **使用复合索引**: 对于多字段查询，使用复合索引 - **定期维护索引**: 定期重建碎片化的索引 ### 7.2 查询优化 - **避免全表扫描**: 使用索引覆盖查询 - **减少查询字段**: 只查询需要的字段 - **使用连接查询**: 合理使用连接查询，避免子查询 - **限制查询结果**: 使用 LIMIT 限制查询结果数量 ### 7.3 存储优化 - **选择合适的字段类型**: 根据实际需求选择合适的字段类型 - **使用分区表**: 对于大表，使用分区表提高查询性能 - **定期清理数据**: 定期清理无用数据，减少表大小 - **使用缓存**: 对于频繁查询的数据，使用 Redis 缓存 ### 7.4 配置优化 - **调整 innodb_buffer_pool_size**: 根据服务器内存大小调整 - **调整 max_connections**: 根据并发量调整 - **启用查询缓存**: 对于读多写少的场景 - **优化日志配置**: 合理配置二进制日志和慢查询日志 ## 8. 安全设计 ### 8.1 数据安全 - **加密存储**: 敏感数据（如密码）加密存储 - **数据备份**: 定期备份数据库 - **数据恢复**: 建立数据恢复机制 - **访问控制**: 严格控制数据库访问权限 ### 8.2 SQL 注入防护 - **使用参数化查询**: 避免直接拼接 SQL - **使用 ORM**: 使用 ThinkPHP ORM 框架 - **输入验证**: 对用户输入进行验证 - **转义特殊字符**: 对特殊字符进行转义 ### 8.3 权限管理 - **最小权限原则**: 只授予必要的权限 - **角色分离**: 不同角色拥有不同权限 - **定期审计**: 定期审计数据库访问日志 ## 9. 备份与恢复 ### 9.1 备份策略 - **全量备份**: 定期进行全量备份 - **增量备份**: 每天进行增量备份 - **日志备份**: 备份二进制日志 ### 9.2 恢复策略 - **全量恢复**: 使用全量备份恢复 - **增量恢复**: 使用增量备份恢复 - **点恢复**: 使用二进制日志进行点恢复 ### 9.3 备份工具 - **mysqldump**: MySQL 自带备份工具 - **xtrabackup**: Percona 提供的备份工具 - **第三方工具**: 如 Navicat 等 ## 10. 版本控制 ### 10.1 数据库迁移 - **使用迁移工具**: 使用 ThinkPHP 数据库迁移工具 - **版本管理**: 对数据库结构变更进行版本管理 - **回滚机制**: 支持数据库结构回滚 ### 10.2 迁移文件命名规范 - **格式**: `YYYYMMDDHHMMSS_描述.php` - **示例**: `20230101000000_create_user_table.php` ### 10.3 迁移文件结构 ```php table('user'); $table->addColumn('username', 'string', ['limit' => 50, 'comment' => '用户名']) ->addColumn('password', 'string', ['limit' => 255, 'comment' => '密码']) ->addColumn('nickname', 'string', ['limit' => 50, 'comment' => '昵称']) ->addColumn('avatar', 'string', ['limit' => 255, 'comment' => '头像']) ->addColumn('mobile', 'string', ['limit' => 20, 'comment' => '手机号']) ->addColumn('email', 'string', ['limit' => 100, 'comment' => '邮箱']) ->addColumn('status', 'tinyint', ['default' => 1, 'comment' => '状态']) ->addColumn('create_time', 'datetime', ['default' => 'CURRENT_TIMESTAMP', 'comment' => '创建时间']) ->addColumn('update_time', 'datetime', ['default' => 'CURRENT_TIMESTAMP', 'update' => 'CURRENT_TIMESTAMP', 'comment' => '更新时间']) ->addColumn('delete_time', 'datetime', ['comment' => '删除时间']) ->addIndex('username', ['unique' => true]) ->addIndex('mobile') ->addIndex('email') ->addIndex('status') ->create(); } } ``` ## 11. 维护与监控 ### 11.1 日常维护 - **定期优化表**: 定期执行 OPTIMIZE TABLE 命令 - **监控表大小**: 监控表大小变化 - **检查慢查询**: 定期分析慢查询日志 - **更新统计信息**: 定期更新表统计信息 ### 11.2 监控指标 - **查询性能**: 监控查询响应时间 - **连接数**: 监控数据库连接数 - **缓存命中率**: 监控缓存命中率 - **磁盘使用率**: 监控磁盘空间使用情况 - **CPU 使用率**: 监控数据库服务器 CPU 使用率 ### 11.3 监控工具 - **MySQL Enterprise Monitor**: MySQL 企业版监控工具 - **Percona Monitoring and Management**: 开源监控工具 - **Zabbix**: 通用监控工具 - **Prometheus + Grafana**: 现代化监控方案 ## 12. 总结本文档描述了 CRMEB 项目的数据库设计规范和最佳实践，包括数据库架构、表结构、索引设计、关系设计、性能优化、安全设计、备份与恢复、版本控制、维护与监控等方面。遵循本文档的设计规范，可以提高数据库性能和可维护性，确保系统的稳定运行。同时，定期对数据库进行维护和监控，可以及时发现和解决潜在问题，保障系统的安全性和可靠性。随着业务的发展和系统的演进，数据库设计也需要不断优化和调整，以适应新的业务需求和技术挑战。 --- ### .Trae/Skills/Php Api/References/Directory Structure (.trae/skills/php-api/references/directory_structure.md) # 目录结构文档 ## 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/模块化设计) --- ### .Trae/Skills/Php Api/References/Error Code (.trae/skills/php-api/references/error_code.md) # 错误码文档 ## 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) --- ### .Trae/Skills/Uniapp/References/Api Flow (.trae/skills/uniapp/references/api_flow.md) # UniApp API 开发流程文档 ## 1. 概述本文档描述了 CRMEB 项目中 UniApp 移动端的 API 开发流程，包括 API 接口设计、请求流程、响应处理、错误处理等，旨在规范 API 开发，提高开发效率和代码质量。 ## 2. API 目录结构 ``` template/uni-app/api/ ├── activity.js # 活动相关接口 ├── admin.js # 管理相关接口 ├── api.js # 基础 API 配置 ├── kefu.js # 客服相关接口 ├── lottery.js # 抽奖相关接口 ├── order.js # 订单相关接口 ├── public.js # 公共接口 ├── store.js # 商城相关接口 └── user.js # 用户相关接口 ``` ## 3. 基础 API 配置 (api.js) ```javascript // 基础 API 配置 const baseURL = 'https://api.crmeb.net'; // 请求超时时间 const timeout = 10000; // 请求拦截器 const requestInterceptor = (config) => { // 添加 token const token = uni.getStorageSync('token'); if (token) { config.header['Authorization'] = `Bearer ${token}`; } // 添加设备信息 config.header['X-Device-Type'] = uni.getSystemInfoSync().platform; return config; }; // 响应拦截器 const responseInterceptor = (response) => { const { data } = response; // 统一处理错误 if (data.code !== 200) { uni.showToast({ title: data.message || '请求失败', icon: 'none' }); // 处理登录过期 if (data.code === 401) { uni.redirectTo({ url: '/pages/login/index' }); } return Promise.reject(data); } return data; }; // 错误处理 const errorHandler = (error) => { uni.showToast({ title: '网络错误，请稍后重试', icon: 'none' }); return Promise.reject(error); }; // 导出配置 export default { baseURL, timeout, requestInterceptor, responseInterceptor, errorHandler }; ``` ## 4. API 接口封装 ### 4.1 通用请求方法 ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ### 4.2 业务接口封装 ```javascript // api/user.js import request from '../utils/request'; // 用户相关接口 export default { // 登录 login: (data) => request.post('/api/user/login', data), // 注册 register: (data) => request.post('/api/user/register', data), // 获取用户信息 getUserInfo: () => request.get('/api/user/info'), // 更新用户信息 updateUserInfo: (data) => request.put('/api/user/info', data), // 修改密码 changePassword: (data) => request.post('/api/user/password', data), // 获取地址列表 getAddressList: () => request.get('/api/user/address'), // 添加地址 addAddress: (data) => request.post('/api/user/address', data), // 更新地址 updateAddress: (id, data) => request.put(`/api/user/address/${id}`, data), // 删除地址 deleteAddress: (id) => request.delete(`/api/user/address/${id}`), // 设置默认地址 setDefaultAddress: (id) => request.put(`/api/user/address/${id}/default`) }; ``` ## 5. API 调用示例 ### 5.1 页面中调用 API ```vue ``` ### 5.2 组件中调用 API ``` /* Detailed source-code truncated for AI context efficiency. */ ``` ## 6. API 开发最佳实践 ### 6.1 命名规范 - **文件命名**: 小写字母，单词之间用下划线分隔，如 `user.js` - **方法命名**: 驼峰命名法，如 `getUserInfo` - **URL 命名**: 小写字母，单词之间用连字符分隔，如 `/api/user/info` - **参数命名**: 驼峰命名法，与后端保持一致 ### 6.2 接口设计规范 - **RESTful 风格**: 遵循 RESTful API 设计规范 - **版本控制**: 在 URL 中包含版本号，如 `/api/v1/user/info` - **统一响应格式**: 所有接口返回统一的响应格式 - **错误处理**: 统一的错误码和错误信息 ### 6.3 请求规范 - **请求方法**: 根据操作类型选择合适的 HTTP 方法 - GET: 获取资源 - POST: 创建资源 - PUT: 更新资源 - DELETE: 删除资源 - **请求头**: 统一添加必要的请求头，如 Authorization、Content-Type 等 - **参数传递**: 根据请求方法选择合适的参数传递方式 - GET: 查询参数 - POST/PUT: 请求体 - DELETE: 查询参数或路径参数 ### 6.4 响应规范 - **成功响应**: ```json { "code": 200, "message": "请求成功", "data": {} } ``` - **失败响应**: ```json { "code": 400, "message": "请求失败", "data": {} } ``` ### 6.5 错误处理规范 - **网络错误**: 统一处理网络错误，如超时、断网等 - **业务错误**: 根据错误码处理不同的业务错误 - **登录过期**: 统一处理登录过期，跳转到登录页面 - **错误提示**: 统一的错误提示方式，使用 uni.showToast ## 7. API 性能优化 ### 7.1 请求优化 - **合并请求**: 多个相关请求合并为一个 - **缓存策略**: 对不经常变化的数据使用缓存 - **请求防抖**: 避免频繁发送相同的请求 - **批量操作**: 支持批量操作，减少请求次数 ### 7.2 响应优化 - **数据结构优化**: 优化响应数据结构，减少数据传输量 - **分页处理**: 对列表数据使用分页 - **字段筛选**: 支持字段筛选，只返回需要的字段 - **压缩传输**: 使用 gzip 压缩传输数据 ### 7.3 代码优化 - **模块化**: 按业务模块划分 API 文件 - **复用代码**: 提取通用的请求逻辑 - **减少冗余**: 避免重复的 API 调用 - **代码可读性**: 保持代码清晰易读 ## 8. 常见问题 ### 8.1 跨域问题 - **问题**: 开发环境中遇到跨域问题 - **解决方案**: 在本地开发服务器中配置跨域代理 ### 8.2 Token 过期问题 - **问题**: Token 过期后请求失败 - **解决方案**: 在响应拦截器中处理 Token 过期，跳转到登录页面 ### 8.3 请求超时问题 - **问题**: 网络不稳定时请求超时 - **解决方案**: 设置合理的超时时间，添加网络状态检测 ### 8.4 重复请求问题 - **问题**: 快速点击按钮导致重复请求 - **解决方案**: 添加请求防抖或锁机制 ### 8.5 数据缓存问题 - **问题**: 缓存数据与服务器数据不一致 - **解决方案**: 合理设置缓存过期时间，提供手动刷新机制 ## 9. 参考资源 - [UniApp 网络请求文档](https://uniapp.dcloud.io/api/request/request) - [RESTful API 设计指南](https://restfulapi.cn/) - [Axios 文档](https://axios-http.com/zh/docs/intro) - [HTTP 方法](https://developer.mozilla.org/zh-CN/docs/Web/HTTP/Methods) ## 10. 总结本文档描述了 CRMEB 项目中 UniApp 移动端的 API 开发流程，包括 API 接口设计、请求流程、响应处理、错误处理等。遵循本文档的开发规范，可以提高 API 开发的效率和质量，确保应用的稳定性和可靠性。随着业务的发展和技术的演进，API 开发流程也需要不断优化和调整，以适应新的业务需求和技术挑战。 --- ### .Trae/Skills/Uniapp/References/Code Style (.trae/skills/uniapp/references/code_style.md) # UniApp 代码规范文档 ## 1. 概述本文档描述了 CRMEB 项目中 UniApp 移动端的代码规范，包括命名规范、代码风格、文件结构、组件开发等，旨在统一代码风格，提高代码质量和可维护性。 ## 2. 命名规范 ### 2.1 目录命名 - **目录名**: 小写字母，单词之间用下划线分隔 - **示例**: `pages/index/`、`components/common/`、`utils/` - **规范**: 简洁明了，反映目录的功能 ### 2.2 文件命名 - **页面文件**: 小写字母，单词之间用下划线分隔 - **示例**: `index.vue`、`login.vue`、`user_info.vue` - **组件文件**: 大写字母开头的 PascalCase 命名风格 - **示例**: `Button.vue`、`NavBar.vue`、`GoodsList.vue` - **JS 文件**: 小写字母，单词之间用下划线分隔 - **示例**: `user.js`、`request.js`、`util.js` - **CSS/SCSS 文件**: 小写字母，单词之间用下划线分隔 - **示例**: `common.scss`、`theme.scss` ### 2.3 变量命名 - **普通变量**: 驼峰命名法 - **示例**: `userInfo`、`goodsList`、`isLoading` - **常量**: 全大写，单词之间用下划线分隔 - **示例**: `BASE_URL`、`MAX_COUNT`、`DEFAULT_PAGE_SIZE` - **布尔变量**: 以 `is` 开头的驼峰命名法 - **示例**: `isShow`、`isLoading`、`isLogin` ### 2.4 函数命名 - **函数名**: 驼峰命名法，动词开头 - **示例**: `getUserInfo`、`submitForm`、`handleClick` - **方法名**: 驼峰命名法 - **示例**: `data`、`methods`、`computed`、`watch` - **生命周期函数**: 按照 Vue 规范命名 - **示例**: `created`、`mounted`、`beforeDestroy` ### 2.5 组件命名 - **组件名**: PascalCase 命名风格 - **示例**: `Button`、`NavBar`、`GoodsList` - **组件标签**: 小写字母，单词之间用连字符分隔 - **示例**: ``、``、`` ### 2.6 其他命名 - **路由命名**: 小写字母，单词之间用连字符分隔 - **示例**: `/pages/index/index`、`/pages/user/login` - **CSS 类名**: 小写字母，单词之间用连字符分隔 - **示例**: `.user-info`、`.goods-list`、`.btn-primary` - **ID 命名**: 小写字母，单词之间用连字符分隔 - **示例**: `#app`、`#header`、`#footer` ## 3. 代码风格 ### 3.1 缩进 - **缩进方式**: 4 个空格 - **示例**: ```vue ``` ### 3.2 换行 - **标签换行**: 多个属性的标签应该换行 - **示例**: ```vue {{ message }} ``` - **代码块换行**: 逻辑代码块应该换行 - **示例**: ```javascript if (condition) { // 代码块 } else { // 代码块 } ``` ### 3.3 空格 - **运算符空格**: 运算符两侧应该有空格 - **示例**: `a + b`、`x = y`、`i < 10` - **逗号空格**: 逗号后面应该有空格 - **示例**: `[1, 2, 3]`、`{ name: '张三', age: 18 }` - **括号空格**: 括号内侧不应该有空格 - **示例**: `if (condition)`、`function (param)` ### 3.4 注释 - **单行注释**: 使用 `//` 注释 - **示例**: `// 这是单行注释` - **多行注释**: 使用 `/* */` 注释 - **示例**: ```javascript /* * 这是多行注释 * 第二行 */ ``` - **文档注释**: 使用 JSDoc 风格的注释 - **示例**: ```javascript /** * 获取用户信息 * @param {number} id - 用户ID * @returns {Promise} 用户信息 */ async function getUserInfo(id) { // 代码 } ``` ### 3.5 引号 - **字符串**: 使用单引号 `''` - **示例**: `const name = '张三'`、`Hello` - **模板字符串**: 使用反引号 `` ` `` - **示例**: `` const url = `${baseUrl}/api/user` `` - **HTML 属性**: 使用双引号 `""` - **示例**: ``、`

{{ title }}

{{ title }}