# PostgreSQL 数据库搭建指南

本项目运行时**必须**连接 PostgreSQL 16+（含 pgvector 扩展），SQLite 已不支持。

---

## 方案一：Docker Compose（推荐，本地开发）

适合本地开发与测试，一条命令启动 PostgreSQL + pgvector。

### 1. 创建 `docker-compose.yml`

在项目根目录或任意位置新建：

```yaml
version: '3.8'

services:
  postgres:
    image: pgvector/pgvector:pg16
    container_name: resume-agent-db
    environment:
      POSTGRES_USER: resume_agent
      POSTGRES_PASSWORD: change-me-in-production
      POSTGRES_DB: resume_agent
    ports:
      - "5435:5432"
    volumes:
      - resume_agent_data:/var/lib/postgresql/data
    restart: unless-stopped

volumes:
  resume_agent_data:
```

### 2. 启动

```bash
docker-compose up -d
```

### 3. 配置 `backend/.env`

```bash
DATABASE_URL=postgresql+psycopg://resume_agent:change-me-in-production@127.0.0.1:5435/resume_agent
RESUME_AGENT_TEST_DATABASE_URL=postgresql+psycopg://resume_agent:change-me-in-production@127.0.0.1:5435/resume_agent_test
```

### 4. 初始化数据库

```bash
cd backend
alembic upgrade head
```

**停止与清理**：
```bash
docker-compose down              # 停止（保留数据）
docker-compose down -v           # 停止并删除数据卷（重置数据库）
```

---

## 方案二：生产环境 PostgreSQL

适合公司已有 PostgreSQL 集群或需要独立部署的场景。

### 1. 安装 PostgreSQL 16+

**Ubuntu/Debian**：
```bash
sudo apt install postgresql-16 postgresql-contrib-16
```

**CentOS/RHEL**：
```bash
sudo dnf install postgresql16-server postgresql16-contrib
sudo postgresql-16-setup initdb
sudo systemctl enable --now postgresql-16
```

**macOS（Homebrew）**：
```bash
brew install postgresql@16
brew services start postgresql@16
```

**Windows**：下载官方安装包 https://www.postgresql.org/download/windows/

### 2. 安装 pgvector 扩展

pgvector 用于向量存储（未来扩展知识库功能时需要，当前轻度优化不依赖）。

**Ubuntu/Debian**：
```bash
sudo apt install postgresql-16-pgvector
```

**从源码安装**（如包管理器无 pgvector）：
```bash
git clone https://github.com/pgvector/pgvector.git
cd pgvector
make PG_CONFIG=/usr/pgsql-16/bin/pg_config  # 路径按实际调整
sudo make install PG_CONFIG=/usr/pgsql-16/bin/pg_config
```

### 3. 创建用户与数据库

以 `postgres` 管理员身份执行：

```sql
CREATE USER resume_agent WITH PASSWORD 'your-strong-password';
CREATE DATABASE resume_agent OWNER resume_agent;
CREATE DATABASE resume_agent_test OWNER resume_agent;

-- 启用 pgvector 扩展（当前可选，未来知识库功能需要）
\c resume_agent
CREATE EXTENSION IF NOT EXISTS vector;
\c resume_agent_test
CREATE EXTENSION IF NOT EXISTS vector;

-- 授权（如果数据库归属已设为 resume_agent 则自动有权限，此行可跳过）
GRANT ALL PRIVILEGES ON DATABASE resume_agent TO resume_agent;
GRANT ALL PRIVILEGES ON DATABASE resume_agent_test TO resume_agent;
```

### 4. 配置 `backend/.env`

将 `host`、`port`、密码替换为实际值：

```bash
DATABASE_URL=postgresql+psycopg://resume_agent:your-strong-password@your-db-host:5432/resume_agent
RESUME_AGENT_TEST_DATABASE_URL=postgresql+psycopg://resume_agent:your-strong-password@your-db-host:5432/resume_agent_test
```

**注意**：生产环境**必须**修改默认密码 `change-me-in-production`。

### 5. 初始化数据库

```bash
cd backend
alembic upgrade head
```

---

## 验证安装

### 检查连接

```bash
cd backend
python -c "from app.postgres_database import PostgresDatabase; db = PostgresDatabase('your-DATABASE_URL-here', 'resume_agent'); db.initialize(); print('✓ 连接成功')"
```

### 运行测试（需要测试库）

```bash
cd backend
pytest tests/test_postgres_environment.py -v
```

---

## 常见问题

