vifo
0666c3ec7b
- 添加 backend/项目实施规范.md - 添加 backend/业务应用模块创建规则.md - 添加 backend/guides/deployment-guide.md - 添加 frontend/admin-ui-icon-guide.md - 添加 frontend/admin-ui-status.md - 更新 README.md 文档索引
434 lines
13 KiB
Markdown
434 lines
13 KiB
Markdown
# 跨团队协作工作流规范
|
||
|
||
> **版本**: 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 讨论。
|