开发指南

面向希望快速上手 RuoYi Office 的开发者，覆盖环境要求、启动命令与内容贡献方式。

环境要求

• Node.js ≥ 20.12.0（推荐与前端工程保持一致）
• 包管理：pnpm ≥ 10.22.0（前端工程强制使用 pnpm）
• 推荐使用现代浏览器与 VS Code / Cursor 等具备 TypeScript 支持的 IDE

项目结构（文档站）

docs/
  .vitepress/        # 站点配置
  index.md           # 首页
  product/           # 产品功能文档目录
    index.md         # 产品功能总览
    system.md        # 系统管理
    bpm.md           # 流程中心
    ...
  guide/             # 开发指南目录
    index.md         # 开发指南
    markdown-examples.md
    api-examples.md
  demo/              # 在线体验目录
    index.md
  donate/            # 捐赠目录
    index.md
  hosting/           # 托管平台目录
    index.md

常用命令（VitePress）

• 本地预览：pnpm docs:dev
• 构建产物：pnpm docs:build
• 本地预览已构建产物：pnpm docs:preview

如未安装 pnpm，可先执行 npm install -g pnpm。

前后端工程参考

• 前端（Vben 版）：ruoyi-office-vben/apps/web-antd，使用 Vue 3 + Vite + Ant Design Vue + Vben Admin + TypeScript。
• 后端：ruoyi-office，基于 Spring Boot 3.5.4 + Spring Cloud Alibaba，支持多租户、工作流、支付、报表等。
• SQL 初始化：ruoyi-office/sql/mysql 下提供组件与业务初始化脚本（含工作台组件）。

代码与规范

• TypeScript 严格模式、ESLint + Prettier 校验；后端遵循阿里巴巴 Java 开发手册。
• 统一错误码与异常处理、操作/登录日志、数据权限、多租户封装。
• 前端组件采用 <script setup>，Props 使用 defineProps/withDefaults，样式优先使用 Tailwind 辅以 Scoped 样式。

---

技术说明

前端技术栈

技术	版本	说明
Vue	3.5.x	渐进式 JavaScript 框架
Vite	6.3.x	下一代前端构建工具
TypeScript	5.8.x	JavaScript 的超集，增加类型系统
Ant Design Vue	4.2.x	企业级 UI 组件库
Element Plus	2.10.x	Vue 3 组件库（部分使用）
Vben Admin	-	企业级中后台模板
Pinia	3.0.x	Vue 状态管理工具
Vue Router	4.5.x	Vue 官方路由
Tailwind CSS	3.4.x	原子化 CSS 框架
VueUse	13.x	Vue 组合式 API 工具集
VeeValidate	4.x	表单验证
Zod	3.25.x	TypeScript 优先的模式验证

后端技术栈

技术	版本	说明
Spring Boot	3.5.x	Java 应用开发框架
Spring Cloud	2025.0.x	微服务架构解决方案
Spring Cloud Alibaba	2023.0.x	阿里微服务组件
Spring Security	6.x	安全认证与授权框架
MyBatis Plus	3.5.x	MyBatis 增强工具
Druid	1.2.x	数据库连接池
Redis	-	分布式缓存
Redisson	3.50.x	Redis 客户端
RocketMQ	2.3.x	消息队列
Flowable	7.0.x	工作流引擎
SkyWalking	9.5.x	分布式链路追踪
MapStruct	1.6.x	对象映射工具
Hutool	5.8.x	Java 工具类库

数据库支持： MySQL、Oracle、PostgreSQL、达梦、人大金仓、SQL Server 等

移动端技术栈

基于 uni-app 跨平台开发框架，一套代码多端运行：

技术	说明
uni-app	跨平台应用开发框架
Vue 3	前端框架
TypeScript	类型安全
uView UI	uni-app 组件库

支持平台： 微信小程序、H5、App（iOS/Android）

移动端开发规范详见：uni-app 开发规范

工作流技术

基于 Flowable 7 的企业级工作流解决方案：

特性	说明
BPMN 2.0	标准流程建模规范
可视化设计器	支持 BPMN 设计器和简易设计器两种模式
动态表单	流程表单动态设计与绑定
多种审批模式	会签、或签、加签、委派、退回、抄送
流程监控	流程实例监控、任务超时提醒
流程报表	流程效率分析、审批统计

单元测试

框架	说明
JUnit 5	Java 单元测试框架
Mockito	Mock 框架
Spring Boot Test	Spring 测试支持
H2 Database	内存数据库（测试用）
Vitest	前端单元测试框架

单元测试规范详见：单元测试

工程化特性

• 代码规范： 遵循阿里巴巴 Java 开发手册，ESLint + Prettier + TypeScript 严格校验
• 代码生成： 根据数据库表自动生成前后端 CRUD 代码
• 自动化构建： Maven/Gradle + pnpm 构建脚本
• 多环境支持： 开发、测试、生产环境配置隔离
• 容器化部署： Docker + Docker Compose 一键部署

更多技术细节详见：技术选型

贡献与协作

1. Fork 或新建分支，保持与主干同步。
2. 提交前确保通过 lint 与构建（前端：pnpm lint && pnpm build；后端：mvn -T 1C clean verify，如适用）。
3. PR/提交信息简明描述改动：范围 + 目的（例：feat: add task list maxRecordNum config）。
4. 文档改动：新增页面请补充到侧边栏/导航；保持中文描述，图示与代码块简洁可复现。

常见问题

• 构建依赖未安装：删除 node_modules 后重新执行 pnpm install。
• 端口占用：VitePress 默认 5173，可通过 pnpm docs:dev -- --port 5174 调整。
• 主题样式不一致：清理 .vitepress/cache 后重启，或在浏览器禁用缓存强制刷新。