ruoyi-vue-plus/.cursorrules

# RuoYi-Vue-Plus 开发规范

## 项目基本信息

**项目名称**: RuoYi-Vue-Plus
**版本**: 5.4.0
**技术架构**: 基于Spring Boot 3.4.6 + Vue 3 + TypeScript 的多租户管理系统
**原始仓库**: https://gitee.com/dromara/RuoYi-Vue-Plus
**文档地址**: https://plus-doc.dromara.org

## 核心技术栈

### 后端技术栈
- **框架**: Spring Boot 3.4.6
- **Java版本**: JDK 17/21
- **Web容器**: Undertow
- **ORM框架**: MyBatis-Plus 3.5.12
- **数据库**: MySQL/Oracle/PostgreSQL/SQLServer (多数据库支持)
- **缓存**: Redis 5-7 + Redisson 3.45.1
- **权限认证**: Sa-Token 1.42.0 + JWT
- **连接池**: HikariCP
- **序列化**: Jackson
- **分布式锁**: Lock4j + Redisson
- **任务调度**: SnailJob 1.5.0
- **工作流**: Warm-Flow 1.7.3
- **文件存储**: Minio/AWS S3协议
- **短信**: sms4j 3.3.4
- **监控**: Spring Boot Admin 3.4.7
- **API文档**: SpringDoc + OpenAPI 3

### 前端技术栈
- **框架**: Vue 3 + TypeScript
- **UI组件**: Element Plus
- **构建工具**: Vite
- **代码风格**: ESLint + Prettier

## 项目结构规范

### 后端模块结构
```
ruoyi-vue-plus/
├── ruoyi-admin/          # 管理后台启动模块
├── ruoyi-common/         # 公共模块组
│   ├── ruoyi-common-core/        # 核心模块
│   ├── ruoyi-common-mybatis/     # MyBatis配置
│   ├── ruoyi-common-redis/       # Redis配置
│   ├── ruoyi-common-satoken/     # Sa-Token配置
│   ├── ruoyi-common-security/    # 安全配置
│   ├── ruoyi-common-tenant/      # 多租户
│   ├── ruoyi-common-web/         # Web配置
│   ├── ruoyi-common-excel/       # Excel处理
│   ├── ruoyi-common-oss/         # 对象存储
│   ├── ruoyi-common-sms/         # 短信
│   ├── ruoyi-common-mail/        # 邮件
│   ├── ruoyi-common-log/         # 日志
│   ├── ruoyi-common-encrypt/     # 加密
│   ├── ruoyi-common-sensitive/   # 脱敏
│   ├── ruoyi-common-translation/ # 翻译
│   ├── ruoyi-common-idempotent/  # 幂等
│   ├── ruoyi-common-ratelimiter/ # 限流
│   ├── ruoyi-common-websocket/   # WebSocket
│   ├── ruoyi-common-sse/         # SSE推送
│   └── ruoyi-common-job/         # 任务调度
├── ruoyi-modules/        # 业务模块组
│   ├── ruoyi-system/     # 系统管理模块
│   ├── ruoyi-demo/       # 示例模块
│   ├── ruoyi-generator/  # 代码生成模块
│   ├── ruoyi-job/        # 任务调度模块
│   └── ruoyi-workflow/   # 工作流模块
├── ruoyi-extend/         # 扩展模块组
└── script/               # 脚本和SQL
```

## 开发规范

### 1. 代码规范
- **严格遵守**: Alibaba Java开发手册
- **命名规范**:
  - 类名: PascalCase (如: UserController)
  - 方法名: camelCase (如: getUserList)
  - 常量: UPPER_SNAKE_CASE (如: MAX_RETRY_COUNT)
  - 包名: 全小写 (如: org.dromara.system)
- **注释规范**: 类和公共方法必须有完整的JavaDoc注释
- **代码格式化**: 使用项目统一的代码格式化配置

### 2. 数据库规范
- **现有数据库模型**: 参考 `docs/design/database/hzdyjs_xg.sql` 中的完整表结构
- **环境配置**: 开发环境数据库信息见 `docs/design/database/database_msg.md`
- **主键设计**: 使用雪花ID (ASSIGN_ID)，不使用数据库自增
- **字段命名**: 下划线命名法 (如: user_name, create_time)
- **基础字段**: 所有业务表必须包含以下字段
  ```sql
  id BIGINT PRIMARY KEY,
  tenant_id VARCHAR(20),     -- 租户ID (多租户)
  create_dept BIGINT,        -- 创建部门
  create_by BIGINT,          -- 创建人
  create_time DATETIME,      -- 创建时间
  update_by BIGINT,          -- 更新人
  update_time DATETIME,      -- 更新时间
  deleted TINYINT DEFAULT 0  -- 逻辑删除标记
  ```
