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