# 睿核科技 (rui) — 项目实施规范

> 本文档基于对当前 rui-framework 项目的全面分析，整理项目结构、业务流、现有规范、推荐修改项及缺少的专业结构，供后续项目实施参考。

---

## 一、项目概述

| 项目属性 | 值 |
|---------|-----|
| **项目名称** | rui-framework |
| **项目类型** | Spring Cloud 微服务架构（通用平台框架） |
| **组织方式** | Monorepo（backend + 可扩展前端） |
| **JDK** | 21 |
| **Spring Boot** | 4.0.3 |
| **Spring Cloud** | 2025.1.1 |
| **Alibaba Cloud** | 2025.1.0.0 |
| **MyBatis Plus** | 3.5.16 |
| **包管理** | Maven + flatten-maven-plugin |
| **配置中心** | Nacos |
| **注册中心** | Nacos |

---

## 二、项目架构图

```
┌─────────────────────────────────────────────────────────────┐
│                        客户端（Web/App/小程序）                │
└─────────────────────────────┬───────────────────────────────┘
                              │
                    ┌─────────▼─────────┐
                    │   rui-gateway     │  ← 灰度路由、负载均衡、请求清洗
                    │      :9300        │
                    └─────────┬─────────┘
                              │
          ┌───────────────────┼───────────────────┐
          │                   │                   │
    ┌─────▼─────┐     ┌──────▼──────┐    ┌──────▼──────┐
    │ rui-auth  │     │rui-service-*│    │ rui-service-*│
    │   :9301   │     │   :9302+    │    │   :9302+    │
    └─────┬─────┘     └──────┬──────┘    └──────┬──────┘
          │                   │                   │
          │          ┌────────▼────────┐          │
          │          │   Nacos Config  │          │
          │          │   Nacos Discovery│          │
          │          └─────────────────┘          │
          │                   │                   │
    ┌─────▼───────────────────▼───────────────────▼─────┐
    │              rui-common（通用基础层）              │
    │  core / web / security / oauth2 / mybatis / feign │
    └───────────────────────────────────────────────────┘
```

---

## 三、模块结构与端口分配

### 3.1 核心框架层

| 模块 | 类型 | 端口 | 职责 |
|------|------|------|------|
| **rui-dependencies** | BOM | - | 全局依赖版本管理（Spring Boot/Cloud/Alibaba） |
| **rui-parent** | Parent POM | - | 统一插件配置（Lombok、flatten、Spring Boot Maven） |

### 3.2 通用基础层（rui-common）

| 子模块 | 职责 | 是否已创建 |
|--------|------|-----------|
| rui-common-core | 核心工具类（Result、BaseEntity、TenantContextHolder） | ✅ |
| rui-common-mybatis | MyBatis Plus + Druid + 多租户拦截器 | ✅ |
| rui-common-security | 资源服务器配置、JWT、@Inner 注解、安全切面 | ✅ |
| rui-common-oauth2 | OAuth2 授权服务器、多种认证 Provider | ✅ |
| rui-common-web | BaseController、QueryBuilder、全局异常处理、OpenAPI | ✅ |
| rui-common-feign | Feign 增强（自动注入租户头、自定义 Registrar） | ✅ |
| rui-common-mq | MQ 抽象接口 | ✅ |
| rui-common-mq-redis | Redis 实现 MQ | ✅ |
| rui-common-mq-rabbitmq | RabbitMQ 实现 MQ | ✅ |
| rui-common-authenticator | TOTP 动态码认证 | ✅ |

### 3.3 业务服务层（rui-service）

