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/guides/AI开发环境配置手册.md
+388
View File
@@ -0,0 +1,388 @@
# AI 开发环境配置手册
> **适用对象**: 业务模块开发者（支付、收银台等）
> **版本**: v1.0
> **更新日期**: 2026-06-03
---
## 目录
1. [概述](#一概述)
2. [环境准备](#二环境准备)
3. [仓库克隆与配置](#三仓库克隆与配置)
4. [GitNexus 索引配置](#四gitnexus-索引配置)
5. [AI 开发工作流](#五ai-开发工作流)
6. [常见问题](#六常见问题)
---
## 一、概述
### 1.1 背景
项目已拆分为独立仓库：
| 仓库 | 地址 | 用途 | 负责人 |
|------|------|------|--------|
| `rui-framework` | `git@gitee.com:pigeon/rui-framework.git` | 框架（backend） | 框架维护者 |
| `rui-payment` | `git@gitee.com:pigeon/rui-payment.git` | 支付模块 | 员工A |
| `rui-cashier` | `git@gitee.com:pigeon/rui-cashier.git` | 收银台模块 | 员工B |
业务开发者**只需要**维护自己的业务仓库，框架依赖通过 Maven 仓库自动下载。
### 1.2 为什么需要本地 clone 框架仓库？
AI（OpenCode）基于 GitNexus 知识图谱工作：
- **业务代码索引**：理解业务逻辑、生成业务代码
- **框架代码索引**：理解框架 API（如 `AuthUtil`、`BizException`）
框架代码以 **jar 包** 形式通过 Maven 引入，AI 无法直接解析 jar 中的 class 文件。因此需要在本地 clone 框架仓库作为**只读参考**，供 AI 索引和查询。
---
## 二、环境准备
### 2.1 基础工具
| 工具 | 最低版本 | 验证命令 | 说明 |
|------|---------|---------|------|
| JDK | 21 | `java -version` | 必须 |
| Maven | 3.9 | `mvn -version` | 必须 |
| Git | 2.40 | `git --version` | 必须 |
| Node.js | 18 | `node --version` | GitNexus 需要 |
### 2.2 配置 Maven 仓库
确保 `~/.m2/settings.xml` 已配置公司 Nexus 仓库认证（向运维获取）：
```xml
<settings>
<servers>
<server>
<id>releases</id>
<username>your-username</username>
<password>your-password</password>
</server>
<server>
<id>snapshots</id>
<username>your-username</username>
<password>your-password</password>
</server>
</servers>
</settings>
```
> **注意**：框架 `rui-parent` 和 `rui-common-*` 已发布到 Nexus，首次编译时会自动下载。
---
## 三、仓库克隆与配置
### 3.1 目录结构
```
~/work/
├── rui-framework/ # 框架仓库（只读参考）
│ ├── backend/
│ └── .gitnexus/ # 框架代码索引
└── rui-payment/ # 业务仓库（主要工作区）
├── pom.xml
├── rui-payment-api/
└── .gitnexus/ # 业务代码索引
```
### 3.2 克隆仓库
**步骤1：克隆框架仓库（所有员工都需要）**
```bash
git clone git@gitee.com:pigeon/rui-framework.git ~/work/rui-framework
```
**步骤2：克隆业务仓库**
```bash
# 员工A（支付）
git clone git@gitee.com:pigeon/rui-payment.git ~/work/rui-payment
# 员工B（收银台）
git clone git@gitee.com:pigeon/rui-cashier.git ~/work/rui-cashier
```
### 3.3 验证编译
```bash
cd ~/work/rui-payment
mvn clean compile -DskipTests
```
预期输出：`BUILD SUCCESS`
如果报错找不到 `rui-parent`，联系框架维护者确认已发布到 Nexus。
---
## 四、GitNexus 索引配置
### 4.1 什么是 GitNexus？
GitNexus 是 AI 的代码智能引擎，通过索引代码库构建知识图谱，帮助 AI：
- 理解代码结构（类、方法、调用关系）
- 分析修改影响（改 A 会波及 B、C）
- 安全导航（不重命名、不遗漏引用）
### 4.2 索引框架仓库
```bash
cd ~/work/rui-framework
npx gitnexus analyze
```
预期输出：
```
Repository indexed successfully
7,504 nodes | 15,350 edges | 268 clusters | 300 flows
```
### 4.3 索引业务仓库
```bash
cd ~/work/rui-payment
npx gitnexus analyze
```
预期输出：
```
Repository indexed successfully
1,601 nodes | 3,921 edges | 63 clusters | 131 flows
```
### 4.4 验证索引
```bash
npx gitnexus list
```
预期输出：
```
Indexed Repositories (2)
spring-ai
Path: ~/work/rui-framework
Stats: 7504 symbols, 15350 edges
rui-payment
Path: ~/work/rui-payment
Stats: 1601 symbols, 3921 edges
```
### 4.5 索引维护
| 场景 | 操作 |
|------|------|
| 业务代码修改后 | `cd ~/work/rui-payment && npx gitnexus analyze` |
| 框架升级后 | `cd ~/work/rui-framework && git pull && npx gitnexus analyze` |
| 索引损坏 | `npx gitnexus clean && npx gitnexus analyze` |
| 检查状态 | `npx gitnexus status` |
---
## 五、AI 开发工作流
### 5.1 启动 AI
在**业务仓库**目录下启动 IDE/OpenCode：
```bash
cd ~/work/rui-payment
# 启动 IDE 或 OpenCode
```
AI 默认使用当前目录的索引（`rui-payment`）。
### 5.2 开发业务代码（默认模式）
AI 自动基于 `rui-payment` 索引工作：
```
用户：帮我写一个订单查询接口
AI：基于 rui-payment 索引分析...
生成 OrderController、OrderService、OrderMapper
```
### 5.3 查询框架 API（跨仓库模式）
当需要理解框架源码时，在对话中指定 `repo` 参数：
**查询类定义：**
```
gitnexus_context({
name: "AuthUtil",
repo: "spring-ai"
})
```
**搜索功能实现：**
```
gitnexus_query({
query: "分布式锁 Redisson",
repo: "spring-ai"
})
```
**分析修改影响：**
```
gitnexus_impact({
target: "BaseController",
repo: "spring-ai",
direction: "upstream"
})
```
**查看执行流程：**
```
gitnexus_query({
query: "用户登录认证流程",
repo: "spring-ai"
})
```
### 5.4 常用查询对照表
| 我想查... | 命令 | 仓库 |
|-----------|------|------|
| `AuthUtil.getUserId()` 怎么用 | `gitnexus_context({name:"AuthUtil", repo:"spring-ai"})` | framework |
| 业务异常怎么抛 | `gitnexus_query({query:"BizException", repo:"spring-ai"})` | framework |
| 分布式锁怎么加 | `gitnexus_query({query:"Redisson分布式锁", repo:"spring-ai"})` | framework |
| 支付订单状态流转 | `gitnexus_query({query:"订单状态", repo:"rui-payment"})` | payment |
| 修改订单会影响哪里 | `gitnexus_impact({target:"OrderService", direction:"upstream"})` | payment |
| 收银台缓存策略 | `gitnexus_query({query:"缓存 CacheKeys", repo:"rui-cashier"})` | cashier |
### 5.5 工作流示例
**场景：开发一个支付退款接口**
```
1. 员工A在 ~/work/rui-payment 中启动 AI
2. 员工：帮我写退款接口
AI基于 rui-payment 索引分析业务代码...
3. 员工：退款时需要校验用户权限吗？
AI：建议调用 AuthUtil.getUserId()...
4. 员工：AuthUtil 有哪些方法？
【AI执行】gitnexus_context({name:"AuthUtil", repo:"spring-ai"})
AI：AuthUtil 提供 getUserId()、getTenantId()、getUser()...
5. 员工：退款金额用 BigDecimal 吗？
【AI执行】gitnexus_query({query:"金额计算 BigDecimal", repo:"spring-ai"})
AI：框架规范要求金额使用 DECIMAL(19,4)，Java 对应 BigDecimal...
6. AI 生成完整代码
```
---
## 六、常见问题
### Q1：AI 提示 "Index is stale"
**原因**：代码已修改但索引未更新。
**解决**：
```bash
cd ~/work/你的仓库
npx gitnexus analyze
```
### Q2：查询框架代码时提示 "Repo not found"
**原因**：框架仓库未索引或索引名称不对。
**解决**：
```bash
# 查看所有索引
npx gitnexus list
# 确认 spring-ai 存在
# 如果不存在，重新索引框架仓库
cd ~/work/rui-framework
npx gitnexus analyze
```
### Q3：编译时找不到 rui-parent
**原因**：框架未发布到 Nexus，或 Maven 仓库配置错误。
**解决**：
1. 确认 `~/.m2/settings.xml` 已配置 Nexus 认证
2. 联系框架维护者确认已执行 `mvn clean deploy`
3. 临时方案：本地 clone framework 后执行 `mvn clean install -DskipTests`
### Q4：框架升级后 AI 给出的 API 已过时
**原因**：框架索引未更新。
**解决**：
```bash
cd ~/work/rui-framework
git pull origin main
npx gitnexus analyze
```
### Q5：发现框架代码有 Bug
**禁止**：直接修改 `~/work/rui-framework` 代码。
**正确做法**：
1. 在业务仓库记录：`docs/框架问题记录.md`
2. 通知框架维护者
3. 等待框架修复并发布新版本
### Q6：AI 回答中引用了不存在的框架类
**原因**：业务仓库依赖的框架版本与本地索引的框架版本不一致。
**解决**：
1. 检查 `pom.xml` 中 parent version（如 `1.0.0`）
2. 确认 `~/work/rui-framework` 的代码版本一致
3. 如果不一致，更新 framework clone 并重新索引
---
## 附录
### A. 各仓库索引名称
| 仓库路径 | 索引名称 | 说明 |
|----------|----------|------|
| `~/work/rui-framework` | `spring-ai` | 基于 pom.xml artifactId |
| `~/work/rui-payment` | `rui-payment` | 基于目录名 |
| `~/work/rui-cashier` | `rui-cashier` | 基于目录名 |
### B. 快速命令速查
```bash
# 克隆所有仓库（新员工一次性执行）
git clone git@gitee.com:pigeon/rui-framework.git ~/work/rui-framework
git clone git@gitee.com:pigeon/rui-payment.git ~/work/rui-payment
# 初始化索引（一次性执行）
cd ~/work/rui-framework && npx gitnexus analyze
cd ~/work/rui-payment && npx gitnexus analyze
# 日常开发
mvn clean install -DskipTests
# 更新索引
npx gitnexus analyze
```
### C. 相关文档
| 文档 | 路径 |
|------|------|
| GitNexus 使用指南 | `docs/gitnexus-guide.md` |
| 环境搭建指南 | `docs/environment-setup.md` |
| 项目规范 | `AGENTS.md` |
---
> **提示**：本手册随项目演进持续更新。如有问题，联系框架维护者或技术负责人。