vifo
a7f3ee3565
同步仓库名称变更，涉及 16 个文件 66 处引用： - ai-skills: 菜单配置 - backend/guides: AI操作手册、环境配置、部署、gitnexus、opencode 工作流 - backend: 模块创建规则、通信规范、协作工作流、实施规范 - frontend: 收银设计、管理后台实施计划 - standards: 数据库设计规范
389 lines
9.5 KiB
Markdown
389 lines
9.5 KiB
Markdown
# 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` |
|
||
|
||
---
|
||
|
||
> **提示**：本手册随项目演进持续更新。如有问题，联系框架维护者或技术负责人。
|