| 服务名 | 端口 | 状态 | 职责 |
|--------|------|------|------|
| **rui-gateway** | **9300** | ✅ 已创建 | 网关（路由、灰度发布、负载均衡、日志） |
| **rui-auth** | **9301** | ✅ 已创建 | 认证授权中心（薄壳，核心逻辑在 rui-common-oauth2） |
| **rui-service-system** | **9302** | ✅ 已创建 | 系统基础服务（租户、客户端、角色/菜单/字典） |
| **rui-service-user** | **9303** | ✅ 已创建 | 用户中心服务（用户详情、等级体系、登录凭证） |
| rui-service-msg | 9304 | ⏳ 预留 | 消息通知服务（SMS/邮件/站内信/App推送） |
| rui-service-file | 9305 | ⏳ 预留 | 文件存储服务（OSS/本地存储） |
| rui-service-order | 9306 | ⏳ 预留 | 订单服务 |
| rui-service-pay | 9307 | ⏳ 预留 | 支付服务（支付通道、回调、对账） |
| rui-service-search | 9308 | ⏳ 预留 | 搜索服务（Elasticsearch 封装） |
| rui-service-cache | 9309 | ⏳ 预留 | 缓存服务（Redis 分布式锁等封装） |
| rui-service-log | 9310 | ⏳ 预留 | 日志收集服务（ELK 集成） |
| rui-service-monitor | 9311 | ⏳ 预留 | 监控告警服务（Micrometer/Prometheus） |

---

## 四、核心业务流

### 4.1 认证授权流程（OAuth2）

```
┌─────────────┐     POST /auth/oauth2/token      ┌──────────────┐
│   客户端    │ ────────────────────────────────> │  rui-auth    │
│  (前端/App) │                                   │    :9301     │
└─────────────┘                                   └──────┬───────┘
                                                         │
                                    1. 获取客户端信息    │
                                    (ClientInnerController)
                                    :9302 /system/inner/client/*
                                                         │
                                    2. 获取用户信息      │
                                    (UserInnerController)
                                    :9303 /user/inner/auth/*
                                                         │
                                                         ▼
                                    3. 生成 JWT Token
                                    (RuiTokenCustomizer)
                                    存储到 Redis
                                                         │
                                                         ▼
┌─────────────┐     返回 Token      ┌──────────────┐
│   客户端    │ <────────────────── │  rui-auth    │
└─────────────┘                     └──────────────┘
```

**支持的认证方式**：
- `password` — 用户名密码
- `sms` — 短信验证码
- `weixin` — 微信登录
- `alipay` — 支付宝登录
- `client_credentials` — 客户端凭证
- `refresh_token` — 刷新令牌

### 4.2 资源访问流程

```
┌─────────────┐     携带 Token      ┌──────────────┐     路由      ┌──────────────┐
│   客户端    │ ──────────────────> │ rui-gateway  │ ───────────> │ 业务服务      │
└─────────────┘                     │    :9300     │              │ :9302/9303+   │
                                    └──────┬───────┘              └──────┬───────┘
                                           │                            │
                                    灰度路由决策                     资源服务器校验
                                    (权重/用户/IP/Header)            (JWT 验证)
                                           │                            │
                                    内部请求头清洗                     @Inner 校验
                                    (INTERNAL_REQUEST)                (SecurityInnerAspect)
```

### 4.3 内部服务调用流程（Feign）

```
业务服务 A                                    业务服务 B
   │                                             │
   │  Feign 调用                                 │
   │ ──────────────────────────────────────────> │
   │                                             │
   │  自动注入 Header                            │
   │  - Authorization (OAuth2 Token)            │
   │  - INTERNAL_REQUEST: INTERNAL              │
   │  - X-Tenant-Id (租户ID)                    │
   │                                             │
   │  通过 @Inner 注解校验                      │
   │  (SecurityInnerAspect)                     │
   │                                             │
   │  返回 Result<T>                            │
   │ <────────────────────────────────────────── │
   │                                             │
   │  Remote 服务层解包                         │
   │  (转换为具体类型)                          │
```

---

## 五、现有规范清单

### 5.1 编码规范

| # | 规范项 | 要求 | 是否加入规则 |
|---|--------|------|------------|
| 1 | 文档语言 | 所有文档、注释必须使用中文 | ✅ 已规则化（AGENTS.md） |
| 2 | 标识符 | 类名/方法名/变量名使用英文 | ✅ 已规则化 |
| 3 | JDK | 21（强制） | ✅ 已规则化 |
| 4 | Lombok | 强制使用，禁止手写 getter/setter/builder | ✅ 已规则化 |
| 5 | 实体类 | 必须继承 BaseEntity，加 @EqualsAndHashCode(callSuper = true) | ✅ 已规则化 |
| 6 | Service 注入 | 构造器注入（private final + 构造器） | ✅ 已规则化 |
| 7 | 类名前缀 | 不加 Rui 前缀，除非与框架类冲突 | ✅ 已规则化 |
| 8 | 版本管理 | 统一使用 ${revision} + flatten-maven-plugin | ✅ 已规则化 |
| 9 | 代码注释 | 所有代码注释使用中文 | ❌ **建议加入规则** |

