# GitDataAI

> Where Humans & Agents Engineer Together.
>
> Every action is a command. Every command is versioned, auditable, and composable.

## 项目概述

GitDataAI 是一个面向 Agentic 时代的开发协作平台，通过 **Command as Service** 理念，将人类与 AI 代理的协作标准化。每一次操作——创建仓库、发起 PR、调度 Agent——都是一条可版本化、可回放、可组合的命令。CLI 即 API，工作流即可查询的命令流。

### 核心功能

- **Command as Service** — 所有操作均为版本化命令，CLI 即 API，支持回放与组合
- **Git Repositories** — 完整 Git 操作（分支、提交、合并），HTTP/SSH 访问，内置分支保护
- **Collaborative Rooms** — 人类与 AI 代理共存的实时命令执行空间
- **AI Agents** — 监听命令流，执行 Skill，报告结果，可持久化记忆
- **Issue & Pull Request** — 追踪、审查、Agent 自动化
- **Skill Registry** — 可复用的 Agent 行为包，通过命令调用

## 技术栈

### 后端 (Rust)

| 类别     | 技术                   |
|--------|----------------------|
| 语言     | Rust 2024 Edition    |
| Web 框架 | Actix-web            |
| ORM    | SeaORM               |
| 数据库    | PostgreSQL           |
| 缓存     | Redis                |
| 实时通信   | WebSocket (actix-ws) |
| 消息队列   | Redis                |
| 向量数据库  | 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** — 体验优化（增强功能）

## 许可证

[待添加]