# 多 AI 隔离开发操作手册

## 🎯 快速开始

### 1. 项目结构总览

```
~/rhkj/
├── rui-frontend/          ← 前端 AI 工作目录
│   ├── admin-ui/
│   ├── cashier-mobile/
│   └── customer-mobile/
│
├── rui-framework/             ← 后端框架 AI 工作目录
│   ├── backend/
│   │   ├── rui-common/
│   │   ├── rui-gateway/
│   │   ├── rui-auth/
│   │   └── rui-service/
│   └── docs/
│
├── rui-framework/app/
│   ├── rui-cashier/       ← 收银 AI 工作目录
│   └── rui-payment/       ← 支付 AI 工作目录
│
└── rui-framework/         ← 框架模块 AI 工作目录
```

---

## 🤖 AI 配置与启动

### 前端 AI

**工作目录：** `~/rhkj/rui-frontend`

**启动步骤：**
```bash
# 1. 进入前端目录
cd ~/rhkj/rui-frontend

# 2. 打开 OpenCode（或其他 AI 工具）
# 根据您使用的工具，执行相应命令
# 例如：cursor . 或 code .

# 3. 在 AI 对话中输入：
```

**AI 指令：**
```
你是前端开发专家。当前项目是 rui-frontend（睿核科技前端工程）。

技术栈：Vue 3 + TypeScript + Vite + pnpm

你的职责：
1. 开发 admin-ui（管理后台）
2. 开发 cashier-mobile（收银移动端）
3. 开发 customer-mobile（顾客移动端）

约束条件：
- 禁止修改后端代码
- 禁止修改 API 接口定义
- 通过 REST API 与后端通信
- 参考 AGENTS.md 文件了解详细边界

当前任务：[描述您的需求]
```

---

### 后端框架 AI

**工作目录：** `~/rhkj/rui-framework`

**启动步骤：**
```bash
# 1. 进入后端目录
cd ~/rhkj/rui-framework

# 2. 打开 OpenCode

# 3. 在 AI 对话中输入：
```

**AI 指令：**
```
你是 Java 后端开发专家。当前项目是 rui-framework（睿核科技后端框架）。

技术栈：Spring Boot 3.x + Spring Cloud + JDK 21 + Maven + MyBatis Plus

你的职责：
1. 维护 rui-common（公共组件）
2. 维护 rui-gateway（网关服务）
3. 维护 rui-auth（认证授权）
4. 维护 rui-service（系统服务：用户、权限等）

约束条件：
- 禁止修改前端代码
- 禁止编写业务逻辑（收银、支付等）
- 只提供基础设施和公共服务
- 通过 FeignClient/REST API 暴露服务
- 参考 AGENTS.md 文件了解详细边界

当前任务：[描述您的需求]
```

---

### 收银模块 AI

**工作目录：** `~/rhkj/rui-framework/app/rui-cashier`

**启动步骤：**
```bash
# 1. 进入收银模块目录
cd ~/rhkj/rui-framework/app/rui-cashier

# 2. 打开 OpenCode

# 3. 在 AI 对话中输入：
```

**AI 指令：**
```
你是 Java 业务开发专家。当前项目是 rui-cashier（睿核科技收银系统）。

技术栈：Spring Boot + MyBatis Plus + MySQL

你的职责：
1. 开发订单管理功能
2. 开发会员管理功能
3. 开发商品管理功能
4. 开发营业报表功能
5. 开发积分系统

约束条件：
- 禁止修改前端代码
- 禁止修改框架代码（在 rui-framework 仓库）
- 禁止直接引用支付模块代码
- 通过 FeignClient 调用框架服务
- 通过 REST API 暴露接口供前端调用
- 参考 AGENTS.md 文件了解详细边界

当前任务：[描述您的需求]
```

---

### 支付模块 AI

**工作目录：** `~/rhkj/rui-framework/app/rui-payment`

**启动步骤：**
```bash
# 1. 进入支付模块目录
cd ~/rhkj/rui-framework/app/rui-payment

# 2. 打开 OpenCode

# 3. 在 AI 对话中输入：
```

