## Work Log - 修复 API 启动阶段 users 主键列兼容问题（2026-05-01）

- 背景：
  - 启动报错 `psycopg.errors.UndefinedColumn: column users.user_id does not exist`，触发点在 `seed_defaults -> _seed_permissions` 的关系加载 SQL。
  - 当前 ORM 与外键约定统一使用 `users.user_id`，但历史库可能残留 `users.id` 主键列命名。

- 本次改动：
  - `api/app/core/database.py`
    - 新增 `_ensure_user_pk_column_compatibility()`。
    - 在 `init_db()` 执行 `Base.metadata.create_all()` 前，针对 PostgreSQL 做一次兼容检查：
      - 若 `users` 表存在，且检测到仅有 `id` 而没有 `user_id`，自动执行：`ALTER TABLE users RENAME COLUMN id TO user_id`。
      - 其余情况不改动（已是 `user_id` 或两者都不存在时直接跳过）。

- 验证：
  - 在 `fquiz-api` 容器内执行 `init_db()`：`init_db_ok`。
  - 在 `fquiz-api` 容器内执行查询，确认当前数据库 `users` 列包含 `user_id`。

- 风险与影响：
  - 影响范围：仅 PostgreSQL 且仅触发于“存在 `users.id` 且缺少 `users.user_id`”的历史库。
  - 该变更属于启动期一次性 DDL 兼容动作；对已规范为 `users.user_id` 的库无行为变化。

## Work Log - 修复 API 启动时报 users.user_name / users.username 列不一致（2026-05-01）

- 背景：
  - API 启动阶段在 `seed_defaults -> _seed_permissions` 查询中触发 ORM 关系预加载，SQL 使用了 `users.user_name`，但当前 PostgreSQL `users` 表实际字段为 `username`，导致 `psycopg.errors.UndefinedColumn`，服务启动失败。

- 本次改动（最小闭环）：
  - 文件：`api/app/core/config.py`
    - 新增配置 `user_username_column`（环境变量 `USER_USERNAME_COLUMN`），可选值 `username` / `user_name`，默认 `username`。
  - 文件：`api/app/models/user.py`
    - `User.username` 列改为基于 `settings.user_username_column` 动态映射，兼容两类历史库结构。
  - 文件：`docker-compose.yml`
    - 为 `api` / `celery-worker` / `celery-beat` 注入 `USER_USERNAME_COLUMN` 环境变量透传。
  - 文件：`.env.example`
    - 新增 `USER_USERNAME_COLUMN=username` 示例配置。

- 验证：
  - `python3 -m py_compile api/app/core/config.py api/app/models/user.py api/app/services/seed_service.py` -> 通过。
  - `USER_USERNAME_COLUMN=user_name POSTGRES_PORT=5434 docker compose up -d --no-deps api` -> 启动成功。
  - `USER_USERNAME_COLUMN=user_name POSTGRES_PORT=5434 docker compose ps api` -> `Up (healthy)`。
  - `curl -fsS http://127.0.0.1:8000/health` -> `{"status":"ok","service":"fquiz-api","version":"0.1.0"}`。

- 风险与影响：
  - 影响面集中在 `User` 模型用户名字段映射。
  - 运行环境需明确 `USER_USERNAME_COLUMN` 与目标数据库实际字段一致；配置错误会在启动阶段继续抛 `UndefinedColumn`。

## Work Log - GitHub Actions 部署分支切换为 dev（2026-05-01）

- 背景：
  - 当前 workflow 仅监听 `main` push，且 deploy job 条件写死为 `refs/heads/main`，导致 `dev` 推送不触发自动部署。

- 本次改动（最小改动）：
  - 文件：`.github/workflows/main.yml`
    - `on.push.branches` 从 `main` 改为 `dev`。
    - `deploy.if` 从 `github.ref == 'refs/heads/main'` 改为 `github.ref == 'refs/heads/dev'`。

- 预期行为：
  - `git push origin dev`：自动触发构建，并在构建成功后执行 deploy。
  - `main` 分支 push：不再触发该 workflow 自动部署链路。

- 风险与影响：
  - 生产发布入口从 `main` 切换到 `dev`，需确认团队分支策略已同步。
  - `workflow_dispatch` 若在非 `dev` 分支触发，deploy job 会被 `if` 条件跳过。