# ruoyi-rust

**Repository Path**: rustdev/ruoyi-rust

## Basic Information

- **Project Name**: ruoyi-rust
- **Description**: RuoYi-Rust(tokio，axum)是一个雄心勃勃的项目，旨在通过现代、高性能的 Rust 语言及其强大的生态系统，完整重写主流Ruoyi的Java Web 框架 后端服务
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 121
- **Forks**: 43
- **Created**: 2025-09-09
- **Last Updated**: 2026-07-25

## Categories & Tags

**Categories**: backend

**Tags**: None

## README

# RuoYi-Rust — 高性能 Rust 重构后端

####  丰盛辉煌

[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Rust Version](https://img.shields.io/badge/rust-1.88%2B-orange.svg)](https://www.rust-lang.org/)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)

---

> 有任何需求，请直接在 Issues 中提出，有时间会慢慢补充完善。

---

**RuoYi-Rust** 是一个雄心勃勃的项目，始于 2025-08-28，旨在通过现代、高性能的 Rust 语言及其强大的生态系统，完整重写主流 Java Web 框架 [RuoYi](https://gitee.com/y_project/RuoYi) 的后端服务。我们追求的目标不仅是功能对等，更是在性能、资源占用、安全性及现代化开发体验上实现全面超越，为 Rust 生态提供一个可复用的企业级管理系统方案。

🔗 **在线演示：[http://212.129.155.221:9081](http://212.129.155.221:9081)** | 账号：`admin` 密码：`admin123`

### 2026-07-21 功能扩展

- **工作流引擎**：新增基于 LogicFlow 的可视化工作流模块，支持流程定义、发起审批、任务审批/驳回/转办、抄送通知、审批历史追踪，内置请假审批示例。
- **Dify AI 智能问答**：集成 Dify AI 平台，支持 SSE 流式对话、多轮会话、思考过程展示，前端打字机效果实时渲染。
- **文件管理增强**：对象存储模块升级，新增大文件分片上传、多存储后端运行时管理、批量文件操作、自动识别存储厂商。
- **实时通信**：新增 WebSocket 双向消息推送和 SSE 服务端推送能力。
- **邮件/短信服务**：内置 SMTP 邮件发送（SSL/STARTTLS）和多供应商短信服务（阿里云、旦米等）。

### 2026-06-29 新版发布

- **前端全面升级**：配套前端从 RuoYi-Vue3 升级为基于 **Vue Vben Admin v5.7.0** 的 [ruoyi-rust-ui-plus](https://gitee.com/rustdev/ruoyi-rust-ui-plus.git)，采用 Vue 3 + TypeScript + Element Plus + Tailwind CSS v4 + UnoCSS，开发体验更佳。
- **代码生成工具增强**：新增完整的代码生成前端页面（导入表、创建表、预览代码、编辑配置、拖拽排序、批量下载），前后端全链路打通。
- **AI 协作新范式**：**所有新业务优先使用代码生成工具产出统一规范的项目骨架，保证架构一致、减少低级 bug；剩余业务细节交由 AI 自动填充，整体提升研发效率**。

## 🎯 配套项目

| 项目 | 说明 |
|------|------|
| **后端** | [ruoyi-rust](https://gitee.com/rustdev/ruoyi-rust.git) — 本项目，Rust 后端服务 |
| **前端（推荐）** | [ruoyi-rust-ui-plus](https://gitee.com/rustdev/ruoyi-rust-ui-plus.git) — 基于 Vue Vben Admin v5.7.0 + Element Plus + TypeScript |
| **前端（旧版）** | [ruo-yi-vue3](https://gitee.com/rustdev/ruo-yi-vue3.git) — RuoYi-Vue3 微调版（已停止维护） |

## ✨ 核心亮点 (Why RuoYi-Rust?)

- 🚀 **极致性能**: 基于 `Tokio` 和 `Axum` 框架，原生异步，无 GC 延迟。提供比原生 JVM 应用更快的 API 响应速度和显著降低的内存占用。

- 🔒 **内存安全**: 借助 Rust 强大的所有权和借用检查机制，从编译层面根除空指针、数据竞争等常见的运行时安全隐患，构建坚如磐石的系统。

- 📦 **极简部署**: 整个后端项目可编译为单个可执行文件（内置缓存系统），不依赖 JRE、Tomcat、Nginx 等任何外部运行时。部署过程从未如此简单：上传文件，启动，仅此而已。

- 🗄️ **多数据库支持**: 内置 **MySQL / PostgreSQL / SQLite** 适配，可通过 URL 或 host/port/database 结构化配置切换数据库，连接池大小、连接/空闲超时等参数均可配置。

- ⚡ **多级权限缓存**: 权限数据支持 **moka 本地缓存 (L1)**、**Redis 缓存 (L2)** 或两级混合模式，角色/菜单/用户授权变更时自动失效对应缓存，显著降低高频鉴权的数据库压力。

- 🛡️ **声明式数据脱敏**: 内置基于 `serde + schemars` 的字段脱敏能力，支持手机号、身份证、邮箱、姓名、AK/SK 等敏感信息按规则输出；既支持 `#[serde(with = "mask_phone")]` 这类开箱即用预设，也支持按字段通过参数化序列化器自定义保留位数与掩码策略，兼顾接口安全与 OpenAPI/JSON Schema 文档一致性。

- 🛠️ **现代化开发体验**:
  - **类型安全的数据库访问**: 采用 **SeaORM** 作为数据库访问层，遵循"数据库 Schema 为唯一真实来源"原则。不仅支持 MySQL / PostgreSQL / SQLite，还能在编译期发现大量不符合数据库表结构的查询错误。
  - **声明式权限控制**: 通过自定义过程宏实现类型安全的声明式 API 权限校验，将权限元数据与业务逻辑高度内聚，彻底告别手写权限字符串带来的风险。
  - **模块化设计**: 采用清晰的 Cargo Workspace 结构和分层架构，实现高内聚、低耦合，便于维护与扩展。
  - **数据库迁移**: 内置 `sea-orm-migration` 数据库迁移模块，Schema 变更通过版本化迁移脚本管理，告别手工维护 SQL。

## 📊 项目状态

我们正在逐步实现 RuoYi 的全部功能。当前已完成的核心模块如下：

- [x] **核心框架**
  - [x] 配置加载 (`config-rs`)
  - [x] 结构化日志 (`tracing`)
  - [x] 数据库连接池 (SeaORM，支持 MySQL / PostgreSQL / SQLite)
  - [x] 统一响应 (`AjaxResult`) 与错误处理 (`AppError`)
  - [x] JWT 认证中间件 (`jwt-simple`)
  - [x] 高性能本地缓存 (`moka`)，可选 Redis 二级缓存
  - [x] 数据库迁移 (`sea-orm-migration`)
  - [x] 客户端登录扩展：登录支持透传 `client_id`，可按客户端配置解析设备类型、固定超时与活跃超时
  - [x] 单端登录控制：支持按 `user_id + device_type` 维度顶号；当 `security.concurrent_login = false` 时，同账号同端新登录会挤掉旧会话
  - [x] 在线会话增强：在线用户记录已保存 `device_type`、`client_id`、活跃超时与固定过期上限，便于区分 Web / App 等登录来源
  - [x] WebSocket 实时通信（双向消息推送，心跳保活）
  - [x] SSE 服务端推送（Server-Sent Events，实时通知广播）
  - [x] 邮件服务（SMTP，支持 SSL / STARTTLS）
  - [x] 短信服务（多供应商适配：阿里云、旦米、Mock、固定验证码模式）
  - [x] API 请求/响应加密（RSA + AES-256-ECB，敏感接口自动加密）
  - [x] 雪花 ID 生成器（可配置 worker_id / datacenter_id / epoch）
  - [x] Excel 导入导出（基于过程宏 `#[derive(ExcelSchema)]`）
  - [x] 字段翻译（字典翻译、OSS ID → URL，基于 `#[TranslateFill]` 宏）
  - [x] 数据脱敏（基于 `serde_mask` 工具，支持 `mask_phone` / `mask_id_card` / `mask_email` / `mask_name` / `mask_ak_sk` / `mask_full`）

- [x] **系统模块 (`system`)**
  - [x] 登录、获取用户信息、动态路由 (`/login`, `/getInfo`, `/getRouters`)
  - [x] 菜单管理
  - [x] 部门管理
  - [x] 字典管理
  - [x] 参数管理
  - [x] 角色管理
  - [x] 用户管理（CRUD、导入导出、数据权限）
  - [x] 系统通知（支持 SSE 广播推送）
  - [x] 岗位管理
  - [x] 客户端管理
  - [x] API Token 管理（签发/撤销/Signer 鉴权）
  - [x] WebSocket 实时消息
  - [x] SSE 实时推送

- [x] **权限体系**
  - [x] 声明式权限校验过程宏 (`ruoyi-macros`)
  - [x] 数据权限（全部 / 本部门 / 本部门及以下 / 自定义 / 仅本人）

- [x] **监控模块 (`monitor`)**
  - [x] 操作日志
  - [x] 登录日志
  - [x] 在线用户
  - [x] 定时任务
  - [x] 服务监控（CPU / 内存 / 磁盘）
  - [x] 缓存监控

- [x] **对象存储 (`oss`)**
  - [x] 文件上传 / 下载
  - [x] 大文件分片上传（>5MB 自动分片，自动管理 Part）
  - [x] AWS S3 协议兼容（推荐 [RustFS](https://github.com/rustfs/rustfs)，同时兼容 MinIO、阿里云 OSS、腾讯云 COS、华为云 OBS、AWS S3 等）
  - [x] 多存储后端配置（运行时切换默认存储后端，支持多 Bucket 管理）
  - [x] 文件管理列表（按 ID 批量查询、URL 获取、删除）
  - [x] 自动识别存储厂商（根据 endpoint 自动判断 path-style / virtual-hosted-style）

- [x] **工作流模块 (`workflow`)**
  - [x] 流程定义管理（CRUD、发布/取消发布、版本管理）
  - [x] 流程实例管理（发起流程、终止流程、我的发起、进度查看）
  - [x] 任务管理（我的待办/已办、审批/驳回、任务转办）
  - [x] 可视化流程设计器（基于 LogicFlow JSON 格式）
  - [x] 审批节点类型：审批人节点（`approver`）、条件分支（`condition`）、抄送节点（`cc`）
  - [x] 审批人解析策略：指定用户 / 指定角色 / 指定部门 / 发起人自己
  - [x] 会签 / 或签审批模式
  - [x] 抄送通知记录
  - [x] 审批历史轨迹记录
  - [x] 请假管理（示例业务流程，演示工作流接入）

- [x] **AI 智能问答 (`agents`)**
  - [x] Dify AI 平台对接（SSE 流式代理）
  - [x] 多轮对话支持（conversation_id 会话续接）
  - [x] 流式事件透传：`message` / `agent_message` / `message_end` / `reasoning_chunk`
  - [x] 思考过程展示（reasoning_chunk 事件透传）
  - [x] 前端 SSE 流式渲染（打字机效果）

- [x] **代码生成工具 (`code-tool`)**
  - [x] 数据库元数据自动提取 (MySQL / PostgreSQL / SQLite)
  - [x] Rust 后端全栈生成 (Model, Service, Handler, Mod, Router)
  - [x] Vue 前端全栈生成 (index.vue, api.ts)
  - [x] **自动化权限宏注入**: 自动生成 `#[require_permission("...")]`，无需手动维护 Enum
  - [x] 结构化 ZIP 下载 (自动分类 backend / frontend / sql 文件夹)
  - [x] 在线预览生成代码（左侧文件树 + 右侧代码展示）
  - [x] 导入已有表 / SQL 创建表 / 同步数据库结构
  - [x] 可视化编辑表配置（字段属性、查询方式、显示类型、字典绑定、拖拽排序）
  - [x] 菜单 SQL 自动生成

## 📌 当前能力补充说明

### 🛡️ 数据脱敏（`serde_mask`）

项目内置基于 `serde + schemars` 的声明式数据脱敏工具，适用于 `VO / DTO / API 返回对象` 中的敏感字段控制。当前已提供以下开箱即用模块：

- `mask_phone`：手机号，保留前 3 后 4
- `mask_id_card`：身份证，保留前 6 后 4
- `mask_email`：邮箱，保留本地部分首字符与完整域名
- `mask_name`：姓名，保留首字符
- `mask_ak_sk`：AK/SK，保留首尾各 1 位
- `mask_full`：全打码（例如 `******`）

#### 基础用法

```rust
use common::utils::serde_mask::{mask_ak_sk, mask_full, mask_phone};
use schemars::JsonSchema;
use serde::Serialize;

#[derive(Serialize, JsonSchema)]
pub struct UserAndOssConfigVo {
    #[schemars(with = "Option<String>")]
    #[serde(with = "mask_phone")]
    pub phone: Option<String>,

    #[schemars(with = "Option<String>")]
    #[serde(with = "mask_ak_sk")]
    pub access_key: Option<String>,

    #[schemars(with = "Option<String>")]
    #[serde(with = "mask_full")]
    pub secret_key: Option<String>,

    pub bucket_name: String,
}
```

#### 为什么有时需要 `#[schemars(with = "Option<String>")]`

如果边界对象同时派生了 `JsonSchema`，并且字段使用了 `#[serde(with = "mask_xxx")]`，建议同时补上：

```rust
#[schemars(with = "Option<String>")]
```

原因是：

- `serde(with = "...")` 负责序列化/反序列化逻辑；
- `schemars` 负责 OpenAPI / JSON Schema 类型推导；
- 对 `Option<String>` 这类字段，显式标注后可以稳定告诉 schema 生成器：该字段对外仍然是“可空字符串”，避免把脱敏模块误判成类型本身。

#### 自定义参数化能力

除预设模块外，`common::utils::serde_mask` 还提供底层可参数化函数：

- `serialize_keep_head_tail(value, serializer, start, end, mask_char)`
- `serialize_full(value, serializer, fixed)`
- `serialize_middle(value, serializer, mask_char)`
- `serialize_email(value, serializer, mask_char)`

适合在具体业务字段上按需封装自己的脱敏规则。

### 🔄 工作流引擎 (`workflow`)

内置轻量级工作流引擎，基于 **LogicFlow** 可视化流程设计器，支持常见的审批流转场景。

#### 核心能力

| 能力 | 说明 |
|------|------|
| **流程定义** | 基于 LogicFlow JSON 格式定义流程，支持发布/取消发布、版本管理 |
| **节点类型** | 开始节点（`start`）、审批人节点（`approver`）、条件分支（`condition`）、抄送节点（`cc`）、结束节点（`end`） |
| **审批人解析** | 支持 4 种策略：指定用户（`user`）、指定角色（`role`）、指定部门（`dept`）、发起人自己（`initiator`） |
| **审批模式** | 会签（所有人同意才通过）/ 或签（任一人同意即通过） |
| **流程操作** | 发起流程、审批同意、驳回、终止、转办任务 |
| **抄送通知** | 流程节点可配置抄送人，自动生成只读抄送记录 |
| **进度追踪** | 查看流程实例的所有任务节点和审批历史记录 |
| **示例业务** | 内置请假审批（`oa_leave`），演示工作流接入方式 |

#### 流程引擎工作原理

1. **流程定义**：前端通过 LogicFlow 设计器绘制流程图，导出 JSON 存入 `wf_process_def`
2. **发起流程**：解析 JSON，BFS 遍历节点图，创建流程实例（`wf_process_instance`）
3. **任务派发**：根据节点 `assigneeType` 和 `assigneeIds` 解析审批人，创建待办任务（`wf_task`）
4. **审批流转**：审批通过后自动推进到下一节点，条件分支按规则路由
5. **流程结束**：到达 `end` 节点时流程完成，记录审批历史（`wf_approval_record`）

#### 数据表

| 表名 | 用途 |
|------|------|
| `wf_process_def` | 流程定义（JSON 格式） |
| `wf_process_instance` | 流程实例 |
| `wf_task` | 任务节点 |
| `wf_task_assign` | 任务审批人 |
| `wf_ins_variable` | 流程实例变量 |
| `wf_cc_record` | 抄送记录 |
| `wf_approval_record` | 审批历史记录 |
| `oa_leave` | 请假业务表（示例） |

#### 后续规划

- [ ] 条件分支表达式求值（当前取第一个分支）
- [ ] 自由流转（加签、减签、回退到任意节点）
- [ ] 多实例并行网关（`parallel`）
- [ ] 子流程嵌套
- [ ] 超时自动处理

---

### 🤖 Dify AI 智能问答 (`agents`)

集成 [Dify](https://dify.ai) AI 平台，提供 SSE 流式智能问答能力。

#### 核心能力

| 能力 | 说明 |
|------|------|
| **流式对话** | 通过 SSE（Server-Sent Events）实时推送 AI 回复，打字机效果 |
| **多轮会话** | 支持 `conversation_id` 续接上下文，实现多轮对话 |
| **思考过程** | 透传 `reasoning_chunk` 事件，展示 AI 推理过程 |
| **事件协议** | 兼容 Dify 原生事件：`message`、`agent_message`、`message_end`、`reasoning_chunk` |
| **认证保护** | 接口需登录态，401 自动跳转登录页 |

#### 配置方式

在 `config/local.toml` 中配置 Dify 连接信息：

```toml
[dify]
enabled = true
base_url = "http://your-dify-host/v1"
api_key = "app-xxxxxxxxxxxxxx"
```

#### 接口说明

- **`POST /prod-api/agents/chat`** — 发送聊天消息，返回 SSE 流式响应
- 请求体：`{ "message": "你的问题", "conversationId": "可选，续接会话" }`
- 前端通过 `fetch` + `ReadableStream` 解析 SSE 事件流

---

### 📁 文件管理 (`oss`)

基于 S3 协议的对象存储管理模块，支持多种云存储后端。

#### 核心能力

| 能力 | 说明 |
|------|------|
| **文件上传** | 支持普通上传（≤50MB）和大文件分片上传（>5MB 自动分片） |
| **文件下载** | 生成预签名 URL，支持直接下载或在线预览 |
| **文件管理** | 列表查询、按 ID 批量查询、批量删除、URL 获取 |
| **多存储后端** | 运行时管理多个存储配置，支持切换默认后端 |
| **自动识别厂商** | 根据 endpoint 自动选择 path-style 或 virtual-hosted-style |

#### 支持的存储后端

| 存储 | 推荐度 | 说明 |
|------|--------|------|
| **RustFS** | ⭐⭐⭐⭐⭐ | Rust 原生，性能 2.3x MinIO，推荐本地部署 |
| **MinIO** | ⭐⭐⭐⭐ | 成熟的开源对象存储 |
| **阿里云 OSS** | ⭐⭐⭐⭐ | 国内云存储首选 |
| **腾讯云 COS** | ⭐⭐⭐⭐ | 腾讯云生态 |
| **华为云 OBS** | ⭐⭐⭐⭐ | 华为云生态 |
| **AWS S3** | ⭐⭐⭐⭐ | 国际标准 |

#### 配置示例

```toml
[oss]
enabled = true
endpoint = "http://127.0.0.1:9000"
access_key = "rustfsadmin"
secret_key = "rustfsadmin"
bucket = "ruoyi"
region = "us-east-1"
prefix = "ruoyi"
path_style = true           # RustFS / MinIO 必须开启
```

#### 接口列表

| 接口 | 方法 | 说明 |
|------|------|------|
| `/oss/upload` | POST | 文件上传（multipart/form-data） |
| `/oss/download/{ossId}` | GET | 文件下载（302 重定向到预签名 URL） |
| `/oss/list` | GET | 文件列表（分页） |
| `/oss/listByIds` | GET | 按 ID 批量查询 |
| `/oss/urlByIds` | GET | 按 ID 获取文件 URL |
| `/oss/{ossId}` | DELETE | 删除文件 |
| `/oss/config/list` | GET | 存储配置列表 |
| `/oss/config` | POST/PUT | 新增/修改存储配置 |
| `/oss/config/changeDefault` | PUT | 切换默认存储后端 |

---

### ⏰ 定时任务当前状态与使用说明（2026-07 第四阶段收口）

当前 `monitor` 模块中的定时任务能力，已经完成本轮 scheduler capability 升级收口，**定位为：单机场景可生产使用**。为了避免误解，这里把当前能力边界、推荐使用方式和暂未承诺范围一次说明清楚。

#### 当前可用能力

- 支持三种执行后端：
  - `direct`
  - `memory`
  - `redis`
- 支持任务管理基础能力：
  - 新增 / 修改 / 删除 / 启停
  - 手动执行一次（run once）
  - 日志查询
- 支持 builtin 任务模板与 `invokeTarget` 方式执行内置任务
- 支持 `concurrent`（当前前端展示为“触发策略”）与最小化 `misfire_policy` 语义落地
- `redis` backend 已具备最小运维闭环：
  - retry
  - dead-letter
  - replay
  - delete
- 已提供后端运维概览接口：
  - `GET /prod-api/monitor/job/backendOpsOverview`

#### 当前推荐使用方式

##### 1. 单机生产推荐 backend

如果是当前这轮能力直接上线，推荐优先使用：

- **`redis` backend**：适合单机生产、链路可观察性更完整
- `memory` backend：适合单机轻量场景或过渡验证
- `direct` backend：适合最简单的即时执行场景，但对长任务的人工 run once 观察要更谨慎

##### 2. run once 结果如何理解

- `direct`：更接近立即执行链路
- `memory / redis`：接口成功优先表示**已派发 / 已入队成功**，不代表最终已经执行完成
- `redis` dead-letter 的 `replay` 成功：表示**已重放回主队列成功**，不代表最终业务执行成功

因此，最终执行结果统一建议结合以下信息判断：

- `sys_job_log`
- worker 日志
- 业务侧实际结果

##### 3. 当前前端字段如何理解

目前前端任务表单里，已按当前后端真实语义做过一轮收口：

- `concurrent` 当前更适合理解为：
  - `重复排队`
  - `冲突跳过`
- `misfire_policy` 当前只在“冲突跳过”路径下才有实际意义
- 当前后端对：
  - `1 = 立即执行`
  - `2 = 执行一次`
  还没有拆成真正不同的两套运行逻辑；前端当前统一只保留“执行一次”展示

##### 4. direct / memory / redis 的当前区别

###### `direct`
- 不走队列
- 更接近立即执行
- 当前主要承载：
  - 手动执行
  - 并发冲突直接跳过
- 不承载 queued backend 的 retry / dead-letter / replay 语义

###### `memory`
- 先入当前进程内存队列
- 当前是**单 worker 串行消费**
- 支持 queued 冲突控制与最小单票补偿语义
- 不提供 dead-letter / replay

###### `redis`
- 先入 Redis 队列
- 当前同样按**单 worker 串行消费**的单机模型收口
- 支持：
  - retry
  - dead-letter
  - replay
  - delete
  - backend 运维概览

#### 当前明确承诺的边界

本轮升级完成后，可以明确承诺：

- **单机部署可用**
- `redis` 可作为当前推荐的单机生产 backend
- `run once` / queued dispatch / retry / dead-letter / replay / delete 的产品语义已收口
- 应用重启后，**启用状态任务会重新注册进 scheduler**
- `backendOpsOverview` 可用于查看：
  - 当前 backend
  - 是否 queued backend
  - Redis 主队列 key
  - dead-letter 队列 key
  - 当前恢复边界
  - 安全清理提示

#### 当前明确不承诺的范围

以下能力**不属于本轮已经完成的范围**：

- 多实例严格一致性
- 分布式唯一消费保障
- leader / distributed lock / claim 模型
- in-flight 任务在进程中断后的自动续跑
- 完整 durable dispatch state machine
- Quartz / XXL-JOB 级完整 misfire / backlog 恢复终态
- exactly-once 分布式保障

也就是说：

> 当前定时任务能力适合**单机生产落地**，不应直接理解为“已经完成多实例调度平台化”。

#### Redis 队列清理说明

若使用 `redis` backend，只有在确认：

- 当前没有任务仍在执行
- 也不再需要观察上一轮 retry / dead-letter / replay 结果

时，才建议清理 Redis 主队列或 dead-letter 队列。否则会破坏排障证据。

#### 后续升级方向

如果后续要继续往上做，可在本轮单机稳定基础上继续推进：

- 多实例最小可运行
- 多实例生产可用
- 更完整的一致性 / claim / ack / in-flight 恢复模型

但这些已经属于**下一条新专题**，不再是当前这轮 scheduler capability 收尾的一部分。



## 🕒 后端统一时间约定

为避免业务时间、日志时间、在线会话时间在不同时区/宿主机设置下出现偏差，项目约定：

- **业务当前时间一律走 `common::utils::time` 提供的统一方法**
  - 需要 `DateTime<FixedOffset>` 时使用 `cst_now()`
  - 需要 `NaiveDateTime`（写库字段、审计字段等）时使用 `cst_naive_now()`
  - 需要标准字符串时使用 `cst_now_string()`
- **禁止在业务代码中直接使用以下方式生成当前时间**
  - `chrono::Local::now()`
  - `Utc::now().naive_utc()`
  - 任何自行拼 offset / `with_timezone(...)` 的临时写法
- **适用范围**
  - 系统管理 / 监控模块的 create_time、update_time、login_time、job_log、在线会话时间
  - 认证、鉴权、SSE、WebSocket、缓存过期判断中由后端自行解释的“当前时间”
  - 导出文件名、日志展示时间、业务层生成的时间戳/时间字符串
- **允许保留 UTC 的场景**
  - 第三方协议或签名明确要求 UTC / ISO8601 Zulu 时间
  - 例如短信供应商、云厂商签名字段、外部 API 协议时间窗
  - 这类场景应优先遵循第三方协议要求，不要强改为东八区

### 给开发者 / AI 协作者的直接规则

- 看到“当前时间”需求，默认先选 `cst_now()` / `cst_naive_now()`，不要先写 `Local::now()` 或 `Utc::now().naive_utc()`
- 如果是对外协议签名时间，先查协议是否明确要求 UTC；只有明确要求 UTC 时才保留 `Utc::now()`
- 若拿不准，应先按“业务时间用东八区统一方法，协议时间按第三方要求”判断，不要混用

### 🔐 框架认证 / 客户端能力当前状态说明

#### 当前已实现

- [x] 登录接口支持传入 `client_id`，并根据 `sys_client` 读取客户端配置
- [x] 可基于客户端配置控制：
  - [x] `device_type`（设备类型隔离）
  - [x] `timeout`（token 固定超时）
  - [x] `active_timeout`（在线会话活跃超时 / 滑动续期）
- [x] 单端登录已接入主登录流程：可按同账号、同设备类型执行顶号
- [x] 已提供后台客户端管理能力：维护 `client_id`、`client_key`、`client_secret`、`grant_type`、`device_type`、超时配置、状态等字段
- [x] 客户端停用后，登录时会拒绝该客户端发起的请求
- [x] 已落地三条登录主链路：
  - [x] `POST /login`：账号密码登录
  - [x] `POST /login/email` + `POST /login/email/code`：邮箱验证码登录
  - [x] `POST /login/sms` + `POST /login/sms/code`：短信验证码登录
- [x] `grant_type` 已接入现有登录准入校验：
  - [x] `password`：限制账号密码登录
  - [x] `email`：限制邮箱验证码发送与邮箱验证码登录
  - [x] `sms`：限制短信验证码发送与短信验证码登录
- [x] 邮箱 / 短信登录除客户端 `grant_type` 外，还会继续校验系统参数与基础能力是否开启：
  - [x] 邮箱：`sys.account.emailEnabled` + 实际 SMTP 配置
  - [x] 短信：`sys.account.smsEnabled` + 实际短信配置（支持 mock / provider / fixed code）
- [x] `/captchaImage` 当前会返回登录页基础开关：
  - [x] `captchaEnabled`
  - [x] `emailEnabled`
  - [x] `smsEnabled`

#### 当前边界 / 尚未完成

- [ ] 还**不是完整 OAuth2 / OIDC 授权中心**
  - 当前的 `grant_type` 更接近“本项目登录方式开关 / 客户端准入配置”，不是标准 OAuth2 授权服务器的完整协议实现
  - 标准意义上的 `authorization_code`、`client_credentials`、`refresh_token`、OIDC、第三方社交授权回调等能力，当前均未完整落地
- [ ] `social` / `xcx` 等授权类型目前主要停留在字典与客户端配置层
  - `sys_client.grant_type` 可以先存这些值
  - 但对应的后端认证处理器、回调链路、令牌交换流程目前还没有完成
- [ ] `/captchaImage` **当前仍是全局登录开关接口，不是按客户端裁剪后的登录能力契约**
  - 当前 handler 只接收 `theme` 查询参数，不接收 `client_id`
  - 返回的 `captchaEnabled`、`emailEnabled`、`smsEnabled` 反映的是系统级能力是否开启
  - 它**不会**直接告诉前端“这个客户端是否允许 `password / email / sms`”
- [ ] 客户端维度的登录方式限制，当前主要体现在**实际登录/发码接口校验**上
  - `POST /login`：当传入 `client_id` 时，会校验该客户端是否允许 `grant_type=password`
  - `POST /login/email` / `POST /login/email/code`：要求 `client_id`，并校验客户端是否允许 `grant_type=email`
  - `POST /login/sms` / `POST /login/sms/code`：要求 `client_id`，并校验客户端是否允许 `grant_type=sms`
- [ ] 密码登录对 `grant_type=password` 的限制，当前仍建立在**前端稳定传入 `client_id`** 的前提下
  - 如果前端不传 `client_id`，仍会走传统账号密码登录主链路
  - 因此，若要真正落实“按客户端限制登录方式”，前端登录入口需要稳定传递 `client_id`
- [ ] 前端登录页与后端客户端能力的联动还没有完全收口
  - 后端三条登录接口和客户端准入校验已经具备
  - 但“前端先拿到某个 client 的完整登录能力视图，再按能力动态裁剪登录方式”这层契约，目前还没有单独收口成一个标准接口

#### 更准确的现阶段理解

当前这套认证 / 客户端能力，已经具备：

- **后端实际登录校验层面的客户端准入控制**
- **账号密码 / 邮箱验证码 / 短信验证码三条主链路**
- **客户端 + 设备类型 + 超时配置联动**

但还没有完全补成：

- **前端先读取客户端登录能力，再动态渲染登录入口的完整契约层**

也就是说：

> 现在“后端真实限制已经有了”，但“前端一次性拿到客户端登录能力画像”的接口契约还没有完全产品化。

## 🛠️ 技术栈 (Tech Stack)

### 后端

| 领域 | 技术选型 | 理由 |
|------|----------|------|
| **语言/运行时** | Rust (Stable) / Tokio | 性能、安全、现代化的异步生态 |
| **Web 框架** | Axum | 模块化、符合人体工程学、与 `tower` 生态无缝集成 |
| **数据库交互** | SeaORM | 异步 ORM，支持 MySQL / PostgreSQL / SQLite，提供类型安全的数据库访问 |
| **数据库迁移** | sea-orm-migration | Schema 版本化迁移，与 SeaORM 深度集成 |
| **序列化** | Serde | Rust 生态的事实标准，性能卓越，功能强大 |
| **配置管理** | `config-rs` | 支持多种格式，支持环境覆盖，简单易用 |
| **日志系统** | `tracing` | 结构化日志，与 `tokio` 和 `axum` 深度集成 |
| **认证/授权** | `argon2` / `jwt-simple` | 现代密码哈希标准；纯 Rust 实现的 JWT 库，轻量安全 |
| **缓存** | `moka` / Redis | 高性能本地缓存，可选 Redis 二级缓存，灵活应对单机或分布式部署 |
| **权限宏** | `syn` / `quote` | 自定义过程宏，实现声明式、编译时安全的权限校验 |
| **对象存储** | AWS SDK S3 | 兼容 S3 协议，推荐 [RustFS](https://github.com/rustfs/rustfs)（Rust 原生，性能 2.3x MinIO），同时兼容 MinIO、阿里云 OSS、腾讯云 COS、华为云 OBS、AWS S3 |
| **工作流引擎** | 自研（LogicFlow JSON） | 轻量级流程引擎，基于 BFS 遍历解析 LogicFlow 可视化设计器导出的流程定义 |
| **AI 集成** | Dify API (SSE) | 对接 Dify AI 平台，通过 SSE 流式代理实现实时智能问答 |
| **实时通信** | WebSocket / SSE | 双向实时消息推送（WebSocket）+ 服务端单向推送（SSE） |
| **邮件服务** | `lettre` | 纯 Rust SMTP 客户端，支持 SSL / STARTTLS |
| **短信服务** | 自研多供应商适配 | 支持阿里云、旦米等多供应商，业务场景枚举 + 配置映射 |
| **OpenAPI** | aide / schemars | 自动生成 Swagger/OpenAPI 文档 |

### 旧前端（原若依框架前端）

当前旧版前端仓库为 [ruo-yi-vue3](https://gitee.com/rustdev/ruo-yi-vue3.git)，仅保留作对照与过渡参考，**已停止维护**。

### 新前端（ruoyi-rust-ui-plus）

| 领域 | 技术选型 | 说明 |
|------|----------|------|
| **框架** | Vue 3.5 + TypeScript 6 | Composition API + `<script setup lang="ts">` |
| **UI 库** | Element Plus 2.14 | 成熟的 Vue 3 组件库 |
| **基础模板** | Vue Vben Admin v5.7.0 | Monorepo 架构，多 UI 变体支持 |
| **CSS** | Tailwind CSS v4 + UnoCSS | 原子化 CSS，高效开发 |
| **状态管理** | Pinia 3 | Vue 3 官方状态管理 |
| **构建工具** | Vite 8 | 极速开发体验 |
| **HTTP 客户端** | Axios + `@vben/request` | 拦截器、Token 刷新、统一错误处理 |
| **包管理** | pnpm + Turborepo | Monorepo 高效管理 |

## 🚀 快速开始

### OpenAPI / Apifox 使用说明

项目已接入 OpenAPI 文档，推荐配合 **Apifox** 使用进行接口调试与管理。

#### OpenAPI 文档地址

后端启动后，可通过以下地址获取 OpenAPI JSON：

```text
/prod-api/openapi.json
```

如果是本地默认启动地址，完整示例为：

```text
http://localhost:8080/prod-api/openapi.json
```

#### 推荐使用方式

1. 先启动后端服务。
2. 打开 **Apifox**。
3. 选择 **导入接口**。
4. 使用 **URL 导入** 方式，填入：

   ```text
   http://localhost:8080/prod-api/openapi.json
   ```

5. 导入完成后，即可在 Apifox 中查看并调试接口。

#### 说明

- `/prod-api/openapi.json` 是当前项目的 OpenAPI 文档接口。
- 推荐优先通过 Apifox 导入该地址，而不是手动维护接口清单。
- 当后端接口、参数或文档注解更新后，可在 Apifox 中重新导入或刷新文档。
- 如果你使用了不同的端口、域名或反向代理前缀，请将上述地址替换为实际访问地址。

### 环境要求

* **Rust**: `1.88` 或更高版本 (通过 `rustup` 安装)
* **Node.js**: `^22.18.0 || ^24.0.0`（前端需要，通过 `nvm` 安装）
* **pnpm**: `>=11.0.0`（前端包管理）
* **数据库（任选其一）**: **MySQL** `5.7+`、**PostgreSQL**、或 **SQLite**（本地体验推荐）

### 1. 克隆项目

```bash
# 克隆后端
git clone https://gitee.com/rustdev/ruoyi-rust.git
cd ruoyi-rust

# 克隆前端（推荐使用新版 Vben 5 前端）
git clone https://gitee.com/rustdev/ruoyi-rust-ui-plus.git
```

### 2. 数据库设置

本项目支持 **MySQL / PostgreSQL / SQLite**，请任选一种准备好数据库服务。

> **数据库初始化无需手动导入 SQL**——项目内置 `sea-orm-migration` 迁移模块，首次启动时会自动执行建表和种子数据填充。

#### 使用自动迁移（推荐）

1. 确保数据库已创建（如 `ry-vue`），且连接账号有建表权限。
2. 编辑 `config/local.toml`，开启自动迁移：
   ```toml
   [migration]
   enabled = true
   ```
3. 启动程序后，迁移模块会自动执行：
   - 创建所有业务表（`sys_*`、`wf_*`、`gen_*` 等）
   - 填充初始种子数据（默认管理员、角色、菜单、字典、客户端配置等）
4. 迁移完成后，**建议将 `enabled` 改回 `false`**，避免每次启动重复执行迁移检查。

#### 迁移模块说明

- 迁移脚本位于 `migration/src/migrations/`，按版本号顺序执行
- 种子数据位于 `migration/src/migrations/seed/`，包含初始用户、角色、菜单、字典等
- 迁移状态记录在数据库的 `seaql_migrations` 表中，已执行过的不会重复执行
- 如果后续版本有 Schema 变更，启动时会自动增量执行新的迁移脚本

> 若无需安装 MySQL/PostgreSQL，可直接使用 **SQLite** 进行本地体验——只需在配置中使用 SQLite 连接，程序会自动创建数据库文件。

### 3. 后端配置

1. 复制环境配置文件：
   ```bash
   cp config/default.toml config/local.toml
   ```

2. 编辑 `config/local.toml`，配置数据库连接。支持以下两种方式：
   - **URL 方式**（推荐）：
     ```toml
     [database]
     url = "mysql://your_user:***@127.0.0.1:3306/ry-vue"
     ```
   - **结构化方式**（便于切换数据库类型）：
     ```toml
     [database]
     host = "127.0.0.1"
     port = 3306
     username = "your_user"
     password = "your_password"
     database = "ry-vue"
     ```
   - 连接池参数可按需调整：
     ```toml
     max_connections = 20
     min_connections = 5
     connect_timeout = 10
     idle_timeout = 600
     ```

3. （可选）配置 IP 地理位置解析（ip2region）：
   ```toml
   [security]
   ip_location_enabled = true
   ```

   **使用说明：**

   - 默认关闭：`security.ip_location_enabled = false`
   - 仓库不会分发 `resources/ip2region_v4.xdb`，请你自行确认合规后下载
   - 下载后放到后端仓库根目录：`resources/ip2region_v4.xdb`
   - 这是**编译期开关**：只有在“配置为 `true` 且该文件存在”时，构建产物才会把 xdb **编译进 `app`**
   - 如果你新增/替换了 xdb 文件，或者修改了这个开关，需要**重新编译后端**才会生效
   - 编译时开关优先读取 `local.toml`，未配置时回退到 `default.toml`

4. （可选）配置 API 请求/响应加密。

   > 这套能力默认约定前后端使用固定请求头 `encrypt-key` 传递加密后的随机 AES 密钥，当前不是可配置项。

   ```toml
   [api_decrypt]
   enabled = true
   public_key = '''替换为你自己的 Base64 DER RSA 公钥'''
   private_key = '''替换为你自己的 Base64 DER RSA 私钥'''
   ```

   **使用说明：**

   - `enabled = true` 后，后端会对带 `encrypt-key` 头的 `POST` / `PUT` 请求先解密，再进入业务处理。
   - 前端只有显式标记 `encrypt: true` 的敏感接口才会走这套加密链路，例如登录、邮箱/短信登录、验证码发送、修改密码、重置密码等。
   - 前端使用 `public_key` 加密随机 AES 密钥并放到 `encrypt-key` 请求头；后端使用 `private_key` 解开该密钥。
   - 后端返回加密响应时，会用 `public_key` 对响应里的随机 AES 密钥重新加密，前端再使用对应的私钥解密响应。
   - **生产环境必须替换仓库默认密钥**。仓库里的示例密钥只适合本地联调，不能直接用于线上。
   - 当前前端与后端必须使用**同一组配套密钥**：
     - 后端 `public_key` = 前端 `VITE_GLOB_API_ENCRYPT_PUBLIC_KEY`
     - 后端 `private_key` = 前端 `VITE_GLOB_API_ENCRYPT_PRIVATE_KEY`
   - 替换密钥后，需要同步更新前端 `.env*` 中的：
     - `VITE_GLOB_API_ENCRYPT_PUBLIC_KEY`
     - `VITE_GLOB_API_ENCRYPT_PRIVATE_KEY`

   **短信验证码 / 阿里云号码认证接入补充：**

   当前仓库已经具备短信登录接口：
   - `POST /prod-api/login/sms/code`：发送短信登录验证码
   - `POST /prod-api/login/sms`：使用手机号 + 短信验证码登录

   其中短信能力有两层开关，**两层都要开**：
   - 文件配置：`[sms].enabled = true`
   - 系统参数：`sys.account.smsEnabled = true`

   **推荐本地先用 mock 调通整条链路：**

   ```toml
   [sms]
   enabled = true
   supplier = "mock"
   default_config_id = "default"
   mock_print_code = true

   [[sms.configs]]
   config_id = "default"
   supplier = "mock"
   template_name = "login_code"
   ```

   这样点击“发送验证码”后，后端日志会打印类似：

   ```text
   [Test SMS] Your code is 123456
   ```

   你可以先复制这个验证码完成短信登录，优先验证：前端按钮、60 秒倒计时、验证码缓存、`grant_type=sms` 客户端限制、登录拿 token 这整条链路。

   **切阿里云 SendSmsVerifyCode 时，推荐这样配：**

   ```toml
   [sms]
   enabled = true
   supplier = "alibaba"
   default_config_id = "aliyun_login"
   mock_print_code = false

   [[sms.configs]]
   config_id = "aliyun_login"
   supplier = "alibaba"
   access_key_id = "你的阿里云 AccessKeyId"
   access_key_secret = "你的阿里云 AccessKeySecret"
   signature = "阿里云号码认证控制台里可用的签名"
   template_id = "阿里云号码认证控制台里的模板 CODE"
   region_id = "cn-hangzhou"
   request_url = "dypnsapi.aliyuncs.com"
   action = "SendSmsVerifyCode"
   version = "2017-05-25"
   template_name = "login_code"
   ```

   **这里要特别注意：**

   - 这个接口不是传统的 `dysmsapi` 普通短信发送接口，而是 **Dypnsapi（云通信号码认证服务）里的验证码发送接口**。
   - 这个接口**可以接到当前框架的短信验证码登录模块上**，而且非常适合“登录验证码”这种场景。
   - 文档里明确要求：优先使用号码认证控制台里**赠送的签名和赠送模板**，不要默认按普通自定义签名去理解。
   - 当前框架已经把 `template_name` 和 `template_id` 分开：
     - `template_name` = 框架内部业务场景名，例如 `login_code` / `register_code`
     - `template_id` = 供应商真实模板编码，例如阿里云模板 CODE

   **后续有多个短信模板时，建议这样管理：**

   - 不要在业务代码里到处硬编码模板 CODE。
   - 优先在框架里按“业务场景枚举”管理，例如：
     - `login_code`
     - `register_code`
     - `reset_password_code`
   - 然后在 `[[sms.configs]]` 里按不同 `config_id + template_name` 维护真实模板。
   - 当前短信登录默认使用的业务场景枚举是：`SmsTemplateScene::LoginCode`，对应 `template_name = "login_code"`。

   **如果你后面要新增注册验证码/找回密码验证码，推荐做法：**

   1. 先在 `framework/src/sms/model.rs` 的 `SmsTemplateScene` 里补一个新场景。
   2. 再在 `config/local.toml` 里新增对应 `[[sms.configs]]`。
   3. 业务代码只传场景枚举，不直接写供应商模板编码。

   **关于阿里云验证码校验能力：**

   `SendSmsVerifyCode` 文档支持两种模式：
   - 你自己传具体验证码值，例如 `{"code":"123456"}`
   - 传 `##code##` 让阿里云生成验证码，再配合它的 `CheckSmsVerifyCode/VerifySmsCode` 一类接口做云端核验

   当前仓库这次接的是**第一种模式**：
   - 验证码仍由本系统生成并写入本地缓存
   - 阿里云负责把验证码短信发出去
   - 登录时仍由本系统校验缓存里的验证码

   这样做的好处是：
   - 和当前仓库现有短信登录链路最兼容
   - 这次就能先把“短信验证码登录”调通
   - 后面如果你想把“验证码生成/核验”完全切到阿里云，再继续接它的校验接口即可

   **联调步骤建议：**

   1. 先确认 `sys_client` 中当前客户端的 `grant_type` 包含 `sms`（仓库默认 app 客户端已包含）。
   2. 先用 mock 跑通：
      - 能发码
      - 能看到日志验证码
      - 能成功短信登录
   3. 再把 `supplier` 改成 `alibaba`，填好阿里云签名与模板。
   4. 如果阿里云返回失败，优先检查：
      - 签名是否来自号码认证控制台可用签名
      - 模板是否来自号码认证控制台可用模板
      - `template_id` 是否填的是模板 CODE
      - `sys.account.smsEnabled` 是否开启
      - `client_id` 对应客户端是否包含 `sms` 授权类型

   **如果你只想单独验证短信通道本身，也可以直接跑 smoke 测试：**

   ```bash
   SMS_SMOKE_PHONE=13800138000 cargo test -p framework sms_send_smoke -- --ignored --nocapture
   ```

   说明：
   - 这是一个**手动 smoke 测试**，不会默认自动执行。
   - 它会读取当前 `config/default.toml + config/local.toml` 里的 `[sms]` 配置。
   - 当前测试默认按 `SmsTemplateScene::LoginCode` 发送，也就是 `template_name = "login_code"`。
   - 如果你配置的是 `mock`，日志里会直接打印模拟验证码。
   - 如果你配置的是 `alibaba`，就会真实请求阿里云 `SendSmsVerifyCode`。
   - 可以额外传 `SMS_SMOKE_CODE=123456` 固定验证码；不传则测试内自动生成 6 位验证码。

   **短信能力设计（当前推荐方式）**

   当前框架短信能力已经拆成两层：

   1. **业务场景枚举**：代码里用 `SmsTemplateScene`
   2. **供应商真实模板配置**：配置文件里用 `[[sms.configs]]`

   这样做的目的：
   - 业务代码只关心“发登录验证码 / 发注册验证码”
   - 不在业务代码里写死供应商模板 CODE
   - 后续切模板时主要改配置，不用到处改业务代码

   **职责边界建议：**

   - `SmsTemplateScene`：表示业务场景，例如
     - `LoginCode`
     - `RegisterCode`
     - `ResetPasswordCode`
   - `template_name`：配置层逻辑模板名，例如
     - `login_code`
     - `register_code`
   - `template_id`：供应商真实模板 CODE，例如阿里云 `100001`
   - `access_key_id / access_key_secret`：统一供应商主密钥；不同供应商在 provider 内做字段适配（例如旦米复用为 ACCOUNT SID / AUTH TOKEN）

   > 结论：**枚举要保留，配置文件也有必要保留。**
   >
   > - 只放枚举里：不方便不同环境/不同供应商切模板
   > - 只放配置里：业务代码容易到处散落字符串
   > - 当前这套“枚举 + 配置映射”更适合后续扩展

   当前 provider 里已经做了供应商适配，例如：
   - 阿里云：`access_key_id = AccessKeyId`，`access_key_secret = AccessKeySecret`
   - 旦米：`access_key_id = ACCOUNT SID`，`access_key_secret = AUTH TOKEN`，`account_id = 业务账号`

   **供应商选择规则（特别是你问的两个 `login_code` 怎么选）：**

   当前优先级是：

   1. **如果显式传 `config_id`**，就强制走这条配置
   2. 否则，如果传了 `template_name` / `SmsTemplateScene`：
      - 先找 `default_config_id` 对应那条配置，并且它的 `template_name` 也匹配
      - 找不到再回退到“第一条匹配该 `template_name` 的配置”
   3. 如果都没传，就走 `default_config_id`

   所以如果阿里云和旦米都配了：
   - `template_name = "login_code"`

   那么**默认会优先走 `default_config_id` 指向的那条**。

   例如：

   ```toml
   [sms]
   default_config_id = "aliyun_login"
   ```

   那正式登录验证码默认就走阿里云；

   如果你改成：

   ```toml
   [sms]
   default_config_id = "danmi_login"
   ```

   那默认就走旦米。
   **当前最小通用发送方式：**

   ```rust
   use framework::sms::{
       SmsClient, SmsSendRequest, SmsTemplateScene, build_code_template_params,
   };

   let resp = sms_client
       .send(
           &SmsSendRequest::single_phone(
               "17633650769",
               build_code_template_params("123456", 5),
           )
           .with_scene(SmsTemplateScene::LoginCode)
           .with_content("您的验证码是123456，5分钟内有效，请勿泄露给他人。"),
       )
       .await?;
   ```

   **如果你想显式指定走哪家供应商的某条模板配置**，就继续加 `config_id`：

   ```rust
   let resp = sms_client
       .send(
           &SmsSendRequest::single_phone(
               "17633650769",
               build_code_template_params("123456", 5),
           )
           .with_scene(SmsTemplateScene::LoginCode)
           .with_config_id("danmi_login")
           .with_content("您的验证码是123456，5分钟内有效，请勿泄露给他人。"),
       )
       .await?;
   ```

   也就是说：
   - 只传 `scene`：走默认配置匹配
   - 传 `scene + config_id`：强制走指定供应商/通道


   **模板参数怎么传：**

   如果是验证码类短信，推荐统一走：

   ```json
   {
     "code": "123456",
     "min": "5",
     "expireMinutes": 5
   }
   ```

   这样可以兼容常见模板变量：
   - `${code}`
   - `${min}`
   - `${expireMinutes}`

   如果后续是通知类/业务类短信，就直接自己传 JSON：

   ```rust
   use serde_json::json;

   let req = SmsSendRequest::single_phone(
       "17633650769",
       json!({
           "orderNo": "SO20260714001",
           "status": "已发货",
           "driver": "张三",
       }),
   )
   .with_scene(SmsTemplateScene::GenericCode);
   ```

   **推荐配置方式：**

   先在配置里保留每个模板一条配置，例如：

   ```toml
   [[sms.configs]]
   config_id = "aliyun_login"
   supplier = "alibaba"
   access_key_id = "同一套阿里云AccessKeyId"
   access_key_secret = "同一套阿里云AccessKeySecret"
   signature = "速通互联验证码"
   template_id = "100001"
   template_name = "login_code"

   [[sms.configs]]
   config_id = "aliyun_register"
   supplier = "alibaba"
   access_key_id = "同一套阿里云AccessKeyId"
   access_key_secret = "同一套阿里云AccessKeySecret"
   signature = "速通互联验证码"
   template_id = "100002"
   template_name = "register_code"
   ```

   这里虽然每条 `[[sms.configs]]` 都会写一遍 `access_key_id / access_key_secret`，
   但它们**完全可以是同一套值**，不是说你必须准备多套阿里云账号。

   这样设计的原因是：
   - 每条短信通道配置都是“完整自描述”的
   - 后续如果某个模板要切到别的账号/别的供应商，不用改框架结构
   - 现在先重复写同一套 AK/SK，换来后面扩展时更稳

   这样后续：
   - 新增枚举场景
   - 新增一条 `[[sms.configs]]`
   - 业务代码继续只传 `SmsTemplateScene`

   这是当前比较稳、也最容易扩展到多模板/多供应商的方式。

   **推荐生成方式 1：直接使用项目内置测试工具（推荐）**

   ```bash
   cargo test -p framework api_encrypt_keygen_smoke -- --nocapture
   ```

   如果你想调整 RSA 位数，可以打开 `framework/tests/api_encrypt_keygen_smoke.rs` 里的 `bits` 常量后重新执行。

   ```bash
   cargo test -p framework api_encrypt_keygen_smoke -- --nocapture
   ```

   命令会直接打印 4 段可复制内容：

   - 后端 `config/local.toml` 的：
     - `api_decrypt.public_key`
     - `api_decrypt.private_key`
   - 前端 `.env*` 的：
     - `VITE_GLOB_API_ENCRYPT_PUBLIC_KEY`
     - `VITE_GLOB_API_ENCRYPT_PRIVATE_KEY`

   > 说明：这 4 个输出本质上是同一对 RSA 密钥，按前后端配置名分别打印，目的是让你可以直接复制粘贴，避免再手动转换格式。

   **推荐生成方式 2（OpenSSL）：**

   ```bash
   # 1) 生成 1024 位 RSA 私钥（PKCS#8 PEM）
   openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:1024 -out api_encrypt_private.pem

   # 2) 从私钥导出公钥 PEM
   openssl rsa -pubout -in api_encrypt_private.pem -out api_encrypt_public.pem

   # 3) 导出后端/前端需要的 Base64 DER 私钥（单行文本）
   openssl pkcs8 -topk8 -inform PEM -outform DER -in api_encrypt_private.pem -nocrypt | openssl base64 -A

   # 4) 导出后端/前端需要的 Base64 DER 公钥（单行文本）
   openssl rsa -pubin -inform PEM -outform DER -in api_encrypt_public.pem | openssl base64 -A
   ```

   **填充规则：**

   - 第 3 步输出的单行 Base64 内容，填到：
     - 后端 `api_decrypt.private_key`
     - 前端 `VITE_GLOB_API_ENCRYPT_PRIVATE_KEY`
   - 第 4 步输出的单行 Base64 内容，填到：
     - 后端 `api_decrypt.public_key`
     - 前端 `VITE_GLOB_API_ENCRYPT_PUBLIC_KEY`

   **如果你本机没有 OpenSSL：**

   - Git for Windows 自带的 `bash` 环境通常可以直接执行 `openssl`。
   - 如果提示命令不存在，再单独安装 OpenSSL 或使用 WSL / Linux 机器生成后复制回来。

5. （可选）配置主键策略（数据库自增 / 雪花 ID）：

   ```toml
   [id]
   # auto = 数据库自增（默认）
   # snowflake = 应用侧生成雪花 ID
   strategy = "auto"
   worker_id = 1
   datacenter_id = 1
   epoch_ms = 1704038400000
   ```

   **配置项说明：**

   - `strategy`
     - `auto`：使用数据库自增主键
     - `snowflake`：使用应用侧雪花 ID
   - `worker_id`：雪花算法工作节点 ID，多实例部署时每个实例必须不同
   - `datacenter_id`：雪花算法机房/分组 ID，同一分组内 `worker_id` 不能重复
   - `epoch_ms`：雪花算法自定义纪元，所有实例必须保持一致

   **使用说明：**

   - **PostgreSQL**
     - 可以在 **数据库自增** 和 **雪花 ID** 之间切换使用。
     - `strategy = "auto"` 时，主键走数据库自增。
     - `strategy = "snowflake"` 时，主键由应用在写入前生成。
     - 如果初始化数据里插入了显式主键，项目迁移会同步 PostgreSQL 序列，避免后续再走自增时发生主键冲突。

   - **MySQL**
     - 只能把 **数据库自增** 和 **雪花 ID** 当成两种长期方案里的**二选一**。
     - 推荐在项目初始化阶段就决定好，不要在已经跑过大量业务数据后频繁来回切换。
     - 原因是：如果 MySQL 表先写入了较大的雪花 ID，会把 `AUTO_INCREMENT` 计数器一并抬高；之后再切回自增，新的自增值也会继续从很大的位置往上走，也就是常说的“自增被撑大”。
     - 因此：
       - 想保持和原若依最接近、最省心：用 `auto`
       - 想做多实例统一发号、避免依赖数据库自增：从一开始就用 `snowflake`

   - **SQLite**
     - 更建议继续使用 `auto`。
     - `snowflake` 主要面向 MySQL / PostgreSQL 的正式部署场景。

   **补充说明：**

   - 切换 `strategy` 后需要**重启应用**才能生效。
   - 多实例部署时，所有实例的 `epoch_ms` 必须一致，且 `worker_id` 不能重复，否则会产生雪花 ID 冲突。

6. （可选）配置缓存驱动。默认使用本地 `moka`；如需 Redis 二级缓存，可修改：

   ```toml
   [cache]
   driver = "redis"
   redis_url = "redis://127.0.0.1:6379/"
   ```

7. （可选）配置对象存储。推荐使用 [RustFS](https://github.com/rustfs/rustfs)（Rust 编写的高性能 S3 兼容对象存储，比 MinIO 快 2.3 倍），同时兼容 MinIO、阿里云 OSS、腾讯云 COS、华为云 OBS、AWS S3 等。
   - **RustFS / MinIO**（推荐，本地部署首选）：
     ```toml
     [oss]
     enabled = true
     endpoint = "http://127.0.0.1:9000"
     access_key = "rustfsadmin"
     secret_key = "rustfsadmin"
     bucket = "ruoyi"
     region = "us-east-1"
     prefix = "ruoyi"
     path_style = true           # RustFS / MinIO 必须开启
     ```
   - **阿里云 OSS**：
     ```toml
     [oss]
     enabled = true
     endpoint = "https://oss-cn-shanghai.aliyuncs.com/"
     access_key = "your_access_key"
     secret_key = "your_secret_key"
     bucket = "your_bucket"
     region = "cn-shanghai"
     prefix = "ruoyi"
     path_style = false           # 阿里云必须关闭，使用虚拟主机风格
     ```
   - **其他 S3 兼容存储**（腾讯云 COS / 华为云 OBS / AWS S3 等）配置方式类似，替换 `endpoint`、`access_key`、`secret_key`、`bucket`、`region` 即可。

   > **RustFS 快速启动**：参见 [RustFS 官方文档](https://github.com/rustfs/rustfs)，单二进制部署，默认监听 `9000` 端口，默认账号 `rustfsadmin`。

### 4. 编译与运行

确保数据库已启动且 `config/local.toml` 中的连接配置正确后，直接编译并启动：

```bash
cargo run -p app
```

看到 `✅ Server listening on 127.0.0.1:8080` 日志表示后端启动成功。

> **数据库自动迁移**：首次启动时，程序会通过内置的 `migration` 模块自动执行数据库迁移，创建所需的表结构，无需手动导入 SQL 脚本。

### 5. 前端设置（ruoyi-rust-ui-plus）

本项目配套前端基于 **Vue Vben Admin v5.7.0**，采用 pnpm Monorepo 架构。

1. 进入前端项目目录，安装依赖：
   ```bash
   cd ruoyi-rust-ui-plus
   pnpm install
   ```

2. 启动开发服务器：
   ```bash
   pnpm dev          # 启动 Element Plus 版本
   ```

3. 打开浏览器访问 `http://localhost:5777`（或终端显示的地址）。
   - **默认登录账号**: `admin`
   - **默认密码**: `admin123`

> **前端项目说明**：ruoyi-rust-ui-plus 是 Vue Vben Admin v5.7.0 Monorepo 的一个 app 变体（`apps/web-ele/`），内置了完整的 RuoYi 业务页面适配，包括代码生成、系统管理、监控中心等全部功能模块。样式统一使用 UnoCSS 原子化类编写。

### 6. 代码生成使用指南

为了解决 Rust 开发中结构体编写繁琐、权限宏配置复杂的痛点，本项目内置了全栈代码生成器。

#### 准备工作

在 MySQL 中创建好业务表（务必写好表注释和字段注释，生成器会自动将其转为代码注释）。也可以通过前端的"创建表"功能直接用 SQL 建表。

#### 可视化操作

1. 登录后台，进入 **系统工具 → 代码生成** 菜单。
2. **导入**：点击"导入"按钮，从数据库中选择尚未导入的表。
3. **预览**：点击"预览"按钮，左侧文件树 + 右侧代码展示，实时查看生成的 Rust 和 Vue 代码。
4. **编辑**：点击"修改"按钮，配置字段属性（Rust 类型、查询方式、显示类型、字典绑定），支持拖拽排序。
5. **生成**：选中表后点击"生成"，下载自动打包好的 ZIP 文件。

#### ZIP 包结构

下载的 ZIP 包采用标准结构化设计，解压后包含三个目录：

```
ruoyi.zip
├── backend/rust/modules/{模块名}/src/{业务名}/   # Rust 后端代码
│   ├── mod.rs          # 模块声明
│   ├── model.rs        # 数据模型（Query/Vo/Entity）
│   ├── service.rs      # 服务层（CRUD 业务逻辑）
│   ├── handler.rs      # 处理器（HTTP Handler + 权限注解）
│   └── router.rs       # 路由注册
├── frontend/element/
│   ├── api/{模块名}/{业务名}.ts          # TypeScript API 层
│   └── views/{模块名}/{业务名}/index.vue # Vue 3 页面组件
└── sql/
    └── menu.sql       # 菜单权限 SQL（导入数据库即可）
```

#### 后端代码部署 (Rust)

1. 将 `backend/rust/modules/{模块名}/src/{业务名}` 文件夹拷贝到项目的 `modules/system/src/` 目录下。
2. 在 `modules/system/src/lib.rs` 中添加：`pub mod 你的业务名;`。
3. 在 `modules/system/src/router.rs` 中挂载路由：
   ```rust
   .merge(你的业务名::router::router())
   ```

#### 前端代码部署 (Vben 5)

1. 将 `frontend/element/api/` 下的 `.ts` 文件拷贝到 `apps/web-ele/src/api/` 对应目录。
2. 将 `frontend/element/views/` 下的文件夹拷贝到 `apps/web-ele/src/views/` 对应目录。
3. 在后台"菜单管理"中新建菜单，组件路径填写为 `模块名/业务名/index`（系统会自动解析到 `views/模块名/业务名/index.vue`）。
4. 导入 `sql/menu.sql` 中的菜单权限数据。

> **提示**：生成器已自动处理了 `LONGBLOB/TEXT` 等特殊类型的兼容性映射，并实现了前后端命名契约（SnakeCase vs CamelCase）的自动转换。

## 🏗️ 项目结构

本项目采用 Cargo Workspace 进行模块化管理，结构清晰，职责分明。

```
ruoyi-rust/                          # Workspace 根目录
├── app/                             # 主程序入口 — 组装所有模块、启动 Web 服务器
├── common/                          # 通用基础库 — AppError、AjaxResult、分页模型、认证上下文
├── framework/                       # 核心框架 — 配置、数据库、日志、JWT、缓存、中间件、SeaORM 实体
├── migration/                       # 数据库迁移 — sea-orm-migration 版本化 Schema 管理
├── modules/
│   ├── system/                      # 核心系统模块 — 用户、角色、菜单、部门、字典、参数、通知、岗位、客户端、API Token
│   ├── monitor/                     # 系统监控模块 — 操作日志、登录日志、在线用户、定时任务、缓存、服务监控
│   ├── oss/                         # 对象存储模块 — 文件上传下载、分片上传、多存储后端管理（推荐 RustFS，兼容 MinIO / 阿里云 OSS / 腾讯云 COS / AWS S3）
│   ├── workflow/                    # 工作流模块 — 流程定义、流程实例、任务审批、抄送、审批历史（基于 LogicFlow）
│   ├── agents/                      # AI 智能问答模块 — Dify 平台对接、SSE 流式对话、多轮会话
│   ├── code-tool/                   # 代码生成工具 — 数据库元数据提取、Tera 模板渲染、ZIP 打包
│   └── ruoyi-test/                  # 演示模块 — 功能示例与测试
├── ruoyi-macros/                    # 过程宏库 — #[require_permission(...)] 声明式权限校验、#[builtin_job] 定时任务注册、#[TranslateFill] 字段翻译
├── config/
│   └── default.toml                 # 默认配置文件
└── sql/                             # 数据库初始化脚本
```

## 📦 部署指南

### 交叉编译（Windows → Linux）

当前推荐准备两套方案，按你的环境选择即可。

#### 方案一：`cross` + Docker（适合追求环境一致、可复用镜像）

该方案**依赖 Docker**。如果你本机已经安装并可正常使用 Docker，可以优先使用这一套。

项目根目录下的 `Dockerfile.cross` 就是给这套方案配套使用的，用于基于 `cross` 官方镜像构建自定义交叉编译环境：

- 基于 `ghcr.io/cross-rs/x86_64-unknown-linux-gnu:main`
- 额外安装 `gcc-12 / g++-12`
- 用来规避部分依赖（如 `aws-lc-sys`）在某些默认工具链下的编译问题
- 首次构建会稍慢，但后续可复用 Docker 缓存，环境更稳定

典型用法：

```bash
# 安装 cross（如未安装）
cargo install cross

# 使用 cross 交叉编译 Linux x86_64
cross build --target x86_64-unknown-linux-musl -p app --release
```

编译产物位于：`target/x86_64-unknown-linux-musl/release/app`

> 如果你要使用这套方案，请注意：`Dockerfile.cross` 与其是配套关系，不建议脱离 Docker 单独理解。

#### 方案二：`cargo-zigbuild` + Zig（更轻便，适合本地直接交叉编译）

如果你不想依赖 Docker，或者更偏向轻量方案，可以使用 `zig` + `cargo-zigbuild`。这一套通常更省资源，安装完成后本地直接编译即可。

Windows 下可按如下方式准备环境：

```bash
winget install zig.zig
cargo install cargo-zigbuild
rustup target add x86_64-unknown-linux-musl
cargo zigbuild --target x86_64-unknown-linux-musl -p app --release
```

编译产物同样位于：`target/x86_64-unknown-linux-musl/release/app`

> 如果只是日常在 Windows 开发机上打 Linux 包，`cargo-zigbuild` 往往比 Docker + cross 更轻便，适合个人开发和快速构建。

#### 其他目标平台

- Linux ARM64：
  - 方案一（cross）：`cross build --target aarch64-unknown-linux-gnu -p app --release`
  - 方案二（zigbuild）：`rustup target add aarch64-unknown-linux-musl && cargo zigbuild --target aarch64-unknown-linux-musl -p app --release`
- Linux x86_64：
  - 方案一（cross）：`cross build --target x86_64-unknown-linux-musl -p app --release`
  - 方案二（zigbuild）：`rustup target add x86_64-unknown-linux-musl && cargo zigbuild --target x86_64-unknown-linux-musl -p app --release`
- Windows：
  - `cargo build -p app --release`
- macOS：
  - `cargo build -p app --release`

### 部署目录结构

建议将“可执行文件、配置覆盖、前端静态资源、日志目录”分开组织，方便后续升级与回滚：

```text
ruoyi-deploy/                        # 部署根目录
├── app                              # 后端可执行文件（从 target/.../release/app 复制）
├── config/
│   ├── default.toml                 # 基础默认配置（从项目 config/ 复制）
│   └── local.toml                   # 生产环境覆盖配置（推荐新增，按需填写）
├── dist/                            # 前端构建产物（从 ruoyi-rust-ui-plus/apps/web-ele/dist 复制）
│   └── ...
└── logs/                            # 日志目录（程序自动创建）
    └── app.log
```

说明：

- 程序会先读取 `config/default.toml`，再按需叠加 `config/local.toml`。
- 因此生产环境更推荐“保留默认配置 + 使用 `local.toml` 覆盖差异项”，而不是直接把 `default.toml` 改成一份难维护的生产专用文件。
- 如果前端由 Nginx 单独托管，`dist/` 也可以不和后端放在同一目录，但文档里的这种结构最直观，适合单机部署。
### 部署步骤

1. **构建前端**（在开发机上）：
   - 修改 `apps/web-ele/.env.production` 中的后端 API 地址：
     ```bash
     # 将以下地址替换为你的实际服务器地址
     VITE_GLOB_API_URL=https://your-domain.com/prod-api
     ```
   - 执行构建命令：
     ```bash
     cd ruoyi-rust-ui-plus
     pnpm install
     pnpm build
     ```
   - 构建产物位于：`apps/web-ele/dist/`

2. **上传文件**：将以下文件上传至服务器
   - 后端可执行文件 `app`
   - 配置文件 `config/default.toml`
   - 前端构建产物 `dist/` 目录

#### 可选：IP 地理位置库（ip2region）说明

- `resources/ip2region_v4.xdb` 用于登录日志等场景的 IP 归属地解析。
- 该文件因法律/分发风险，项目仓库默认**不提供**，需要使用者自行下载并放到后端仓库根目录的 `resources/` 下。
- 配置项位于：

  ```toml
  [security]
  ip_location_enabled = false
  ```

- 行为说明：
  - `false`：系统不使用该文件，构建时也**不会**把它打包进 `app`
  - `true` + 文件存在：构建时会把 `resources/ip2region_v4.xdb` **编译进 `app`**
  - `true` + 文件不存在：系统会退化为不做 IP 归属地解析，并在编译/运行时给出提示
- 因为采用的是**编译进二进制**的方式，所以生产部署时：
  - **开启后只需上传新的 `app`**，不需要再额外上传 `resources/ip2region_v4.xdb`
  - 关闭时也不会把该文件带进最终产物

3. **赋予执行权限**（Linux）：
   ```bash
   chmod +x app
   ```

4. **修改配置**：优先编辑 `config/local.toml`，按需覆盖生产环境数据库、缓存等配置；`default.toml` 建议保留为基础默认配置。

5. **启动服务**：
   ```bash
   # 直接运行
   ./app
   
   # 或使用 systemd 管理（推荐）
   sudo systemctl start ruoyi-rust
   sudo systemctl enable ruoyi-rust  # 开机自启
   ```

### systemd 服务配置（可选）

创建 `/etc/systemd/system/ruoyi-rust.service`：

```ini
[Unit]
Description=RuoYi Rust Backend Service
After=network.target

[Service]
Type=simple
User=www
WorkingDirectory=/opt/ruoyi-deploy
ExecStart=/opt/ruoyi-deploy/app
Restart=always
RestartSec=10

[Install]
WantedBy=multi-user.target
```

## 🤝 贡献指南

我们热烈欢迎任何形式的贡献！无论是提交 Issue、修复 Bug 还是实现新功能。请参考我们的 [CONTRIBUTING.md](CONTRIBUTING.md) 文件了解详细的贡献流程和编码规范。

## 📄 许可证 (License)

本项目采用 [MIT License](LICENSE) 开源许可证。

## 交流与赞助

如果有对本项目感兴趣的朋友，欢迎加入 QQ 群一起交流学习，让我们一起变得更强。

**ruoyi-rust 交流 QQ 群: 512670767**



## 🙏 鸣谢

* 感谢原项目 [RuoYi-Vue](https://gitee.com/y_project/RuoYi-Vue) 提供的优秀设计和前端实现。
* 感谢 [RuoYi-Vue3](https://gitcode.com/yangzongzhuan/RuoYi-Vue3) 提供的 Vue3 前端版本。
* 感谢 [Vue Vben Admin](https://github.com/vbenjs/vue-vben-admin) 提供的现代化 Vue 3 管理模板。
* 感谢 [RustFS](https://github.com/rustfs/rustfs) 提供的高性能 Rust 原生 S3 兼容对象存储，作为本项目默认对象存储方案。
* 感谢 [Dify](https://dify.ai) 提供的开源 AI 应用开发平台，本项目 AI 智能问答模块基于 Dify API 实现。