diff --git a/docs/ARCHITECTURE-LAYERS.md b/docs/ARCHITECTURE-LAYERS.md deleted file mode 100644 index 2332600..0000000 --- a/docs/ARCHITECTURE-LAYERS.md +++ /dev/null @@ -1,903 +0,0 @@ -# Code 项目架构分层图 - -> 一个现代化的代码协作与团队沟通平台 -> -> 技术栈：Rust (后端) + TypeScript/React (前端) + Kubernetes (部署) - ---- - -## 系统全景架构 - -``` -┌─────────────────────────────────────────────────────────────────────────────────────────────────────┐ -│ 用 户 层 │ -│ │ -│ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐ │ -│ │ Web 浏览器 │ │ Git 客户端 │ │ 外部 CI/CD │ │ -│ │ (React SPA) │ │ (git/SSH) │ │ (GitHub/GitLab) │ │ -│ └────────┬─────────┘ └────────┬─────────┘ └────────┬─────────┘ │ -└──────────────────┼────────────────────────────────┼────────────────────────────────┼────────────────┘ - │ │ │ - │ HTTP/WS │ Git Protocol │ Webhook - │ │ │ -┌──────────────────▼────────────────────────────────▼────────────────────────────────▼────────────────┐ -│ 接入层 (Ingress/LB) │ -│ │ -│ ┌──────────────────────────────────────────────────────────────────────────────────┐ │ -│ │ Load Balancer / K8s Ingress (:80/:443) │ │ -│ └──────────────────────┬──────────────────────┬──────────────────────┬─────────────┘ │ -└────────────────────────────────┼──────────────────────┼──────────────────────┼──────────────────────┘ - │ │ │ - │ REST API │ Git Ops │ Webhook - │ │ │ -┌────────────────────────────────▼──────────────────────▼──────────────────────▼──────────────────────┐ -│ 应 用 服 务 层 (apps/) │ -│ │ -│ ┌────────────────────┐ ┌────────────────────┐ ┌────────────────────┐ ┌────────────────────┐ │ -│ │ apps/app │ │ apps/gitserver │ │ apps/git-hook │ │ apps/email │ │ -│ │ 主 Web API 服务 │ │ Git HTTP/SSH 服务 │ │ Git Hook 处理器 │ │ 邮件发送 Worker │ │ -│ │ :8080 │ │ :8021/:2222 │ │ Worker │ │ Worker │ │ -│ │ HTTP + WebSocket │ │ HTTP + SSH │ │ 异步任务 │ │ 队列消费 │ │ -│ │ 多实例部署 │ │ 单实例 │ │ 单实例 │ │ 单实例 │ │ -│ └─────────┬──────────┘ └─────────┬──────────┘ └─────────┬──────────┘ └─────────┬──────────┘ │ -└─────────────┼───────────────────────┼───────────────────────┼───────────────────────┼───────────────┘ - │ │ │ │ - │ │ │ │ -┌─────────────▼───────────────────────▼───────────────────────▼───────────────────────▼───────────────┐ -│ 应 用 编 排 层 (apps/operator) │ -│ │ -│ ┌───────────────────────────────────────────────────────────────────────────────────────┐ │ -│ │ apps/operator (Kubernetes Operator) │ │ -│ │ │ │ -│ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ │ -│ │ │ App CRD │ │GitSrv CRD│ │Email CRD │ │Hook CRD │ │Mig CRD │ │ │ -│ │ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ └────┬─────┘ │ │ -│ │ │ │ │ │ │ │ │ -│ │ ▼ ▼ ▼ ▼ ▼ │ │ -│ │ ┌──────────────────────────────────────────────────────────────────────────┐ │ │ -│ │ │ K8s 资源 (Deployments, Services, PVCs, Jobs) │ │ │ -│ │ └──────────────────────────────────────────────────────────────────────────┘ │ │ -│ └───────────────────────────────────────────────────────────────────────────────────────┘ │ -└────────────────────────────────────────────────────────────────────────────────────────────────────┘ - │ │ │ │ - │ │ │ │ -┌─────────────▼───────────────────────▼───────────────────────▼───────────────────────▼───────────────┐ -│ 业 务 逻 辑 层 (libs/service) │ -│ │ -│ ┌─────────────────────────────────────────────────────────────────────────────────────────┐ │ -│ │ AppService { 全局服务聚合 } │ │ -│ │ │ │ -│ │ ┌─────────┐ ┌────────┐ ┌─────┐ ┌──────────┐ ┌───────────┐ ┌────────┐ ┌───────────┐ │ │ -│ │ │ agent/ │ │ auth/ │ │git/ │ │ issue/ │ │ project/ │ │ user/ │ │ pull_req/ │ │ │ -│ │ │ (8文件) │ │ (10) │ │(16) │ │ (8) │ │ (20) │ │ (12) │ │ (5) │ │ │ -│ │ │ AI模型 │ │ 认证 │ │Git │ │ Issue │ │ 项目管理 │ │ 用户 │ │ PR审查 │ │ │ -│ │ │ 管理 │ │ 会话 │ │操作 │ │ 追踪 │ │ 权限控制 │ │ 偏好 │ │ 合并 │ │ │ -│ │ └─────────┘ └────────┘ └─────┘ └──────────┘ └───────────┘ └────────┘ └───────────┘ │ │ -│ │ │ │ -│ │ + utils/(project,repo,user) + ws_token + error + Pager │ │ -│ └──────────────────────────────────────┬──────────────────────────────────────────────────┘ │ -└──────────────────────────────────────────┼──────────────────────────────────────────────────────────┘ - │ - ┌──────────────────────┼──────────────────────┐ - │ │ │ -┌───────────────────▼──────────┐ ┌────────▼─────────────┐ ┌──────▼────────────────────────────┐ -│ HTTP 路由层 (libs/api) │ │ WebSocket 层 │ │ 后台 Worker 层 │ -│ 100 个路由文件 │ │ (libs/room) │ │ │ -│ │ │ │ │ libs/queue: │ -│ /api/auth/* (9端点) │ │ /ws │ │ MessageProducer │ -│ /api/git/* (100+端点) │ │ /ws/rooms/{id} │ │ RedisPubSub │ -│ /api/projects/* (50+端点) │ │ /ws/projects/{id} │ │ room_worker_task │ -│ /api/issue/* (30+端点) │ │ │ │ start_email_worker │ -│ /api/room/* (40+端点) │ │ 实时消息广播 │ │ │ -│ /api/pull_request/* (20端点)│ │ 多实例同步 │ │ libs/git/hook: │ -│ /api/agent/* (15端点) │ │ AI 流式输出 │ │ GitServiceHooks │ -│ /api/user/* (20端点) │ │ │ │ GitHookPool │ -│ /api/openapi/* (文档) │ │ │ │ │ -└───────────┬────────────────┘ └──────────┬───────────┘ └─────────────┬───────────────────────┘ - │ │ │ - └─────────────────────────────┼───────────────────────────┘ - │ -┌─────────────────────────────────────────▼────────────────────────────────────────────────────────┐ -│ 基 础 设 施 层 (Infrastructure Libs) │ -│ │ -│ ┌───────────────────┐ ┌───────────────────┐ ┌───────────────────┐ ┌───────────────────┐ │ -│ │ libs/models │ │ libs/db │ │ libs/config │ │ libs/session │ │ -│ │ 92 个实体文件 │ │ 数据库连接池 │ │ 全局配置管理 │ │ 会话管理中间件 │ │ -│ │ Sea-ORM 实体定义 │ │ 缓存抽象 │ │ .env 加载 │ │ Redis Store │ │ -│ │ 类型别名 │ │ 重试机制 │ │ 12 子模块 │ │ JWT + Cookie │ │ -│ └─────────┬─────────┘ └─────────┬─────────┘ └─────────┬─────────┘ └─────────┬─────────┘ │ -│ │ │ │ │ │ -│ ┌─────────▼─────────┐ ┌────────▼─────────┐ ┌─────────▼─────────┐ ┌─────────▼─────────┐ │ -│ │ libs/git │ │ libs/agent │ │ libs/email │ │ libs/avatar │ │ -│ │ 19 子模块 │ │ 6 子模块 │ │ SMTP 邮件发送 │ │ 图片处理 │ │ -│ │ libgit2 封装 │ │ OpenAI 集成 │ │ lettre 客户端 │ │ image crate │ │ -│ │ HTTP + SSH 协议 │ │ Qdrant 向量库 │ │ 模板引擎 │ │ 缩放/裁剪 │ │ -│ └─────────┬─────────┘ └─────────┬─────────┘ └─────────┬─────────┘ └─────────┬─────────┘ │ -│ │ │ │ │ │ -│ ┌─────────▼─────────┐ ┌────────▼─────────┐ ┌─────────▼───────────────────────▼─────────┐ │ -│ │ libs/queue │ │ libs/room │ │ libs/migrate │ │ -│ │ 消息队列 │ │ 实时聊天室 │ │ 82+ 数据库迁移脚本 │ │ -│ │ Redis Streams │ │ 19 子模块 │ │ sea-orm-migration │ │ -│ │ Pub/Sub │ │ WebSocket 管理 │ │ up/down/fresh/refresh/reset │ │ -│ └─────────┬─────────┘ └─────────┬─────────┘ └─────────────────────────────────────────┘ │ -│ │ │ │ -│ ┌─────────▼─────────┐ ┌────────▼─────────┐ │ -│ │ libs/webhook │ │ libs/rpc │ libs/transport │ -│ │ (占位) │ │ (占位) │ (占位) │ -│ └───────────────────┘ └─────────────────┘ │ -└────────────────────────────────────────────────────────────────────────────────────────────────┘ - │ │ - │ │ -┌─────────────▼──────────────────────▼────────────────────────────────────────────────────────────┐ -│ 存 储 层 │ -│ │ -│ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐ │ -│ │ PostgreSQL │ │ Redis │ │ Qdrant │ │ 文件系统 │ │ -│ │ :5432 │ │ :6379 │ │ :6333 │ │ │ │ -│ │ │ │ │ │ │ │ /data/avatars │ │ -│ │ • 用户数据 │ │ • 会话存储 │ │ • 向量嵌入 │ │ /data/repos │ │ -│ │ • 项目/仓库 │ │ • 缓存数据 │ │ • AI 索引 │ │ • 头像图片 │ │ -│ │ • Issue/PR │ │ • Pub/Sub │ │ • 相似度检索 │ │ • Git 仓库 │ │ -│ │ • Room 消息 │ │ • Stream 队列 │ │ │ │ • 上传文件 │ │ -│ │ • 评论/标签 │ │ • Hook 队列 │ │ │ │ │ │ -│ └──────────────────┘ └──────────────────┘ └──────────────────┘ └──────────────────┘ │ -└────────────────────────────────────────────────────────────────────────────────────────────────┘ - │ - │ 外部 API - │ -┌─────────────▼────────────────────────────────────────────────────────────────────────────────────┐ -│ 外 部 服 务 │ -│ │ -│ ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐ │ -│ │ SMTP 服务器 │ │ OpenAI API │ │ Embedding API │ │ -│ │ :587 │ │ HTTPS │ │ HTTPS │ │ -│ │ │ │ │ │ │ │ -│ │ • 邮件发送 │ │ • 聊天补全 │ │ • 文本向量化 │ │ -│ │ • 通知邮件 │ │ • AI 助手 │ │ • 相似度计算 │ │ -│ └──────────────────┘ └──────────────────┘ └──────────────────┘ │ -└────────────────────────────────────────────────────────────────────────────────────────────────┘ -``` - ---- - -## 前端架构分层 - -``` -┌────────────────────────────────────────────────────────────────────────────────────────────────┐ -│ 前 端 应 用 层 (src/) │ -│ │ -│ ┌──────────────────────────────────────────────────────────────────────────────────────────┐ │ -│ │ Vite + React + TypeScript │ │ -│ │ │ │ -│ │ src/main.tsx ──▶ App.tsx ──▶ BrowserRouter ──▶ Routes │ │ -│ │ │ │ -│ │ ┌───────────────────────┐ ┌───────────────────────┐ ┌───────────────────────┐ │ │ -│ │ │ 页面层 (app/) │ │ 组件层 (components/) │ │ 状态管理层 │ │ │ -│ │ │ 59 页面组件 │ │ 108 UI 组件 │ │ │ │ │ -│ │ │ │ │ │ │ TanStack Query │ │ │ -│ │ │ auth/ (4) │ │ ui/ (66) │ │ (服务端状态) │ │ │ -│ │ │ init/ (2) │ │ room/ (20) │ │ │ │ │ -│ │ │ user/ (1) │ │ repository/ (8) │ │ React Context │ │ │ -│ │ │ project/ (22) │ │ project/ (4) │ │ (全局状态) │ │ │ -│ │ │ repository/ (12) │ │ auth/ (2) │ │ │ │ │ -│ │ │ settings/ (8) │ │ layout/ (2) │ │ Local State │ │ │ -│ │ │ │ │ │ │ (组件状态) │ │ │ -│ │ └───────────┬───────────┘ └───────────┬───────────┘ └───────────┬────────────┘ │ │ -│ │ │ │ │ │ │ -│ │ └────────────────────────────┼────────────────────────────┘ │ │ -│ │ │ │ │ -│ │ ┌────────────────────────────────────────┼────────────────────────────────────────┐ │ │ -│ │ │ API 客户端层 │ │ │ -│ │ │ │ │ │ -│ │ │ src/client/ ──▶ openapi-ts 自动生成 (从 openapi.json) │ │ │ -│ │ │ 400+ API 函数 + 完整 TypeScript 类型 │ │ │ -│ │ │ Axios HTTP 客户端 │ │ │ -│ │ └──────────────────────────────────────────────────────────────────────────────────┘ │ │ -│ │ │ │ -│ │ ┌──────────────────────────────────────────────────────────────────────────────────┐ │ │ -│ │ │ 工具层 │ │ │ -│ │ │ │ │ │ -│ │ │ src/hooks/ ──▶ 自定义 React Hooks │ │ │ -│ │ │ src/lib/ ──▶ 工具函数 (api-error, rsa, date 等) │ │ │ -│ │ │ src/contexts/ ──▶ React Context (User, Theme 等) │ │ │ -│ │ │ src/assets/ ──▶ 静态资源 (图片、图标) │ │ │ -│ │ └──────────────────────────────────────────────────────────────────────────────────┘ │ │ -│ └──────────────────────────────────────────────────────────────────────────────────────────┘ │ -└────────────────────────────────────────────────────────────────────────────────────────────────┘ -``` - ---- - -## 前端路由结构 - -``` -/ 首页/仪表板 -│ -├── /auth/ 认证路由 -│ ├── /login 登录页 -│ ├── /register 注册页 -│ ├── /password/reset 密码重置 -│ └── /verify-email 邮箱验证 -│ -├── /init/ 初始化路由 -│ ├── /project 初始化项目 -│ └── /repository 初始化仓库 -│ -├── /user/:user 用户资料页 -│ -├── /settings/ 个人设置 -│ ├── /profile 个人资料 -│ ├── /account 账户设置 -│ ├── /security 安全设置 -│ ├── /tokens 访问令牌 -│ ├── /ssh-keys SSH 密钥 -│ ├── /preferences 偏好设置 -│ └── /activity 活动日志 -│ -├── /project/:project_name/ 项目路由 -│ ├── / 项目概览 -│ ├── /activity 项目活动 -│ ├── /repositories 仓库列表 -│ ├── /issues Issue 列表 -│ │ ├── /new 新建 Issue -│ │ └── /:issueNumber Issue 详情 -│ ├── /boards 看板列表 -│ │ └── /:boardId 看板详情 -│ ├── /members 成员管理 -│ ├── /room 聊天室列表 -│ │ └── /:roomId 聊天室 -│ ├── /articles 文章 -│ ├── /resources 资源 -│ └── /settings/ 项目设置 -│ ├── /general 通用设置 -│ ├── /labels 标签管理 -│ ├── /billing 账单 -│ ├── /members 成员管理 -│ ├── /oauth OAuth 配置 -│ └── /webhook Webhook 管理 -│ -├── /repository/:namespace/:repoName/ 仓库路由 -│ ├── / 仓库概览 -│ ├── /branches 分支管理 -│ ├── /commits 提交历史 -│ │ └── /:oid 提交详情 -│ ├── /contributors 贡献者 -│ ├── /files 文件浏览 -│ ├── /tags 标签 -│ ├── /pull-requests PR 列表 -│ │ ├── /new 新建 PR -│ │ └── /:prNumber PR 详情 -│ └── /settings 仓库设置 -│ -├── /search 全局搜索 -└── /notifications 通知中心 -``` - ---- - -## 后端服务依赖关系 - -``` -┌──────────────────────────────────────────────────────────────────────────────────────┐ -│ apps/ 应用依赖关系 │ -│ │ -│ apps/app ────────────────┐ │ -│ apps/email ──────────────┤ │ -│ apps/git-hook ───────────┤──▶ libs/config (全局配置) │ -│ apps/gitserver ──────────┤──▶ libs/db (数据库连接池 + 缓存) │ -│ apps/migrate ────────────┤──▶ libs/session (会话管理) │ -│ apps/operator ───────────┘──▶ libs/migrate (数据库迁移) │ -│ ├──▶ libs/service (业务逻辑层) │ -│ │ │ │ -│ │ ├──▶ libs/api (HTTP 路由) │ -│ │ │ │ -│ │ ├──▶ libs/agent (AI 服务) │ -│ │ ├──▶ libs/avatar (头像处理) │ -│ │ ├──▶ libs/email (邮件发送) │ -│ │ ├──▶ libs/room (聊天室) │ -│ │ │ │ │ -│ │ │ └──▶ libs/queue (消息队列) │ -│ │ │ │ -│ │ └──▶ libs/git (Git 操作) │ -│ │ │ │ -│ │ ├──▶ git2 (libgit2 绑定) │ -│ │ ├──▶ git2-hooks (Git 钩子) │ -│ │ └──▶ russh (SSH 协议) │ -│ │ │ -│ └──▶ libs/models (数据模型 - 所有层共享) │ -│ │ │ -│ ├──▶ users/ (12 实体) │ -│ ├──▶ projects/ (19 实体) │ -│ ├──▶ repos/ (16 实体) │ -│ ├──▶ issues/ (10 实体) │ -│ ├──▶ pull_request/ (5 实体) │ -│ ├──▶ rooms/ (11 实体) │ -│ ├──▶ agents/ (6 实体) │ -│ ├──▶ ai/ (3 实体) │ -│ └──▶ system/ (3 实体) │ -└──────────────────────────────────────────────────────────────────────────────────────┘ -``` - ---- - -## libs/models 实体分组 - -``` -┌─────────────────────────────────────────────────────────────────────────┐ -│ libs/models 实体分组 (92 个) │ -├─────────────────────────────────────────────────────────────────────────┤ -│ │ -│ Users (12 实体) │ -│ ┌─────────────────────────────────────────────────────────────────┐ │ -│ │ user 用户基本信息 │ │ -│ │ user_2fa 双因素认证 │ │ -│ │ user_activity_log 用户活动日志 │ │ -│ │ user_email 用户邮箱 │ │ -│ │ user_email_change 邮箱变更历史 │ │ -│ │ user_notification 用户通知 │ │ -│ │ user_password 用户密码 │ │ -│ │ user_password_reset 密码重置令牌 │ │ -│ │ user_preferences 用户偏好设置 │ │ -│ │ user_relation 用户关系 │ │ -│ │ user_ssh_key SSH 密钥 │ │ -│ │ user_token 访问令牌 │ │ -│ └─────────────────────────────────────────────────────────────────┘ │ -│ │ -│ Projects (19 实体) │ -│ ┌─────────────────────────────────────────────────────────────────┐ │ -│ │ project 项目基本信息 │ │ -│ │ project_access_log 访问日志 │ │ -│ │ project_activity 活动记录 │ │ -│ │ project_audit_log 审计日志 │ │ -│ │ project_billing 账单信息 │ │ -│ │ project_billing_history 账单历史 │ │ -│ │ project_board 看板 │ │ -│ │ project_board_card 看板卡片 │ │ -│ │ project_board_column 看板列 │ │ -│ │ project_follow 项目关注 │ │ -│ │ project_history_name 历史名称 │ │ -│ │ project_label 项目标签 │ │ -│ │ project_like 项目点赞 │ │ -│ │ project_member_ 成员邀请 │ │ -│ │ invitations │ │ -│ │ project_member_join_ 加入问答 │ │ -│ │ answers │ │ -│ │ project_member_join_ 加入请求 │ │ -│ │ request │ │ -│ │ project_member_join_ 加入设置 │ │ -│ │ settings │ │ -│ │ project_members 项目成员 │ │ -│ │ project_watch 项目观看 │ │ -│ └─────────────────────────────────────────────────────────────────┘ │ -│ │ -│ Repos (16 实体) │ -│ ┌─────────────────────────────────────────────────────────────────┐ │ -│ │ repo 仓库基本信息 │ │ -│ │ repo_branch 分支信息 │ │ -│ │ repo_branch_protect 分支保护 │ │ -│ │ repo_collaborator 协作者 │ │ -│ │ repo_commit 提交记录 │ │ -│ │ repo_fork 仓库 Fork │ │ -│ │ repo_history_name 历史名称 │ │ -│ │ repo_hook Git 钩子 │ │ -│ │ repo_lfs_lock LFS 锁定 │ │ -│ │ repo_lfs_object LFS 对象 │ │ -│ │ repo_lock 仓库锁定 │ │ -│ │ repo_star 仓库星标 │ │ -│ │ repo_tag 仓库标签 │ │ -│ │ repo_upstream 上游仓库 │ │ -│ │ repo_watch 仓库观看 │ │ -│ │ repo_webhook 仓库 Webhook │ │ -│ └─────────────────────────────────────────────────────────────────┘ │ -│ │ -│ Issues (10 实体) │ -│ ┌─────────────────────────────────────────────────────────────────┐ │ -│ │ issue Issue 基本信息 │ │ -│ │ issue_assignee Issue 负责人 │ │ -│ │ issue_comment Issue 评论 │ │ -│ │ issue_comment_reaction 评论表情 │ │ -│ │ issue_label Issue 标签 │ │ -│ │ issue_pull_request Issue 关联 PR │ │ -│ │ issue_reaction Issue 表情 │ │ -│ │ issue_repo Issue 仓库 │ │ -│ │ issue_subscriber Issue 订阅者 │ │ -│ └─────────────────────────────────────────────────────────────────┘ │ -│ │ -│ Pull Requests (5 实体) │ -│ ┌─────────────────────────────────────────────────────────────────┐ │ -│ │ pull_request PR 基本信息 │ │ -│ │ pull_request_commit PR 提交记录 │ │ -│ │ pull_request_review PR 审查 │ │ -│ │ pull_request_review_ PR 审查评论 │ │ -│ │ comment │ │ -│ │ pull_request_review_ PR 审查请求 │ │ -│ │ request │ │ -│ └─────────────────────────────────────────────────────────────────┘ │ -│ │ -│ Rooms (11 实体) │ -│ ┌─────────────────────────────────────────────────────────────────┐ │ -│ │ room 聊天室基本信息 │ │ -│ │ room_ai 聊天室 AI 配置 │ │ -│ │ room_category 聊天室分类 │ │ -│ │ room_member 聊天室成员 │ │ -│ │ room_message 聊天消息 │ │ -│ │ room_message_edit_ 消息编辑历史 │ │ -│ │ history │ │ -│ │ room_message_reaction 消息表情 │ │ -│ │ room_notifications 聊天室通知 │ │ -│ │ room_pin 聊天室置顶 │ │ -│ │ room_thread 聊天室 Thread │ │ -│ └─────────────────────────────────────────────────────────────────┘ │ -│ │ -│ Agents (6 实体) │ -│ ┌─────────────────────────────────────────────────────────────────┐ │ -│ │ model AI 模型 │ │ -│ │ model_capability 模型能力 │ │ -│ │ model_parameter_profile 模型参数配置 │ │ -│ │ model_pricing 模型定价 │ │ -│ │ model_provider 模型提供商 │ │ -│ │ model_version 模型版本 │ │ -│ └─────────────────────────────────────────────────────────────────┘ │ -│ │ -│ AI (3 实体) │ -│ ┌─────────────────────────────────────────────────────────────────┐ │ -│ │ ai_session AI 会话 │ │ -│ │ ai_tool_auth AI 工具认证 │ │ -│ │ ai_tool_call AI 工具调用 │ │ -│ └─────────────────────────────────────────────────────────────────┘ │ -│ │ -│ System (3 实体) │ -│ ┌─────────────────────────────────────────────────────────────────┐ │ -│ │ label 系统标签 │ │ -│ │ notify 系统通知 │ │ -│ └─────────────────────────────────────────────────────────────────┘ │ -└─────────────────────────────────────────────────────────────────────────┘ -``` - ---- - -## libs/service 业务模块 - -``` -┌─────────────────────────────────────────────────────────────────────────┐ -│ libs/service 业务模块 (93 个文件) │ -├─────────────────────────────────────────────────────────────────────────┤ -│ │ -│ agent/ AI 模型管理 (8 文件) │ -│ ├── code_review AI 代码审查 │ -│ ├── model AI 模型管理 │ -│ ├── model_capability 模型能力管理 │ -│ ├── model_parameter_ 模型参数配置 │ -│ │ profile │ -│ ├── model_pricing 模型定价管理 │ -│ ├── model_version 模型版本管理 │ -│ ├── pr_summary PR 摘要生成 │ -│ └── provider 模型提供商管理 │ -│ │ -│ auth/ 认证管理 (10 文件) │ -│ ├── captcha 验证码管理 │ -│ ├── email 邮箱认证 │ -│ ├── login 登录逻辑 │ -│ ├── logout 登出逻辑 │ -│ ├── me 当前用户信息 │ -│ ├── password 密码管理 │ -│ ├── register 注册逻辑 │ -│ ├── rsa RSA 加密 │ -│ └── totp TOTP 双因素认证 │ -│ │ -│ git/ Git 操作 (16 文件) │ -│ ├── archive 仓库归档 │ -│ ├── blocking 阻塞操作 │ -│ ├── blame Git Blame │ -│ ├── blob Blob 操作 │ -│ ├── branch 分支操作 │ -│ ├── branch_ 分支保护 │ -│ │ protection │ -│ ├── commit 提交操作 │ -│ ├── contributors 贡献者统计 │ -│ ├── diff Diff 操作 │ -│ ├── init 仓库初始化 │ -│ ├── refs 引用操作 │ -│ ├── repo 仓库操作 │ -│ ├── star 星标操作 │ -│ ├── tag 标签操作 │ -│ ├── tree 树操作 │ -│ └── watch 观看操作 │ -│ │ -│ issue/ Issue 管理 (8 文件) │ -│ ├── assignee 负责人管理 │ -│ ├── comment 评论管理 │ -│ ├── issue Issue CRUD │ -│ ├── label 标签管理 │ -│ ├── pull_request Issue 关联 PR │ -│ ├── reaction 表情回应 │ -│ ├── repo 仓库 Issue │ -│ └── subscriber 订阅者管理 │ -│ │ -│ project/ 项目管理 (20 文件) │ -│ ├── activity 项目活动 │ -│ ├── audit 审计日志 │ -│ ├── avatar 项目头像 │ -│ ├── billing 账单管理 │ -│ ├── board 看板管理 │ -│ ├── can_use 权限检查 │ -│ ├── info 项目信息 │ -│ ├── init 项目初始化 │ -│ ├── invitation 邀请管理 │ -│ ├── join_answers 加入问答 │ -│ ├── join_request 加入请求 │ -│ ├── join_settings 加入设置 │ -│ ├── labels 标签管理 │ -│ ├── like 点赞管理 │ -│ ├── members 成员管理 │ -│ ├── repo 仓库管理 │ -│ ├── repo_ 仓库权限 │ -│ │ permission │ -│ ├── settings 项目设置 │ -│ ├── standard 项目标准 │ -│ ├── transfer_repo 仓库转移 │ -│ └── watch 观看管理 │ -│ │ -│ pull_request/ PR 管理 (5 文件) │ -│ ├── merge PR 合并 │ -│ ├── pull_request PR CRUD │ -│ ├── review PR 审查 │ -│ ├── review_comment 审查评论 │ -│ └── review_request 审查请求 │ -│ │ -│ user/ 用户管理 (12 文件) │ -│ ├── access_key 访问密钥 │ -│ ├── avatar 用户头像 │ -│ ├── chpc 用户 CHPC │ -│ ├── notification 通知管理 │ -│ ├── notify 通知发送 │ -│ ├── preferences 偏好设置 │ -│ ├── profile 用户资料 │ -│ ├── projects 用户项目 │ -│ ├── repository 用户仓库 │ -│ ├── ssh_key SSH 密钥 │ -│ ├── subscribe 订阅管理 │ -│ └── user_info 用户信息 │ -│ │ -│ utils/ 工具函数 (3 文件) │ -│ ├── project 项目工具 │ -│ ├── repo 仓库工具 │ -│ └── user 用户工具 │ -│ │ -│ ws_token WebSocket Token 服务 │ -│ error 服务层错误 │ -│ Pager 分页结构体 │ -└─────────────────────────────────────────────────────────────────────────┘ -``` - ---- - -## libs/api 路由模块 - -``` -┌─────────────────────────────────────────────────────────────────────────┐ -│ libs/api 路由模块 (100 个文件) │ -├─────────────────────────────────────────────────────────────────────────┤ -│ │ -│ auth/ 认证路由 (9 文件) │ -│ ├── captcha 验证码接口 │ -│ ├── email 邮箱认证接口 │ -│ ├── login 登录接口 │ -│ ├── logout 登出接口 │ -│ ├── me 当前用户接口 │ -│ ├── password 密码接口 │ -│ ├── register 注册接口 │ -│ ├── totp TOTP 接口 │ -│ └── ws_token WebSocket Token 接口 │ -│ │ -│ git/ Git 路由 (18 文件) │ -│ ├── archive 归档接口 │ -│ ├── blame Blame 接口 │ -│ ├── blob Blob 接口 │ -│ ├── branch 分支接口 │ -│ ├── branch_ 分支保护接口 │ -│ │ protection │ -│ ├── commit 提交接口 │ -│ ├── contributors 贡献者接口 │ -│ ├── diff Diff 接口 │ -│ ├── init 初始化接口 │ -│ ├── refs 引用接口 │ -│ ├── repo 仓库接口 │ -│ ├── star 星标接口 │ -│ ├── tag 标签接口 │ -│ ├── tree 树接口 │ -│ └── watch 观看接口 │ -│ │ -│ project/ 项目路由 (17 文件) │ -│ ├── activity 活动接口 │ -│ ├── audit 审计接口 │ -│ ├── billing 账单接口 │ -│ ├── board 看板接口 │ -│ ├── info 信息接口 │ -│ ├── init 初始化接口 │ -│ ├── invitation 邀请接口 │ -│ ├── join_answers 加入问答接口 │ -│ ├── join_request 加入请求接口 │ -│ ├── join_settings 加入设置接口 │ -│ ├── labels 标签接口 │ -│ ├── like 点赞接口 │ -│ ├── members 成员接口 │ -│ ├── repo 仓库接口 │ -│ ├── settings 设置接口 │ -│ ├── transfer_repo 仓库转移接口 │ -│ └── watch 观看接口 │ -│ │ -│ issue/ Issue 路由 (10 文件) │ -│ ├── assignee 负责人接口 │ -│ ├── comment 评论接口 │ -│ ├── comment_ 评论表情接口 │ -│ │ reaction │ -│ ├── issue_label Issue 标签接口 │ -│ ├── label 标签接口 │ -│ ├── pull_request Issue 关联 PR 接口 │ -│ ├── reaction 表情接口 │ -│ ├── repo 仓库 Issue 接口 │ -│ └── subscriber 订阅者接口 │ -│ │ -│ room/ 聊天室路由 (14 文件) │ -│ ├── ai AI 接口 │ -│ ├── category 分类接口 │ -│ ├── draft_and_ 草稿和历史接口 │ -│ │ history │ -│ ├── member 成员接口 │ -│ ├── message 消息接口 │ -│ ├── notification 通知接口 │ -│ ├── pin 置顶接口 │ -│ ├── reaction 表情接口 │ -│ ├── room 聊天室接口 │ -│ ├── thread Thread 接口 │ -│ ├── ws WebSocket 接口 │ -│ ├── ws_handler WebSocket 处理器 │ -│ ├── ws_types WebSocket 类型 │ -│ └── ws_universal 通用 WebSocket 接口 │ -│ │ -│ pull_request/ PR 路由 (5 文件) │ -│ ├── merge 合并接口 │ -│ ├── pull_request PR CRUD 接口 │ -│ ├── review 审查接口 │ -│ ├── review_comment 审查评论接口 │ -│ └── review_request 审查请求接口 │ -│ │ -│ agent/ AI Agent 路由 (8 文件) │ -│ ├── code_review 代码审查接口 │ -│ ├── model 模型接口 │ -│ ├── model_ 模型能力接口 │ -│ │ capability │ -│ ├── model_ 模型参数配置接口 │ -│ │ parameter_profile │ -│ ├── model_pricing 模型定价接口 │ -│ ├── model_version 模型版本接口 │ -│ ├── pr_summary PR 摘要接口 │ -│ └── provider 模型提供商接口 │ -│ │ -│ user/ 用户路由 (10 文件) │ -│ ├── access_key 访问密钥接口 │ -│ ├── chpc CHPC 接口 │ -│ ├── notification 通知接口 │ -│ ├── preferences 偏好接口 │ -│ ├── profile 资料接口 │ -│ ├── projects 项目接口 │ -│ ├── repository 仓库接口 │ -│ ├── ssh_key SSH 密钥接口 │ -│ ├── subscribe 订阅接口 │ -│ └── user_info 用户信息接口 │ -│ │ -│ openapi/ OpenAPI 文档生成 │ -│ route/ 路由聚合 │ -│ error/ API 错误处理 │ -└─────────────────────────────────────────────────────────────────────────┘ -``` - ---- - -## 服务间通信机制 - -``` -┌────────────────────────────────────────────────────────────────────────────────────────────┐ -│ 服务间通信机制 │ -│ │ -│ ┌──────────────────────────────────────────────────────────────────────────────────┐ │ -│ │ Redis (核心通信总线) │ │ -│ │ │ │ -│ │ Redis Streams ──▶ 异步消息队列 │ │ -│ │ ├── room:stream:{room_id} 房间消息持久化 │ │ -│ │ └── email:stream 邮件发送队列 │ │ -│ │ │ │ -│ │ Redis Pub/Sub ──▶ 实时事件广播 │ │ -│ │ ├── room:pub:{room_id} 房间级广播 │ │ -│ │ └── project:pub:{proj_id} 项目级广播 │ │ -│ │ │ │ -│ │ Redis Lists ──▶ 任务队列 │ │ -│ │ ├── {hook}:sync Git Hook 同步任务 │ │ -│ │ ├── {hook}:fsck Git Hook 完整性检查 │ │ -│ │ └── {hook}:gc Git Hook 垃圾回收 │ │ -│ └──────────────────────────────────────────────────────────────────────────────────┘ │ -│ │ -│ ┌──────────────────────────────────────────────────────────────────────────────────┐ │ -│ │ HTTP/REST API ──▶ 同步服务调用 │ │ -│ │ ├── app ↔ gitserver Git 元数据查询 │ │ -│ │ └── app → 外部 AI 服务 OpenAI 兼容 API 调用 │ │ -│ └──────────────────────────────────────────────────────────────────────────────────┘ │ -│ │ -│ ┌──────────────────────────────────────────────────────────────────────────────────┐ │ -│ │ WebSocket ──▶ 客户端实时通信 │ │ -│ │ ├── /ws 通用 WebSocket (多房间订阅) │ │ -│ │ ├── /ws/rooms/{room_id} 房间级 WebSocket │ │ -│ │ └── /ws/projects/{proj_id} 项目级 WebSocket │ │ -│ └──────────────────────────────────────────────────────────────────────────────────┘ │ -│ │ -│ ┌──────────────────────────────────────────────────────────────────────────────────┐ │ -│ │ Kubernetes CRD + Operator ──▶ 基础设施编排 │ │ -│ │ ├── apps.code.dev App CRD → Deployment + Service │ │ -│ │ ├── gitservers.code.dev GitServer CRD → Deployment + Service + PVC │ │ -│ │ ├── emailworkers.code.dev EmailWorker CRD → Deployment │ │ -│ │ ├── githooks.code.dev GitHook CRD → Deployment + ConfigMap │ │ -│ │ └── migrates.code.dev Migrate CRD → Job │ │ -│ └──────────────────────────────────────────────────────────────────────────────────┘ │ -└────────────────────────────────────────────────────────────────────────────────────────────┘ -``` - ---- - -## 数据流详解 - -### 1. 聊天消息流程 - -``` -客户端 A app 实例 1 Redis app 实例 2 客户端 B - │ │ │ │ │ - │── WS 发送消息 ───────▶│ │ │ │ - │ │── XADD ──────────────▶│ │ │ - │ │ room:stream:{id} │ │ │ - │ │── PUBLISH ────────────▶│ │ │ - │ │ room:pub:{id} │ │ │ - │ │ │── 事件通知 ────────────▶│ │ - │ │ │ │── WS 推送 ────────────▶│ - │◀─ ACK ───────────────│ │ │ │ - │ │ │ │ │ - │ │◀──── XREADGROUP ─────│ │ │ - │ │ (room_worker) │ │ │ - │ │── 写入 PostgreSQL ────│ │ │ -``` - -### 2. Git Push 流程 - -``` -客户端 gitserver Redis git-hook PostgreSQL - │ │ │ │ │ - │── git push ────────▶│ │ │ │ - │ (HTTP/SSH) │ │ │ │ - │ │── git-receive-pack──▶│ │ │ - │ │── LPUSH ────────────▶│ │ │ - │ │ {hook}:sync │ │ │ - │◀─ ACK ─────────────│ │ │ │ - │ │ │── BRPOPLPUSH ─────▶│ │ - │ │ │ │── 同步元数据 ────────▶│ - │ │ │ │── 可选: fsck/gc ─────▶│ - │ │ │◀── XACK ──────────│ │ -``` - -### 3. 邮件发送流程 - -``` -业务逻辑 app Redis email-worker SMTP - │ │ │ │ │ - │── 触发邮件 ────────▶│ │ │ │ - │ │── XADD ───────────▶│ │ │ - │ │ email:stream │ │ │ - │◀─ 返回 ───────────│ │ │ │ - │ │ │── XREADGROUP ─────▶│ │ - │ │ │ │── 渲染模板 ──────────▶│ - │ │ │ │── SMTP 发送 ─────────▶│ - │ │ │◀── XACK ──────────│ │ -``` - -### 4. AI 聊天流程 - -``` -客户端 app OpenAI API Qdrant PostgreSQL - │ │ │ │ │ - │── AI 消息 ──────────▶│ │ │ │ - │ │── 生成 Embedding ──▶│ │ │ - │ │◀──── 向量 ──────────│ │ │ - │ │── 存储向量 ─────────────────────────────▶│ │ - │ │── 流式 Chat ─────────▶│ │ │ - │◀─ Stream Chunk ──────│◀──── Stream ─────────│ │ │ - │ │ │ │ │ - │ │── 保存消息 ────────────────────────────────────────────────▶│ - │ │── 检索相似消息 ────────────────────────▶│ │ - │ │◀── 相似结果 ───────────────────────────│ │ -``` - ---- - -## 技术栈汇总 - -### 后端技术栈 - -| 类别 | 技术 | 版本 | -|------|------|------| -| **语言** | Rust | Edition 2024 | -| **Web 框架** | Actix-web | 4.13.0 | -| **WebSocket** | Actix-ws | 0.4.0 | -| **ORM** | SeaORM | 2.0.0-rc.37 | -| **数据库** | PostgreSQL | - | -| **缓存/消息** | Redis | 1.1.0 | -| **向量库** | Qdrant | 1.17.0 | -| **Git** | git2 / russh | 0.20.0 / 0.55.0 | -| **邮件** | Lettre | 0.11.19 | -| **AI** | async-openai | 0.34.0 | -| **K8s** | kube-rs | 0.98 | -| **gRPC** | Tonic | 0.14.5 | -| **日志** | slog / tracing | 2.8 / 0.1.44 | - -### 前端技术栈 - -| 类别 | 技术 | 版本 | -|------|------|------| -| **语言** | TypeScript | 5.9 | -| **框架** | React | 19.2 | -| **路由** | React Router | 7.13 | -| **构建** | Vite + SWC | 8.0 | -| **UI** | shadcn/ui + Tailwind | 4.11 / 4.2 | -| **状态** | TanStack Query | 5.96 | -| **HTTP** | Axios + OpenAPI 生成 | 1.7 | -| **Markdown** | react-markdown + Shiki | 10 / 1 | -| **拖拽** | dnd-kit | 6.3 | - ---- - -## Docker 与 K8s 部署 - -``` -┌──────────────────────────────────────────────────────────────────────────────┐ -│ Docker 镜像 (6 个) │ -│ │ -│ docker/app.Dockerfile ──▶ apps/app 主应用镜像 │ -│ docker/email-worker.Dockerfile ──▶ apps/email 邮件 Worker 镜像 │ -│ docker/git-hook.Dockerfile ──▶ apps/git-hook Git Hook 镜像 │ -│ docker/gitserver.Dockerfile ──▶ apps/gitserver Git Server 镜像 │ -│ docker/migrate.Dockerfile ──▶ apps/migrate 数据库迁移镜像 │ -│ docker/operator.Dockerfile ──▶ apps/operator K8s Operator 镜像 │ -└──────────────────────────────────────────────────────────────────────────────┘ - -┌──────────────────────────────────────────────────────────────────────────────┐ -│ Kubernetes CRD (5 个) │ -│ │ -│ docker/crd/app-crd.yaml ──▶ apps.code.dev │ -│ docker/crd/gitserver-crd.yaml ──▶ gitservers.code.dev │ -│ docker/crd/email-worker-crd.yaml ──▶ emailworkers.code.dev │ -│ docker/crd/git-hook-crd.yaml ──▶ githooks.code.dev │ -│ docker/crd/migrate-crd.yaml ──▶ migrates.code.dev │ -└──────────────────────────────────────────────────────────────────────────────┘ - -┌──────────────────────────────────────────────────────────────────────────────┐ -│ K8s 部署配置 │ -│ │ -│ docker/operator/deployment.yaml ──▶ Operator Deployment │ -│ docker/operator/example/ ──▶ CRD 使用示例 │ -│ code-system.yaml │ -└──────────────────────────────────────────────────────────────────────────────┘ -``` - ---- - -## 关键设计特点 - -| 特点 | 描述 | -|------|------| -| **Monorepo 架构** | Rust workspace + 前端 monorepo，统一管理 | -| **清晰分层** | 路由层 → 业务层 → 基础设施层 → 存储层，职责明确 | -| **异步优先** | 基于 Redis Streams 的异步消息处理 | -| **实时通信** | WebSocket + Redis Pub/Sub 实现多实例同步 | -| **K8s 原生** | Operator + 5 个 CRD 管理全生命周期 | -| **类型安全** | OpenAPI 自动生成 TypeScript 客户端 | -| **可扩展** | 服务独立部署，水平扩展 | -| **Git 兼容** | 完整支持 HTTP/SSH Git 协议 + LFS | -| **AI 集成** | 原生集成 OpenAI 兼容 API + 向量检索 | -| **92 个数据库实体** | 覆盖用户、项目、仓库、Issue、PR、聊天室、AI 等完整业务域 | diff --git a/docs/BRANCH-PROTECTION.md b/docs/BRANCH-PROTECTION.md deleted file mode 100644 index 114961e..0000000 --- a/docs/BRANCH-PROTECTION.md +++ /dev/null @@ -1,71 +0,0 @@ -# 分支保护规则配置 - -以下规则需要在 GitHub 仓库设置界面手动配置，或通过 Terraform/Ansible 等基础设施即代码工具自动化。 - -## main 分支保护规则 - -路径：**Settings → Branches → Branch protection rules → Add rule** - -### 必填项 - -| 配置项 | 值 | 说明 | -|--------|-----|------| -| Branch name pattern | `main` | 匹配 main 分支 | -| Protect matching branches | ✅ 启用 | 开启分支保护 | -| **Require pull request reviews** | ✅ 要求 | 合并前至少 1 人 review | -| **Require approvals** | `1` | 最少审批数量 | -| Dismiss stale approvals | ✅ 启用 | PR 更新后需重新审批 | -| Require review from Code Owners | ☐ 可选 | 建议开启 | -| **Require status checks to pass before merging** | ✅ 要求 | 必须通过 CI | -| Required status checks | `rust-check`, `rust-test`, `frontend-check` | CI job 名称 | -| **Require branches to be up to date before merging** | ☐ 可选 | 建议不启用，避免复杂 | -| Do not allow bypassing the above settings | ✅ 启用 | 即使 admin 不能绕过 | - -### 安全设置 - -| 配置项 | 值 | -|--------|-----| -| Lock branch | ☐ 可选（不勾选，CI 仍可推送） | -| Allow force pushes | ☐ 禁用（禁止 force push） | -| Allow deletions | ☐ 禁用（禁止删除分支） | - -## develop 分支保护规则 - -路径：**Settings → Branches → Branch protection rules → Add rule** - -| 配置项 | 值 | -|--------|-----| -| Branch name pattern | `develop` | -| Protect matching branches | ✅ 启用 | -| Require pull request reviews | ✅ 要求 | -| Require approvals | `1` | -| Dismiss stale approvals | ✅ 启用 | -| Require status checks to pass before merging | ✅ 要求 | -| Required status checks | `rust-check`, `rust-test`, `frontend-check` | -| Do not allow bypassing | ✅ 启用 | -| Allow force pushes | ☐ 禁用 | - -## 自动清理已合并分支 - -建议安装 GitHub App [Branch Clean Up](https://github.com/apps/branch-cleanup) 或在 PR 合并后自动删除源分支： - -- **Settings → General → Automatically delete head branches** → ✅ 启用 - -## 使用 GitHub CLI 配置（自动化） - -如果需要通过代码自动化配置，可以使用 `gh` CLI： - -```bash -# 安装 gh -brew install gh - -# 登录 -gh auth login - -# 创建 branch protection rule for main -gh api repos/{owner}/{repo}/branches/main/protection -X PUT \ - -f required_status_checks='{"strict":true,"contexts":["rust-check","rust-test","frontend-check"]}' \ - -f enforce_admins=true \ - -f required_pull_request_reviews='{"required_approving_review_count":1,"dismiss_stale_reviews":true}' \ - -f allow_force_pushes=false -``` diff --git a/docs/COMMIT-CONVENTION.md b/docs/COMMIT-CONVENTION.md deleted file mode 100644 index 44c95e1..0000000 --- a/docs/COMMIT-CONVENTION.md +++ /dev/null @@ -1,77 +0,0 @@ -# Commit Message 规范 - -本项目采用 [Conventional Commits](https://www.conventionalcommits.org/) 规范。 - -## 格式 - -``` -(): - -[optional body] - -[optional footer(s)] -``` - -## 示例 - -``` -feat(api): add workspace member invitation endpoint -fix(frontend): correct sidebar collapse state on resize -docs: update API documentation for /repos endpoints -refactor(service): extract auth logic into separate module -hotfix(k8s): add missing health probe for gitserver -``` - -## Type - -| Type | Description | -|------|-------------| -| `feat` | 新功能 | -| `fix` | Bug 修复 | -| `docs` | 仅文档变更 | -| `style` | 代码格式（不影响功能） | -| `refactor` | 重构（不是修复也不是新功能） | -| `perf` | 性能优化 | -| `test` | 添加或修正测试 | -| `chore` | 构建或辅助工具变更 | -| `build` | 影响构建系统或依赖 | -| `ci` | CI/CD 配置 | -| `revert` | 回滚之前的提交 | - -## Scope - -| Scope | 说明 | -|-------|------| -| `frontend` | React 前端 | -| `api` | REST API 路由 | -| `service` | 业务逻辑层 | -| `models` | 数据库模型 | -| `k8s` | Kubernetes 部署 | -| `deploy` | Docker/Helm 部署 | -| `git` | Git 仓库功能 | -| `room` | 实时聊天 | -| `agent` | AI Agent | -| `db` | 数据库迁移 | - -## 规则 - -1. **每条提交应仅包含一个逻辑变更** -2. **description 首字母小写，使用祈使句** -3. **禁止句号结尾** -4. **Body 解释 what 和 why，不解释 how** -5. **Footer 引用相关 Issue** - -## Git Alias - -在 `~/.gitconfig` 中添加快捷别名： - -```ini -[alias] - co = checkout - cm = commit -m - lg = log --oneline --graph --decorate - amend = commit --amend --no-edit - uncommit = reset --soft HEAD~1 -``` - -或使用 commitlint 钩子自动验证（见 `.husky/commit-msg`）。 diff --git a/docs/GITFLOW.md b/docs/GITFLOW.md deleted file mode 100644 index 31a2a00..0000000 --- a/docs/GITFLOW.md +++ /dev/null @@ -1,191 +0,0 @@ -# Git Flow 分支策略 - -## 概述 - -本项目采用 [Git Flow](https://nvie.com/posts/a-successful-git-branching-model/) 分支模型，结合 GitHub Flow 的简洁性，适合本项目的发布节奏。 - -## 分支结构 - -``` -main ← 生产环境，始终保持可发布状态 -│ -├── develop ← 开发集成分支，所有功能分支合并至此 -│ │ -│ ├── feature/xxx ← 功能分支，从 develop 创建 -│ │ -│ ├── release/0.3.0 ← 发布分支，从 develop 创建 -│ │ -│ └── hotfix/0.2.10 ← 热修复分支，从 main 创建 -``` - -## 长期分支 - -| 分支 | 用途 | 保护状态 | -|------|------|----------| -| `main` | 生产环境代码 | 强制保护，禁止 force push | -| `develop` | 开发集成，所有功能最终汇入 | 建议保护 | - -## 临时分支 - -| 前缀 | 用途 | 创建来源 | 合并目标 | -|------|------|----------|----------| -| `feature/` | 新功能开发 | `develop` | `develop` | -| `release/` | 发布准备 | `develop` | `main` + `develop` | -| `hotfix/` | 生产环境紧急修复 | `main` | `main` + `develop` | - -## 工作流程 - -### 1. 功能开发 (feature) - -```bash -# 从 develop 创建功能分支 -git checkout develop -git checkout -b feature/user-dashboard - -# 开发完成后，提交 PR 到 develop -git push origin feature/user-dashboard -``` - -### 2. 发布准备 (release) - -```bash -# 从 develop 创建发布分支 -git checkout develop -git checkout -b release/0.3.0 - -# 在 release 分支上做最后的修复和版本号更新 -# 修复完成后，合并到 main 并打标签 -git checkout main -git merge release/0.3.0 --no-ff -git tag -a v0.3.0 -m "Release v0.3.0" - -# 同时合并回 develop -git checkout develop -git merge release/0.3.0 --no-ff - -# 删除发布分支 -git branch -d release/0.3.0 -``` - -### 3. 热修复 (hotfix) - -```bash -# 从 main 创建热修复分支 -git checkout main -git checkout -b hotfix/0.2.10 - -# 修复完成后，合并到 main 并打标签 -git checkout main -git merge hotfix/0.2.10 --no-ff -git tag -a v0.2.10 -m "Hotfix v0.2.10" - -# 同时合并回 develop -git checkout develop -git merge hotfix/0.2.10 --no-ff - -# 删除热修复分支 -git branch -d hotfix/0.2.10 -``` - -## 分支命名规范 - -``` -feature/-<简短描述> -release/<版本号> -hotfix/<版本号> -``` - -示例： -- `feature/123-user-dashboard` -- `feature/456-oauth-integration` -- `release/0.3.0` -- `hotfix/0.2.10` - -## 合并 (Merge) 策略 - -- **功能分支 → develop**：使用 `git merge --no-ff`，保留功能分支历史 -- **release → main + develop**：使用 `git merge --no-ff` -- **hotfix → main + develop**：使用 `git merge --no-ff` -- **PR 合并**：在 GitHub 界面使用 "Squash and merge" 或 "Create a merge commit" - -## 提交信息规范 - -采用 [Conventional Commits](https://www.conventionalcommits.org/) 格式： - -``` -(): - -[optional body] - -[optional footer] -``` - -### Type 类型 - -| Type | 说明 | -|------|------| -| `feat` | 新功能 | -| `fix` | Bug 修复 | -| `docs` | 仅文档变更 | -| `style` | 代码格式（不影响功能） | -| `refactor` | 重构（不是修复也不是新功能） | -| `perf` | 性能优化 | -| `test` | 添加或修正测试 | -| `chore` | 构建或辅助工具变更 | - -### Scope 范围 - -使用受影响的主要模块： - -| Scope | 说明 | -|-------|------| -| `frontend` | 前端代码 | -| `backend` | 后端通用 | -| `api` | API 路由/Handler | -| `service` | 业务逻辑层 | -| `models` | 数据库模型 | -| `k8s` | Kubernetes 部署 | -| `deploy` | 部署配置 | -| `git` | Git 相关功能 | -| `room` | 实时聊天功能 | -| `agent` | AI Agent 功能 | -| `db` | 数据库/迁移 | - -### 示例 - -``` -feat(frontend): add user dashboard page -fix(api): handle nil pointer in workspace handler -docs: update API documentation for /repos endpoints -refactor(service): extract auth logic into separate module -hotfix(k8s): add missing health probe for gitserver -``` - -## 标签 (Tag) 策略 - -使用语义化版本号： - -```bash -# 发布标签 -git tag -a v0.2.9 -m "Release v0.2.9" - -# 带签名的标签（推荐） -git tag -s v0.2.9 -m "Release v0.2.9" -``` - -版本号格式：`v..` -- `major`：破坏性变更 -- `minor`：新功能（向后兼容） -- `patch`：Bug 修复 - -## 分支清理 - -功能分支合并后应删除： - -```bash -# 删除本地分支 -git branch -d feature/xxx - -# 删除远程分支 -git push origin --delete feature/xxx -```