# ruoyi-cloud-pro

**Repository Path**: sagframe/ruoyi-cloud-pro

## Basic Information

- **Project Name**: ruoyi-cloud-pro
- **Description**: No description available
- **Primary Language**: Java
- **License**: MIT
- **Default Branch**: dev
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 2
- **Created**: 2026-06-07
- **Last Updated**: 2026-06-07

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# ruoyi-cloud-pro 企业级快速开发平台
---

## 一、平台简介

**ruoyi-cloud-pro**（太乙微服务快速开发平台）是基于 Spring Cloud Alibaba 2025 全栈微服务架构的企业级快速开发平台，对 RuoYi-Cloud和RuoYi-Cloud-Plus进行了**全方位重写与深度升级**（不兼容原框架）。平台采用 DDD 领域驱动设计思想，以 **SqlToy-Plus** 替代 MyBatis-Plus 作为 ORM 框架，以 **Sa-Token** 替代 Spring Security 作为权限认证框架，以 **Apache Dubbo 3.x** 替代 Feign 作为 RPC 框架，打造了一套高性能、高扩展、生产可用的微服务基座。

---

## 二、核心亮点

### 🏗️ 全栈微服务架构

| 组件 | 技术选型 | 说明 |
|------|---------|------|
| 注册/配置中心 | **Alibaba Nacos** | 源码集成，便于调试扩展与二次开发，内置监控 |
| 服务网关 | **Spring Cloud Gateway** | 扩展内网鉴权、请求体缓存、跨域、请求响应日志 |
| RPC 调用 | **Apache Dubbo 3.x** | 高性能 RPC，替代 Feign，网络更稳定 |
| 限流熔断 | **Alibaba Sentinel** | 源码集成，可视化监控面板 |
| 分布式事务 | **Alibaba Seata** | 源码集成，对接 Nacos，简化搭建部署 |
| 链路追踪 | **Apache SkyWalking** | 全链路追踪，实时查看请求经过的每个节点 |
| 任务调度 | **SnailJob** | 天生分布式，支持分片、重试、DAG 任务流 |
| 消息队列 | **Kafka / RocketMQ / RabbitMQ** | 延迟消息、事务消息、流消息全覆盖 |
| 消息总线 | **Spring Cloud Bus** | 跨服务事件通知 |

### 🔐 安全认证体系

| 特性 | 说明 |
|------|------|
| **Sa-Token + JWT** | 轻量级权限认证，低耦合高扩展，网关统一鉴权 |
| 网关鉴权 | Gateway 统一校验 Token，用户 ID 透传至下游微服务 |
| 权限注解 | 支持登录校验、角色校验、权限校验、二级认证、HttpBasic、AND/OR 复杂表达式 |
| 分布式幂等 | 参考美团 GTIS 防重系统，基于 Redis 实现幂等校验 |
| 数据脱敏 | 注解 + Jackson 序列化脱敏，支持身份证、手机号、邮箱、银行卡等 |
| 数据加解密 | 注解 + 拦截器自动加解密，支持 AES、RSA、SM2、SM4 等国密算法 |

### 🚀 高性能 ORM — SqlToy-Plus

| 特性 | 说明 |
|------|------|
| **Lambda 链式查询** | `Wrappers.lambdaWrapper(Entity.class).eq(...)` 类型安全，编译期检查 |
| **零 XML 开发** | 简单 CRUD 无需 XML，复杂 SQL 支持 `@SqlToy` 注解或直接传入 SQL |
| **分页封装** | 统一 `PageResult` 响应，自动转换页码参数 |
| **雪花 ID** | `@TableId(type = IdType.ASSIGN_ID)` 内置雪花算法主键生成 |
| **多数据源** | 配合 dynamic-datasource 支持异构数据库动态切换 |
| **SQL 监控** | p6spy 输出完整 SQL 与执行时间 |

### 📦 DDD 标准分层架构

每个业务微服务严格遵循领域驱动设计分层：

