rui/rui-docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: 迁移 spring-ai 通用文档到 rui-docs

Browse Source 
从 docs-local 迁移以下文档：

- backend/guides/: AI开发环境配置、Nacos配置、GitNexus指南、OpenCode工作流等

- backend/templates/: Superpowers设计模板、计划模板、审查清单

- backend/config-templates/: 应用配置模板、Nacos配置

- backend/design/: 数据库表结构规划

- backend/specs/: 项目文档治理、MQ统一推送设计

- backend/: 代码分析报告、Feign分析报告、文档治理报告

- frontend/design/: Admin-UI分模块打包设计
This commit is contained in:
pigeon
2026-06-04 09:31:24 +08:00
parent 2e38c53434
commit 19de7e24ec
36 changed files with 5872 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
backend/specs/2026-06-02-项目文档治理与Superpowers流程规范化-design.md
+587
View File
@@ -0,0 +1,587 @@
# 项目文档治理与 Superpowers 流程规范化
> **设计日期**: 2026-06-02
> **版本**: v1.0
> **状态**: 已批准（待实施）
> **目标**: 建立完整的项目文档体系，将 Superpowers 工作流融入项目规范
---
## 一、项目背景
### 1.1 现状分析
当前项目（睿核科技 - rui）是一个基于 Spring Cloud 的微服务通用平台框架，已开发支付模块（rui-payment）等业务模块。项目文档和代码规范主要维护在 `AGENTS.md` 中。
### 1.2 存在的问题
通过对现有 `AGENTS.md`（668 行）和项目文档体系的分析，发现以下 **7 类问题**：
| 问题类型 | 具体表现 | 影响 |
|---------|---------|------|
| **结构混乱** | 规范、指南、规则混杂，无清晰层级 | 查找信息困难，新成员上手慢 |
| **缺少导航** | 无目录、无文档地图 | 无法快速定位需要的规范 |
| **Superpowers 缺失** | 完全没有工作流说明 | 团队无法按标准流程协作 |
| **格式错误** | 多处 `**` 标记不匹配、表格格式问题 | 阅读体验差，可能误解 |
| **内容缺失** | 无环境搭建指南、无模块创建指引、无代码审查规范 | 新人无法自助上手 |
| **职责越界** | GitNexus 工具配置与项目规范混在一起 | 文档职责不清晰 |
| **信息孤岛** | 未引用 `docs/` 下的其他文档 | 文档之间无关联 |
### 1.3 目标定义
1. **建立标准**：重构 AGENTS.md，使其成为项目的"宪法"
2. **查漏补缺**：系统检查现有文档和代码，生成分类问题清单
3. **融入流程**：将 Superpowers 工作流融入项目规范
4. **持续可用**：建立可复用的模板和检查清单
---
## 二、整体工作流设计
采用 **三阶段流水线**，每阶段都有明确的输入、输出和验收标准：
```
┌─────────────────────────────────────────────────────────────────┐
│ 阶段一：重构 AGENTS.md（建立标准） │
│ 输入：现有 AGENTS.md + 项目文档体系 │
│ 输出：新版 AGENTS.md（项目宪法） │
│ 验收：文档结构清晰、规范完整、Superpowers 流程融入 │
└───────────────────────────┬─────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ 阶段二：全面查漏补缺（基于标准） │
│ 输入：新版 AGENTS.md + 现有项目所有文档和代码 │
│ 输出：分类问题清单（高/中/低优先级） │
│ 验收：检查覆盖率 100%、问题可追踪、有优先级 │
└───────────────────────────┬─────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ 阶段三：修复与规范化（建立流程） │
│ 输入：问题清单 │
│ 输出：修复后的文档/代码 + Superpowers 工作流模板 + 改进报告 │
│ 验收：高优先级问题全部修复、流程可运行、报告完整 │
└─────────────────────────────────────────────────────────────────┘
```
---
## 三、阶段一：重构 AGENTS.md
### 3.1 现有文档诊断
**格式问题清单**：
- 第 173 行：`SecurityUtils` 后的 `**` 未闭合
- 第 176-178 行：多处 `**` 标记不匹配
- 表格格式在部分终端渲染异常
**内容缺失清单**：
- 缺少项目级 README.md
- 缺少开发环境搭建指南
- 缺少 Superpowers 工作流说明
- 缺少代码审查规范
- 缺少模块创建标准流程
**结构问题清单**：
- 无文档地图/目录
- GitNexus 配置与项目规范混杂
- 章节间无逻辑递进关系
### 3.2 新版结构设计
```
AGENTS.md（项目宪法 - 所有开发者必读）
├── 1. 文档地图（新增）← 60秒了解项目文档体系
├── 2. 项目概览（精简）← 技术栈、仓库结构
├── 3. 环境准备（新增）← 开发环境、初始化步骤
├── 4. Superpowers 工作流（新增）← 四阶段开发流程
├── 5. 编码规范（合并优化）← 所有代码规范集中
├── 6. 基础设施速查（优化）← 工具类、注解、复用原则
├── 7. 模块开发指南（新增）← 如何创建标准业务模块
├── 8. 运维规范（合并）← Git、数据库、Nacos、构建
├── 9. 协作规范（优化）← 对话管理、工作边界
└── 10. 附录（新增）← 错误码、数据类型、文档索引
```
### 3.3 章节详细设计
#### 第 1 章：文档地图（新增）
目标：让新成员在 60 秒内了解项目文档体系
内容：
- 文档体系全景图
- 快速导航（按角色：新手/开发者/架构师）
- 文档更新规则（谁维护、何时更新）
#### 第 2 章：项目概览（精简现有内容）
保留：
- 项目名称、类型
- 精简版仓库结构（突出 app/ 和 backend/）
- 技术栈表格
移除：
- 过详细的技术说明（迁移到专门文档）
#### 第 3 章：环境准备（新增）
内容：
- 开发环境要求（JDK 21、Maven、MySQL、Node.js 等）
- 项目初始化步骤（clone → 配置 → 构建 → 运行）
- IDE 配置建议（IntelliJ IDEA 插件、代码风格）
- 验证清单（如何确认环境就绪）
#### 第 4 章：Superpowers 工作流（新增）
核心内容，四阶段流程：
**Phase 1: Brainstorming（头脑风暴）**
- 目标：明确需求、确定方案
- 输入：用户原始需求
- 输出：批准的设计方向
- 检查清单：
- [ ] 是否已探索项目上下文？
- [ ] 是否已提出澄清问题？
- [ ] 是否已对比 2-3 种方案？
- [ ] 用户是否已确认方向？
**Phase 2: Spec Writing（规格编写）**
- 目标：编写详细设计文档
- 输入：批准的设计方向
- 输出：设计文档（保存到 `docs/superpowers/specs/`）
- 检查清单：
- [ ] 是否包含背景与目标？
- [ ] 是否包含详细设计？
- [ ] 是否包含验收标准？
- [ ] 是否已完成自我审查？
- [ ] 用户是否已审查批准？
**Phase 3: Plan Writing（计划编写）**
- 目标：编写可执行的实施计划
- 输入：批准的设计文档
- 输出：实施计划（保存到 `docs/superpowers/plans/`）
- 检查清单：
- [ ] 是否已分解为具体任务？
- [ ] 每个任务是否有明确的验收标准？
- [ ] 是否有风险评估？
- [ ] 用户是否已审查批准？
**Phase 4: Implementation（实施执行）**
- 目标：按计划执行任务
- 输入：实施计划
- 输出：代码 + 文档更新
- 检查清单：
- [ ] 是否按任务逐个执行？
- [ ] 每个任务是否已完成验证？
- [ ] 是否已更新实施跟踪文档？
- [ ] 是否已完成最终审查？
#### 第 5 章：编码规范（合并优化现有章节）
合并内容：
- 基础编码规范（Lombok、命名、注释）
- 模块 Bean 注入规范
- Mapper 规范
- Controller 规范
- URL 路由规范
- 异常处理规范
- 日志规范
- 测试规范
优化点：
- 统一用表格展示"正确 vs 错误"示例
- 增加常见错误模式说明
- 增加检查工具建议（如 Checkstyle 规则）
#### 第 6 章：基础设施速查（优化）
优化内容：
- 工具类速查表（增加使用场景列）
- 注解速查表（增加参数说明）
- 复用原则（增加反例说明）
#### 第 7 章：模块开发指南（新增）
内容：
- 何时需要新建模块
- 模块命名规范
- 模块标准结构（common/core/provider/api/task）
- 创建步骤清单
- AutoConfiguration 配置
- 模块间依赖规则
#### 第 8 章：运维规范（合并现有章节）
合并内容：
- Git 提交规范
- 数据库脚本执行规则
- Nacos 配置管理规则
- 构建与发布规范
- 前端构建规则
#### 第 9 章：协作规范（优化现有章节）
优化内容：
- OpenCode `/new` 使用指南（增加决策树）
- 工作边界规则（增加流程图）
- 框架问题处理流程（增加模板）
#### 第 10 章：附录（新增）
内容：
- 错误码分配表（完整区间划分）
- 数据类型对照表（MySQL ↔ Java ↔ JDBC）
- 相关文档索引（docs/ 下所有文档的导航）
- 术语表
### 3.4 职责分离
**GitNexus 配置迁移**：
将 AGENTS.md 中的 GitNexus 部分（第 626-668 行）迁移到独立文档：`docs/gitnexus-guide.md`
原因：
- AGENTS.md 是"项目规范"，GitNexus 是"工具配置"
- 职责分离后，AGENTS.md 更聚焦
- GitNexus 指南可以独立更新
---
## 四、阶段二：全面查漏补缺
### 4.1 检查策略
基于新版 AGENTS.md 的 10 个章节，设计 **4 维度检查清单**：
#### 维度一：文档体系完整性（检查 `docs/` 目录）
| 检查项 | 检查内容 | 优先级 | 当前状态 |
|--------|---------|--------|---------|
| 1.1 | 是否存在 `README.md` 项目总览 | 🔴 高 | ❌ 缺失 |
| 1.2 | 每个业务模块是否有独立设计文档 | 🔴 高 | ⚠️ 仅支付模块有 |
| 1.3 | 是否存在环境搭建指南 | 🔴 高 | ❌ 缺失 |
| 1.4 | 是否存在数据库变更记录 | 🟡 中 | ❌ 缺失 |
| 1.5 | API 文档是否完整 | 🟡 中 | 待确认 |
| 1.6 | 文档之间是否有交叉引用 | 🟡 中 | ❌ 无引用 |
| 1.7 | 实施跟踪文档是否最新 | 🟢 低 | ⚠️ 支付模块显示完成 |
#### 维度二：AGENTS.md 规范落地（检查代码库）
| 检查项 | 检查内容 | 优先级 | 检查方式 |
|--------|---------|--------|---------|
| 2.1 | 所有 Entity 是否继承 BaseEntity | 🔴 高 | 代码扫描 |
| 2.2 | 是否使用 Lombok | 🔴 高 | 代码扫描 |
| 2.3 | Service 是否使用构造器注入 | 🔴 高 | 代码扫描 |
| 2.4 | Mapper SQL 是否使用 `#prefix#` | 🔴 高 | 正则匹配 |
| 2.5 | Controller 是否按规范分类 | 🟡 中 | 目录检查 |
| 2.6 | 标准 CRUD 是否继承 BaseController | 🟡 中 | 代码扫描 |
| 2.7 | 异常处理是否统一用 BizException | 🟡 中 | 代码扫描 |
| 2.8 | Git 提交是否符合规范格式 | 🟢 低 | 提交历史检查 |
#### 维度三：项目结构与配置
| 检查项 | 检查内容 | 优先级 | 当前状态 |
|--------|---------|--------|---------|
| 3.1 | 模块命名是否符合规范 | 🔴 高 | ✅ 符合 |
| 3.2 | 每个模块是否有 AutoConfiguration | 🔴 高 | 待确认 |
| 3.3 | `application-dev.yml` 是否在 `.gitignore` | 🔴 高 | ✅ 符合 |
| 3.4 | Nacos 配置是否已推送 | 🟡 中 | 待确认 |
| 3.5 | 数据库脚本是否已执行 | 🟡 中 | 待确认 |
#### 维度四：Superpowers 流程就绪度
| 检查项 | 检查内容 | 优先级 | 当前状态 |
|--------|---------|--------|---------|
| 4.1 | 是否存在 `docs/superpowers/` 目录 | 🔴 高 | ❌ 缺失 |
| 4.2 | 是否存在设计文档模板 | 🔴 高 | ❌ 缺失 |
| 4.3 | 是否存在实施计划模板 | 🔴 高 | ❌ 缺失 |
| 4.4 | 是否存在代码审查清单 | 🟡 中 | ❌ 缺失 |
### 4.2 输出格式
每个问题按以下格式记录：
```markdown
### 🔴 HIGH-001: 缺少 README.md
| 属性 | 内容 |
|------|------|
| **检查项** | 文档体系完整性 - 1.1 |
| **问题描述** | 项目根目录缺少 README.md，新成员无法快速了解项目 |
| **影响范围** | 所有新加入的开发者 |
| **建议修复** | 创建 README.md，包含项目简介、技术栈、快速开始、文档索引 |
| **参考标准** | AGENTS.md 第 1 章 |
| **优先级** | 🔴 高 |
```
### 4.3 问题分类与优先级
**优先级定义**：
| 优先级 | 定义 | 修复时限 |
|--------|------|---------|
| 🔴 高 | 阻碍开发或违反核心规范 | 立即修复 |
| 🟡 中 | 影响效率或存在风险 | 1 周内修复 |
| 🟢 低 | 优化建议 | 下次迭代处理 |
---
## 五、阶段三：修复与规范化
### 5.1 修复计划（按优先级）
#### 🔴 高优先级（必须立即修复）
| 序号 | 任务 | 输出物 | 验收标准 |
|------|------|--------|---------|
| H1 | 创建 README.md | `/README.md` | 包含项目简介、技术栈、快速开始、文档索引 |
| H2 | 重构 AGENTS.md | `/AGENTS.md` | 10 章结构完整、格式正确、无遗漏 |
| H3 | 创建 Superpowers 目录结构 | `docs/superpowers/` | 目录存在且结构正确 |
| H4 | 创建设计文档模板 | `docs/superpowers/templates/design-template.md` | 包含所有必需章节 |
| H5 | 创建实施计划模板 | `docs/superpowers/templates/plan-template.md` | 包含任务分解和验收标准 |
| H6 | 迁移 GitNexus 指南 | `docs/gitnexus-guide.md` | 内容完整、AGENTS.md 中已移除 |
#### 🟡 中优先级（建议 1 周内修复）
| 序号 | 任务 | 输出物 | 验收标准 |
|------|------|--------|---------|
| M1 | 补充环境搭建指南 | `docs/environment-setup.md` | 步骤可执行、有验证方法 |
| M2 | 创建代码审查清单 | `docs/superpowers/templates/review-checklist.md` | 覆盖主要规范点 |
| M3 | 检查模块 AutoConfiguration | 代码修复 | 每个可复用模块都有 |
| M4 | 检查 Nacos 配置同步 | 配置确认 | 所有配置已推送 |
#### 🟢 低优先级（可选优化）
| 序号 | 任务 | 输出物 | 验收标准 |
|------|------|--------|---------|
| L1 | 补充数据库变更记录 | `docs/database-changelog.md` | 记录所有表结构变更 |
| L2 | 统一文档交叉引用 | 各文档更新 | 相关文档间有链接 |
| L3 | 检查测试覆盖率 | 报告 | 核心业务覆盖 ≥ 80% |
### 5.2 Superpowers 工作流模板
#### 模板一：设计文档模板
```markdown
# <模块/功能名称> 设计文档
> **设计日期**: YYYY-MM-DD
> **版本**: v1.0
> **状态**: 设计中/已批准
> **目标**: <一句话描述目标>
---
## 一、背景与目标
### 1.1 现状分析
<描述当前现状、存在的问题>
### 1.2 目标定义
<明确本次设计的目标，建议 3-5 条>
---
## 二、详细设计
### 2.1 整体架构
<架构图、流程图>
### 2.2 核心组件
<各组件的职责、接口>
### 2.3 数据流
<数据如何流转>
### 2.4 接口设计
<API 定义>
### 2.5 数据库设计
<表结构、索引>
### 2.6 错误处理
<异常场景、错误码>
---
## 三、验收标准
- [ ] <可验证的验收条件 1>
- [ ] <可验证的验收条件 2>
- [ ] <可验证的验收条件 3>
---
## 四、风险与依赖
| 风险 | 影响 | 缓解措施 |
|------|------|---------|
| <风险 1> | 高/中/低 | <措施> |
```
#### 模板二：实施计划模板
```markdown
# <模块/功能名称> 实施计划
> **计划日期**: YYYY-MM-DD
> **版本**: v1.0
> **状态**: 待执行/执行中/已完成
> **关联设计**: <链接到设计文档>
---
## 一、任务清单
### Phase 1: <阶段名称>
| 序号 | 任务 | 负责人 | 预估工时 | 状态 | 验证方式 |
|------|------|--------|---------|------|---------|
| 1.1 | <具体任务> | <负责人> | <工时> | ⬜ | <如何验证> |
---
## 二、进度跟踪
| 日期 | 完成任务 | 遇到的问题 | 解决方案 |
|------|---------|-----------|---------|
| YYYY-MM-DD | <任务> | <问题> | <方案> |
---
## 三、完成总结
- **实际工时**: <X 小时>
- **偏差分析**: <与预估的差异及原因>
- **经验教训**: <可复用的经验>
```
#### 模板三：代码审查清单
```markdown
# 代码审查清单
## 基础规范
- [ ] 使用 Lombok，无手写 getter/setter
- [ ] Service 使用构造器注入
- [ ] Entity 继承 BaseEntity
- [ ] 类名不加 Rui 前缀（除非冲突）
## Mapper 规范
- [ ] SQL 使用 `#prefix#` 占位符
- [ ] 无硬编码表前缀
## Controller 规范
- [ ] 标准 CRUD 继承 BaseController
- [ ] URL 路径符合规范
- [ ] 使用正确注解（@Inner、@AuthIgnore 等）
## 异常与日志
- [ ] 使用 BizException 而非 RuntimeException
- [ ] 返回 Result.ok()/Result.fail()
- [ ] 日志无敏感信息
## 测试
- [ ] 核心逻辑有单元测试
- [ ] 测试命名符合规范
```
### 5.3 改进报告模板
```markdown
# 项目文档治理改进报告
> **报告日期**: YYYY-MM-DD
> **治理范围**: 项目文档体系 + AGENTS.md + Superpowers 流程
> **执行人**: <执行者>
---
## 一、检查统计
| 维度 | 检查项数 | 发现问题 | 已修复 | 待修复 |
|------|---------|---------|--------|--------|
| 文档体系完整性 | X | Y | Z | W |
| 代码规范落地 | X | Y | Z | W |
| 项目结构与配置 | X | Y | Z | W |
| Superpowers 就绪度 | X | Y | Z | W |
| **合计** | **X** | **Y** | **Z** | **W** |
## 二、问题分布
<图表或表格展示问题分布>
## 三、关键改进
1. <改进 1：重构 AGENTS.md>
2. <改进 2：建立 Superpowers 流程>
3. <改进 3：...>
## 四、后续建议
1. <建议 1>
2. <建议 2>
```
---
## 六、验收标准
### 6.1 阶段验收标准
| 阶段 | 验收标准 | 验证方式 |
|------|---------|---------|
| 阶段一 | AGENTS.md 结构清晰、内容完整、格式正确 | 人工审查 |
| 阶段二 | 检查覆盖率 100%、问题清单完整 | 逐项核对 |
| 阶段三 | 高优先级问题全部修复、模板可用 | 实际使用验证 |
### 6.2 最终验收标准
- [ ] 新成员可在 30 分钟内通过 AGENTS.md 了解项目规范
- [ ] Superpowers 四阶段流程可在项目中完整运行
- [ ] 所有文档间有交叉引用，无信息孤岛
- [ ] 代码规范有自动化检查手段（或明确的手动检查清单）
---
## 七、风险与依赖
| 风险 | 影响 | 缓解措施 |
|------|------|---------|
| 重构 AGENTS.md 期间，团队仍在开发新功能 | 中 | 使用分支管理，重构完成后再合并 |
| 检查清单不够全面，遗漏问题 | 中 | 基于 AGENTS.md 逐条设计检查项，确保覆盖 |
| 团队成员不习惯 Superpowers 流程 | 低 | 提供培训和模板，逐步推广 |
| 文档更新后无人维护 | 中 | 明确文档负责人，纳入代码审查 |
---
## 八、附录
### 8.1 术语表
| 术语 | 说明 |
|------|------|
| Superpowers | OpenCode 的规范化工作流框架 |
| Brainstorming | 头脑风暴阶段，明确需求和方案 |
| Spec | 设计文档/规格说明书 |
| AGENTS.md | 项目规范文档（项目宪法） |
### 8.2 相关文档
| 文档 | 路径 | 说明 |
|------|------|------|
| AGENTS.md | `/AGENTS.md` | 项目规范（待重构） |
| 支付模块设计 | `docs/支付模块架构设计.md` | 示例设计文档 |
| 支付模块跟踪 | `docs/支付模块实施跟踪.md` | 示例跟踪文档 |
### 8.3 参考标准
- 本设计文档本身遵循 Superpowers 流程编写
- 模板设计参考了行业最佳实践
---
> **文档结束**
> 下一步：进入实施计划阶段（由 Superpowers Plan Writer 执行）
backend/specs/2026-06-04-mq-unified-push-design.md
+236
View File
@@ -0,0 +1,236 @@
# MQ 统一推送入口设计文档
> **设计日期**: 2026-06-04
> **版本**: v1.0
> **状态**: 已批准
> **目标**: 创建统一消息队列推送入口 MqClient，封装多 Provider 路由、Action 注入、异常兜底，对标 spring-rui MqDefaultClient
---
## 一、背景与目标
### 1.1 现状分析
当前项目已有基础 MQ 能力：
- `MqService` 接口：提供 `send()` 方法，面向业务开发者直接使用
- `Message<T>` 模型：含 id, topic, payload, headers, timestamp, retryCount
- `RedisMqService` / `RabbitMqService`：分别基于 Redis Pub/Sub 和 RabbitMQ 的实现
- `MqTopic` 注解：用于方法级消息订阅
**存在的问题**：
1. 缺乏统一推送门面：业务代码需要直接注入 `MqService` 并选择实现，无法自动按 Provider 路由
2. 无 Provider 抽象：无法在多环境（开发用 Redis、生产用 RabbitMQ）间平滑切换
3. 无 Action 语义：消息缺乏"添加/删除/更新"等业务动作标识
4. 异常处理分散：各实现自行处理异常，缺乏统一兜底
### 1.2 目标定义
1. 创建 `MqClient` 门面类，作为业务层唯一推送入口
2. 引入 `MqPublisher` Provider 接口，实现多 MQ 后端自动路由
3. 扩展 `Message` 模型，支持 action、provider、exchange、delay 等高级字段
4. 保持现有 `MqService` 接口不变，确保向后兼容
5. 所有推送操作统一异常捕获和日志记录
---
## 二、详细设计
### 2.1 整体架构
```
┌─────────────────────────────────────────────────────────────┐
│ 业务层 (Business) │
│ MqClient.publish(...) │
└──────────────────────────┬──────────────────────────────────┘
│
┌──────────────────────────▼──────────────────────────────────┐
│ MqClient (门面/统一入口) │
│ · 自动从 Spring 容器获取所有 MqPublisher 实现 │
│ · 按 support(MqProvider) 过滤匹配的 Publisher │
│ · 自动注入 action 到 payload │
│ · 统一 try-catch + 日志 │
└──────────────────────────┬──────────────────────────────────┘
│
┌───────────────┼───────────────┐
▼ ▼ ▼
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ RedisMqPublisher │ │ RabbitMqPublisher│ │ FutureProvider │
│ (Redis实现) │ │ (RabbitMQ实现) │ │ (可扩展) │
└─────────────────┘ └─────────────────┘ └─────────────────┘
```
### 2.2 核心组件
| 组件 | 职责 | 位置 |
|------|------|------|
| `MqClient` | 统一推送门面，业务层唯一入口 | `rui-common-mq` |
| `MqPublisher` | Provider 能力接口，定义 support + publish | `rui-common-mq` |
| `MqProvider` | Provider 枚举（RABBITMQ, REDIS） | `rui-common-mq` |
| `MqProperties` | 配置属性（默认 provider、topic prefix） | `rui-common-mq` |
| `MqAction` | 消息动作枚举（ADDED, DELETED 等） | `rui-common-mq` |
| `Message<T>` | 扩展后的消息模型 | `rui-common-mq` |
### 2.3 数据流
```
启动阶段 (一次)
│
▼
Spring 注入 List<MqPublisher> → 遍历注册到 EnumMap
│
▼
publisherMap = { RABBITMQ: RabbitMqPublisher, REDIS: RedisMqPublisher }
运行时 (每次 publish)
│
▼
MqClient.publish(String topic, MqAction action, T payload)
│
├─ 1. 构造 Message<T>
├─ 2. 若 action != NONE，将 action 序列化后注入 payload
├─ 3. 若 message.provider == null，使用 MqProperties 默认值
├─ 4. publisherMap.get(provider) → O(1) 直接取到 Publisher
├─ 5. 调用 publisher.publish(message)
└─ 6. catch Exception → log.error，不抛异常
```
### 2.4 接口设计
**MqClient（门面类）**
采用**构造器注入 + 启动预构建 EnumMap**，避免运行时遍历：
```java
@Component
@Slf4j
public class MqClient {
private final MqProperties properties;
private final EnumMap<MqProvider, MqPublisher> publisherMap = new EnumMap<>(MqProvider.class);
public MqClient(MqProperties properties, List<MqPublisher> publishers) {
this.properties = properties;
for (MqPublisher p : publishers) {
publisherMap.put(p.getProvider(), p); // O(1) 注册
}
}
/** 使用默认 Provider 推送 */
public <T> void publish(String topic, T payload);
/** 使用默认 Provider 推送，带 Action */
public <T> void publish(String topic, MqAction action, T payload);
/** 指定 Provider 推送 */
public <T> void publish(MqProvider provider, String topic, T payload);
/** 指定 Provider 推送，带 Action */
public <T> void publish(MqProvider provider, String topic, MqAction action, T payload);
/** 完整 Message 推送 */
public <T> void publish(Message<T> message);
private MqPublisher resolve(MqProvider provider) {
return publisherMap.get(provider); // O(1) 查找
}
}
```
**MqPublisher（Provider 接口）**
```java
public interface MqPublisher {
/** 返回该 Publisher 支持的 Provider 类型 */
MqProvider getProvider();
/** 基础推送 */
<T> void publish(String topic, T payload);
/** 完整消息推送 */
<T> void publish(Message<T> message);
}
```
**MqProvider（枚举）**
```java
public enum MqProvider {
RABBITMQ,
REDIS
}
```
**MqProperties（配置）**
```java
@ConfigurationProperties(prefix = "mq")
@Data
public class MqProperties {
private MqProvider provider = MqProvider.RABBITMQ;
private String prefix = "rui";
public String enTopic(String topic) { ... }
public String deTopic(String topic) { ... }
}
```
**MqAction（动作枚举，精简版）**
```java
public enum MqAction {
NONE, ADDED, DELETED, UPDATED, CREATED,
CANCEL, ENABLED, SUCCESSFUL, FAILURE
}
```
### 2.5 扩展现有实现
**RedisMqService** 调整：
- 实现 `MqPublisher` 接口
- `support(MqProvider.REDIS)` 返回 true
- `publish()` 复用现有 `send()` 逻辑
**RabbitMqService** 调整：
- 实现 `MqPublisher` 接口
- `support(MqProvider.RABBITMQ)` 返回 true
- `publish()` 复用现有 `send()` 逻辑
### 2.6 错误处理
- **异常策略**：`MqClient` 所有 publish 方法统一 try-catch，记录 error 日志，不抛异常给业务层
- **Provider 不匹配**：若找不到支持该 Provider 的 Publisher，记录 warn 日志
- **Payload 为空**：自动创建空 JSON 对象 `{}`
---
## 三、验收标准
- [ ] `MqClient` 可正常注入并调用 `publish()` 发送消息
- [ ] 通过配置 `mq.provider=redis` 可自动切换到 Redis 实现
- [ ] `publish(topic, MqAction.ADDED, payload)` 发送的消息包含 action 字段
- [ ] 发送异常时不抛异常，仅记录日志
- [ ] 现有 `MqService.send()` 调用不受影响，向后兼容
- [ ] 项目可正常编译通过
---
## 四、风险与依赖
| 风险 | 影响 | 缓解措施 |
|------|------|---------|
| 现有 `MqService` 被多处使用 | 中 | 不修改 `MqService`，新建 `MqPublisher` 接口 |
| `Message<T>` 扩展后序列化兼容性 | 低 | 新增字段均为可空，不影响现有序列化 |
| SpringUtil 在静态方法中可能未初始化 | 低 | MqClient 通过构造器注入，非静态调用 |
---
## 五、对标分析
| 维度 | spring-rui (MqDefaultClient) | 本设计 (MqClient) |
|------|------------------------------|-------------------|
| 门面类名 | `MqDefaultClient` | `MqClient`（更简洁） |
| Provider 接口 | `MqService`（含 support/publish） | `MqPublisher`（不冲突现有 `MqService`） |
| 配置类名 | `MqAutoConfiguration` | `MqProperties`（更语义化） |
| JSON 框架 | fastjson2 | Jackson（适配本项目） |
| Provider 支持 | MQTT, RABBITMQ, REDIS | RABBITMQ, REDIS（MQTT 暂不需要） |
| Action 枚举 | `Actions`（80+ 项） | `MqAction`（精简 9 项） |
| 包名 | `org.rui.common.mq` | `com.rui.common.mq` |