fix(api): add users pk column compatibility at startup

memory/2026-05-01.md

@@ -0,0 +1,20 @@
+## 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` 的库无行为变化。