docs: 迁移 spring-ai 通用文档到 rui-docs

从 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分模块打包设计
2026-06-04 09:31:24 +08:00
parent 2e38c53434
commit 19de7e24ec
36 changed files with 5872 additions and 0 deletions
@@ -0,0 +1,322 @@
+# OpenCode 多仓库操作指南
+
+> **版本**: v1.0  
+> **创建日期**: 2026-06-04  
+> **适用**: rui 项目前后端分离开发团队
+
+---
+
+## 一、项目结构概览
+
+rui 项目采用**多仓库**架构：
+
+```
+~/rhkj/
+├── spring-ai/              # 后端仓库（Java/Spring）
+│   ├── backend/            # 基础框架
+│   ├── app/                # 应用模块
+│   └── docs/               # 文档
+│
+└── rui-frontend/           # 前端仓库（Vue/Node.js）
+    ├── admin-ui/           # 管理后台
+    ├── cashier-mobile/     # 收银移动端
+    └── customer-mobile/    # 顾客端
+```
+
+**原则**：一个 OpenCode 会话只处理一个仓库。
+
+---
+
+## 二、启动 OpenCode 的正确姿势
+
+### 2.1 后端开发（spring-ai）
+
+```bash
+# 1. 进入后端目录
+cd /Users/zhangsheng/rhkj/spring-ai
+
+# 2. 启动 OpenCode（命令行方式）
+opencode
+
+# 3. 会话启动后，明确告知角色
+```
+
+**启动时输入**（粘贴到 OpenCode 对话框）：
+
+```
+你现在进入【后端开发模式】。
+
+工作目录：/Users/zhangsheng/rhkj/spring-ai
+负责范围：backend/ 和 app/ 目录下的 Java 代码
+技术栈：Spring Boot 4.x、Spring Cloud、MyBatis Plus、JDK 21
+
+规则：
+1. 只能修改 backend/ 和 app/ 下的代码
+2. 发现前端需求时，提醒用户创建 Gitee Issue
+3. 编码规范参考 docs/AGENTS.md
+
+当前任务：【在这里描述你的具体任务】
+```
+
+---
+
+### 2.2 前端开发（rui-frontend）
+
+```bash
+# 1. 进入前端目录
+cd /Users/zhangsheng/rhkj/rui-frontend
+
+# 2. 启动 OpenCode
+opencode
+
+# 3. 会话启动后，明确告知角色
+```
+
+**启动时输入**（粘贴到 OpenCode 对话框）：
+
+```
+你现在进入【前端开发模式】。
+
+工作目录：/Users/zhangsheng/rhkj/rui-frontend
+负责范围：admin-ui/、cashier-mobile/、customer-mobile/
+技术栈：Vue 3、TypeScript、Element Plus、Vite、pnpm
+
+规则：
+1. 只能修改前端项目下的代码
+2. 需要后端接口时，在 spring-ai 仓库创建 Gitee Issue
+3. 编码规范参考 AGENTS.md
+4. 使用 pnpm workspace 管理多项目
+
+当前任务：【在这里描述你的具体任务，如：开发用户管理页面】
+```
+
+---
+
+### 2.3 框架开发（仅修改 backend/）
+
+```
+你现在进入【框架开发模式】。
+
+工作目录：/Users/zhangsheng/rhkj/spring-ai
+负责范围：仅 backend/ 目录
+角色：基础框架维护者
+
+规则：
+1. 只能修改 backend/ 下的代码
+2. 不修改任何 app/ 目录下的业务代码
+3. 保持框架的通用性和向后兼容性
+4. 修改公共接口时，评估对 app/ 的影响
+
+当前任务：【描述框架任务】
+```
+
+---
+
+## 三、切换工作流的正确方式
+
+### ❌ 错误示范
+
+在一个 OpenCode 会话中：
+```
+用户：帮我修改后端接口
+AI：好的，已修改 backend/xxx.java
+用户：再帮我改一下前端页面
+AI：好的，已修改 admin-ui/xxx.vue  ← 错误！上下文已污染
+```
+
+### ✅ 正确示范
+
+**场景 1：同一仓库内切换任务**
+
+如果任务相关（如修改后端接口 + 对应单元测试），可以在同一会话中完成。
+
+如果任务不相关（如用户管理 + 订单管理），建议：
+```
+用户：/new
+AI：已创建新会话
+用户：【输入新的任务描述】
+```
+
+**场景 2：跨仓库协作**
+
+```
+# 后端仓库会话
+用户：开发用户查询接口
+AI：已完成，接口路径：GET /user/admin/list
+
+# 需要前端对接时
+用户：需要前端开发列表页面
+AI：请创建新会话处理前端任务。
+   在 rui-frontend 目录启动 OpenCode，输入前端开发模式提示词。
+   接口文档：http://localhost:8080/doc.html#/user/list
+
+# 用户切换到前端仓库，新建会话
+用户：/new
+【进入 rui-frontend 目录，启动新 OpenCode 会话】
+用户：根据接口文档开发用户列表页面
+AI：好的，开始开发前端页面...
+```
+
+---
+
+## 四、跨仓库通信机制
+
+### 4.1 前端需要后端接口
+
+**前端会话**中：
+```
+我需要后端提供用户批量导入接口，参数是 Excel 文件
+```
+
+OpenCode 应该回答：
+```
+请在 spring-ai 仓库创建 Issue，使用模板：api_request.md
+
+Issue 内容：
+标题：[API-REQ] 用户模块需要批量导入接口
+内容：...
+
+创建后，在 backend/ 开发会话中处理该 Issue
+```
+
+### 4.2 后端接口完成通知前端
+
+**后端会话**中：
+```
+接口已实现，Swagger 地址：/doc.html#/user/import
+请通知前端团队进行对接
+```
+
+OpenCode 应该：
+```
+已在 Issue 中回复前端团队。
+前端可以在 rui-frontend 仓库的新会话中进行对接开发。
+```
+
+---
+
+## 五、目录访问限制检查
+
+启动会话后，可以让 OpenCode 自我检查：
+
+```
+请确认你的工作范围：
+1. 可以修改哪些目录？
+2. 不能修改哪些目录？
+3. 如果需要跨仓库协作，应该怎么做？
+```
+
+期望回答：
+```
+1. 可修改：backend/、app/（后端模式）或 admin-ui/（前端模式）
+2. 不可修改：frontend/（后端模式）或 backend/（前端模式）
+3. 跨仓库协作：通过 Gitee Issue 进行
+```
+
+---
+
+## 六、常见问题
+
+### Q1: 我不小心在错误目录启动了 OpenCode，怎么办？
+
+**答**：
+1. 保存当前对话（如有重要信息）
+2. 关闭当前 OpenCode 窗口
+3. 切换到正确目录重新启动
+4. 使用 `/new` 创建新会话
+
+### Q2: 一个功能需要同时修改前后端，怎么操作？
+
+**答**：
+1. **方法 A（推荐）**：先在一个仓库完成，提交后切换到另一个仓库
+   - 在 spring-ai 开发接口 → 提交 PR
+   - 在 rui-frontend 开发页面 → 提交 PR
+   
+2. **方法 B（并行）**：两个 OpenCode 窗口同时工作
+   - 窗口 1：spring-ai 目录，开发后端
+   - 窗口 2：rui-frontend 目录，开发前端
+   
+3. **不要**：在一个会话中同时修改两个仓库
+
+### Q3: OpenCode 能记住跨仓库的上下文吗？
+
+**答**：不能。每个 OpenCode 会话是独立的：
+- 不同目录 = 不同上下文
+- 即使同一个目录，`/new` 后也是全新上下文
+- 需要人工传递关键信息（如接口文档链接）
+
+### Q4: 怎么快速查看当前在哪个仓库？
+
+**答**：在 OpenCode 中输入：
+```
+请告诉我当前工作目录和可修改范围
+```
+
+### Q5: 可以用同一个 OpenCode 窗口切换目录吗？
+
+**答**：不建议。OpenCode 启动时会锁定工作目录。如果需要切换：
+1. 关闭当前窗口
+2. `cd` 到新目录
+3. 重新启动 OpenCode
+
+---
+
+## 七、快捷键和命令速查
+
+| 操作 | 命令 |
+|------|------|
+| 创建新会话 | `/new` |
+| 查看当前目录 | `pwd` |
+| 查看文件树 | `tree -L 2` |
+| 查看 Git 状态 | `git status` |
+| 切换分支 | `git checkout branch-name` |
+
+---
+
+## 八、最佳实践
+
+1. **明确角色**：启动时明确告知 OpenCode 当前角色和范围
+2. **单一职责**：一个会话只做一件事（一个功能/一个 Bug）
+3. **及时提交**：完成一个功能后立即 `git commit`，不要积压
+4. **Issue 驱动**：跨仓库需求通过 Issue 追踪，不要口头传递
+5. **文档优先**：复杂功能先写设计文档，再编码
+6. **定期 /new**：对话超过 20-30 轮后，新建会话保持上下文清晰
+
+---
+
+## 九、模板库
+
+### 启动模板
+
+保存以下模板，启动时直接粘贴：
+
+**后端启动模板**：
+```markdown
+你现在进入【后端开发模式】。
+工作目录：/Users/zhangsheng/rhkj/spring-ai
+技术栈：Spring Boot 4.x、JDK 21、MyBatis Plus
+规则：只能修改 backend/ 和 app/ 目录
+当前任务：【填写】
+```
+
+**前端启动模板**：
+```markdown
+你现在进入【前端开发模式】。
+工作目录：/Users/zhangsheng/rhkj/rui-frontend
+技术栈：Vue 3、TypeScript、Element Plus、Vite
+规则：只能修改前端项目目录
+当前任务：【填写】
+```
+
+---
+
+## 十、相关文档
+
+- [跨团队协作规范](./cross-team-workflow.md)
+- [后端项目规范](../AGENTS.md)
+- [前端项目规范](../../rui-frontend/AGENTS.md)
+- [Gitea 自建 Git 服务器](./self-hosted-git-server.md)
+
+---
+
+> **提示**：本文档是活文档，根据团队实践持续更新。如有建议请提交 PR。