Files

T

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

从 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分模块打包设计

2026-06-04 09:34:03 +08:00

20 KiB

Raw Blame History

项目文档治理与 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 目标定义

建立标准：重构 AGENTS.md，使其成为项目的"宪法"
查漏补缺：系统检查现有文档和代码，生成分类问题清单
融入流程：将 Superpowers 工作流融入项目规范
持续可用：建立可复用的模板和检查清单

二、整体工作流设计

采用 三阶段流水线，每阶段都有明确的输入、输出和验收标准：

┌─────────────────────────────────────────────────────────────────┐
│  阶段一：重构 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 输出格式

每个问题按以下格式记录：

### 🔴 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 工作流模板

模板一：设计文档模板

# <模块/功能名称> 设计文档

> **设计日期**: 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> | 高/中/低 | <措施> |

模板二：实施计划模板

# <模块/功能名称> 实施计划

> **计划日期**: YYYY-MM-DD  
> **版本**: v1.0  
> **状态**: 待执行/执行中/已完成  
> **关联设计**: <链接到设计文档>

---

## 一、任务清单

### Phase 1: <阶段名称>

| 序号 | 任务 | 负责人 | 预估工时 | 状态 | 验证方式 |
|------|------|--------|---------|------|---------|
| 1.1 | <具体任务> | <负责人> | <工时> | ⬜ | <如何验证> |

---

## 二、进度跟踪

| 日期 | 完成任务 | 遇到的问题 | 解决方案 |
|------|---------|-----------|---------|
| YYYY-MM-DD | <任务> | <问题> | <方案> |

---

## 三、完成总结

- **实际工时**: <X 小时>
- **偏差分析**: <与预估的差异及原因>
- **经验教训**: <可复用的经验>

模板三：代码审查清单

# 代码审查清单

## 基础规范
- [ ] 使用 Lombok，无手写 getter/setter
- [ ] Service 使用构造器注入
- [ ] Entity 继承 BaseEntity
- [ ] 类名不加 Rui 前缀（除非冲突）

## Mapper 规范
- [ ] SQL 使用 `#prefix#` 占位符
- [ ] 无硬编码表前缀

## Controller 规范
- [ ] 标准 CRUD 继承 BaseController
- [ ] URL 路径符合规范
- [ ] 使用正确注解（@Inner、@AuthIgnore 等）

## 异常与日志
- [ ] 使用 BizException 而非 RuntimeException
- [ ] 返回 Result.ok()/Result.fail()
- [ ] 日志无敏感信息

## 测试
- [ ] 核心逻辑有单元测试
- [ ] 测试命名符合规范

5.3 改进报告模板

# 项目文档治理改进报告

> **报告日期**: 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 执行）

20 KiB Raw Blame History Unescape Escape