### Q1: `ModuleNotFoundError: No module named 'psycopg'`

安装 Python 驱动：
```bash
pip install psycopg[binary]
```

### Q2: `FATAL: password authentication failed`

- 检查 `.env` 中的密码是否正确
- PostgreSQL 默认可能只允许本地 Unix socket 连接，需修改 `pg_hba.conf`：
  ```
  # 允许密码认证（开发环境）
  host    all             all             127.0.0.1/32            md5
  ```
  修改后重启 PostgreSQL：`sudo systemctl restart postgresql-16`

### Q3: `FATAL: database "resume_agent" does not exist`

执行方案二第 3 步创建数据库。

### Q4: `could not open extension control file ".../vector.control"`

pgvector 未安装或路径不对，执行方案二第 2 步。当前轻度优化功能可暂不安装（但测试套件会跳过 pgvector 相关测试）。

---

## 从 SQLite 迁移到 PostgreSQL

如果你有旧的 SQLite 数据库（`backend/data/resume_agent.db`），可一键迁移：

```bash
cd backend
# 确保 PostgreSQL 已启动且 alembic upgrade head 已执行
python scripts/migrate_sqlite_to_postgres.py \
  --sqlite-path data/resume_agent.db \
  --postgres-url "postgresql+psycopg://resume_agent:password@127.0.0.1:5435/resume_agent"
```

迁移完成后 SQLite 文件可归档备份（不要删除，以防回滚）。

---

## 多环境 Schema 隔离（可选）

如果多个开发者或环境共用一个 PostgreSQL 实例，可用不同 schema 隔离：

```bash
# 开发者 A
export RESUME_AGENT_DATABASE_SCHEMA=dev_alice

# 开发者 B  
export RESUME_AGENT_DATABASE_SCHEMA=dev_bob

# 测试 CI
export RESUME_AGENT_DATABASE_SCHEMA=ci_test
```

每个 schema 自动创建独立表，互不影响。默认 schema 是 `resume_agent`。

---

## ⚠️ 为什么不要打包现有数据库镜像

如果你已在本地运行过项目并考虑"把我的数据库导出给其他人用"，**请不要这样做**：

| 问题 | 后果 |
|---|---|
| **本地库含测试 PII** | 测试用的真实简历、手机号会随镜像泄露到其他环境 |
| **schema 版本分裂** | 如果本地库含未发布的表结构（如深度优化功能的实验性迁移），其他人拿到的库与代码不匹配 |
| **无法追踪变更** | 镜像是"某一时刻的快照"，后续表结构变更无法增量同步，只能重新导出（覆盖生产数据）或手写 SQL 补丁 |
| **违反 Alembic 设计** | Alembic 迁移链才是 schema 的唯一事实来源；绕过它会导致 `alembic current` 显示错误版本，后续 `upgrade` 失败 |

**正确做法**：每个环境独立执行 `alembic upgrade head`（从零建表），通过**迁移文件**而非**数据库快照**同步 schema。

---

## 多仓库协作：如何同步 Schema 变更（Alembic 迁移）

适用场景：原始开发仓库（含深度优化等未发布功能）与交付仓库（resume-agent-offerpai）分离，需定期同步表结构。

### 原则

- **Alembic 迁移文件是 schema 的唯一事实来源**，不传数据库镜像
- 每个环境通过 `alembic upgrade head` 应用迁移，保证 schema 一致
- 新功能的表结构变更先在开发仓库测试，稳定后再合并进交付仓库

### 工作流

#### 1. 开发仓库添加新功能（如深度优化）

当你在原始仓库开发深度优化功能并需要新增表时：

```bash
# 在开发仓库 backend/
alembic revision -m "add deep optimization knowledge tables"
```

Alembic 会生成新迁移文件，例如 `backend/alembic/versions/20260806_06_add_deep_knowledge.py`。

编辑该文件实现表结构变更：

```python
def upgrade() -> None:
    op.create_table(
        'knowledge_entries',
        sa.Column('id', sa.Integer(), primary_key=True),
        sa.Column('content', sa.Text(), nullable=False),
        # ... 其他列
    )

def downgrade() -> None:
    op.drop_table('knowledge_entries')
```

在本地测试：

```bash
alembic upgrade head      # 应用迁移
alembic downgrade -1      # 回滚测试
alembic upgrade head      # 重新应用
pytest tests/test_deep_optimization.py  # 功能测试
```

#### 2. 决定是否合并进交付仓库

开发完成后，根据发布计划决定：