```
com.taiyi.xxx
├── api/                    # 接口层
│   ├── web/                #   Web 控制器（面向前端）
│   ├── rpc/                #   Dubbo RPC 实现（面向微服务）
│   ├── dto/                #   请求 DTO（XxxDTO）
│   └── vo/                 #   响应 VO（XxxVO）
├── service/                # 服务层（直接实现，无接口）
├── domain/                 # 领域层
│   ├── model/              #   领域模型（实体类）
│   ├── consts/             #   常量定义
│   └── enums/              #   枚举类
└── infra/                  # 基础设施层
    ├── config/             #   配置类
    ├── handler/            #   全局异常处理器
    └── filter/             #   过滤器
```

### 🌐 多租户 & 工作流

- **多租户**：租户管理、租户套餐、过期时间、用户数量、企业信息，开箱即用
- **工作流**：基于 warm-flow，支持转办、委派、加减签、会签、或签、票签等复杂审批

---

## 三、技术栈全景

| 分类 | 技术 | 版本 |
|------|------|------|
| **核心框架** | Spring Boot | 3.5 |
| **微服务** | Spring Cloud | 2025.0 |
| **注册/配置** | Alibaba Nacos | 2.5.1 |
| **RPC** | Apache Dubbo | 3.x |
| **ORM** | **SqlToy / SqlToy-Plus** | **5.6.71** |
| **权限认证** | **Sa-Token** | **1.45.0** |
| **缓存** | Redis + Redisson | 3.52.0 |
| **搜索引擎** | ElasticSearch + Easy-Es | 7.17 |
| **消息队列** | Kafka / RocketMQ / RabbitMQ | - |
| **分布式事务** | Alibaba Seata | - |
| **任务调度** | SnailJob | 1.10.0 |
| **文件存储** | MinIO / AWS S3 | - |
| **Excel** | FastExcel (原 EasyExcel) | 1.3.0 |
| **接口文档** | SpringDoc + Knife4j | 2.8 |
| **工具库** | Hutool + Lombok + MapStruct-Plus | 5.8 / 1.18 / 1.5 |
| **序列化** | Jackson | Spring 内置 |
| **监控** | Prometheus + Grafana + Spring Boot Admin | - |
| **链路追踪** | Apache SkyWalking | 9.6 |
| **容器** | Undertow (XNIO 高性能) | Spring 内置 |
| **Java** | JDK 17+ / JDK 21+ | - |

---

## 四、项目结构

