Files

T

vifo a7f3ee3565 refactor: 全局替换 spring-ai -> rui-framework

同步仓库名称变更，涉及 16 个文件 66 处引用：
- ai-skills: 菜单配置
- backend/guides: AI操作手册、环境配置、部署、gitnexus、opencode 工作流
- backend: 模块创建规则、通信规范、协作工作流、实施规范
- frontend: 收银设计、管理后台实施计划
- standards: 数据库设计规范

2026-06-08 12:56:39 +08:00

24 KiB

Raw Permalink Blame History

睿核科技 (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	✅ 已规则化
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，实际代码使用 Result	统一术语，删除或更新旧文档

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 建议立即加入的规则

## 数据库规范

- **表命名**: 统一前缀 `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 建议后续加入的规则

## 测试规范

- **覆盖率**: 核心业务逻辑覆盖率不低于 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 周）

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

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

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

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

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

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

24 KiB Raw Permalink Blame History Unescape Escape

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

一、项目概述

二、项目架构图

三、模块结构与端口分配

3.1 核心框架层

3.2 通用基础层（rui-common）

3.3 业务服务层（rui-service）

四、核心业务流

4.1 认证授权流程（OAuth2）

4.2 资源访问流程

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

五、现有规范清单

5.1 编码规范

5.2 Feign 规范

5.3 URL 路由规范

5.4 Controller 分类规范

5.5 数据库规范

5.6 Git 规范

5.7 Maven 规范

5.8 配置中心规范（Nacos）

六、推荐修改项

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

6.2 中优先级（近期完善）

6.3 低优先级（按需实施）

七、缺少的专业结构

7.1 必须补充的结构

7.2 建议补充的结构

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

8.1 建议立即加入的规则

8.2 建议后续加入的规则

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

十、后续实施路线图

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

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

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

24 KiB

Raw Permalink Blame History