# 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** — 体验优化（增强功能）

## 许可证

[待添加]