```
ruoyi-cloud-pro
├── ruoyi-auth/                     # 认证授权服务
├── ruoyi-gateway/                  # API 网关（鉴权/路由/限流/日志）
├── ruoyi-common/                   # 公共模块（30+ 插件化组件）
│   ├── ruoyi-common-core/          #   核心工具
│   ├── ruoyi-common-sqltoy/        #   SqlToy-Plus 集成
│   ├── ruoyi-common-satoken/       #   Sa-Token 集成
│   ├── ruoyi-common-redis/         #   Redis/Redisson
│   ├── ruoyi-common-dubbo/         #   Dubbo RPC
│   ├── ruoyi-common-security/      #   安全框架
│   ├── ruoyi-common-log/           #   操作日志
│   ├── ruoyi-common-excel/         #   Excel 导入导出
│   ├── ruoyi-common-encrypt/       #   数据加解密
│   ├── ruoyi-common-sensitive/     #   数据脱敏
│   ├── ruoyi-common-translation/   #   数据翻译
│   ├── ruoyi-common-tenant/        #   多租户
│   ├── ruoyi-common-idempotent/    #   分布式幂等
│   ├── ruoyi-common-oss/           #   对象存储
│   ├── ruoyi-common-mail/          #   邮件
│   ├── ruoyi-common-sms/           #   短信
│   ├── ruoyi-common-elasticsearch/ #   搜索引擎
│   ├── ruoyi-common-bus/           #   消息总线
│   ├── ruoyi-common-websocket/     #   WebSocket
│   ├── ruoyi-common-sse/           #   SSE 推送
│   ├── ruoyi-common-seata/         #   分布式事务
│   ├── ruoyi-common-logstash/      #   日志收集
│   ├── ruoyi-common-skylog/        #   链路日志
│   ├── ruoyi-common-prometheus/    #   指标采集
│   ├── ruoyi-common-social/        #   社会化登录
│   ├── ruoyi-common-nacos/         #   Nacos 集成
│   ├── ruoyi-common-loadbalancer/  #   负载均衡
│   ├── ruoyi-common-ratelimiter/   #   限流
│   ├── ruoyi-common-doc/           #   接口文档
│   ├── ruoyi-common-json/          #   JSON 序列化
│   ├── ruoyi-common-job/           #   任务调度
│   └── ruoyi-common-service-impl/  #   通用业务实现
├── ruoyi-modules/                  # 业务模块
│   ├── ruoyi-system/               #   系统管理（用户/角色/菜单/部门/岗位/字典/参数/通知/租户）
│   ├── ruoyi-gen/                  #   代码生成器
│   ├── ruoyi-job/                  #   任务调度
│   ├── ruoyi-resource/             #   资源管理（OSS/短信/邮件）
│   ├── ruoyi-workflow/             #   工作流
│   └── ruoyi-member/               #   会员管理
├── ruoyi-api/                      # 微服务 API（Dubbo 接口定义 + DTO）
├── ruoyi-infra/                    # 基础设施服务
│   ├── ruoyi-nacos/                #   Nacos Server（源码集成）
│   ├── ruoyi-monitor/              #   Spring Boot Admin 监控
│   ├── ruoyi-seata-server/         #   Seata Server（源码集成）
│   └── ruoyi-snailjob-server/      #   SnailJob Server（源码集成）
├── ruoyi-example/                  # 示例模块
│   ├── ruoyi-demo/                 #   功能演示（CRUD/树表/ES/分库分表/加密/Excel等）
│   └── ruoyi-test-mq/              #   消息队列测试
└── script/                         # 部署脚本
    ├── config/                     #   Nacos/Grafana 配置
    └── docker/                     #   Docker Compose 编排
```

---

## 五、与 RuoYi-Cloud / RuoYi-Cloud-Plus 对比

### 5.1 架构设计对比

| 维度 | ruoyi-cloud-pro | ruoyi-cloud-plus | ruoyi-cloud |
|------|-----------------|------------------|-------------|
| **架构风格** | DDD 领域驱动 + 标准分层 | 传统三层架构 | 传统三层架构 |
| **分层规范** | api/service/domain/infra 四层严格分离 | controller/service/mapper | controller/service/mapper |
| **ORM 框架** | **SqlToy-Plus**（Lambda 链式查询，零 XML） | MyBatis-Plus | MyBatis（XML 手写 SQL） |
| **RPC 框架** | **Apache Dubbo 3.x**（高性能二进制协议） | Apache Dubbo 3.x | OpenFeign（HTTP 调用，网络波动大） |
| **认证框架** | **Sa-Token**（轻量、注解驱动、网关透传） | Sa-Token | Spring Security（配置繁琐） |
| **Spring Boot** | **3.5**（最新） | 3.x | 2.x |
| **Spring Cloud** | **2025.0**（最新） | 2022.x | Hoxton/Spring Cloud Alibaba |
| **JDK** | **17 / 21** | 17 | 8 / 11 |
| **Web 容器** | **Undertow**（XNIO 高性能） | Undertow | Tomcat |

### 5.2 功能特性对比

