开发指南
RuoYi Office 是一套可二开的企业管理平台。业务写在 yudao-module-*，横切在 yudao-framework，组织与文件在 system / infra。PC 走 Vben，移动端走 UniApp，审批、进销存、制造仓储可以按模块裁剪。
本指南面向二次开发。环境拉起见 快速开始。默认端口 48080，管理端 /admin-api，用户端 /app-api。进程怎么拆见 技术架构。
功能分层
业务系统构建于通用模块，通用模块实现于框架组件。业务模块只写领域；安全、租户、联表、缓存由框架横切，不要在某个 Controller 里再造一套返回码或分页。
系统架构：业务系统 → 通用模块 → 框架组件。
| 层 | 职责 | 放什么 | 仓库 |
|---|---|---|---|
| 业务系统 | 只写本域单据和台账 | OA、HRM、CRM、ERP、MES、WMS、Mall、AI、IoT、IM、合同 / 项目 / 资产、公众号 / 报表 | ruoyi-office/yudao-module-* |
| 通用模块 | 给业务用的平台能力 | System、Infra、BPM、Pay、Member、Report | 菜单在系统管理 / 基础设施 / 工作流 |
| 框架组件 | 装配即生效，没有自己的业务菜单 | Web、Security、MyBatis、Redis、MQ、Job、Protection、Monitor、Tenant、DataPermission、Excel、WebSocket | ruoyi-office/yudao-framework/ |
硬规则：
- 新业务只依赖平台（system / infra / framework，按需 bpm / pay）。OA 模块不要去引 CRM 的表。
- Starter 不出现
processDefinitionKey。审批契约在yudao-common的FlowBillService，发布和办理在 BPM。
三端与两个前缀
三端只打框架约定的两个前缀。Controller 不要手写 /admin-api，由 WebProperties 按包名拼：**.controller.admin.** 走管理端，**.controller.app.** 走用户端。
| 端 | 工程 | 打哪个前缀 |
|---|---|---|
| 管理端 PC | ruoyi-office-vben/apps/web-antd/ | /admin-api |
| 移动 / 小程序 | ruoyi-office-uniapp/ | /admin-api（管理端登录）或 /app-api（会员端） |
| 大屏 | ruoyi-office-ui-go-view/ | 按报表 / 大屏接口走同一套前缀 |
示意图：前缀是契约，不是某一个进程名。进程怎么装见技术架构。
工作区地图
根目录是多仓工作区，不要把前端页写进 Java 模块，也不要把增量 SQL 写进业务 jar。
| 名称 | 说明 | 仓库路径 |
|---|---|---|
| 后端 | 启动入口与模块聚合 | ruoyi-office/ |
| 框架 | Starter 与 yudao-common | ruoyi-office/yudao-framework/ |
| 业务模块 | *-api 契约 + *-server 实现 | ruoyi-office/yudao-module-*/ |
| PC | 管理端主应用 | ruoyi-office-vben/apps/web-antd/ |
| 移动 | 分包按模块 | ruoyi-office-uniapp/ |
| 库脚本 | dump + 按日增量 | ruoyi-office-db/ |
后端分层固定为 controller / service / dal / convert / vo。返回统一 CommonResult，业务失败走 ServiceException。
一次请求落在哪一层
管理端请求先进框架，再进业务。完整过滤器链见 框架层。
示意图：鉴权、租户、数据范围是框架横切。Controller 只调本模块 Service。
| 名称 | 落在哪 | 仓库路径 |
|---|---|---|
| 前缀与扫包 | 框架 Web | yudao-spring-boot-starter-web WebProperties |
| Token | 框架 Security | TokenAuthenticationFilter |
| 租户 | 框架 biz-tenant，默认打开 | yudao-spring-boot-starter-biz-tenant |
| 功能权限 | 菜单上的权限字 | @PreAuthorize |
| 数据权限 | 角色数据范围 | @DataPermission |
| 持久化 | 框架 MyBatis | BaseMapperX / 联表 |
租户、权限、审批
这三件事经常被写错层。
租户是字段隔离。拦截器给 SQL 拼 tenant_id。忽略租户的注解要少用，忽略错了会串户。
功能权限写在菜单上，不是框架另开一张权限表。数据权限按角色数据范围滤行。按钮示例：角色数据权限 1064。
审批不是框架菜单。业务单实现 FlowBillService，流程模型自己绑 formCustomViewPath。用车的 key 是 oa_car_apply_bill，来自 OaBillTypeEnum，不是目录名 car。
不要用目录名当流程 key
FlowBillService 按各模块单据枚举找实现。模型里的自定义表单路径必须和页面目录一致，例如 apply/info，不要指向已删的 apply/detail。
模块怎么裁
交付分 OA 版和全功能版。OA 版包含系统、基建、流程、协同办公、人力等；全功能版再包含 CRM、ERP、商城、AI、合同、资产等。本地减模块见 迁移模块。
菜单 id：官方 1–9999，二开 10000–99999。初始化用 ruoyi-office-db/dump/latest/ 的 schema 与 static_data。之后改表走 ruoyi-office-db/update/ 按日增量。
怎么读
先读架构设计，再走 核心必学：跑起来 → 租户 → 权限 → 流程配置 → 两种表单。框架层在「框架」组，系统与基建在「平台」组，业务按管理端顶级菜单收在后面。
示意图：先对骨架，再走学习地图，再下钻框架和业务域。
跑通系统，装完租户、权限、流程配置和两种表单。
01 骨架项目结构先对目录，再读框架层：一次请求怎么过 Token、租户、权限、联表。
02 流程流程功能设计业务单实现 FlowBillService。不要用目录名当 processDefinitionKey。
| 阶段 | 读完能做什么 | 下一篇 |
|---|---|---|
| 0 架构 | 对上三层和两种部署 | 总览 → 技术架构 |
| 1 核心必学 | 登录、建租户、配角色、发布一条流程 | 核心必学 |
| 2 骨架 | 会对目录，会改 VO / 权限 / 租户 | 项目结构 → 框架层 |
| 3 业务 | 打开对应子系统总览，再进功能篇 | 下表 |
平台补丁（用户、文件、生成器、监控）在改完骨架后再读：系统功能设计、基建功能设计。前端目录约定见 前端工程结构。
业务域
先点功能设计总览，再进该组功能篇。仓储有三套表（模块 WMS wms_*、MES mes_wm_*、ERP erp_stock），先看 WMS、MES、ERP 怎么选。
| 域 | 总览 | 管理端根菜单 |
|---|---|---|
| 流程与表单 | 流程功能设计 | BPM |
| 协同办公 | OA 功能设计 | /oa |
| 人力 | 人力功能设计 | /hrm |
| 合同 / 项目 / 资产 | 合同、项目、资产 | /contract /project /asset |
| 客户 / 进销存 | CRM、ERP | /crm /erp |
| 制造 / 仓储 | MES、WMS | 6261 /mes、7400 /wms |
| 交易与内容 | 支付、会员、商城、公众号 | /pay /member /mall /mp |
| 智能与物联 | AI、IoT、IM、报表 | /ai /iot /im /report |
