修复用户状态列映射兼容问题

Co-authored-by: multica-agent <github@multica.ai>

.env.example

@@ -12,6 +12,7 @@ DB_USERNAME=fquiz
 DB_PASSWORD=fquiz
 USER_USERNAME_COLUMN=username
 USER_PASSWORD_COLUMN=password_hash
+USER_STATUS_COLUMN=status
 FILE_VFS_ROOT=./data/vfs
 MINIO_ENABLED=true
 MINIO_ENDPOINT=http://minio:9000

api/app/core/config.py

@@ -25,6 +25,7 @@ class Settings(BaseSettings):
     db_password: str = "fquiz"
     user_username_column: Literal["username", "user_name"] = "username"
     user_password_column: Literal["password", "password_hash"] = "password_hash"
+    user_status_column: Literal["status", "state"] = "status"
     file_vfs_root: str = "./data/vfs"
     minio_enabled: bool = False
     minio_endpoint: str = "http://minio:9000"

api/app/models/user.py

@@ -39,7 +39,12 @@ class User(Base):
         settings.user_password_column,
         String(255),
     )
-    status: Mapped[str] = mapped_column("state", String(32), default="ENABLED", index=True)
+    status: Mapped[str] = mapped_column(
+        settings.user_status_column,
+        String(32),
+        default="ENABLED",
+        index=True,
+    )
     created_at: Mapped[datetime] = mapped_column(
         "create_date",
         DateTime(timezone=False),

docker-compose.yml

@@ -104,6 +104,7 @@ services:
       DB_PASSWORD: ${DB_PASSWORD:-fquiz}
       USER_USERNAME_COLUMN: ${USER_USERNAME_COLUMN:-username}
       USER_PASSWORD_COLUMN: ${USER_PASSWORD_COLUMN:-password_hash}
+      USER_STATUS_COLUMN: ${USER_STATUS_COLUMN:-status}
       FILE_VFS_ROOT: ${FILE_VFS_ROOT:-./data/vfs}
       MINIO_ENABLED: ${MINIO_ENABLED:-true}
       MINIO_ENDPOINT: ${MINIO_ENDPOINT:-http://minio:9000}
@@ -179,6 +180,7 @@ services:
       DB_PASSWORD: ${DB_PASSWORD:-fquiz}
       USER_USERNAME_COLUMN: ${USER_USERNAME_COLUMN:-username}
       USER_PASSWORD_COLUMN: ${USER_PASSWORD_COLUMN:-password_hash}
+      USER_STATUS_COLUMN: ${USER_STATUS_COLUMN:-status}
       CELERY_BROKER_URL: ${CELERY_BROKER_URL:-redis://redis:6379/0}
       CELERY_RESULT_BACKEND: ${CELERY_RESULT_BACKEND:-redis://redis:6379/1}
       CELERY_TIMEZONE: ${CELERY_TIMEZONE:-Asia/Shanghai}
@@ -217,6 +219,7 @@ services:
       DB_PASSWORD: ${DB_PASSWORD:-fquiz}
       USER_USERNAME_COLUMN: ${USER_USERNAME_COLUMN:-username}
       USER_PASSWORD_COLUMN: ${USER_PASSWORD_COLUMN:-password_hash}
+      USER_STATUS_COLUMN: ${USER_STATUS_COLUMN:-status}
       CELERY_BROKER_URL: ${CELERY_BROKER_URL:-redis://redis:6379/0}
       CELERY_RESULT_BACKEND: ${CELERY_RESULT_BACKEND:-redis://redis:6379/1}
       CELERY_TIMEZONE: ${CELERY_TIMEZONE:-Asia/Shanghai}

memory/2026-05-01.md

@@ -130,3 +130,27 @@
 - 风险与影响：
   - 影响面集中在 `User` 模型密码字段映射。
   - 运行环境需确保 `USER_PASSWORD_COLUMN` 与目标数据库实际字段一致；若配置错误，启动阶段仍可能抛 `UndefinedColumn`。
+
+## Work Log - 修复 API 启动时报 users.state 列不存在（2026-05-01）
+
+- 背景：
+  - 启动报错 `psycopg.errors.UndefinedColumn: column users.state does not exist`。
+  - 触发点同样在 `seed_defaults -> _seed_permissions` 的关系预加载过程中，ORM 查询 `users` 全字段时固定引用了 `state`，但目标库实际字段为 `status`。
+
+- 本次改动（最小闭环）：
+  - 文件：`api/app/core/config.py`
+    - 新增配置 `user_status_column`（环境变量 `USER_STATUS_COLUMN`），可选值 `status` / `state`，默认 `status`。
+  - 文件：`api/app/models/user.py`
+    - `User.status` 列改为基于 `settings.user_status_column` 动态映射，兼容两类历史库结构。
+  - 文件：`docker-compose.yml`
+    - 为 `api` / `celery-worker` / `celery-beat` 注入 `USER_STATUS_COLUMN` 环境变量透传。
+  - 文件：`.env.example`
+    - 新增 `USER_STATUS_COLUMN=status` 示例配置。
+
+- 验证：
+  - `rg -n "USER_STATUS_COLUMN|user_status_column"` 命中配置、模型、compose、env 示例，映射链路完整。
+  - `git diff` 检查仅包含本次预期的 4 个文件改动。
+
+- 风险与影响：
+  - 影响面集中在 `User` 模型状态字段映射。
+  - 运行环境需确保 `USER_STATUS_COLUMN` 与目标数据库实际字段一致；若配置错误，启动阶段仍可能抛 `UndefinedColumn`。