| 功能 | ruoyi-cloud-pro | ruoyi-cloud-plus | ruoyi-cloud |
|------|-----------------|------------------|-------------|
| **多租户** | ✅ 租户管理 + 套餐管理 + 数据隔离 | ✅ 支持 | ❌ |
| **工作流** | ✅ warm-flow（会签/或签/转办/委派/加减签） | ✅ 支持 | ❌ |
| **数据脱敏** | ✅ 注解 + Jackson 序列化脱敏 | ✅ 支持 | ❌ |
| **数据加解密** | ✅ 注解 + 拦截器（AES/RSA/SM2/SM4 国密） | ✅ 支持 | ❌ |
| **数据翻译** | ✅ 注解 + Jackson 动态翻译 | ✅ 支持 | ❌ |
| **分布式幂等** | ✅ 参考美团 GTIS，Redis 实现 | ✅ 支持 | ❌ |
| **SSE 推送** | ✅ Token 鉴权 + 分布式会话同步 | ✅ 支持 | ❌ |
| **WebSocket** | ✅ Token 鉴权 + 分布式会话同步 | ✅ 支持 | ❌ |
| **社会化登录** | ✅ JustAuth（微信/QQ/支付宝等） | ✅ 支持 | ❌ |
| **分库分表** | ✅ Apache Sharding-Proxy | ✅ 支持 | ❌ |
| **消息总线** | ✅ Spring Cloud Bus | ✅ 支持 | ❌ |
| **链路追踪** | ✅ Apache SkyWalking | ✅ 支持 | ❌ |
| **ELK 日志** | ✅ 完整 ELK 方案 | ✅ 支持 | ❌ |
| **Prometheus 监控** | ✅ + Grafana 大屏 | ✅ 支持 | ❌ |
| **代码生成** | ✅ 多数据源 + SqlToy 适配 | ✅ MyBatis-Plus 适配 | ✅ 基础生成 |
| **短信** | ✅ 阿里/腾讯，接口化扩展 | ✅ 支持 | ❌ |
| **邮件** | ✅ mail-api 通用协议 | ✅ 支持 | ❌ |
| **云存储** | ✅ AWS S3 协议（七牛/阿里/腾讯） | ✅ 支持 | ❌ |
| **接口文档** | ✅ SpringDoc + javadoc 零注解 | ✅ SpringDoc | ❌ Springfox（已停维） |
| **国际化** | ✅ 请求头动态切换 + 注解国际化 | ✅ 支持 | ⚠️ 基础 |
| **Demo 案例** | ✅ 独立模块，功能齐全 | ✅ 支持 | ❌ |

### 5.3 核心差异化优势

#### 1️⃣ SqlToy-Plus 替代 MyBatis-Plus — 更优雅的 ORM 体验

| 对比项 | SqlToy-Plus | MyBatis-Plus |
|--------|-------------|--------------|
| 查询方式 | **Lambda 链式** `Wrappers.lambdaWrapper(Entity.class).eq(...)` | LambdaQueryWrapper |
| 复杂 SQL | `@SqlToy` 注解或直接传入 SQL，**无需 XML** | 需要编写 XML Mapper 文件 |
| 分页 | `PageResult` 统一封装，自动转换 | Page 对象，需手动转换 |
| 主键策略 | `@TableId(type = IdType.ASSIGN_ID)` 雪花算法 | `@TableId` 雪花算法 |
| 缓存翻译 | **内置缓存翻译**，SQL 级别自动关联翻译 | 无，需手动关联查询 |
| SQL 监控 | p6spy 输出完整 SQL + 执行时间 | p6spy |
| 学习成本 | 低，API 直觉化 | 中，需熟悉 Wrapper 体系 |
| 扩展性 | Dao/Service 双模式，灵活选择 | Service/Mapper 固定模式 |

**SqlToy-Plus 的独特优势**：
- **缓存翻译**：SQL 级别的缓存翻译机制，自动将 ID 翻译为名称，无需手写关联查询，大幅减少 SQL 复杂度
- **零 XML 开发**：简单 CRUD 完全不需要 XML，复杂 SQL 支持 `@SqlToy` 注解或直接传入 SQL 字符串
- **分页优化**：自动优化分页查询（如先查 count 再查数据），支持游标分页
- **更安全的 API**：Lambda 链式查询编译期类型检查，杜绝字段名拼写错误

#### 2️⃣ Sa-Token 替代 Spring Security — 更轻量的安全框架