**AI 指令：**
```
你是 Java 业务开发专家。当前项目是 rui-payment（睿核科技支付系统）。

技术栈：Spring Boot + MyBatis Plus + MySQL

你的职责：
1. 开发支付订单管理
2. 开发支付渠道管理
3. 开发退款管理
4. 开发分账系统
5. 开发对账系统

约束条件：
- 禁止修改前端代码
- 禁止修改框架代码（在 rui-framework 仓库）
- 禁止直接引用收银模块代码
- 通过 FeignClient 调用框架服务
- 通过 REST API 暴露接口供收银模块调用
- 参考 AGENTS.md 文件了解详细边界

当前任务：[描述您的需求]
```

---

## 📋 常用操作命令

### 代码推送（所有 AI 通用）

```bash
# 查看修改
git status

# 添加修改
git add .

# 提交（使用规范格式）
git commit -m "feat: 功能描述

- 详细修改点1
- 详细修改点2"

# 推送到 Gitea
git push origin main

# 查看推送结果（钉钉会收到通知）
```

### 查看 CI/CD 构建状态

```bash
# 查看 Actions 运行状态
# 访问：https://git.vifo.cc/rui/{仓库名}/actions
```

### 模块间通信示例

**收银模块调用支付模块：**
```java
// 在 rui-cashier 模块中
@FeignClient("rui-payment")
public interface PaymentFeignClient {
    
    @PostMapping("/api/v1/pay/order")
    Result<PayResult> createPayOrder(@RequestBody PayOrderDTO dto);
}
```

**前端调用收银接口：**
```typescript
// 在 rui-frontend 中
const API_BASE = '/api';

const cashierApi = {
    createOrder: (data) => axios.post(`${API_BASE}/cashier/order`, data),
    getOrderList: () => axios.get(`${API_BASE}/cashier/order/list`)
};
```

---

## 🔔 协作流程

### 当需要其他 AI 支持时

1. **在 Gitea 创建 Issue**
   ```
   标题：[需求] 收银模块需要支付接口支持
   内容：
   - 需求描述：创建订单后需要发起支付
   - 期望接口：POST /api/v1/pay/order
   - 请求参数：{ orderNo, amount, payType }
   - 所属仓库：rui-payment
   ```

2. **等待对应 AI 处理**
   - 支付 AI 会看到钉钉通知
   - 支付 AI 实现接口并推送代码

3. **联调测试**
   - 收银 AI 使用新接口
   - 测试环境验证

---

## 📁 重要文件位置

| 文件 | 位置 | 说明 |
|------|------|------|
| AI 边界配置 | `AGENTS.md` | 每个仓库根目录 |
| 通信规范 | `rui-framework/docs/module-communication.md` | 模块间通信规范 |
| CI 配置 | `.gitea/workflows/*.yml` | 自动化构建 |
| 后端 POM | `rui-framework/backend/pom.xml` | Maven 根配置 |

---

## ⚠️ 注意事项

1. **不要跨仓库修改代码** - 每个 AI 只能修改自己的仓库
2. **提交前检查** - 确认修改范围符合 AGENTS.md
3. **及时推送** - 代码完成后立即推送到 Gitea
4. **查看通知** - 关注钉钉消息了解其他模块动态

---

## 🆘 故障排除

### 推送失败
```bash
# 检查远程仓库
git remote -v

# 确认是 Gitea 地址
gitea  ssh://git@git.vifo.cc:222/rui/xxx.git

# 如果失败，检查 SSH 密钥
ssh -p 222 git@git.vifo.cc
```

### CI 构建失败
```bash
# 查看构建日志
# 访问：https://git.vifo.cc/rui/{仓库}/actions
```

### 钉钉没收到通知
```bash
# 检查 Webhook 配置
# 访问：https://git.vifo.cc/rui/{仓库}/settings/hooks
```

---

> **最后提醒**：每个 AI 严格在自己的边界内工作，通过 REST API 协作，禁止直接引用其他模块代码！