- **业务表参考**: 现有业务表包括宿舍管理、工作流等，参考现有表结构规范
- **索引规范**:
  - 租户字段必须建索引
  - 常用查询字段建复合索引
  - 外键字段建索引

### 3. API接口规范
- **RESTful设计**: 遵循REST API设计原则
- **统一响应格式**:
  ```json
  {
    "code": 200,
    "msg": "操作成功",
    "data": {}
  }
  ```
- **权限控制**: 使用Sa-Token注解进行权限校验
  ```java
  @SaCheckPermission("system:user:list")
  ```
- **参数校验**: 使用Validation注解进行参数校验
- **API文档**: 使用SpringDoc自动生成，基于JavaDoc注释

### 4. 业务层规范
- **Service接口**: 业务逻辑抽象为Service接口
- **Service实现**: 实现类以Impl结尾
- **DTO/VO分离**:
  - DTO: 数据传输对象
  - VO: 视图对象
  - Bo: 业务对象
- **对象转换**: 使用MapStruct-Plus进行对象转换
- **事务管理**: 使用@Transactional注解，支持多数据源事务

### 5. 数据层规范
- **Mapper接口**: 继承BaseMapper<Entity>
- **实体类规范**:
  ```java
  @Data
  @EqualsAndHashCode(callSuper = true)
  @TableName("sys_user")
  public class SysUser extends BaseEntity {
      @TableId(value = "user_id", type = IdType.ASSIGN_ID)
      private Long userId;
      // 其他字段...
  }
  ```
- **分页查询**: 使用PageQuery基类
- **数据权限**: 使用@DataPermission注解

## 关键配置规范

### 1. 多租户配置
- **启用多租户**: `tenant.enable: true`
- **排除表配置**: 系统表需要在`tenant.excludes`中配置
- **租户字段**: 业务表必须包含tenant_id字段

### 2. 数据库配置
- **动态数据源**: 使用dynamic-datasource
- **主库配置**: 数据源名称为master
- **数据库密码**: 生产环境必须加密存储
- **连接池**: 使用HikariCP，合理配置连接数

### 3. Redis配置
- **单机配置**: 开发环境使用单机Redis
- **集群配置**: 生产环境建议使用集群
- **key前缀**: 使用`redisson.keyPrefix`设置统一前缀
- **密码配置**: Redis必须设置密码

### 4. 安全配置
- **JWT密钥**: 必须修改默认密钥
- **接口加密**: 生产环境开启API加解密
- **权限排除**: 静态资源和公开接口在`security.excludes`配置

## 文档管理规范

### 1. 需求文档 (docs/requirements/)
- **需求说明**: 详细的功能需求描述
- **原型设计**: UI原型和交互设计
- **业务流程**: 业务流程图和规则

### 2. 设计文档 (docs/design/)
- **系统设计**: 系统架构和模块设计
- **数据库设计**: ER图、表结构和字段说明
  - **完整数据库模型**: `docs/design/database/hzdyjs_xg.sql`
  - **环境配置信息**: `docs/design/database/database_msg.md`
  - **设计文档管理**: `docs/design/database/README.md`
- **接口设计**: API接口设计和数据格式

### 3. 开发文档 (docs/development/)
- **开发指南**: 开发环境搭建和规范
- **代码样例**: 标准代码示例
- **问题记录**: 开发过程中的问题和解决方案

### 4. 测试文档 (docs/testing/)
- **测试计划**: 测试策略和计划
- **测试用例**: 详细测试用例
- **测试报告**: 测试结果和问题报告

### 5. 部署文档 (docs/deployment/)
- **环境配置**: 各环境配置说明
- **部署脚本**: 自动化部署脚本
- **运维手册**: 运维操作手册

### 6. 中间件配置 (docs/middleware/)
- **MySQL配置**: 数据库配置和优化
- **Redis配置**: 缓存配置和集群方案
- **Nginx配置**: 反向代理和负载均衡
- **监控配置**: 监控组件配置

## 代码变更规则

### 1. 强制更新规则
每次代码调整必须同步更新以下文档:
- **API文档**: 接口变更时更新OpenAPI文档
- **数据库文档**: 表结构变更时更新DDL和文档
  - 必须同步更新 `docs/design/database/hzdyjs_xg.sql`
  - 必须同步更新 `docs/design/database/README.md` 中的表结构说明
  - 环境配置变更需更新 `docs/design/database/database_msg.md`
