Add comprehensive project documentation for architecture and development guidelines

2025-06-18 07:44:36 +00:00
parent 7cee12c412
commit bbf6135e39
6 changed files with 610 additions and 0 deletions
--- a/.cursor/rules/business-modules.mdc
+++ b/.cursor/rules/business-modules.mdc
@@ -0,0 +1,73 @@
+# 业务模块指南
+
+## 系统核心模块
+
+### system 模块 - 系统管理
+**路径**: [yudao-module-system](mdc:yudao-module-system)
+**功能**: 用户管理、角色权限、菜单管理、部门岗位、字典配置、操作日志等
+**核心包**: `cn.iocoder.yudao.module.system`
+
+### infra 模块 - 基础设施
+**路径**: [yudao-module-infra](mdc:yudao-module-infra)
+**功能**: 文件存储、配置管理、代码生成、定时任务、API 文档等
+**核心包**: `cn.iocoder.yudao.module.infra`
+
+## 可选业务模块
+
+### bpm 模块 - 工作流程
+**路径**: [yudao-module-bpm](mdc:yudao-module-bpm)
+**技术栈**: Flowable 6.8.0
+**功能**: 流程设计器、流程实例、任务管理、表单设计
+**特色**: 支持 BPMN 和仿钉钉双设计器
+
+### pay 模块 - 支付系统
+**路径**: [yudao-module-pay](mdc:yudao-module-pay)
+**功能**: 支付应用、支付订单、退款管理、支付渠道配置
+**支持**: 支付宝、微信支付、银联等主流支付方式
+
+### mall 模块 - 商城系统
+**路径**: [yudao-module-mall](mdc:yudao-module-mall)
+**子模块**:
+- `yudao-module-product`: 商品管理
+- `yudao-module-promotion`: 营销活动
+- `yudao-module-trade`: 交易订单
+- `yudao-module-statistics`: 数据统计
+
+### member 模块 - 会员中心
+**路径**: [yudao-module-member](mdc:yudao-module-member)
+**功能**: 会员管理、等级体系、积分签到、标签分组
+
+### crm 模块 - 客户关系管理
+**路径**: [yudao-module-crm](mdc:yudao-module-crm)
+**功能**: 线索管理、客户管理、联系人、商机、合同、回款
+
+### erp 模块 - 企业资源计划
+**路径**: [yudao-module-erp](mdc:yudao-module-erp)
+**功能**: 产品管理、库存管理、采购管理、销售管理、财务管理
+
+### mp 模块 - 微信公众号
+**路径**: [yudao-module-mp](mdc:yudao-module-mp)
+**功能**: 账号管理、粉丝管理、消息管理、自动回复、菜单管理
+
+### ai 模块 - AI 大模型
+**路径**: [yudao-module-ai](mdc:yudao-module-ai)
+**功能**: 对话聊天、图片生成、音乐生成、思维导图
+**支持**: OpenAI、文心一言、通义千问等主流模型
+
+### iot 模块 - 物联网
+**路径**: [yudao-module-iot](mdc:yudao-module-iot)
+**功能**: 设备管理、数据采集、远程控制
+**插件化**: 支持 MQTT、HTTP 等多种协议
+
+### report 模块 - 数据报表
+**路径**: [yudao-module-report](mdc:yudao-module-report)
+**功能**: 报表设计器、大屏设计器、数据可视化
+
+## 模块间依赖关系
+- **基础依赖**: system <- 所有业务模块
+- **支付依赖**: pay <- mall (商城依赖支付)
+- **会员依赖**: member <- mall (商城依赖会员)
+- **工作流**: bpm 可被任意模块集成
+
+## 模块配置激活
+在 [pom.xml](mdc:pom.xml) 中控制模块的启用/禁用，根据业务需求按需集成。
--- a/.cursor/rules/common-patterns.mdc
+++ b/.cursor/rules/common-patterns.mdc
@@ -0,0 +1,189 @@
+# 常用开发模式指南
+
+## Controller 层开发模式
+
+### 标准 REST API 模式
+```java
+@RestController
+@RequestMapping("/admin-api/system/user")
+@Validated
+@Api(tags = "管理后台 - 用户")
+public class UserController {
+    
+    @PostMapping("/create")
+    @ApiOperation("创建用户")
+    @PreAuthorize("@ss.hasPermission('system:user:create')")
+    public CommonResult<Long> createUser(@Valid @RequestBody UserCreateReqVO reqVO) {
+        return success(userService.createUser(reqVO));
+    }
+}
+```
+
+### 分页查询模式
+```java
+@GetMapping("/page")
+@ApiOperation("获得用户分页")
+@PreAuthorize("@ss.hasPermission('system:user:query')")
+public CommonResult<PageResult<UserRespVO>> getUserPage(@Valid UserPageReqVO reqVO) {
+    PageResult<UserDO> pageResult = userService.getUserPage(reqVO);
+    return success(UserConvert.INSTANCE.convertPage(pageResult));
+}
+```
+
+## Service 层开发模式
+
+### 事务处理模式
+```java
+@Service
+@Validated
+public class UserServiceImpl implements UserService {
+    
+    @Transactional(rollbackFor = Exception.class)
+    public Long createUser(UserCreateReqVO reqVO) {
+        // 校验用户存在
+        validateUserExists(reqVO.getUsername());
+        // 插入用户
+        UserDO user = UserConvert.INSTANCE.convert(reqVO);
+        userMapper.insert(user);
+        return user.getId();
+    }
+}
+```
+
+## 数据访问层模式
+
+### MyBatis Plus 使用
+```java
+@Mapper
+public interface UserMapper extends BaseMapperX<UserDO> {
+    
+    default PageResult<UserDO> selectPage(UserPageReqVO reqVO) {
+        return selectPage(reqVO, new LambdaQueryWrapperX<UserDO>()
+                .likeIfPresent(UserDO::getUsername, reqVO.getUsername())
+                .eqIfPresent(UserDO::getStatus, reqVO.getStatus())
+                .betweenIfPresent(UserDO::getCreateTime, reqVO.getCreateTime())
+                .orderByDesc(UserDO::getId));
+    }
+}
+```
+
+## 权限控制模式
+
+### 菜单权限
+```java
+@PreAuthorize("@ss.hasPermission('system:user:query')")
+```
+
+### 数据权限
+```java
+@DataPermission(deptAlias = "d", userAlias = "u")
+```
+
+### 多租户
+```java
+@TenantIgnore // 忽略多租户
+@TenantInfo  // 获取租户信息
+```
+
+## 异常处理模式
+
+### 业务异常
+```java
+// 抛出业务异常
+throw exception(USER_NOT_EXISTS);
+
+// 在 ErrorCodeConstants 中定义
+ErrorCode USER_NOT_EXISTS = new ErrorCode(1002001001, "用户不存在");
+```
+
+### 全局异常处理
+框架自动处理，返回统一格式的错误响应。
+
+## 对象转换模式
+
+### MapStruct 转换器
+```java
+@Mapper
+public interface UserConvert {
+    UserConvert INSTANCE = Mappers.getMapper(UserConvert.class);
+    
+    UserDO convert(UserCreateReqVO bean);
+    UserRespVO convert(UserDO bean);
+    PageResult<UserRespVO> convertPage(PageResult<UserDO> page);
+}
+```
+
+## 枚举使用模式
+
+### 通用枚举
+```java
+@AllArgsConstructor
+@Getter
+public enum CommonStatusEnum implements IntArrayValuable {
+    ENABLE(0, "开启"),
+    DISABLE(1, "关闭");
+    
+    private final Integer status;
+    private final String name;
+}
+```
+
+## 配置管理模式
+
+### 配置类定义
+```java
+@ConfigurationProperties(prefix = "yudao.security")
+@Data
+public class SecurityProperties {
+    private Set<String> permitAllUrls = new HashSet<>();
+}
+```
+
+## 缓存使用模式
+
+### Redis 缓存
+```java
+@Cacheable(value = RedisKeyConstants.USER, key = "#id")
+public UserDO getUser(Long id) {
+    return userMapper.selectById(id);
+}
+```
+
+## 消息队列模式
+
+### 发送消息
+```java
+@Resource
+private RedisTemplate<String, Object> redisTemplate;
+
+// 发送消息
+redisTemplate.convertAndSend("user.create", userId);
+```
+
+## 单元测试模式
+
+### 服务层测试
+```java
+@ExtendWith(MockitoExtension.class)
+class UserServiceImplTest {
+    
+    @InjectMocks
+    private UserServiceImpl userService;
+    
+    @Mock
+    private UserMapper userMapper;
+    
+    @Test
+    void testCreateUser() {
+        // given
+        UserCreateReqVO reqVO = randomPojo(UserCreateReqVO.class);
+        
+        // when
+        Long userId = userService.createUser(reqVO);
+        
+        // then
+        assertNotNull(userId);
+        verify(userMapper).insert(any());
+    }
+}
+```
--- a/.cursor/rules/deployment-guide.mdc
+++ b/.cursor/rules/deployment-guide.mdc
@@ -0,0 +1,171 @@
+# 项目启动和部署指南
+
+## 快速启动
+
+### 环境要求
+- **JDK**: 1.8+ (推荐 JDK 8 或 JDK 17)
+- **Maven**: 3.6+
+- **MySQL**: 5.7+ 或 8.0+
+- **Redis**: 5.0+
+- **Node.js**: 16+ (前端项目)
+
+### 启动步骤
+
+#### 1. 数据库初始化
+```sql
+-- 创建数据库
+CREATE DATABASE ruoyi_vue_pro;
+
+-- 导入数据表结构和基础数据
+-- 使用 sql/mysql/ruoyi-vue-pro.sql
+```
+SQL 脚本路径：[sql/mysql/ruoyi-vue-pro.sql](mdc:sql/mysql/ruoyi-vue-pro.sql)
+
+#### 2. 配置修改
+编辑配置文件：[application.yaml](mdc:yudao-server/src/main/resources/application.yaml)
+```yaml
+spring:
+  datasource:
+    url: jdbc:mysql://127.0.0.1:3306/ruoyi_vue_pro
+    username: root
+    password: 123456
+  
+  data:
+    redis:
+      host: 127.0.0.1
+      port: 6379
+      password: 
+```
+
+#### 3. 启动后端服务
+运行主类：[YudaoServerApplication.java](mdc:yudao-server/src/main/java/cn/iocoder/yudao/server/YudaoServerApplication.java)
+```bash
+# 或使用 Maven 命令
+mvn spring-boot:run -f yudao-server/pom.xml
+```
+
+#### 4. 访问管理后台
+- **后端 API**: http://localhost:48080
+- **API 文档**: http://localhost:48080/doc.html
+- **默认账号**: admin / admin123
+
+## Docker 部署
+
+### Docker Compose 部署
+使用提供的 Docker 配置：[script/docker/docker-compose.yml](mdc:script/docker/docker-compose.yml)
+
+```bash
+cd script/docker
+docker-compose up -d
+```
+
+### 自定义 Docker 镜像
+使用项目的 Dockerfile：[yudao-server/Dockerfile](mdc:yudao-server/Dockerfile)
+
+```bash
+# 构建镜像
+docker build -t yudao-server .
+
+# 运行容器
+docker run -d -p 48080:48080 yudao-server
+```
+
+## 生产环境部署
+
+### 配置优化
+1. **数据库连接池调优**
+2. **Redis 连接配置**
+3. **JVM 参数优化**
+4. **日志级别调整**
+
+### 部署脚本
+使用提供的部署脚本：[script/shell/deploy.sh](mdc:script/shell/deploy.sh)
+
+### 监控配置
+- **应用监控**: Spring Boot Admin
+- **链路追踪**: SkyWalking
+- **日志收集**: 集成日志中心
+
+## 前端项目启动
+
+### Vue3 版本 (推荐)
+```bash
+git clone https://gitee.com/yudaocode/yudao-ui-admin-vue3.git
+cd yudao-ui-admin-vue3
+npm install
+npm run dev
+```
+
+### Vue2 版本
+```bash
+git clone https://gitee.com/yudaocode/yudao-ui-admin-vue2.git
+cd yudao-ui-admin-vue2
+npm install
+npm run dev
+```
+
+## 常见问题
+
+### 启动失败
+1. 检查数据库连接配置
+2. 确认 Redis 服务正常
+3. 查看启动日志错误信息
+4. 参考官方文档: https://doc.iocoder.cn/quick-start/
+
+### 端口冲突
+默认端口 48080，可在配置文件中修改：
+```yaml
+server:
+  port: 48080
+```
+
+### 内存不足
+调整 JVM 参数：
+```bash
+java -Xms512m -Xmx1024m -jar yudao-server.jar
+```
+
+## 多环境配置
+
+### 开发环境
+- 配置文件：`application-dev.yaml`
+- 数据库：本地 MySQL
+- Redis：本地 Redis
+
+### 测试环境
+- 配置文件：`application-test.yaml`
+- 外部数据库和 Redis
+
+### 生产环境
+- 配置文件：`application-prod.yaml`
+- 高可用数据库集群
+- Redis 集群
+
+## CI/CD 集成
+
+### Jenkins 部署
+使用提供的 Jenkins 配置：[script/jenkins/Jenkinsfile](mdc:script/jenkins/Jenkinsfile)
+
+### 自动化部署流程
+1. 代码提交触发构建
+2. 执行单元测试
+3. 构建 Docker 镜像
+4. 部署到目标环境
+5. 健康检查
+
+## 性能调优
+
+### 数据库优化
+- 添加适当索引
+- 分库分表（如需要）
+- 读写分离配置
+
+### 缓存策略
+- Redis 缓存热点数据
+- 本地缓存配置
+- 缓存过期策略
+
+### 应用优化
+- 连接池参数调优
+- 线程池配置
+- GC 参数优化
--- a/.cursor/rules/development-guide.mdc
+++ b/.cursor/rules/development-guide.mdc
@@ -0,0 +1,82 @@
+# 开发规范指南
+
+## 代码规范
+遵循《阿里巴巴 Java 开发手册》规范，代码注释详细。
+
+## 新增业务模块步骤
+
+### 1. 创建模块目录
+```
+yudao-module-{模块名}/
+├── pom.xml
+└── src/main/java/cn/iocoder/yudao/module/{模块名}/
+```
+
+### 2. 标准包结构
+```java
+cn.iocoder.yudao.module.{模块名}
+├── api/
+│   ├── {功能}Api.java           // 对外接口定义
+│   └── {功能}ApiImpl.java       // 接口实现
+├── controller/
+│   └── admin/                   // 管理后台控制器
+│       └── {功能}Controller.java
+├── service/
+│   ├── {功能}Service.java       // 业务接口
+│   └── {功能}ServiceImpl.java   // 业务实现
+├── dal/
+│   ├── dataobject/             // 数据对象
+│   │   └── {功能}DO.java
+│   └── mysql/                  // MySQL 实现
+│       └── {功能}Mapper.java
+├── convert/
+│   └── {功能}Convert.java       // 对象转换
+├── enums/
+│   └── {功能}Enum.java         // 枚举定义
+└── framework/
+    └── {模块}Configuration.java // 配置类
+```
+
+### 3. 核心注解和工具类使用
+
+#### 权限控制
+```java
+@PreAuthorize("@ss.hasPermission('system:user:query')")
+```
+
+#### 数据权限
+```java
+@DataPermission(deptAlias = "d")
+```
+
+#### 多租户
+```java
+@TenantIgnore // 忽略多租户
+```
+
+#### 操作日志
+```java
+@OperateLog(type = CREATE)
+```
+
+### 4. API 设计规范
+- 使用 RESTful 风格
+- 统一返回 `CommonResult<T>` 格式
+- 使用 `@Valid` 进行参数校验
+- 使用 `@ApiOperation` 添加接口文档
+
+### 5. 数据库设计规范
+- 表名使用模块前缀：`{模块名}_{表名}`
+- 必备字段：`id`, `create_time`, `update_time`, `creator`, `updater`, `deleted`, `tenant_id`
+- 使用 MyBatis Plus 的 `BaseEntity` 基类
+
+## 代码生成器使用
+1. 访问管理后台的代码生成功能
+2. 导入数据库表
+3. 配置生成选项
+4. 一键生成前后端代码
+
+## 测试规范
+- 单元测试使用 JUnit 5 + Mockito
+- 集成测试继承 `BaseDbUnitTest`
+- 测试配置文件：[application-unit-test.yaml](mdc:yudao-module-system/src/test/resources/application-unit-test.yaml)
--- a/.cursor/rules/module-structure.mdc
+++ b/.cursor/rules/module-structure.mdc
@@ -0,0 +1,50 @@
+# 模块结构指南
+
+## 核心模块详解
+
+### 基础框架模块
+- **yudao-common**：通用工具类和基础组件
+- **yudao-framework**：Spring Boot 自动配置和扩展
+- **yudao-dependencies**：统一依赖版本管理
+
+### 系统核心模块
+- **yudao-module-system**：系统管理功能（用户、角色、菜单、部门等）
+- **yudao-module-infra**：基础设施功能（文件、配置、代码生成等）
+
+### 业务扩展模块（可选）
+- **yudao-module-bpm**：工作流程管理，基于 Flowable
+- **yudao-module-pay**：支付系统，支持多渠道支付
+- **yudao-module-member**：会员中心管理
+- **yudao-module-mall**：商城系统功能
+- **yudao-module-crm**：客户关系管理
+- **yudao-module-erp**：企业资源计划
+- **yudao-module-mp**：微信公众号管理
+- **yudao-module-report**：报表和大屏功能
+- **yudao-module-ai**：AI 大模型集成
+- **yudao-module-iot**：物联网设备管理
+
+## 模块激活配置
+在 [pom.xml](mdc:pom.xml) 中通过注释/取消注释来控制模块的激活：
+```xml
+<!-- 默认激活的核心模块 -->
+<module>yudao-module-system</module>
+<module>yudao-module-infra</module>
+
+<!-- 可选业务模块（注释表示未激活）-->
+<!--<module>yudao-module-member</module>-->
+<!--<module>yudao-module-bpm</module>-->
+```
+
+## 前端对应项目
+- **Vue3 + element-plus**：现代化管理后台
+- **Vue3 + vben(ant-design-vue)**：企业级管理后台
+- **Vue2 + element-ui**：经典版管理后台
+- **uni-app**：移动端和小程序支持
+
+## 数据库支持
+项目支持多种数据库，脚本位于 [sql/](mdc:sql/) 目录：
+- MySQL（推荐）
+- PostgreSQL
+- Oracle
+- SQL Server
+- 国产数据库（达梦、人大金仓等）
--- a/.cursor/rules/project-architecture.mdc
+++ b/.cursor/rules/project-architecture.mdc
@@ -0,0 +1,45 @@
+# 芋道管理系统项目架构指南
+
+## 项目概述
+这是一个基于 Spring Boot 2.7.18 + Vue3 的企业级快速开发平台，采用多模块架构设计。
+
+## 核心架构
+
+### 主要入口点
+- 应用启动类：[YudaoServerApplication.java](mdc:yudao-server/src/main/java/cn/iocoder/yudao/server/YudaoServerApplication.java)
+- 根 Maven 配置：[pom.xml](mdc:pom.xml)
+
+### 核心模块结构
+- **yudao-dependencies**：Maven 依赖版本管理
+- **yudao-framework**：Java 框架拓展和通用组件
+- **yudao-server**：主服务器，整合所有模块
+- **各业务模块**：按业务领域拆分的独立模块
+
+### 技术栈
+- **后端框架**：Spring Boot 2.7.18 + Spring Security + MyBatis Plus
+- **数据库**：MySQL + Redis + 支持多种国产数据库
+- **工作流**：Flowable 6.8.0
+- **API 文档**：Springdoc + Swagger
+- **监控**：Spring Boot Admin + SkyWalking
+
+### 包结构规范
+```
+cn.iocoder.yudao.module.{模块名}
+├── api/          # 对外接口定义
+├── controller/   # REST 控制器
+├── service/      # 业务逻辑层
+├── dal/          # 数据访问层
+├── convert/      # 对象转换器
+├── enums/        # 枚举定义
+└── framework/    # 模块框架配置
+```
+
+### 配置文件
+- 主配置：[application.yaml](mdc:yudao-server/src/main/resources/application.yaml)
+- 数据库脚本：[sql/mysql/](mdc:sql/mysql/)
+
+## 关键设计模式
+- **多模块架构**：业务功能按模块独立开发和部署
+- **统一响应格式**：所有 API 使用统一的响应结构
+- **分层架构**：Controller -> Service -> DAO 的经典三层架构
+- **权限控制**：基于 RBAC 的细粒度权限管理