fquiz/memory/2026-05-01.md

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 条件跳过。