rui-docs/backend/guides/AI开发操作手册.md

多 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

启动步骤：

# 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

启动步骤：

# 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

启动步骤：

# 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

启动步骤：

# 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 通用）

# 查看修改
git status

# 添加修改
git add .

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

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

# 推送到 Gitea
git push origin main

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

查看 CI/CD 构建状态

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

模块间通信示例

收银模块调用支付模块：

// 在 rui-cashier 模块中
@FeignClient("rui-payment")
public interface PaymentFeignClient {
    
    @PostMapping("/api/v1/pay/order")
    Result<PayResult> createPayOrder(@RequestBody PayOrderDTO dto);
}

前端调用收银接口：

// 在 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. 查看通知 - 关注钉钉消息了解其他模块动态

---

🆘 故障排除

推送失败

# 检查远程仓库
git remote -v

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

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

CI 构建失败

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

钉钉没收到通知

# 检查 Webhook 配置
# 访问：https://git.vifo.cc/rui/{仓库}/settings/hooks

---

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