# 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)

  rui-framework
    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: "rui-framework"
})
```

**搜索功能实现：**
```
gitnexus_query({
  query: "分布式锁 Redisson",
  repo: "rui-framework"
})
```

**分析修改影响：**
```
gitnexus_impact({
  target: "BaseController",
  repo: "rui-framework",
  direction: "upstream"
})
```

**查看执行流程：**
```
gitnexus_query({
  query: "用户登录认证流程",
  repo: "rui-framework"
})
```

### 5.4 常用查询对照表

| 我想查... | 命令 | 仓库 |
|-----------|------|------|
| `AuthUtil.getUserId()` 怎么用 | `gitnexus_context({name:"AuthUtil", repo:"rui-framework"})` | framework |
| 业务异常怎么抛 | `gitnexus_query({query:"BizException", repo:"rui-framework"})` | framework |
| 分布式锁怎么加 | `gitnexus_query({query:"Redisson分布式锁", repo:"rui-framework"})` | 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:"rui-framework"})
   AI：AuthUtil 提供 getUserId()、getTenantId()、getUser()...

5. 员工：退款金额用 BigDecimal 吗？
   【AI执行】gitnexus_query({query:"金额计算 BigDecimal", repo:"rui-framework"})
   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

# 确认 rui-framework 存在
# 如果不存在，重新索引框架仓库
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` | `rui-framework` | 基于 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` |

---

> **提示**：本手册随项目演进持续更新。如有问题，联系框架维护者或技术负责人。