# 开发指南

本文档将帮助您了解XUGOU项目的开发环境配置、项目结构和开发流程。

## 环境要求

在开始开发XUGOU项目之前，请确保您的系统满足以下要求：

- **Node.js** >= 18
- **Go** >= 1.24
- **Git**

## 项目结构

XUGOU项目分为三个主要部分：

### 前端 (frontend)

前端使用React + TypeScript开发，目录结构如下：

```
frontend/
├── public/           # 静态资源
├── src/              # 源代码
│   ├── api/          # API调用
│   ├── components/   # 通用组件
│   ├── pages/        # 页面组件
│   ├── store/        # 状态管理
│   ├── styles/       # 样式文件
│   ├── types/        # TypeScript类型定义
│   └── utils/        # 工具函数
├── .env.local        # 本地环境变量
├── package.json      # 项目依赖
├── tsconfig.json     # TypeScript配置
└── vite.config.ts    # Vite配置
```

### 后端 (backend)

后端基于Cloudflare Workers开发，目录结构如下：

```
backend/
├── src/              # 源代码
│   ├── controllers/  # 控制器
│   ├── models/       # 数据模型
│   ├── routes/       # 路由定义
│   └── utils/        # 工具函数
├── schema.sql        # 数据库架构
├── wrangler.toml     # Cloudflare Workers配置
└── package.json      # 项目依赖
```

### 客户端 (agent)

监控客户端使用Go语言开发，目录结构如下：

```
agent/
├── cmd/              # 命令行命令
│   └── agent/        # 命令行实现
├── pkg/              # 功能包
│   ├── collector/    # 数据收集器
│   └── reporter/     # 数据上报器
├── main.go           # 程序入口
└── go.mod            # Go依赖
```

## 开发流程

### 1. 克隆项目

```bash
git clone https://github.com/zaunist/xugou.git
cd xugou
```

### 2. 前端开发

```bash
# 进入前端目录
cd frontend

# 安装依赖
pnpm install

# 配置环境变量
cp .env.local.example .env.local
# 编辑.env.local，设置后端API地址

# 启动开发服务器
pnpm run dev
```

前端开发服务器将在 `http://localhost:5173` 启动。

### 3. 后端开发

```bash
# 进入后端目录
cd backend

# 安装依赖
pnpm install

# 启动开发服务器
pnpm run dev
```

后端开发服务器将在本地启动，通常在控制台输出中会显示地址。

### 4. 客户端开发

```bash
# 进入客户端目录
cd agent

# 构建客户端
go build -o xugou-agent

# 运行客户端（控制台输出模式）
./xugou-agent --server console start
```

## 代码提交规范

为保持代码库的一致性和可维护性，请遵循以下代码提交规范：

1. **分支管理**：
   - `main`：主分支，只接受稳定版本的合并
   - `dev`：开发分支，日常开发在此分支上进行
   - 功能分支：以`feature/`为前缀，例如`feature/dashboard`
   - 修复分支：以`fix/`为前缀，例如`fix/memory-leak`

2. **提交信息**：
   - 格式：`类型: 描述`，例如`feat: 添加用户认证功能`
   - 类型包括：
     - `feat`：新功能
     - `fix`：修复bug
     - `docs`：文档更新
     - `style`：代码风格修改（不影响代码功能）
     - `refactor`：重构代码
     - `test`：添加或修改测试
     - `chore`：构建过程或工具变动

3. **代码审查**：所有代码合并到主分支前需要通过代码审查