264 lines
7.7 KiB
Markdown
264 lines
7.7 KiB
Markdown
# Code API
|
|
|
|
> 一个现代化的代码协作与团队沟通平台，融合 GitHub 的代码管理体验与 Slack 的实时沟通功能。
|
|
|
|
## 项目概述
|
|
|
|
Code API 是一个全栈 monorepo 项目，采用 Rust 后端 + React 前端的技术栈。项目实现了类似 GitHub 的 Issue 追踪、Pull Request 代码审查、Git 仓库管理，以及类似 Slack 的实时聊天 Room 功能。
|
|
|
|
### 核心功能
|
|
|
|
- **代码仓库管理** — Git 仓库浏览、分支管理、文件操作
|
|
- **Issue 追踪** — 创建、分配、标签、评论 Issue
|
|
- **Pull Request** — 代码审查、Inline Comment、CI 状态检查
|
|
- **实时聊天 (Room)** — 团队频道、消息回复、Thread 讨论
|
|
- **通知系统** — 邮件通知、Webhook 集成
|
|
- **用户系统** — 认证、会话管理、权限控制
|
|
|
|
## 技术栈
|
|
|
|
### 后端 (Rust)
|
|
|
|
| 类别 | 技术 |
|
|
|------|------|
|
|
| 语言 | Rust 2024 Edition |
|
|
| Web 框架 | Actix-web |
|
|
| ORM | SeaORM |
|
|
| 数据库 | PostgreSQL |
|
|
| 缓存 | Redis |
|
|
| 实时通信 | WebSocket (actix-ws) |
|
|
| 消息队列 | NATS |
|
|
| 向量数据库 | Qdrant |
|
|
| Git 操作 | git2 / git2-ext |
|
|
| 认证 | JWT + Session |
|
|
| API 文档 | utoipa (OpenAPI) |
|
|
|
|
### 前端 (TypeScript/React)
|
|
|
|
| 类别 | 技术 |
|
|
|------|------|
|
|
| 语言 | TypeScript 5.9 |
|
|
| 框架 | React 19 |
|
|
| 路由 | React Router v7 |
|
|
| 构建工具 | Vite 8 + SWC |
|
|
| UI 组件 | shadcn/ui + Tailwind CSS 4 |
|
|
| 状态管理 | TanStack Query |
|
|
| HTTP 客户端 | Axios + OpenAPI 生成 |
|
|
| Markdown | react-markdown + Shiki |
|
|
| 拖拽 | dnd-kit |
|
|
|
|
## 项目结构
|
|
|
|
```
|
|
code/
|
|
├── apps/ # 应用程序入口
|
|
│ ├── app/ # 主 Web 应用
|
|
│ ├── gitserver/ # Git HTTP/SSH 服务器
|
|
│ ├── git-hook/ # Git Hook 处理服务
|
|
│ ├── email/ # 邮件发送服务
|
|
│ ├── migrate/ # 数据库迁移工具
|
|
│ └── operator/ # Kubernetes 操作器
|
|
├── libs/ # 共享库
|
|
│ ├── api/ # REST API 路由与处理器
|
|
│ ├── models/ # 数据库模型 (SeaORM)
|
|
│ ├── service/ # 业务逻辑层
|
|
│ ├── db/ # 数据库连接池
|
|
│ ├── config/ # 配置管理
|
|
│ ├── session/ # 会话管理
|
|
│ ├── git/ # Git 操作封装
|
|
│ ├── room/ # 实时聊天服务
|
|
│ ├── queue/ # 消息队列
|
|
│ ├── webhook/ # Webhook 处理
|
|
│ ├── rpc/ # RPC 服务 (gRPC/Tonic)
|
|
│ ├── email/ # 邮件发送
|
|
│ ├── agent/ # AI Agent 集成
|
|
│ ├── avatar/ # 头像处理
|
|
│ ├── transport/ # 传输层
|
|
│ └── migrate/ # 迁移脚本
|
|
├── src/ # 前端源代码
|
|
│ ├── app/ # 页面路由组件
|
|
│ ├── components/ # 可复用组件
|
|
│ ├── contexts/ # React Context
|
|
│ ├── client/ # API 客户端 (OpenAPI 生成)
|
|
│ ├── hooks/ # 自定义 Hooks
|
|
│ └── lib/ # 工具函数
|
|
├── docker/ # Docker 配置
|
|
├── scripts/ # 构建脚本
|
|
├── openapi.json # OpenAPI 规范文件
|
|
└── Cargo.toml # Rust Workspace 配置
|
|
```
|
|
|
|
## 快速开始
|
|
|
|
### 环境要求
|
|
|
|
- **Rust**: 最新稳定版 (Edition 2024)
|
|
- **Node.js**: >= 20
|
|
- **pnpm**: >= 10
|
|
- **PostgreSQL**: >= 14
|
|
- **Redis**: >= 6
|
|
|
|
### 安装步骤
|
|
|
|
1. **克隆仓库**
|
|
```bash
|
|
git clone <repository-url>
|
|
cd code
|
|
```
|
|
|
|
2. **配置环境变量**
|
|
```bash
|
|
cp .env.example .env
|
|
# 编辑 .env 文件，配置数据库连接等信息
|
|
```
|
|
|
|
3. **启动数据库与 Redis**
|
|
```bash
|
|
# 使用 Docker 启动（推荐）
|
|
docker compose -f docker/docker-compose.yml up -d
|
|
```
|
|
|
|
4. **数据库迁移**
|
|
```bash
|
|
cargo run -p migrate
|
|
```
|
|
|
|
5. **启动后端服务**
|
|
```bash
|
|
cargo run -p app
|
|
```
|
|
|
|
6. **启动前端开发服务器**
|
|
```bash
|
|
pnpm install
|
|
pnpm dev
|
|
```
|
|
|
|
7. **访问应用**
|
|
- 前端: http://localhost:5173
|
|
- 后端 API: http://localhost:8080
|
|
|
|
## 开发指南
|
|
|
|
### 后端开发
|
|
|
|
```bash
|
|
# 运行所有测试
|
|
cargo test
|
|
|
|
# 运行特定模块测试
|
|
cargo test -p service
|
|
|
|
# 检查代码质量
|
|
cargo clippy --workspace
|
|
|
|
# 格式化代码
|
|
cargo fmt --workspace
|
|
|
|
# 生成 OpenAPI 文档
|
|
pnpm openapi:gen-json
|
|
```
|
|
|
|
### 前端开发
|
|
|
|
```bash
|
|
# 安装依赖
|
|
pnpm install
|
|
|
|
# 启动开发服务器
|
|
pnpm dev
|
|
|
|
# 构建生产版本
|
|
pnpm build
|
|
|
|
# 代码检查
|
|
pnpm lint
|
|
|
|
# 生成 OpenAPI 客户端
|
|
pnpm openapi:gen
|
|
```
|
|
|
|
### 数据库迁移
|
|
|
|
```bash
|
|
# 创建新迁移
|
|
cd libs/migrate && cargo run -- create <migration_name>
|
|
|
|
# 执行迁移
|
|
cargo run -p migrate
|
|
```
|
|
|
|
## 配置说明
|
|
|
|
### 必需配置项
|
|
|
|
| 变量名 | 说明 | 示例 |
|
|
|--------|------|------|
|
|
| `APP_DATABASE_URL` | PostgreSQL 连接 | `postgresql://user:pass@localhost/db` |
|
|
| `APP_REDIS_URL` | Redis 连接 | `redis://localhost:6379` |
|
|
| `APP_AI_API_KEY` | AI 服务 API Key | `sk-xxxxx` |
|
|
| `APP_SMTP_*` | SMTP 邮件配置 | 见 `.env.example` |
|
|
|
|
### 可选配置项
|
|
|
|
| 变量名 | 默认值 | 说明 |
|
|
|--------|--------|------|
|
|
| `APP_DATABASE_MAX_CONNECTIONS` | 10 | 数据库连接池大小 |
|
|
| `APP_LOG_LEVEL` | info | 日志级别 |
|
|
| `APP_QDRANT_URL` | - | 向量数据库地址 |
|
|
| `APP_REPOS_ROOT` | /data/repos | Git 仓库存储路径 |
|
|
|
|
完整配置请参考 `.env.example`。
|
|
|
|
## API 文档
|
|
|
|
启动服务后访问 http://localhost:8080/swagger-ui 查看完整的 API 文档。
|
|
|
|
## 架构设计
|
|
|
|
### 后端分层架构
|
|
|
|
```
|
|
┌─────────────────────────────────────┐
|
|
│ apps/app │ ← 应用入口
|
|
├─────────────────────────────────────┤
|
|
│ libs/api │ ← HTTP 路由/Handler
|
|
├─────────────────────────────────────┤
|
|
│ libs/service │ ← 业务逻辑层
|
|
├─────────────────────────────────────┤
|
|
│ libs/models │ libs/db │ libs/git│ ← 数据访问层
|
|
├─────────────────────────────────────┤
|
|
│ PostgreSQL │ Redis │ Qdrant │ ← 存储层
|
|
└─────────────────────────────────────┘
|
|
```
|
|
|
|
### 前端目录结构
|
|
|
|
```
|
|
src/
|
|
├── app/ # 页面级组件 (按功能模块组织)
|
|
│ ├── project/ # 项目相关页面 (Issue、Settings)
|
|
│ ├── repository/ # 仓库相关页面 (PR、代码浏览)
|
|
│ └── settings/ # 用户设置
|
|
├── components/ # 可复用组件
|
|
│ ├── ui/ # 基础 UI 组件 (shadcn)
|
|
│ ├── project/ # 项目相关组件
|
|
│ ├── repository/ # 仓库相关组件
|
|
│ └── room/ # 聊天相关组件
|
|
├── contexts/ # React Context (用户、聊天室等)
|
|
├── client/ # OpenAPI 生成的客户端
|
|
└── lib/ # 工具函数与 Hooks
|
|
```
|
|
|
|
## 任务清单
|
|
|
|
项目当前开发任务详见 [task.md](./task.md)，按优先级分为：
|
|
|
|
- **P0** — 阻塞性问题（核心流程不通）
|
|
- **P1** — 核心体验（关键功能）
|
|
- **P2** — 体验优化（增强功能）
|
|
|
|
## 许可证
|
|
|
|
[待添加]
|