# 跨团队协作工作流规范

> **版本**: v1.0  
> **创建日期**: 2026-06-04  
> **适用范围**: rui 项目所有开发角色（框架、应用、前端）

---

## 一、背景与目的

### 1.1 问题背景

rui 项目采用多仓结构：
- **后端仓库**：`rui-framework`（backend + app/*）
- **前端仓库**：`rui-frontend`（admin-ui + cashier-mobile + customer-mobile）

在使用 OpenCode AI 辅助开发时存在以下痛点：

- **上下文污染**：一个 OpenCode 会话同时处理框架、应用、前端，导致理解混乱
- **边界模糊**：开发应用模块时直接修改框架代码，破坏框架稳定性
- **协作困难**：前端需要接口时无法有效通知后端，应用发现框架 Bug 时修复流程不规范

### 1.2 目标

- **仓库隔离**：前后端独立仓库，各自独立发版
- **会话隔离**：每个 OpenCode 会话只处理一个职责领域
- **边界清晰**：通过文件访问限制防止跨域修改
- **规范协作**：通过 Gitee Issue 模板实现标准化跨团队沟通
- **可追溯性**：所有跨团队协作都有记录，便于后续审计

---

## 二、角色与职责边界

### 2.1 仓库结构

```
# 后端仓库：rui-framework
rui-framework/
├── backend/              # 基础框架
├── app/                  # 应用模块（支付、收银等）
├── docs/                 # 后端文档
└── ...

# 前端仓库：rui-frontend
rui-frontend/
├── admin-ui/             # 管理后台（Vue 3）
├── cashier-mobile/       # 收银系统移动端
├── customer-mobile/      # 收银系统顾客端
└── ...
```

### 2.2 三种开发角色

| 角色 | 所属仓库 | 负责目录 | 可修改范围 | 只读范围 | 会话配置 |
|------|---------|---------|-----------|---------|---------|
| **框架开发** | rui-framework | `backend/` | `backend/**` | `app/**` | `framework.json` |
| **应用开发** | rui-framework | `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/              rui-framework/
┌─────────────┐           ┌─────────────┐
│  前端会话    │           │    后端      │
│  (admin-ui) │           │   会话       │
└──────┬──────┘           └──────┬──────┘
       │                         │
       │  在 rui-framework 仓库创建   │
       │  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 时，明确指定仓库和角色：

**后端仓库（rui-framework）**：
```
工作目录：/Users/zhangsheng/rhkj/rui-framework
角色：框架开发
限制：只能修改 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）和后端仓库（rui-framework）是什么关系？

**答**：
- **独立仓库**：前端和后端是完全独立的 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 讨论。