| 对比项 | Sa-Token | Spring Security |
|--------|----------|-----------------|
| 学习成本 | **极低**，API 直觉化 | 高，配置链式复杂 |
| 注解鉴权 | `@SaCheckLogin` `@SaCheckRole` `@SaCheckPermission` | `@PreAuthorize` + SpEL 表达式 |
| 权限表达式 | 支持 AND/OR/复杂组合 | 仅支持 SpEL |
| 网关集成 | Gateway 统一鉴权 + 用户 ID 透传 | 需要自定义过滤器 |
| 二级认证 | **内置支持** | 需自行实现 |
| HttpBasic | **内置支持** | 需配置 |
| 会话管理 | **内置分布式会话** | 需集成 Spring Session |
| 多端互斥登录 | **内置支持** | 需自行实现 |

#### 3️⃣ Apache Dubbo 替代 Feign — 更可靠的 RPC

| 对比项 | Apache Dubbo 3.x | OpenFeign |
|--------|-------------------|-----------|
| 通信协议 | **Triple（HTTP/2 + gRPC 兼容）** | HTTP/1.1 |
| 序列化 | **Hessian2 / Protobuf**（二进制高效） | JSON（文本低效） |
| 性能 | **3-10 倍于 Feign** | 基准 |
| 服务治理 | 内置路由、熔断、限流 | 依赖外部组件 |
| 超时重试 | 精细化配置 | 基础配置 |
| 网络稳定性 | **长连接，网络波动影响小** | 短连接，网络波动大 |

#### 4️⃣ DDD 标准分层 — 更清晰的架构边界

| 对比项 | ruoyi-cloud-pro (DDD) | 传统三层架构 |
|--------|----------------------|-------------|
| 职责划分 | api/service/domain/infra 四层严格分离 | controller/service/mapper 混合 |
| DTO/VO 归属 | **api 层**，与接口同包管理 | domain/bo + domain/vo，与实体混合 |
| 服务层 | 无接口直接实现，减少冗余 | 接口 + 实现，类爆炸 |
| 领域模型 | domain/model 纯 POJO，无框架注解 | 实体类混杂基础设施注解 |
| 基础设施 | infra 层独立管理配置/异常/过滤器 | 配置散落各处 |
| 微服务间调用 | api 模块独立，Dubbo 接口 + DTO | 接口定义与实现耦合 |

#### 5️⃣ 基础设施源码集成 — 开箱即用

| 组件 | ruoyi-cloud-pro | ruoyi-cloud-plus | ruoyi-cloud |
|------|-----------------|------------------|-------------|
| Nacos | **源码集成**，可调试可扩展 | 外部搭建 | 外部搭建 |
| Seata | **源码集成**，对接 Nacos | 外部搭建 | 外部搭建 |
| Sentinel | **源码集成**，监控面板 | 外部搭建 | 外部搭建 |
| SnailJob | **源码集成**，管理中心 | 外部搭建 | Quartz |
| Spring Boot Admin | **源码集成**，在线日志 | 外部搭建 | ❌ |

**源码集成的优势**：无需单独下载部署，Docker Compose 一键启动，调试时可断点进入源码，二次开发无需反编译。

---

## 六、业务功能

| 业务 | 功能说明 | 状态 |
|------|---------|------|
| 租户管理 | 租户套餐、过期时间、用户数量、企业信息 | ✅ |
| 租户套餐 | 套餐内菜单管理、套餐分配 | ✅ |
| 用户管理 | 用户配置、部门/角色/岗位分配 | ✅ |
| 部门管理 | 树结构部门配置 | ✅ |
| 岗位管理 | 岗位信息配置 | ✅ |
| 菜单管理 | 菜单/按钮/权限配置 | ✅ |
| 角色管理 | 角色权限分配、数据权限 | ✅ |
| 字典管理 | 系统字典维护 | ✅ |
| 参数管理 | 系统参数配置 | ✅ |
| 通知公告 | 系统通知发布 | ✅ |
| 操作日志 | 操作记录查询 | ✅ |
| 登录日志 | 登录记录查询 | ✅ |
| 在线用户 | 在线用户监控、强退 | ✅ |
| 缓存监控 | Redis 缓存监控 | ✅ |
| 代码生成 | 一键生成 CRUD 代码与页面 | ✅ |
| 文件管理 | OSS 文件上传/下载/管理 | ✅ |
| 短信管理 | 短信发送/模板管理 | ✅ |
| 邮件管理 | 邮件发送/模板管理 | ✅ |
| 工作流 | 流程设计/审批/转办/委派/加减签 | ✅ |
| 会员管理 | 会员注册/认证/管理 | ✅ |

