rui/rui-docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

Browse Source 
- 添加 backend/项目实施规范.md
- 添加 backend/业务应用模块创建规则.md
- 添加 backend/guides/deployment-guide.md
- 添加 frontend/admin-ui-icon-guide.md
- 添加 frontend/admin-ui-status.md
- 更新 README.md 文档索引
This commit is contained in:
pigeon
2026-06-04 09:03:21 +08:00
parent d0771597a6
commit 0666c3ec7b
9 changed files with 2340 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files
backend/跨团队协作工作流.md
+433
View File
@@ -0,0 +1,433 @@
# 跨团队协作工作流规范
> **版本**: v1.0
> **创建日期**: 2026-06-04
> **适用范围**: rui 项目所有开发角色（框架、应用、前端）
---
## 一、背景与目的
### 1.1 问题背景
rui 项目采用多仓结构：
- **后端仓库**：`spring-ai`（backend + app/*）
- **前端仓库**：`rui-frontend`（admin-ui + cashier-mobile + customer-mobile）
在使用 OpenCode AI 辅助开发时存在以下痛点：
- **上下文污染**：一个 OpenCode 会话同时处理框架、应用、前端，导致理解混乱
- **边界模糊**：开发应用模块时直接修改框架代码，破坏框架稳定性
- **协作困难**：前端需要接口时无法有效通知后端，应用发现框架 Bug 时修复流程不规范
### 1.2 目标
- **仓库隔离**：前后端独立仓库，各自独立发版
- **会话隔离**：每个 OpenCode 会话只处理一个职责领域
- **边界清晰**：通过文件访问限制防止跨域修改
- **规范协作**：通过 Gitee Issue 模板实现标准化跨团队沟通
- **可追溯性**：所有跨团队协作都有记录，便于后续审计
---
## 二、角色与职责边界
### 2.1 仓库结构
```
# 后端仓库：spring-ai
spring-ai/
├── backend/ # 基础框架
├── app/ # 应用模块（支付、收银等）
├── docs/ # 后端文档
└── ...
# 前端仓库：rui-frontend
rui-frontend/
├── admin-ui/ # 管理后台（Vue 3）
├── cashier-mobile/ # 收银系统移动端
├── customer-mobile/ # 收银系统顾客端
└── ...
```
### 2.2 三种开发角色
| 角色 | 所属仓库 | 负责目录 | 可修改范围 | 只读范围 | 会话配置 |
|------|---------|---------|-----------|---------|---------|
| **框架开发** | spring-ai | `backend/` | `backend/**` | `app/**` | `framework.json` |
| **应用开发** | spring-ai | `app/{模块}/` | `app/{模块}/**` | `backend/**` | `app-module.json` |
| **前端开发** | rui-frontend | `admin-ui/` | `admin-ui/**` | `cashier-mobile/`, `customer-mobile/` | `admin-ui.json` |
### 2.2 职责矩阵
| 操作 | 框架会话 | 应用会话 | 前端会话 |
|------|---------|---------|---------|
| 修改框架代码 | ✅ | ❌ 禁止 | ❌ 禁止 |
| 修改应用代码 | ❌ 禁止 | ✅ | ❌ 禁止 |
| 修改前端代码 | ❌ 禁止 | ❌ 禁止 | ✅ |
| 报告框架 Bug | ✅ 接收并处理 | ✅ 创建 Issue | ✅ 创建 Issue |
| 请求新接口 | ✅ 实现 | ✅ 实现 | ✅ 创建 Issue |
| 修改接口文档 | ✅ | ✅ | ❌ 禁止 |
---
## 三、协作场景与流程
### 场景一：前端/应用需要后端接口
**触发条件**：前端（rui-frontend 仓库）或应用模块在开发过程中需要新的后端接口支持
**协作流程**（跨仓库协作）：
```
rui-frontend/ spring-ai/
┌─────────────┐ ┌─────────────┐
│ 前端会话 │ │ 后端 │
│ (admin-ui) │ │ 会话 │
└──────┬──────┘ └──────┬──────┘
│ │
│ 在 spring-ai 仓库创建 │
│ Issue [API-REQ] │
└────────────────────────→│
│ │
│ 回复：接口已实现 │
│ Swagger 地址：xxx │
│←────────────────────────┘
│ │
│ 根据 Swagger 开发/联调 │
│ │
```
**详细步骤**：
1. **需求方**（前端或应用）在 Gitee 创建 Issue
- 使用模板：`api_request.md`
- 标题格式：`[API-REQ] 一句话描述`
- 标签：`api-request`, `cross-team`
- 必填信息：接口路径、请求/响应格式、业务规则
2. **实现方**（后端）处理 Issue
- 在 backend/ 下实现接口
- 更新 Swagger 文档
- 提交 PR 并关联 Issue
- 在 Issue 中回复接口信息
3. **需求方**验证并关闭 Issue
- 根据 Swagger 开发/联调
- 确认无误后关闭 Issue
**示例**：
- 前端 Issue：`[API-REQ] 用户管理需要批量导入接口`
- 后端回复：`接口已实现，Swagger: /doc.html#/用户管理/importUsers`
---
### 场景二：应用发现框架 Bug
**触发条件**：应用模块在开发过程中发现基础框架存在问题
**协作流程**：
```
┌─────────────┐ 创建 Issue ┌─────────────┐
│ 应用模块 │ ──────────────────→ │ 框架 │
│ 会话 │ [FRAMEWORK] 模板 │ 会话 │
└─────────────┘ └─────────────┘
↑ │
│ 回复：已修复 + 版本号 │
└──────────────────────────────────┘
↑ │
│ 升级依赖并验证 │
└──────────────────────────────────┘
```
**详细步骤**：
1. **发现方**（应用模块）在 Gitee 创建 Issue
- 使用模板：`framework_bug.md`
- 标题格式：`[FRAMEWORK] 一句话描述`
- 标签：`framework`, `cross-team`, `bug`
- 必填信息：复现路径、期望/实际行为、影响评估
2. **框架方**处理 Issue
- 复现问题
- 在 backend/ 下修复
- 发布新版本（更新 pom.xml 版本号）
- 在 Issue 中回复修复版本
3. **应用方**升级依赖
- 更新 pom.xml 中的框架依赖版本
- 验证问题是否修复
- 关闭 Issue
**重要原则**：
- ❌ **严禁**应用会话直接修改 backend/ 下的代码
- ✅ 即使是很小的改动，也要走 Issue 流程
- ✅ 紧急情况下可先临时 workaround，但必须同步创建 Issue
**示例**：
- 应用 Issue：`[FRAMEWORK] BaseController 分页查询在 search 为空时 NPE`
- 框架回复：`已修复，版本 v2.1.3，请升级依赖`
---
### 场景三：通用跨团队任务
**触发条件**：不属于接口需求或框架 Bug 的其他协作任务
**协作流程**：
1. **提出方**在 Gitee 创建 Issue
- 使用模板：`cross_team_task.md`
- 标题格式：`[CROSS] 一句话描述`
- 明确说明：谁来做、做什么、何时完成
2. **接收方**处理并关闭
**适用场景**：
- 需要其他模块提供配置数据
- 需要协调数据库变更
- 需要共享文档或工具
---
## 四、OpenCode 会话启动规范
### 4.1 启动前准备
每次启动 OpenCode 前，明确当前角色：
| 我要做什么 | 应该启动的会话 | 工作区配置 |
|-----------|--------------|-----------|
| 开发框架通用能力 | 框架会话 | `framework.json` |
| 开发支付模块 | 应用会话（支付） | `app-module.json` |
| 开发用户模块 | 应用会话（用户） | `app-module.json` |
| 开发前端页面 | 前端会话 | `admin-ui.json` |
### 4.2 启动方式
#### 方式一：手动指定（推荐）
启动 OpenCode 时，明确指定仓库和角色：
**后端仓库（spring-ai）**：
```
工作目录：/Users/zhangsheng/rhkj/spring-ai
角色：框架开发
限制：只能修改 backend/ 下的代码
```
**前端仓库（rui-frontend）**：
```
工作目录：/Users/zhangsheng/rhkj/rui-frontend
角色：前端开发
限制：只能修改 admin-ui/ 下的代码
```
#### 方式二：使用工作区配置（如果 OpenCode 支持）
**后端仓库**参考 `.opencode/workspace/` 目录下的 JSON 配置文件：
- `framework.json` - 框架开发
- `app-module.json` - 应用模块开发
**前端仓库**参考 `rui-frontend/.opencode/workspace/` 目录下的配置文件（需自行创建）。
### 4.3 会话切换规则
- **同一功能内**：保持同一会话，不要频繁切换
- **跨模块切换**：使用 `/new` 创建新会话
- **对话轮次过多**（超过 20-30 轮）：建议新建会话
---
## 五、Gitee Issue 使用规范
### 5.1 Issue 模板位置
```
.gitee/issue_templates/
├── api_request.md # 接口需求
├── framework_bug.md # 框架问题
└── cross_team_task.md # 通用任务
```
### 5.2 标签规范
| 标签 | 用途 | 颜色 |
|------|------|------|
| `api-request` | 接口需求 | 蓝色 |
| `framework` | 框架相关问题 | 红色 |
| `cross-team` | 跨团队协作 | 紫色 |
| `bug` | 缺陷 | 红色 |
| `frontend→backend` | 前端调后端 | 绿色 |
| `app→framework` | 应用调框架 | 橙色 |
### 5.3 标题规范
| 类型 | 格式 | 示例 |
|------|------|------|
| 接口需求 | `[API-REQ] {模块}需要{功能}` | `[API-REQ] 用户模块需要批量导入接口` |
| 框架问题 | `[FRAMEWORK] {问题简述}` | `[FRAMEWORK] BaseController 分页查询 NPE` |
| 通用任务 | `[CROSS] {任务简述}` | `[CROSS] 协调订单表索引变更` |
### 5.4 处理时效
| 优先级 | 响应时间 | 解决时间 |
|--------|---------|---------|
| P0-阻塞 | 2 小时内 | 24 小时内 |
| P1-高 | 4 小时内 | 3 天内 |
| P2-中 | 1 天内 | 1 周内 |
| P3-低 | 2 天内 | 排期处理 |
---
## 六、目录访问控制
### 6.1 框架会话（backend/）
```
可修改：
backend/
docs/framework/
只读（禁止修改）：
app/
admin-ui/
docs/superpowers/ # 除非涉及框架规范更新
```
### 6.2 应用会话（app/{模块}/）
```
可修改：
app/{当前模块}/
docs/{当前模块}/
只读（禁止修改）：
backend/
admin-ui/
app/其他模块/ # 需要调用时通过 Feign/HTTP
```
### 6.3 前端会话（admin-ui/）
```
可修改：
admin-ui/
只读（禁止修改）：
backend/
app/
```
---
## 七、最佳实践
### 7.1 沟通优先于修改
- 发现其他域的问题 → 先创建 Issue → 不要直接修改
- 需要其他域支持 → 先创建 Issue → 等待响应
### 7.2 信息完整减少往返
创建 Issue 时尽量提供完整信息：
- ✅ 包含复现路径
- ✅ 包含期望结果
- ✅ 包含截图/日志
- ❌ 避免只有"这个功能有问题"这样模糊的描述
### 7.3 及时关闭已完成的 Issue
- 接口验证通过后立即关闭
- Bug 修复验证后立即关闭
- 长期未关闭的 Issue 需要定期 review
### 7.4 版本管理
- 框架修复后及时更新版本号
- 应用模块及时升级框架依赖
- 在 Issue 中明确记录版本信息
### 7.5 紧急问题处理
遇到阻塞性紧急问题：
1. 先在应用侧做临时 workaround（记录 commit）
2. 同步创建 Issue 通知框架团队
3. 框架修复后，移除 workaround 并升级依赖
---
## 八、常见问题
### Q1: 我发现框架有个很明显的小 bug，也必须走 Issue 流程吗？
**答**：是的。即使是一行代码的修改，也要走 Issue 流程。因为：
- 框架代码影响所有应用模块
- 需要评估影响范围
- 需要同步版本更新
### Q2: 前端仓库（rui-frontend）和后端仓库（spring-ai）是什么关系？
**答**：
- **独立仓库**：前端和后端是完全独立的 Git 仓库
- **通过 API 关联**：前端通过 HTTP 接口调用后端服务
- **通过 Issue 协作**：跨仓库的需求通过 Gitee Issue 进行沟通
- **独立部署**：前端和后端可以独立构建、独立部署
### Q3: 为什么前端要独立仓库？
**答**：
- **技术栈不同**：前端使用 Vue/Node.js，后端使用 Java/Spring
- **构建工具不同**：前端用 Vite/pnpm，后端用 Maven
- **发布节奏不同**：前端可以独立发版，不需要等后端
- **团队分工**：前端和后端可能由不同团队维护
- **避免污染**：node_modules（几百 MB）不进入后端仓库
### Q4: 前端如何获取后端接口信息？
**答**：
1. 查看后端 Swagger 文档：`http://{backend-host}/doc.html`
2. 通过 Gitee Issue 询问后端团队
3. 参考已有的 service/ 目录下的 API 定义
### Q5: 前端可以直接看 backend 的代码来了解接口吗？
**答**：可以查看（只读），但不应该依赖阅读源码来了解接口。应该：
- 查看 Swagger 文档
- 通过 Issue 询问后端
- 参考已有的 service/ 目录下的 API 定义
### Q6: 应用模块之间如何协作？
**答**：应用模块之间通过以下方式协作：
- **接口调用**：使用 FeignClient 调用 `/inner/` 路径
- **MQ 消息**：通过消息队列解耦
- **共享 DTO**：定义在 `rui-xxx-common` 模块中
跨应用模块的接口需求同样使用 `api_request.md` 模板。
### Q7: 如果框架会话和应用会话同时修改了代码怎么办？
**答**：由于有目录访问限制，不会出现同时修改同一文件的情况。框架只改 backend/，应用只改 app/，天然隔离。
---
## 九、相关文档
- [项目规范](../AGENTS.md)
- [前端仓库](../../rui-frontend/README.md)
- [设计文档模板](superpowers/templates/design-template.md)
- [实施计划模板](superpowers/templates/plan-template.md)
---
## 十、更新记录
| 版本 | 日期 | 更新内容 | 作者 |
|------|------|---------|------|
| v1.0 | 2026-06-04 | 初稿 | OpenCode |
---
> **提示**：本文档是活文档，随着团队协作实践的发展会持续更新。如有建议，请提交 PR 或创建 Issue 讨论。