**情况 A：深度优化暂不发布**  
→ 迁移文件留在开发仓库，交付仓库不同步（两个仓库的 schema 暂时分叉）

**情况 B：深度优化已稳定，准备发布**  
→ 将新迁移文件复制进交付仓库：

```bash
# 复制迁移文件
cp resume-agent/backend/alembic/versions/20260806_06_*.py \
   resume-agent-offerpai/backend/alembic/versions/

# 同时复制相关代码模块
cp -r resume-agent/backend/app/deep_optimization \
      resume-agent-offerpai/backend/app/
```

#### 3. 交付仓库用户升级数据库

其他开发者或生产环境拉取最新代码后：

```bash
cd backend
alembic upgrade head
```

Alembic 会**自动检测本地数据库版本**，只应用新增的迁移（如 `06_add_deep_knowledge.py`），已有的表结构不受影响。

**验证迁移成功**：

```bash
alembic current
# 输出：06 (head), add deep optimization knowledge tables
```

#### 4. 回滚（如果新功能有问题）

```bash
alembic downgrade -1     # 回退一个版本
# 或指定目标版本
alembic downgrade 05
```

### 注意事项

1. **迁移文件命名保持顺序**：Alembic 按文件名前缀排序（`20260806_06_`），不要手动改编号
2. **不要修改已发布的迁移**：已在生产环境执行的迁移文件禁止编辑；如需修正，写新的迁移
3. **复制迁移时检查依赖**：如果新迁移引用了其他未发布的表，需一并复制依赖的迁移
4. **测试先行**：新迁移在开发环境验证通过后再合并；生产环境升级前先在预发环境测试

### 查看迁移历史

```bash
alembic history --verbose
# 显示完整迁移链与当前版本
```

### 如果两个仓库的迁移链已分叉

如果长期未同步导致迁移编号冲突（例如两边都有 `06_` 开头的迁移但内容不同）：

```bash
# 在交付仓库重新编号新迁移
cd resume-agent-offerpai/backend
alembic revision -m "sync: merge deep optimization from main repo"
# 手动编辑生成的文件，将开发仓库的迁移内容复制进来
```

**最佳实践**：定期（如每次发版）同步迁移文件，避免分叉。

---

## 示例：完整的多仓库协作流程

**场景**：你在开发仓库完成了深度优化功能，需要同步到交付仓库供公司团队使用。

### Step 1：开发仓库提交迁移

```bash
cd resume-agent/backend
alembic revision -m "add deep optimization tables"
# 编辑生成的迁移文件，实现 upgrade/downgrade
alembic upgrade head
pytest  # 验证功能
git add alembic/versions/20260806_06_*.py app/deep_optimization/
git commit -m "feat: add deep optimization module with knowledge tables"
```

### Step 2：同步到交付仓库

```bash
cd ../resume-agent-offerpai
cp ../resume-agent/backend/alembic/versions/20260806_06_*.py \
   backend/alembic/versions/
cp -r ../resume-agent/backend/app/deep_optimization \
      backend/app/
git add backend/alembic/versions/ backend/app/deep_optimization/
git commit -m "feat: sync deep optimization from main repo"
git push origin master
```

### Step 3：公司团队升级

```bash
# 其他开发者拉取最新代码
git pull origin master
cd backend
alembic upgrade head
# 输出：
# INFO  [alembic.runtime.migration] Running upgrade 05 -> 06, add deep optimization tables
pytest  # 验证本地环境
```

### Step 4：生产环境升级（零停机）

```bash
# 生产服务器
cd /opt/resume-agent/backend
git pull
alembic upgrade head  # Alembic 自动只应用新迁移，已有数据不受影响
sudo systemctl restart resume-agent
```

---

## 总结

| 场景 | 推荐方案 |
|---|---|
| 首次部署 | 方案一（Docker Compose）或方案二（独立 PG），然后 `alembic upgrade head` |
| 多人协作 | 每人独立建库 + 共享迁移文件（通过 Git），不传数据库镜像 |
| Schema 升级 | 开发仓库写迁移 → 测试 → 复制到交付仓库 → 其他人 `alembic upgrade` |
| 数据迁移 | 用迁移文件的 `op.execute("INSERT ...")` 或独立脚本（如 `scripts/seed_demo_data.py`） |
| 回滚 | `alembic downgrade <target_revision>` |

**禁止操作**：`pg_dump` 整个库然后 `psql < dump.sql` 覆盖他人数据库 —— 会破坏 Alembic 版本追踪。