# Git 克隆和使用指南

## 项目信息

- **GitHub 仓库地址**：https://github.com/bujie9527/wecom-ai-assistant
- **默认分支**：`main`
- **项目类型**：Monorepo（backend + admin + deploy + docs）

## 克隆项目

### 方式一：HTTPS 克隆（推荐）

```bash
# 克隆项目
git clone https://github.com/bujie9527/wecom-ai-assistant.git

# 进入项目目录
cd wecom-ai-assistant
```

**如果需要认证**（推送代码时）：
```bash
# 使用 Personal Access Token 作为密码
git clone https://github.com/bujie9527/wecom-ai-assistant.git
# 用户名：bujie9527
# 密码：你的 GitHub Personal Access Token
```

### 方式二：SSH 克隆（需要配置 SSH 密钥）

```bash
# 克隆项目
git clone git@github.com:bujie9527/wecom-ai-assistant.git

# 进入项目目录
cd wecom-ai-assistant
```

**配置 SSH 密钥**：
1. 生成 SSH 密钥：`ssh-keygen -t ed25519 -C "your_email@example.com"`
2. 将公钥添加到 GitHub：https://github.com/settings/keys
3. 测试连接：`ssh -T git@github.com`

## 项目结构

```
wecom-ai-assistant/
├── backend/          # Python FastAPI 后端
├── admin/            # Next.js 管理后台
├── deploy/            # 部署配置和脚本
├── docs/             # 项目文档
├── scripts/          # 自动化脚本
├── docker-compose.yml # 本地开发配置
└── README.md         # 项目说明
```

## 快速开始

### 1. 克隆项目

```bash
git clone https://github.com/bujie9527/wecom-ai-assistant.git
cd wecom-ai-assistant
```

### 2. 配置环境变量

```bash
# 复制环境变量模板
cp .env.example .env

# Windows PowerShell
Copy-Item .env.example .env

# 编辑 .env 文件，填写必需配置
```

### 3. 启动项目

```bash
# 使用 Docker Compose 一键启动
docker compose up -d

# 查看服务状态
docker compose ps

# 查看日志
docker compose logs -f
```

### 4. 访问服务

- **管理后台**：http://localhost
- **后端 API**：http://localhost:8000/api/health
- **PostgreSQL**：localhost:5432

## 常用 Git 操作

### 拉取最新代码

```bash
# 拉取远程最新代码
git pull origin main

# 或指定远程分支
git pull origin main --rebase
```

### 推送代码

```bash
# 添加更改
git add .

# 提交更改
git commit -m "描述你的更改"

# 推送到远程
git push origin main
```

### 查看分支

```bash
# 查看所有分支
git branch -a

# 查看远程分支
git branch -r

# 切换分支
git checkout branch-name
```

### 查看提交历史

```bash
# 查看提交历史
git log --oneline

# 查看最近 10 条提交
git log --oneline -10

# 查看图形化历史
git log --graph --oneline --all
```

## 分支管理

### 创建新分支

```bash
# 从 main 分支创建新分支
git checkout -b feature/new-feature

# 推送新分支到远程
git push -u origin feature/new-feature
```

### 合并分支

```bash
# 切换到 main 分支
git checkout main

# 拉取最新代码
git pull origin main

# 合并功能分支
git merge feature/new-feature

# 推送合并后的代码
git push origin main
```

## 推送代码到 GitHub

### 使用 HTTPS（需要 Token）

```bash
# 方式一：在 URL 中嵌入 token（不推荐，但方便）
git remote set-url origin https://bujie9527:YOUR_TOKEN@github.com/bujie9527/wecom-ai-assistant.git
git push origin main

# 方式二：使用 Git Credential Manager（推荐）
# Git 会提示输入用户名和密码
# 用户名：bujie9527
# 密码：你的 GitHub Personal Access Token
git push origin main
```

### 使用 SSH（推荐，更安全）

```bash
# 配置 SSH 密钥后
git remote set-url origin git@github.com:bujie9527/wecom-ai-assistant.git
git push origin main
```

## 配置 Git 用户信息

```bash
# 设置用户名
git config user.name "bujie9527"

# 设置邮箱
git config user.email "your_email@example.com"

# 查看配置
git config --list
```

## 忽略文件

项目已配置 `.gitignore`，以下文件不会被提交：

- `.env`、`.env.prod`（环境变量文件）
- `.github-config`（GitHub 配置文件，包含敏感 token）
- `node_modules/`（Node.js 依赖）
- `__pycache__/`（Python 缓存）
- `.next/`（Next.js 构建文件）
- `logs/`（日志文件）

## 故障排查

### 推送时提示认证失败

**问题**：`fatal: Authentication failed`

**解决方案**：
1. 检查 GitHub Personal Access Token 是否有效
2. 确认 token 权限包含 `repo`
3. 更新远程 URL：`git remote set-url origin https://bujie9527:YOUR_TOKEN@github.com/bujie9527/wecom-ai-assistant.git`

### 拉取时提示冲突

**问题**：`error: Your local changes would be overwritten by merge`

**解决方案**：
```bash
# 保存本地更改
git stash

# 拉取最新代码
git pull origin main

# 恢复本地更改
git stash pop
```

### 无法连接到 GitHub

**问题**：`fatal: unable to access 'https://github.com/...'`

**解决方案**：
1. 检查网络连接
2. 检查防火墙设置
3. 如果在中国大陆，可能需要配置代理或使用镜像

## 相关文档

- [GitHub 快速开始指南](./github-quickstart.md)
- [GitHub 配置文件指南](./github-config-guide.md)
- [项目 README](../README.md)

## 获取帮助

- **Git 官方文档**：https://git-scm.com/doc
- **GitHub 帮助**：https://docs.github.com
- **项目 Issues**：https://github.com/bujie9527/wecom-ai-assistant/issues