fix(api): support configurable users username column mapping

memory/2026-05-01.md

@@ -18,3 +18,28 @@
 - 风险与影响：
   - 影响范围：仅 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`。