---

## 七、会员模块（ruoyi-member）详解

### 7.1 模块简介

**ruoyi-member** 是面向 C 端用户的会员管理微服务，独立于后台系统管理（ruoyi-system），专门处理前台会员的注册、登录、认证、管理等业务。模块严格遵循 DDD 标准分层架构，采用 **api 模块 + server 模块** 的双模块设计，实现接口定义与业务实现的物理隔离，支持 Dubbo RPC 跨服务调用。

### 7.2 模块结构

```
ruoyi-member
├── ruoyi-member-api/                  # API 模块（面向其他微服务）
│   └── cn.taiyi.member.api
│       ├── MemberRpc.java             # Dubbo RPC 接口定义
│       ├── model/
│       │   └── MemberLoginUser.java   # 会员登录用户模型（继承 LoginUser）
│       ├── req/
│       │   ├── GetMemberByPhoneReqDTO.java    # 手机号查询请求
│       │   └── GetMemberByWechatReqDTO.java   # 微信查询请求
│       └── resp/
│           └── MemberRespDTO.java     # 会员信息响应
│
└── ruoyi-member-server/               # 服务实现模块
    └── cn.taiyi.member
        ├── api/                       # 接口层
        │   ├── web/
        │   │   ├── app/               #   C 端接口（面向会员）
        │   │   │   ├── MemberAuthController.java        # 会员认证（发送验证码）
        │   │   │   ├── MemberUserController.java        # 会员信息查询
        │   │   │   └── MemberRealAuthController.java    # 实名认证申请/查询
        │   │   ├── admin/             #   B 端接口（面向管理员）
        │   │   │   ├── MemberAdminController.java       # 会员管理（列表/编辑/删除/重置密码/停启用）
        │   │   │   └── MemberRealAuthAdminController.java # 实名审核（列表/审核）
        │   │   ├── dto/               #   请求 DTO
        │   │   └── vo/                #   响应 VO
        │   └── rpc/
        │       └── MemberRpcImpl.java # Dubbo RPC 实现
        ├── service/                   # 服务层
        │   ├── MemberAuthService.java       # 会员认证服务（注册/登录/验证码）
        │   ├── MemberUserService.java       # 会员管理服务（CRUD/分页/状态变更）
        │   └── MemberRealAuthService.java   # 实名认证服务（申请/审核/查询）
        ├── domain/                    # 领域层
        │   ├── model/
        │   │   ├── MemberUser.java          # 会员用户实体
        │   │   ├── MemberLoginRecord.java   # 登录记录实体
        │   │   └── MemberRealAuth.java      # 实名认证实体
        │   ├── consts/
        │   │   └── MemberConstants.java     # 业务常量（错误码等）
        │   └── enums/
        │       ├── MemberStatusEnum.java    # 会员状态枚举
        │       ├── LoginTypeEnum.java       # 登录类型枚举
        │       ├── IdCardTypeEnum.java      # 证件类型枚举
        │       └── RealNameStatusEnum.java  # 实名状态枚举
        └── infra/                     # 基础设施层
            └── config/
                └── MemberSwaggerConfig.java # 接口文档配置
```

### 7.3 核心功能

#### 📱 多渠道注册与登录

| 登录方式 | 说明 |
|---------|------|
| **手机号 + 短信验证码** | 发送验证码至手机，Redis 缓存 5 分钟有效，支持自动注册 |
| **手机号 + 密码** | BCrypt 加密存储，安全可靠 |
| **微信授权登录** | 基于 OpenID/UnionID 自动匹配，首次自动注册 |