- **配置文档**: 配置项变更时更新配置说明
- **部署文档**: 部署流程变更时更新部署手册

### 2. 版本管理
- **文档版本**: 与代码版本保持同步
- **变更记录**: 记录每次变更的内容和原因
- **向后兼容**: 接口变更需要考虑向后兼容性

### 3. 质量检查
- **代码审查**: 所有代码变更需要经过Code Review
- **文档审查**: 文档变更需要技术负责人审查
- **测试验证**: 功能变更需要对应的测试用例

## 性能优化规范

### 1. 数据库优化
- **SQL优化**: 避免N+1查询，合理使用批量操作
- **索引优化**: 根据查询模式建立合适索引
- **分页优化**: 大数据量查询使用流式分页

### 2. 缓存策略
- **Redis缓存**: 热点数据使用Redis缓存
- **本地缓存**: 字典数据使用本地缓存
- **缓存过期**: 合理设置缓存过期时间

### 3. 代码优化
- **异步处理**: 耗时操作使用异步执行
- **连接池**: 合理配置各种连接池参数
- **JVM优化**: 生产环境JVM参数调优

## 安全规范

### 1. 数据安全
- **敏感数据**: 使用数据脱敏和加密
- **SQL注入**: 使用参数化查询
- **XSS防护**: 启用XSS过滤器

### 2. 接口安全
- **认证授权**: 所有接口需要认证和授权
- **参数校验**: 严格的参数校验和格式检查
- **接口加密**: 敏感接口启用加解密

### 3. 系统安全
- **日志安全**: 不在日志中输出敏感信息
- **配置安全**: 密码等敏感配置加密存储
- **网络安全**: 使用HTTPS协议

## 开发工具推荐

### 1. IDE配置
- **IDEA**: 推荐使用IntelliJ IDEA
- **插件**: Lombok、MyBatis-Plus、Alibaba规约检查
- **代码模板**: 使用统一的代码模板

### 2. 调试工具
- **数据库**: Navicat/DataGrip
- **Redis**: RedisDesktopManager
- **API测试**: Postman/Swagger UI
- **日志查看**: 使用SpringBoot Admin

### 3. 代码质量
- **静态检查**: SonarQube
- **代码格式**: Google Java Format
- **依赖检查**: OWASP Dependency Check

## 快速开始模板

### 1. 新建业务模块步骤
1. 在ruoyi-modules下创建新模块
2. 配置pom.xml依赖
3. 创建标准目录结构: controller/service/mapper/domain
4. 编写业务代码，遵循上述规范
5. 添加单元测试
6. 更新相关文档

### 2. 标准Controller模板
```java
@RestController
@RequestMapping("/system/user")
@Api(tags = "用户管理")
public class SysUserController extends BaseController {

    @Autowired
    private ISysUserService userService;

    @SaCheckPermission("system:user:list")
    @GetMapping("/list")
    @Operation(summary = "查询用户列表")
    public TableDataInfo<SysUserVo> list(SysUserBo user, PageQuery pageQuery) {
        return userService.queryPageList(user, pageQuery);
    }
}
```

### 3. 标准Service模板
```java
@Service
public class SysUserServiceImpl implements ISysUserService {

    @Autowired
    private SysUserMapper userMapper;

    @Override
    public TableDataInfo<SysUserVo> queryPageList(SysUserBo bo, PageQuery pageQuery) {
        LambdaQueryWrapper<SysUser> lqw = buildQueryWrapper(bo);
        Page<SysUserVo> result = userMapper.selectVoPage(pageQuery.build(), lqw);
        return TableDataInfo.build(result);
    }
}
```

## 注意事项

1. **严格遵循框架规范**: 不要随意修改框架核心配置
2. **安全第一**: 所有对外接口必须进行权限校验
3. **性能考虑**: 大数据量操作需要考虑性能影响
4. **文档同步**: 代码变更必须同步更新文档
5. **测试验证**: 功能开发完成后必须进行充分测试
6. **向后兼容**: 接口变更需要考虑对现有功能的影响

## 参考资源

- **官方文档**: https://plus-doc.dromara.org
- **源码仓库**: https://gitee.com/dromara/RuoYi-Vue-Plus
- **问题反馈**: https://gitee.com/dromara/RuoYi-Vue-Plus/issues
- **技术交流**: 查看官方文档获取交流群信息
- **本地文档**: 查看docs/目录下的详细文档