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 的库无行为变化。