# 环境配置指南

## 前置条件

- [Anaconda](https://www.anaconda.com/download) 或 [Miniconda](https://docs.conda.io/en/latest/miniconda.html) 已安装
- Git 已安装

---

## 1. 创建 Conda 环境

```bash
conda create -n ax-backend python=3.11 -y
```

> Python 版本要求 3.10+，推荐使用 3.11。

---

## 2. 激活环境

```bash
conda activate ax-backend
```

激活后终端提示符前应显示 `(ax-backend)`。

---

## 3. 安装依赖

进入项目根目录后安装 `requirements.txt`：

```bash
cd d:/code/ax-backend
pip install -r requirements.txt
```

> `weasyprint` 在 Windows 上依赖 GTK 运行时，若安装报错见下方[常见问题](#常见问题)。

---

## 4. 配置环境变量

复制示例文件并按实际情况填写：

```bash
cp .env.example .env
```

`.env` 关键配置项：

```env
# 数据库
DATABASE_URL=postgresql+asyncpg://user:password@localhost:5432/ax_backend

# Redis（阶段 2 引入）
REDIS_URL=redis://localhost:6379/0

# JWT 密钥（阶段 2 引入，生产环境务必替换）
JWT_SECRET_KEY=your-secret-key-here

# 文件存储路径（模板上传，阶段 1 引入）
TEMPLATE_STORAGE_PATH=./storage/templates
```

---

## 5. 初始化数据库

确保 PostgreSQL 已启动，并已创建对应数据库，然后执行 Alembic 迁移：

```bash
alembic upgrade head
```

---

## 6. 启动服务

```bash
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
```

服务启动后访问：

- API 文档（Swagger）：http://localhost:8000/docs
- 备用文档（ReDoc）：http://localhost:8000/redoc

---

## 7. 验证安装

```bash
python -c "import fastapi, sqlalchemy, pydantic; print('OK')"
```

输出 `OK` 即表示核心依赖安装正常。

---

## 常见问题

### weasyprint 在 Windows 上安装失败

`weasyprint` 依赖 GTK3 运行时，Windows 需要额外安装：

1. 下载并安装 [GTK3 Runtime for Windows](https://github.com/tschoonj/GTK-for-Windows-Runtime-Environment-Installer/releases)
2. 安装完成后重新执行 `pip install weasyprint==63.1`

> weasyprint 仅在阶段 3（PDF 导出）用到，阶段 0/1/2 开发可暂时跳过，注释掉 `requirements.txt` 中对应行即可。

### asyncpg 编译失败

`asyncpg` 需要 C 编译器。Windows 上推荐安装预编译包：

```bash
pip install asyncpg --prefer-binary
```

### conda activate 不生效（Windows CMD）

在 CMD 中需先初始化：

```bash
conda init cmd.exe
```

关闭并重新打开终端后再执行 `conda activate ax-backend`。

---

## 退出环境

```bash
conda deactivate
```

## 删除环境

```bash
conda remove -n ax-backend --all -y
```