### 5.2 Feign 规范

| # | 规范项 | 要求 | 是否加入规则 |
|---|--------|------|------------|
| 1 | contextId | 必须使用，隔离 Bean 命名空间 | ✅ 已规则化 |
| 2 | 服务名 | value = "${feign.providers.xxx:默认名}" 外部化 | ✅ 已规则化 |
| 3 | 返回值 | Inner API 统一返回 Result<T> | ✅ 已规则化 |
| 4 | 注册方式 | META-INF/spring.factories 注册 CloudFeignAutoConfiguration | ✅ 已规则化 |
| 5 | 调用头 | @Headers("INTERNAL_REQUEST: INTERNAL") 自动注入 | ✅ 已规则化 |
| 6 | 解包方式 | Remote 服务层解包并转换 | ✅ 已规则化 |
| 7 | 降级处理 | 禁止使用 fallback/fallbackFactory，Remote 层 try-catch | ✅ 已规则化 |

### 5.3 URL 路由规范

| # | 规范项 | 要求 | 是否加入规则 |
|---|--------|------|------------|
| 1 | 格式 | /{模块}/{目录层级...}/{功能}/{方法} | ✅ 已规则化 |
| 2 | 模块位置 | 模块标识在最前（方便网关路由） | ✅ 已规则化 |
| 3 | 内部标识 | 内部接口统一使用 /inner | ✅ 已规则化 |
| 4 | 网关配置 | 网关只需配置 /{模块}/** | ✅ 已规则化 |

### 5.4 Controller 分类规范

| 控制器命名 | 路径前缀 | 认证要求 | 用途 | 是否加入规则 |
|-----------|---------|---------|------|------------|
| XxxController | /{模块}/{功能}/** | 需认证 | 常规业务接口 | ✅ 已规则化 |
| XxxEntryController | /{模块}/entry/** | 免认证 | 对外入口（注册、登录前） | ✅ 已规则化 |
| XxxNotifyController | /{模块}/notify/** | 免认证 | 第三方回调（支付、Webhook） | ✅ 已规则化 |
| XxxInnerController | /{模块}/inner/** | @Inner 控制 | 内部 Feign 调用 | ✅ 已规则化 |

### 5.5 数据库规范

| # | 规范项 | 要求 | 是否加入规则 |
|---|--------|------|------------|
| 1 | 实体基类 | 继承 BaseEntity（含 id, createTime, updateTime, tenantId, deleted） | ✅ 已实现 |
| 2 | 多租户 | 使用 MyBatis Plus 多租户拦截器（TenantLineInnerInterceptor） | ✅ 已实现 |
| 3 | 逻辑删除 | 使用 @TableLogic 注解，字段名 deleted | ✅ 已实现 |
| 4 | 自动填充 | 使用 MetaObjectHandler 自动填充创建/更新时间 | ✅ 已实现 |
| 5 | 表命名 | 统一前缀 rui_{模块}_{表名}（如 rui_user_credential） | ⚠️ **建议规则化** |
| 6 | 字段命名 | 下划线命名，主键 id，租户 tenant_id | ⚠️ **建议规则化** |
| 7 | SQL 防注入 | 启用 BlockAttackInnerInterceptor（防全表更新/删除） | ✅ 已实现 |

### 5.6 Git 规范

| # | 规范项 | 要求 | 是否加入规则 |
|---|--------|------|------------|
| 1 | 自动提交 | 每次修改后自动 git commit，不推送 | ✅ 已规则化 |
| 2 | 推送时机 | 由用户提示或累积多次提交后统一推送 | ✅ 已规则化 |
| 3 | 忽略目录 | app/、config/ 加入 .gitignore | ✅ 已规则化 |
| 4 | 提交信息 | 使用中文描述，格式：type(scope): 描述 | ❌ **建议加入规则** |
| 5 | 分支策略 | main 为主分支，功能分支开发 | ❌ **建议加入规则** |

### 5.7 Maven 规范

| # | 规范项 | 要求 | 是否加入规则 |
|---|--------|------|------------|
| 1 | 版本管理 | ${revision} + flatten-maven-plugin | ✅ 已规则化 |
| 2 | 版本发布 | mvn deploy -Drevision=x.x.x | ✅ 已规则化 |
| 3 | 正式仓库 | https://maven.dev.vifo.cc/repository/maven-releases/ | ✅ 已规则化 |
| 4 | 快照仓库 | https://maven.dev.vifo.cc/repository/maven-snapshots/ | ✅ 已规则化 |
| 5 | 依赖引入 | 版本在 rui-dependencies 中统一管理 | ✅ 已规则化 |
| 6 | relativePath | 子模块必须指定 relativePath 指向 rui-parent | ✅ 已实现 |

### 5.8 配置中心规范（Nacos）

| # | 规范项 | 要求 | 是否加入规则 |
|---|--------|------|------------|
| 1 | 配置拆分 | 每个服务独立 Data ID（rui-{服务名}.yaml） | ✅ 已实现 |
| 2 | 共享配置 | rui-common.yaml 存放全局配置 | ✅ 已实现 |
| 3 | 数据库配置 | rui-data.yaml 存放 MySQL/Druid/MyBatis 配置 | ✅ 已实现 |
| 4 | 端口配置 | 每个服务配置在各自 Nacos 配置文件中 | ✅ 已实现 |
| 5 | 灰度配置 | 在 rui-gateway.yaml 中配置 grayscale.rules | ✅ 已实现 |
| 6 | 配置推送 | 使用 push-nacos-config.sh 统一推送 | ✅ 已实现 |

---

## 六、推荐修改项

### 6.1 高优先级（建议立即修改）

| # | 修改项 | 当前问题 | 修改建议 |
|---|--------|---------|---------|
| 1 | **rui-auth 过于单薄** | 仅 2 个 Java 文件（启动类 + 配置类） | 将 AuthServerConfig 下沉到 rui-common-oauth2，或补充 Token 管理、Session 管理等接口 |
| 2 | **rui-service-system 不完整** | 仅 4 个文件，无完整 Controller/Service/Mapper | 尽快补齐租户管理、菜单/角色/字典的 CRUD 接口 |
| 3 | **Mapper XML 缺失** | 全局未找到 .xml Mapper 文件 | 确认是否全注解 SQL（当前 JdbcTemplate 直接写 SQL），建议补充 MyBatis Plus 的 Mapper 接口 |
| 4 | **rui-dependencies 中声明了未存在的模块** | rui-common-mq-mqtt 在 BOM 中声明但目录不存在 | 删除该声明或创建对应模块 |
| 5 | **自动配置注册方式不统一** | 部分模块使用 spring.factories，部分未注册 | 统一使用 META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports |
| 6 | **BaseController 字段反射注入** | bindCurrentUser 使用反射调用 setter | 改用 MetaObjectHandler 统一处理，或使用构造器注入 |
| 7 | **文档术语不统一** | docs/spring-rui 代码分析报告.md 提到 R<T>，实际代码使用 Result<T> | 统一术语，删除或更新旧文档 |

### 6.2 中优先级（近期完善）

| # | 修改项 | 当前问题 | 修改建议 |
|---|--------|---------|---------|
| 1 | **单元测试缺失** | 未见到 src/test/java 目录 | 补充 JUnit 5 + Mockito 测试框架，编写基础单元测试 |
| 2 | **日志追踪缺失** | 无 TraceID 链路追踪 | 引入 MDC + TraceID 过滤器，实现请求全链路追踪 |
| 3 | **QueryBuilder 区间查询弱** | putBetween 仅支持字符串拼接 | 支持日期/数字区间查询，前端传递 JSON 格式查询条件 |
| 4 | **MybatisProperties 利用率低** | 已定义配置但 TenantHandler 仍部分硬编码 | 完全配置驱动，租户字段名、逻辑删除字段名均可配置 |
| 5 | **灰度负载均衡缺少降级计数** | 灰度实例不可用时直接回退稳定实例 | 增加灰度实例健康检查，记录降级次数和比例 |
| 6 | **app/ 目录验证** | .gitignored，当前为空 | 按 docs/业务应用模块创建规则.md 创建示例模块（如 rui-payment），验证规范可行性 |

### 6.3 低优先级（按需实施）

| # | 修改项 | 当前问题 | 修改建议 |
|---|--------|---------|---------|
| 1 | **分布式链路追踪** | 无 SkyWalking / Micrometer Tracing | 引入 Micrometer Tracing + Brave 实现链路追踪 |
| 2 | **监控告警模块** | Nacos 有配置占位，backend 无代码 | 集成 Micrometer + Prometheus，或接入 Sentinel Dashboard |
| 3 | **工具类补齐** | 部分通用工具可能缺失 | 移植 SpringUtil、JsonUtil、IdWorker 等工具类到 rui-common-core |
| 4 | **缓存抽象层** | Redis 使用直接，无统一缓存接口 | 在 rui-common-core 中定义 CacheManager 接口，支持多级缓存 |
| 5 | **限流降级** | 缺少统一限流策略 | 在网关层集成 Sentinel，或基于 Redis 实现分布式限流 |

---

## 七、缺少的专业结构

### 7.1 必须补充的结构

| 结构 | 缺失模块 | 重要性 | 实施建议 |
|------|---------|--------|---------|
| **完整的 rui-service-system** | rui-service-system | 🔴 高 | 补充 SystemTenant、SystemMenu、SystemRole、SystemDict、SystemConfig 的 Entity、Mapper、Service、Controller |
| **Mapper 接口层** | rui-service-user、rui-service-system | 🔴 高 | 为所有 Entity 创建 Mapper 接口，继承 BaseMapper，使用 @Mapper 注解 |
| **单元测试目录** | 所有模块 | 🔴 高 | 创建 src/test/java 和 src/test/resources，编写至少一个示例测试类 |
| **自动配置注册** | rui-common-* 模块 | 🟡 中 | 每个模块创建 META-INF/spring/org.springframework.boot.autoconfigure.AutoConfiguration.imports |
| **业务应用示例模块** | app/ 目录 | 🟡 中 | 创建 rui-payment-api/common/core/provider/task 示例，验证业务模块创建规则 |

### 7.2 建议补充的结构

| 结构 | 说明 | 重要性 | 实施建议 |
|------|------|--------|---------|
| **API 文档自动生成** | OpenAPI/SpringDoc 已集成，但未统一配置 | 🟡 中 | 统一配置 API 文档标题、版本、鉴权方式，生成在线文档 |
| **数据库变更管理** | 缺少 Flyway/Liquibase | 🟡 中 | 引入 Flyway 管理数据库版本，脚本放在 src/main/resources/db/migration/ |
| **代码质量检查** | 缺少 Checkstyle/SpotBugs | 🟢 低 | 配置 Checkstyle 规则，集成到 Maven 构建流程 |
| **Docker 支持** | 缺少 Dockerfile / docker-compose | 🟢 低 | 为每个服务创建 Dockerfile，提供 docker-compose.yml 本地开发环境 |
| **Kubernetes 配置** | 缺少 K8s YAML | 🟢 低 | 提供基础的 Deployment、Service、ConfigMap 模板 |
| **SonarQube 集成** | 缺少代码质量扫描 | 🟢 低 | 配置 SonarQube 扫描，设置质量门禁 |

---

## 八、新规范建议（需加入 AGENTS.md）

### 8.1 建议立即加入的规则

```markdown
## 数据库规范

- **表命名**: 统一前缀 `rui_{模块}_{表名}`，如 `rui_user_credential`
- **字段命名**: 下划线命名法，主键 `id`，租户 `tenant_id`，逻辑删除 `deleted`
- **实体类**: 必须继承 `BaseEntity`，使用 `@TableName` 指定表名
- **Mapper**: 必须继承 `BaseMapper<Entity>`，使用 `@Mapper` 注解
- **SQL**: 优先使用 MyBatis Plus 条件构造器，复杂 SQL 使用 XML 或 @Select

## Git 提交规范

- **格式**: `type(scope): 中文描述`
- **type**: feat/fix/docs/style/refactor/test/chore
- **示例**: `feat(user): 添加用户等级查询接口`
- **要求**: 每次提交原子性，不混合多个功能修改

## 代码注释规范

- **语言**: 所有注释使用中文
- **类注释**: 说明类的作用、作者、创建日期
- **方法注释**: 说明方法用途、参数、返回值
- **复杂逻辑**: 必须添加行内注释说明业务意图

## 接口版本规范

- **REST API**: 对外接口建议添加版本前缀，如 `/v1/user/info`
- **兼容性**: 重大变更升级版本号，保持向后兼容
```

### 8.2 建议后续加入的规则

```markdown
## 测试规范

- **覆盖率**: 核心业务逻辑覆盖率不低于 80%
- **测试类型**: 单元测试（JUnit 5 + Mockito）+ 集成测试（@SpringBootTest）
- **命名**: 测试类以 Test 结尾，测试方法以 should_ 开头

## 日志规范

- **级别**: DEBUG（开发调试）、INFO（业务流水）、WARN（可恢复异常）、ERROR（严重错误）
- **格式**: 包含 TraceID、用户ID、操作类型、耗时
- **禁止**: 禁止输出密码、Token、身份证号等敏感信息

## 异常处理规范

- **自定义异常**: 业务异常统一继承 BizException
- **错误码**: 统一错误码规范，按模块分配区间
- **全局处理**: 通过 GlobalExceptionHandler 统一处理，不遗漏异常
```

---

## 九、Nacos 配置清单（已推送）

| Data ID | 服务 | 端口 | 状态 |
|---------|------|------|------|
| rui-common.yaml | 全局共享 | - | ✅ |
| rui-data.yaml | DB 模块共享 | - | ✅ |
| rui-gateway.yaml | 网关 | 9300 | ✅ |
| rui-auth.yaml | 认证中心 | 9301 | ✅ |
| rui-service-system.yaml | 系统服务 | 9302 | ✅ |
| rui-service-user.yaml | 用户服务 | 9303 | ✅ |
| rui-service-msg.yaml | 消息服务 | 9304 | ⏳ 预留 |
| rui-service-file.yaml | 文件服务 | 9305 | ⏳ 预留 |
| rui-service-order.yaml | 订单服务 | 9306 | ⏳ 预留 |
| rui-service-pay.yaml | 支付服务 | 9307 | ⏳ 预留 |
| rui-service-search.yaml | 搜索服务 | 9308 | ⏳ 预留 |
| rui-service-cache.yaml | 缓存服务 | 9309 | ⏳ 预留 |
| rui-service-log.yaml | 日志服务 | 9310 | ⏳ 预留 |
| rui-service-monitor.yaml | 监控服务 | 9311 | ⏳ 预留 |

---

## 十、后续实施路线图

### Phase 1：基础完善（1-2 周）

1. ✅ 补齐 rui-service-system 的完整 CRUD
2. ✅ 为所有 Entity 补充 Mapper 接口
3. ✅ 统一自动配置注册方式
4. ✅ 补充单元测试基类和示例
5. ✅ 创建 app/ 目录示例模块

### Phase 2：功能增强（2-4 周）

1. 引入日志链路追踪（TraceID）
2. 完善 QueryBuilder 区间查询
3. 补充 API 文档自动生成配置
4. 引入 Flyway 数据库版本管理
5. 完善灰度发布的降级策略

### Phase 3：生产就绪（4-6 周）

1. 引入分布式链路追踪（SkyWalking/Micrometer）
2. 完善监控告警模块
3. 配置 Docker 和 docker-compose
4. 集成 SonarQube 代码质量检查
5. 编写完整的运维部署文档

---

> **文档版本**: v1.0
> **创建日期**: 2026-05-28
> **适用范围**: rui-framework 项目及后续同类项目
> **维护方式**: 随项目实施迭代更新