You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
This file contains ambiguous Unicode characters that may be confused with others in your current locale. If your use case is intentional and legitimate, you can safely ignore this warning. Use the Escape button to highlight these characters.
# Cursor项目规范
## 基本设置
- 使用中文回答所有问题
- 按照Sequential Thinking方法进行代码设计和实现
## 依赖约束
- 使用Maven作为依赖管理工具
- 使用Maven项目结构
- 使用SpringBoot2.1.4.RELEASE作为框架
- 使用JDK1.8作为开发语言
- 使用Lombok作为代码简化工具
## 项目结构和命名规范
- 组件命名：
- 函数命名：
- 常量命名：
- 文件夹结构遵循Maven项目规范
- 接口命名： ，
- 类型定义： ，
- 文档类统一输出至docs文件夹，
## 代码风格
- 使用TypeScript类型定义
- 统一代码缩进和格式
- 使用ESLint和Prettier规则
## 开发流程规则
1. 问题分析：明确任务目标和约束条件
2. 设计方案：设计数据结构和算法
3. 实现步骤：自顶向下实现功能
4. 测试验证：编写单元测试和集成测试
## 代码审查标准
- 代码必须符合既定规范
- 关键函数和组件必须有注释
- 复杂算法需要解释思路
## 提交规范
- 遵循语义化提交信息格式：
- 主分支只接受经过测试的代码
## 文档要求
- API接口必须有清晰文档
- 更新README文件反映最新项目状态
## 代码稳定性保障
- 修改已完成功能前必须先理解其完整设计意图
- 所有API更改必须向下兼容
- 使用单元测试保护核心功能逻辑
- 重构代码时必须保持功能等价性
- 在修改前创建功能快照或临时分支
- 每次更改后必须验证不破坏现有功能
- 使用TODO或FIXME标签清晰标记未完成修改
## 版本控制规则
- 使用语义化版本管理
- 关键功能更改必须通过代码审查
- 维护变更日志记录所有修改
- 为已稳定功能模块添加"锁定注释"标记：/* @stable - 请勿修改 */
## UI设计规范
- 遵循现代设计趋势和最佳实践
- 使用设计系统确保一致性（ ）
- 实现响应式设计，确保在不同设备上显示良好
- 使用CSS变量统一管理颜色、字体、间距等设计标记
- 优先采用Flexbox或Grid布局系统
- 确保适当的留白和视觉层次
- 实现无障碍访问标准（ ）
## UI组件标准
- 使用组件库作为基础（ ）
- 自定义组件需符合现代设计审美
- 设计组件应包含默认、悬停、聚焦、禁用等状态
- 使用适当的动画和过渡效果增强用户体验
- 确保设计一致性：同类元素使用相同样式
- 使用主题系统支持亮色/暗色模式切换
- 根据用户操作提供视觉反馈
## 设计资源
- 维护设计风格指南和UI组件库
- 使用标准化图标库（ ）
- 图片和插图需保持一致的风格
- 颜色选择须符合品牌标识并确保足够对比度
## 依赖管理规范
- 优先使用国内镜像站点安装依赖
- npm包使用淘宝镜像：
- yarn设置：
- pnpm设置：
- pip包使用清华镜像：
- Docker镜像使用阿里云：
- Maven依赖使用阿里云：
- Gradle依赖使用阿里云：
- 安装新依赖前先验证其在国内是否可访问
- 如确实需使用国外资源，应提供备选方案或离线安装包
- package.json中添加镜像设置脚本便于团队统一配置
- 记录所有依赖的具体版本和来源以便追踪
## 测试自动化规范
- 编写单元测试覆盖所有关键功能
- 实现端到端测试验证用户流程
- 使用测试驱动开发(TDD)方法
- 每次提交前运行自动化测试
- 维护测试数据与生产环境隔离
## 调试与日志规范
- 统一使用日志级别（ ）
- 日志信息需包含上下文和时间戳
- 生产环境禁用调试代码和console语句
- 关键流程增加日志记录点便于问题追踪
- 使用结构化日志格式便于分析
## 代码复杂度控制
- 函数不超过50行，
- 每个函数只做一件事情，保持单一职责
- 嵌套不超过3层，
- 控制圈复杂度不超过10
- 复杂逻辑应拆分为多个小函数
## 状态管理规范
- 明确状态管理方案（ ）
- 区分本地状态和全局状态
- 避免状态冗余和重复存储
- 实现不可变状态更新模式
- 为复杂状态提供初始值和验证机制
## 异步操作规范
- 统一使用async/await或Promise
- 实现请求超时和重试机制
- 处理并发请求限制
- 取消不必要的请求以节省资源
- 使用Loading状态指示异步操作进行中
## 代码重用策略
- 提取通用逻辑为Hooks或工具函数
- 使用组合而非继承实现代码复用
- 避免复制粘贴代码，而应重构为共享组件
- 通用功能应考虑发布为内部npm包
- 明确区分业务逻辑和技术实现
## 项目文档体系
- 维护项目架构图和关键流程图
- 记录技术选型理由和限制条件
- 为API和数据模型提供详细文档
- 记录已知问题和解决方案
- 提供新开发者入门指南
## 构建与发布流程
- 使用CI/CD实现自动化构建和部署
- 区分开发、测试、预发布和生产环境
- 实现回滚机制应对紧急问题
- 使用版本化静态资源避免缓存问题
- 配置文件应随环境变化而不需修改代码
## 可访问性和兼容性规范
- 确保键盘可访问性
- 使用ARIA标签增强屏幕阅读器支持
- 确保适当的颜色对比度
- 响应式设计支持从移动到桌面的所有设备
- 针对低带宽和弱网络场景优化
## 问题追踪与修复流程
- 使用标准化的问题报告模板
- 问题修复前先编写复现步骤
- 每个bug修复应包含相应测试避免回归
- 重大问题需进行根本原因分析
- 定期审查常见错误类型并改进开发流程
## 代码注释最佳实践
- 写清楚为什么这样做，而不仅是做了什么
- 用注释标记未来需要优化的地方
- 所有公共API必须有注释文档
- 复杂业务逻辑需要解释业务规则
- 避免废弃或过时的注释
## 数据处理与安全
- 敏感数据传输必须加密
- 用户输入必须验证和清洗
- 实现数据备份和恢复策略
- 遵循数据最小化原则，只收集必要信息
- 实现适当的数据过期和销毁机制
## 性能优化指南
- 实现资源懒加载和按需加载
- 优化关键渲染路径提高首屏加载速度
- 使用适当的缓存策略减少网络请求
- 批量处理DOM操作避免重排和重绘
- 定期进行性能审计和优化
## 可维护性原则
- 优先考虑代码可理解性而非简洁性
- 避免过早优化和不必要的抽象
- 关键决策需在代码中记录理由
- 避免使用黑魔法和难以理解的技巧
- 团队培训和知识共享机制
## 技术债务管理
- 使用TODO和FIXME标记需要改进的地方
- 定期安排时间清理技术债务
- 新功能实现前评估现有代码质量
- 记录所有已知问题和临时解决方案
- 使用代码质量工具定期评估项目健康度
## 用户体验设计规范
- 所有操作必须提供用户反馈
- 错误信息应该清晰并提供解决方案
- 降低操作复杂度，减少用户认知负担
- 界面风格保持一致性
- 考虑边缘情况和用户出错恢复路径