# ruoyi-plus-flutter

**Repository Path**: sunlunchang/ruoyi-plus-flutter

## Basic Information

- **Project Name**: ruoyi-plus-flutter
- **Description**: 基于RuoYi-Vue-Plus实现的Flutter客户端
- **Primary Language**: Dart
- **License**: MIT
- **Default Branch**: develop-2.0
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 152
- **Forks**: 66
- **Created**: 2024-09-13
- **Last Updated**: 2026-07-28

## Categories & Tags

**Categories**: cross-platform-mobiledev

**Tags**: None

## README

# RuoYi Flutter Plus

## 提示

本项目使用 FVM 固定 Flutter `3.44.8`、Dart `3.12.2`，后续可在完整验证后主动
升级。当前严格维护和验收 Android API 24+、iOS 13+、Web；Windows、Linux、
macOS 工程入口继续保留，本轮未作为严格验收平台。

## 💡 简介

**RuoYi Flutter Plus** 是一个对接
[RuoYi-Vue-Plus](https://gitee.com/dromara/RuoYi-Vue-Plus) 后端协议的企业级
Flutter 多模块客户端脚手架。项目采用 Flutter Workspace 架构，将可复用基础能力、
跨业务共享能力和 RuoYi 示例业务分层组织，为后续抽取通用脚手架或开发新业务项目
提供真实、完整的调用范例。

### ⭐ 核心亮点

- 🎯 **多平台工程**：当前重点维护 Android、iOS、Web，并保留桌面端工程入口。
- 🏗️ **Workspace 架构**：模块化设计、统一依赖解析，基础能力与示例业务边界清晰。
- 🔐 **完整 RBAC 权限体系**：覆盖用户、角色、部门、岗位、菜单和按钮权限。
- 🏢 **多租户 SaaS 能力**：包含租户、租户套餐及相关业务配置。
- 📊 **丰富业务功能**：涵盖系统管理、日志监控、文件管理、缓存监控等真实页面。
- 🎨 **Material 3 设计**：支持明暗主题并默认跟随系统。
- 🌍 **模块化国际化**：中文、英文跟随系统语言，其他语言回退简体中文。
- 📦 **便捷工程工具**：提供依赖解析、本地化、代码生成、清理和调试编译脚本。

## 🏗️ 项目架构

项目采用 Flutter Workspace 多模块架构，各层职责清晰，基础能力和 RuoYi 示例业务
可以分别演进。

### 📁 模块结构总览

```text
ruoyi-flutter-plus/
├── .agents/skills/              # Codex 项目技能与公开 API 参考
├── scaffold/                    # 当前架构指南和脚手架清理清单
├── tool/                        # Workspace 统一任务入口
├── scripts/                     # Shell、Batch 便捷脚本
├── lib/                         # 应用装配、启动、路由、主题和根页面
├── 📦 基础设施层
│   ├── base/                    # 网络、Result 解码、配置、App MVVM
│   └── lib_module/
│       ├── fast/                # 列表、分页、刷新和页面组合
│       ├── db_base/             # 偏好存储命名空间和启动快照
│       └── form_extra/          # FormBuilder 字段与类型化表单绑定
├── 🔌 功能特性层
│   └── feature/
│       ├── auth/                # 登录认证
│       ├── bizapi/              # 公共业务实体、仓储和会话状态
│       ├── component/           # 字典、树、附件、裁剪和 Web 内容
│       ├── welcome/             # 欢迎页和自动登录决策
│       └── mix/                 # 可选原生混合容器适配
└── 💼 业务应用层
    └── business/
        ├── biz_main/            # 主业务入口和仪表盘
        ├── system/              # 系统管理
        └── user/                # 用户、部门、岗位和角色管理
```

依赖方向：

```text
根应用 / business
        ↓
feature
        ↓
base / lib_module
        ↓
boxes_flutter
```

基础包不反向依赖示例业务。Repository 不操作 Widget、Toast、Navigator 或共享业务
状态，页面状态和交互反馈由 VM 与应用装配层负责。

### 🎯 模块详细介绍

#### 📦 基础设施层

**核心模块**

- **[Base - 基础核心模块](base/README.md)** 🔧
  提供 Retrofit 网络环境、响应解码、运行配置、启动任务和应用层 MVVM 门面。

**工具库模块**

- **[Fast - 快速开发能力](lib_module/fast/README.md)** ⚡
  提供 `BaseListDataVmSub`、`BasePageDataVmSub`、刷新视图和常用页面组合。

- **[DB Base - 数据持久化](lib_module/db_base/README.md)** 💾
  提供异步偏好存储命名空间、启动期配置快照和旧数据迁移能力。

- **[Form Extra - 表单扩展](lib_module/form_extra/README.md)** 📝
  提供基于 `flutter_form_builder` 的字段组件和类型化 `FormBinding<T>`。

#### 🔌 功能特性层

- **[Auth - 认证授权](feature/auth/README.md)** 🔐
  提供登录、验证码、多租户登录参数和完整会话初始化入口。

- **[BizAPI - 跨业务 API](feature/bizapi/README.md)** 🌐
  按领域组织公共实体、Retrofit 仓储、字典状态、用户状态和会话服务。

- **[Component - 通用组件](feature/component/README.md)** 🎨
  提供字典选择、树形选择、附件、图片裁剪和跨平台 Web 内容组件。

- **[Welcome - 欢迎页](feature/welcome/README.md)** 👋
  负责欢迎页展示、自动登录超时和登录页/首页去向决策。

- **[Mix - 原生混合](feature/mix/README.md)** 🔗
  保留 Flutter 与原生混合容器的可选适配入口。

#### 💼 业务应用层

- **[BizMain - 主业务入口](business/biz_main/README.md)** 🏠
  提供应用主框架、导航结构和数据仪表盘。

- **[System - 系统管理](business/system/README.md)** ⚙️
  提供租户、字典、菜单、参数、公告、日志、OSS、在线用户和缓存监控等功能。

- **[User - 用户管理](business/user/README.md)** 👥
  提供用户、部门、岗位、角色、个人中心和权限分配等功能。

## 🔗 配套后端系统

| 后端系统 | 版本 | 仓库地址 | 说明 |
| --- | --- | --- | --- |
| RuoYi-Vue-Plus | 5.X | [Gitee](https://gitee.com/dromara/RuoYi-Vue-Plus) | 当前主要对接目标 |
| RuoYi-Cloud-Plus | 2.X | [Gitee](https://gitee.com/dromara/RuoYi-Cloud-Plus) | 使用前需按网关和认证协议调整环境配置 |

> 请确保后端接口版本与本项目实体、路由和认证协议一致。

## 🚀 快速开始

### 环境要求

- FVM。
- Flutter `3.44.8`、Dart `3.12.2`，由 `.fvmrc` 固定。
- Android 使用 JDK 17，最低 API 24。
- iOS 最低 13.0。
- Android Studio、VS Code 或 IntelliJ IDEA。

### 安装依赖

```bash
fvm install
fvm flutter pub get
```

也可以使用便捷脚本：

```bash
# macOS / Linux
./scripts/pub_get_all.sh

# Windows
scripts\pub_get_all.bat
```

### 生成并运行

```bash
# 生成所有模块的国际化代码
fvm dart run tool/workspace.dart gen-l10n

# 生成 Retrofit、JsonSerializable 和资源代码
fvm dart run tool/workspace.dart codegen

# 运行应用
fvm flutter run
```

对应的 Shell、Batch 入口仍可使用：

```bash
./scripts/gen_l10n_all.sh
./scripts/build_runner_all.sh
```

### 调试编译

```bash
fvm flutter build apk --debug
fvm flutter build ios --simulator --debug
fvm flutter build web --debug
```

这里只要求调试编译，不需要生成发布包。更多命令见
[scripts/README.md](scripts/README.md)。

### 脚手架与开发文档

- [当前脚手架架构](scaffold/standards/current-architecture.md)
- [现代化迁移指南](MIGRATION.md)
- [仓库协作约定](AGENTS.md)
- [脚手架索引](scaffold/INDEX.md)
- [干净脚手架检查清单](scaffold/checklists/clean-scaffold.md)

### Codex 技能入口

项目技能位于 [.agents/skills](.agents/skills)，技能中的 API 和示例均以当前公开
门面为准：

| 聚合技能 | 使用场景 |
| --- | --- |
| [project-all](.agents/skills/project-all/SKILL.md) | 选择本项目分析、工程、领域和平台技能 |
| [boxes-flutter-all](.agents/skills/boxes-flutter-all/SKILL.md) | 选择 Boxes Flutter 的 MVVM、路由、UI 和工具能力 |

更具体的项目技能和 `boxes-flutter-*` 技能由聚合技能按任务边界选择，
不需要在 README 中重复整套 API。

## 📱 在线体验

**测试账号**：admin / admin123

- **Android APK 下载**：[发布页面](https://gitee.com/sunlunchang/ruoyi-plus-flutter/releases)

## 🛠️ 技术栈

### 核心框架

| 技术 | 版本 | 说明 |
| --- | --- | --- |
| Flutter | 3.44.8 | FVM 固定的稳定版 Flutter SDK |
| Dart | 3.12.2 | 当前 Flutter SDK 配套版本 |
| Material 3 | Flutter SDK | 明暗主题和语义化设计 token |

### 主要依赖

| 库名 | 功能 |
| --- | --- |
| [boxes_flutter](https://gitee.com/sunlunchang/boxes-flutter) | MVVM、Result、Command、路由、分页、选择和工具基础框架 |
| [provider](https://pub.dev/packages/provider) | 依赖注入和状态监听 |
| [retrofit](https://pub.dev/packages/retrofit) + [dio](https://pub.dev/packages/dio) | 类型化网络协议与请求执行 |
| [easy_refresh](https://pub.dev/packages/easy_refresh) | 下拉刷新和加载更多 |
| [flutter_form_builder](https://pub.dev/packages/flutter_form_builder) | 表单构建与校验 |
| [fl_chart](https://pub.dev/packages/fl_chart) | 数据图表 |
| [cached_network_image](https://pub.dev/packages/cached_network_image) | 网络图片加载与缓存 |
| [webview_flutter](https://pub.dev/packages/webview_flutter) | Android、iOS Web 内容 |
| [shared_preferences](https://pub.dev/packages/shared_preferences) | 异步偏好存储 |

完整依赖及锁定版本见 [pubspec.yaml](pubspec.yaml) 和 `pubspec.lock`。

## ✨ 架构特色

### 🏗️ Workspace 模块化架构

- **统一解析依赖**：根 `pubspec.lock` 固定完整依赖图，日常拉取不会自动漂移。
- **模块独立维护**：每个模块保持自己的公开门面、资源和本地化内容。
- **基础与业务分离**：可删除 `business/*` 抽取新项目，不让基础层反向依赖业务。
- **职责边界清晰**：根应用、业务层、功能层、基础层保持单向依赖。

### 🎨 MVVM 架构模式

- **View**：使用 `AppBasePage`、`AppBaseState` 和 Provider 渲染页面。
- **ViewModel**：保存页面状态、Command、Repository 和 VmSub，不保存
  `BuildContext`。
- **Model**：使用明确的实体和不可变状态表达业务数据。
- **Repository**：通过 Retrofit 获取数据，并返回类型化 `Result<T>`。

### 🔄 列表与分页组件

- **`ListDataVd<T>`**：统一普通列表的首次加载、刷新、空数据和失败状态。
- **`PageDataVd<T>`**：统一分页刷新、追加、失败重试和无更多状态。
- **`BaseListDataVmSub<T>`**：封装普通列表数据所有权和过期响应处理。
- **`BasePageDataVmSub<T>`**：封装从第 1 页开始的分页状态和请求生命周期。

## 📋 功能列表

基于 [RuoYi-Vue-Plus 5.X](https://gitee.com/dromara/RuoYi-Vue-Plus) 并结合移动端
特性实现：

| 业务 | 功能说明 | 本项目是否实现 | 后续是否实现或更新 |
| --- | --- | --- | --- |
| 主题切换 | 支持 Material 3 白天/黑夜主题切换，默认跟随系统主题 | 是 | 是 |
| 系统登录 | 通过系统给定的账号密码进行登录 | 是 | 是 |
| 租户管理 | 管理租户套餐、过期时间、用户数量和企业信息等 | 是 | 是 |
| 租户套餐管理 | 管理租户可使用的套餐及套餐所包含的菜单 | 是 | 是 |
| 用户管理 | 新增用户并分配所属部门、角色和岗位等 | 是 | 是 |
| 部门管理 | 配置公司、部门、小组等树形组织机构和数据权限 | 是 | 是 |
| 岗位管理 | 配置系统用户所属职务 | 是 | 是 |
| 菜单管理 | 配置系统菜单、操作权限和按钮权限标识等 | 是 | 是 |
| 角色管理 | 分配角色菜单权限并按机构划分数据范围 | 是 | 是 |
| 字典管理 | 维护系统中经常使用的固定数据 | 是 | 是 |
| 参数管理 | 管理系统动态配置参数 | 是 | 是 |
| 通知公告 | 系统通知公告信息发布维护 | 仅支持查看 | 是 |
| 操作日志 | 查询正常操作、异常信息等系统日志 | 是 | 是 |
| 登录日志 | 查询系统登录和登录异常记录 | 是 | 是 |
| 文件管理 | 文件展示、上传、下载和删除等管理 | 是 | 是 |
| 文件配置管理 | 动态管理文件上传、下载所需配置 | 是 | 是 |
| 在线用户管理 | 监控在线用户并执行强制退出 | 是 | 是 |
| 代码生成 | 多数据源前后端代码生成和 CRUD 下载 | 否 | 否 |
| 缓存监控 | 查询系统缓存信息和命令统计 | 是 | 是 |
| 服务监控 | 监视 CPU、内存、磁盘、堆栈和在线日志等 | 否 | 否 |
| 定时任务 | 报表、任务、日志和执行器管理 | 否 | 否 |
| 在线构建器 | 拖动表单元素生成相应的 Flutter 代码 | 否 | 否 |
| WebView | 在 App 内打开网页 | 是 | 是 |
| 使用案例 | 展示系统基础能力的真实使用案例 | 是 | 是 |
| 工作流 | 系统工作流模块业务功能 | 否 | 是 |
| 我的任务 | 系统个人任务模块业务功能 | 否 | 是 |

## 📖 开发指南

### 批量执行脚本

本项目提供 macOS、Linux 和 Windows 便捷脚本，内部统一通过 FVM 执行：

```bash
# 获取 Workspace 依赖
./scripts/pub_get_all.sh

# 生成所有模块国际化代码
./scripts/gen_l10n_all.sh

# 生成 Retrofit、JsonSerializable 和资源代码
./scripts/build_runner_all.sh

# 清理所有模块构建产物
./scripts/clean_all.sh
```

Windows 使用同名 `.bat` 文件。详细说明见 [scripts/README.md](scripts/README.md)。

### 添加新模块

1. 在对应层级目录下创建模块。
2. 在根 `pubspec.yaml` 的 `workspace:` 中添加模块路径。
3. 为跨包能力建立顶层公开门面，避免其他模块深层导入实现文件。
4. 运行 `fvm flutter pub get`。
5. 按需补充模块 README、本地化、测试和 `.agents/skills` API 参考。

### 代码规范

- 遵循 [Effective Dart](https://dart.dev/effective-dart)。
- 使用 `fvm dart format` 格式化代码。
- 使用 `fvm flutter analyze` 检查代码质量。
- 公共签名使用具体类型，JSON 边界使用 `Object?`。
- 页面、网络、业务和工具类遵守单一职责、高内聚、低耦合原则。

## 🤝 参与贡献

欢迎提交 Issue 和 Pull Request！

1. Fork 本仓库。
2. 创建特性分支（`git checkout -b feature/AmazingFeature`）。
3. 提交更改（`git commit -m 'Add some AmazingFeature'`）。
4. 推送分支（`git push origin feature/AmazingFeature`）。
5. 提交 Pull Request。

## 📄 开源协议

本项目基于 MIT 协议开源。

## 💖 捐献作者

感谢每一位支持者的慷慨相助！您的每一份贡献都是对我莫大的鼓励。

| | |
| --- | --- |
| ![微信收款](screenshot/94e00d3610816730d689567fe904464c_origin.png '微信收款') | ![支付宝收款](screenshot/5ede006d8b15ba913588e66ed89fd68a_origin.jpg '支付宝收款') |

## 演示图例

| | | |
| --- | --- | --- |
| ![屏幕截图](screenshot/Screenshot_20250321_114430_android.slc.ruoyi_plus_flutter.jpg '屏幕截图') | ![屏幕截图](screenshot/Screenshot_20250321_114446_android.slc.ruoyi_plus_flutter.jpg '屏幕截图') | ![屏幕截图](screenshot/Screenshot_20250321_114500_android.slc.ruoyi_plus_flutter.jpg '屏幕截图') |
| ![屏幕截图](screenshot/Screenshot_20250321_114507_android.slc.ruoyi_plus_flutter.jpg '屏幕截图') | ![屏幕截图](screenshot/Screenshot_20250321_114513_android.slc.ruoyi_plus_flutter.jpg '屏幕截图') | ![屏幕截图](screenshot/Screenshot_20250321_114520_android.slc.ruoyi_plus_flutter.jpg '屏幕截图') |
| ![屏幕截图](screenshot/Screenshot_20250321_114527_android.slc.ruoyi_plus_flutter.jpg '屏幕截图') | ![屏幕截图](screenshot/Screenshot_20250321_114534_android.slc.ruoyi_plus_flutter.jpg '屏幕截图') | ![屏幕截图](screenshot/Screenshot_20250321_114540_android.slc.ruoyi_plus_flutter.jpg '屏幕截图') |
| ![屏幕截图](screenshot/Screenshot_20250321_114544_android.slc.ruoyi_plus_flutter.jpg '屏幕截图') | ![屏幕截图](screenshot/Screenshot_20250321_114551_android.slc.ruoyi_plus_flutter.jpg '屏幕截图') | ![屏幕截图](screenshot/Screenshot_20250321_114556_android.slc.ruoyi_plus_flutter.jpg '屏幕截图') |
| ![屏幕截图](screenshot/Screenshot_20250321_114603_android.slc.ruoyi_plus_flutter.jpg '屏幕截图') | ![屏幕截图](screenshot/Screenshot_20250321_114618_android.slc.ruoyi_plus_flutter.jpg '屏幕截图') | ![屏幕截图](screenshot/Screenshot_20250321_114639_android.slc.ruoyi_plus_flutter.jpg '屏幕截图') |
| ![屏幕截图](screenshot/Screenshot_20250321_114647_android.slc.ruoyi_plus_flutter.jpg '屏幕截图') | ![屏幕截图](screenshot/Screenshot_20250321_114656_android.slc.ruoyi_plus_flutter.jpg '屏幕截图') | ![屏幕截图](screenshot/Screenshot_20250321_114707_android.slc.ruoyi_plus_flutter.jpg '屏幕截图') |
| ![屏幕截图](screenshot/Screenshot_20250321_114711_android.slc.ruoyi_plus_flutter.jpg '屏幕截图') | ![屏幕截图](screenshot/Screenshot_20250321_115955_android.slc.ruoyi_plus_flutter.jpg '屏幕截图') | ![屏幕截图](screenshot/Screenshot_20250321_114917_android.slc.ruoyi_plus_flutter.jpg '屏幕截图') |
| ![屏幕截图](screenshot/Screenshot_20250321_114923_android.slc.ruoyi_plus_flutter.jpg '屏幕截图') | | |