**自动注册机制**：调用 `registerOrGetByPhone` / `registerOrGetByOpenid` 时，若会员不存在则自动创建，实现"登录即注册"的无感体验。

#### 🛡️ 实名认证全流程

```
会员申请 → 待审核(PENDING) → 审核通过(APPROVED) / 审核驳回(REJECTED)
                ↑                    ↓
        可重新提交申请         会员状态同步更新
```

- **申请**：会员提交真实姓名、证件类型、证件号、证件照片
- **防重复提交**：审核中状态禁止重复申请
- **审核**：管理员通过/驳回，驳回需填写原因
- **脱敏展示**：C 端查询自动对证件号进行掩码处理（`3101**********1234`）
- **状态同步**：审核结果自动同步至会员表的 `realNameStatus` 字段

#### 👥 会员管理（B 端）

| 功能 | 接口 | 说明 |
|------|------|------|
| 分页查询 | `GET /members/list` | 支持昵称/手机号/状态/实名状态筛选 |
| 详情查询 | `GET /members/{id}` | 查看会员完整信息 |
| 编辑会员 | `PUT /members` | 修改昵称/邮箱/性别/状态 |
| 删除会员 | `DELETE /members/{id}` | 物理删除会员 |
| 重置密码 | `PUT /members/{id}/reset-password` | BCrypt 加密新密码 |
| 停启用 | `PUT /members/{id}/status` | 切换正常/停用状态 |

#### 🔗 Dubbo RPC 开放能力

通过 `MemberRpc` 接口向其他微服务暴露会员能力：

| 方法 | 说明 |
|------|------|
| `getMemberById` | 按 ID 查询会员信息 |
| `getMemberByPhone` | 按手机号查询会员信息 |
| `getMemberByWechat` | 按微信 OpenID/UnionID 查询 |
| `checkRealName` | 校验会员是否已实名认证 |
| `getMemberLoginUserByPhone` | 手机号获取登录用户（认证服务调用） |
| `getMemberLoginUserByOpenid` | OpenID 获取登录用户（认证服务调用） |
| `registerOrGetByPhone` | 手机号自动注册或获取（登录即注册） |
| `registerOrGetByOpenid` | OpenID 自动注册或获取（登录即注册） |

### 7.4 设计优势

#### 1️⃣ C/B 端接口物理隔离

```
/app/members/*        → C 端会员接口（SaCheckLogin 鉴权）
/app/members/auth/*   → C 端认证接口（公开/登录校验）
/members/*            → B 端管理接口（SaCheckPermission 权限校验）
```

- **C 端**（`/app/` 前缀）：面向会员用户，轻量鉴权，关注自身数据
- **B 端**（无前缀）：面向后台管理员，细粒度权限控制，管理全部数据
- **好处**：避免接口混用导致权限越权，URL 语义清晰，网关路由配置简单

#### 2️⃣ api 模块独立发布

```
ruoyi-member-api（仅接口 + DTO，无实现依赖）
     ↑ 依赖
其他微服务（如 ruoyi-auth 认证服务）
```

- 其他微服务只需引入 `ruoyi-member-api` 即可调用会员能力
- **无需依赖整个会员服务实现**，减少依赖传递和冲突
- DTO 实现 `Serializable`，Dubbo 序列化零配置

#### 3️⃣ 登录即注册的无感体验

```java
// 认证服务调用：手机号不存在则自动注册
MemberLoginUser user = memberRpc.registerOrGetByPhone(phone);
```

- 用户首次使用手机号或微信登录时，自动创建会员账号
- 无需单独的注册流程，降低用户流失率
- 与 `ruoyi-auth` 认证服务深度集成，Sa-Token 签发 Token

#### 4️⃣ 网关鉴权 + 用户 ID 透传

```java
@PostMapping
public Result<Void> applyRealAuth(@RequestHeader("X-User-Id") Long memberId, ...) {
    // 直接从 Header 获取用户 ID，无需解析 Token
}
```

