rui/rui-docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
rui-docs/backend/跨团队协作工作流.md
T
vifo a7f3ee3565 refactor: 全局替换 spring-ai -> rui-framework 
同步仓库名称变更，涉及 16 个文件 66 处引用：
- ai-skills: 菜单配置
- backend/guides: AI操作手册、环境配置、部署、gitnexus、opencode 工作流
- backend: 模块创建规则、通信规范、协作工作流、实施规范
- frontend: 收银设计、管理后台实施计划
- standards: 数据库设计规范
2026-06-08 12:56:39 +08:00

13 KiB
Raw Permalink Blame History

跨团队协作工作流规范

版本: 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/，天然隔离。

九、相关文档

十、更新记录

版本 日期 更新内容 作者
v1.0 2026-06-04 初稿 OpenCode

提示：本文档是活文档，随着团队协作实践的发展会持续更新。如有建议，请提交 PR 或创建 Issue 讨论。

Reference in New Issue View Git Blame Copy Permalink