- Gateway 统一校验 Token 有效性，将 `userId` 写入 `X-User-Id` Header 透传
- 微服务无需重复校验 Token，直接从 Header 获取当前用户
- 减少微服务对 Redis/Token 的直接依赖，架构更解耦

#### 5️⃣ 统一错误码体系

```java
public final class MemberConstants {
    public static final int MEMBER_NOT_FOUND = 2001;          // 会员不存在
    public static final int MEMBER_PHONE_EXISTS = 2002;       // 手机号已存在
    public static final int MEMBER_DISABLED = 2005;           // 会员已停用
    public static final int MEMBER_REAL_AUTH_PENDING = 2008;  // 实名审核中
    public static final int MEMBER_REAL_AUTH_ALREADY = 2009;  // 已完成实名
    // ...
}
```

- 错误码按模块划分（2xxx = 会员模块），与全局响应结构 `Result<T>` 配合
- 前端可根据错误码精准提示，无需解析中文消息
- 全局异常处理器统一捕获 `ServiceException`，返回标准 JSON 响应

#### 6️⃣ 数据安全与隐私保护

| 安全措施 | 说明 |
|---------|------|
| **密码加密** | BCrypt 单向哈希，不可逆 |
| **证件号脱敏** | C 端查询自动掩码 `3101**********1234` |
| **敏感字段过滤** | VO 不暴露 password/salt 等敏感字段 |
| **网关鉴权** | Token 校验在网关完成，微服务不直接处理认证 |
| **权限细控** | B 端接口 `@SaCheckPermission` 注解级权限校验 |

### 7.5 与认证服务（ruoyi-auth）的协作

```
┌──────────┐    1.登录请求     ┌──────────┐    2.查询/注册会员    ┌───────────────┐
│  前端APP  │ ──────────────→ │  Gateway  │ ──────────────────→ │  ruoyi-auth   │
└──────────┘                  └──────────┘                      └───────┬───────┘
                                                                    │ 3.Dubbo RPC
                                                                    ↓
                                                              ┌───────────────┐
                                                              │ ruoyi-member  │
                                                              │ (MemberRpc)   │
                                                              └───────────────┘
                                                                    │ 4.返回 MemberLoginUser
                                                                    ↓
                                                              ┌───────────────┐
                                                              │  ruoyi-auth   │
                                                              │ Sa-Token 签发  │
                                                              │ Token 返回前端  │
                                                              └───────────────┘
```

1. 前端发起登录请求（手机号/微信）
2. Gateway 校验白名单，转发至认证服务
3. 认证服务通过 Dubbo 调用 `MemberRpc` 获取/注册会员
4. 认证服务使用 `MemberLoginUser` 构建 Sa-Token 会话，签发 Token 返回前端

---

## 八、快速开始

### 环境要求

| 依赖 | 版本要求 |
|------|---------|
| JDK | 17+ (推荐 21) |
| Maven | 3.8+ |
| MySQL | 8.0+ |
| Redis | 6.0+ |
| Node.js | 18+ |

### 一键启动（Docker Compose）

```bash
# 克隆项目
git clone https://gitee.com/dong96888/ruoyi-cloud-pro.git

# 进入部署目录
cd ruoyi-cloud-pro/script/docker

# 一键启动所有基础设施（Nacos/MySQL/Redis/MinIO等）
docker-compose up -d
```

### 本地开发

```bash
# 1. 启动基础设施（Nacos/MySQL/Redis）
# 2. 导入 Nacos 配置（script/config/nacos/）
# 3. 按顺序启动服务
#    - ruoyi-nacos（Nacos Server）
#    - ruoyi-gateway（API 网关）
#    - ruoyi-auth（认证服务）
#    - ruoyi-system（系统服务）
#    - ruoyi-resource（资源服务）
# 4. 启动前端
cd ruoyi-admin-web
npm install
npm run dev
```

---

## 九、开源协议

本项目基于 [MIT 协议](LICENSE) 开源，可免费商用。请在项目中保留开源协议文件即可。