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

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。

Work Log - GitHub Actions 部署分支切换为 dev（2026-05-01）

• 背景：

  • 当前 workflow 仅监听 main push，且 deploy job 条件写死为 refs/heads/main，导致 dev 推送不触发自动部署。

• 本次改动（最小改动）：

  • 文件：.github/workflows/main.yml
    • on.push.branches 从 main 改为 dev。
    • deploy.if 从 github.ref == 'refs/heads/main' 改为 github.ref == 'refs/heads/dev'。

• 预期行为：

  • git push origin dev：自动触发构建，并在构建成功后执行 deploy。
  • main 分支 push：不再触发该 workflow 自动部署链路。

• 风险与影响：

  • 生产发布入口从 main 切换到 dev，需确认团队分支策略已同步。
  • workflow_dispatch 若在非 dev 分支触发，deploy job 会被 if 条件跳过。

Work Log - 修复 docker db 端口 5433 冲突并改为 5434（2026-05-01）

• 背景：

  • docker compose 启动 db 报错：Bind for 0.0.0.0:5433 failed: port is already allocated。
  • 现有默认口径为宿主机映射 5433->5432，与本机已占用端口冲突。

• 本次改动（最小闭环）：

  • 文件：docker-compose.yml
    • db.ports 默认映射从 ${POSTGRES_PORT:-5433}:5432 改为 ${POSTGRES_PORT:-5434}:5432。
  • 文件：.env.example
    • POSTGRES_PORT 默认值从 5433 改为 5434。
    • 本机直连 DB_PORT 默认值从 5433 改为 5434。
  • 文件：api/app/core/config.py
    • db_port 默认值从 5433 改为 5434，与环境模板和 compose 默认保持一致。
  • 文件：README.md
    • 本地 PostgreSQL 示例端口从 localhost:5433 更新为 localhost:5434。
  • 文件：MEMORY.md
    • 宿主机默认 POSTGRES_PORT 与本机直连 DB_PORT 长期口径同步更新为 5434。

• 验证：

  • POSTGRES_PORT=5434 docker compose up -d db -> fquiz-db 启动成功。
  • docker compose ps -a -> fquiz-db 状态 Up ... (healthy)。
  • docker inspect fquiz-db --format '{{json .HostConfig.PortBindings}}' -> 5432/tcp 映射 HostPort=5434。

• 风险与影响：

  • 影响范围：本地/部署侧依赖默认 5433 的连接配置需同步为 5434，否则会出现连接失败。
  • 容器内服务间连接不受影响，仍通过 db:5432 通信。

Work Log - 统一 GitHub 发布默认 PostgreSQL 端口为 5434（2026-05-01）

• 背景：

  • 仓库本地 docker-compose.yml 默认端口已是 5434，但 GitHub Actions 发布脚本内联的 docker-compose.prod.yml 与首次生成 .env 仍使用 5433，存在口径不一致。

• 本次改动（最小改动）：

  • 文件：.github/workflows/main.yml
    • 将发布脚本中 db.ports 默认映射从 ${POSTGRES_PORT:-5433}:5432 改为 ${POSTGRES_PORT:-5434}:5432。
    • 将首次初始化 .env 模板中的 POSTGRES_PORT=5433 改为 POSTGRES_PORT=5434。

• 验证：

  • rg -n "POSTGRES_PORT:-5434|POSTGRES_PORT=5434" .github/workflows/main.yml 命中两处，未发现 workflow 内 5433 残留。

• 风险与影响：

  • 影响范围：仅 GitHub 发布脚本默认值，不影响已存在且手工维护的服务器 .env。
  • 若线上环境明确依赖 5433，需在服务器 .env 显式保留 POSTGRES_PORT=5433。

Work Log - 修复 API 启动时报 users.password 列不存在（2026-05-01）

• 背景：

  • 启动报错 psycopg.errors.UndefinedColumn: column users.password does not exist。
  • 触发点在 seed_defaults -> _seed_permissions 的查询过程中，SQLAlchemy 关系预加载 Role.users 时会查询 users 全字段；当前 ORM 将 password_hash 绑定到 users.password，但目标库字段为 password_hash。

• 本次改动（最小闭环）：

  • 文件：api/app/core/config.py
    • 新增配置 user_password_column（环境变量 USER_PASSWORD_COLUMN），可选值 password / password_hash，默认 password_hash。
  • 文件：api/app/models/user.py
    • User.password_hash 改为基于 settings.user_password_column 动态映射，兼容两类历史库结构。
  • 文件：docker-compose.yml
    • 为 api / celery-worker / celery-beat 注入 USER_PASSWORD_COLUMN 环境变量透传。
  • 文件：.env.example
    • 新增 USER_PASSWORD_COLUMN=password_hash 示例配置。

• 验证：

  • python3 -m py_compile api/app/core/config.py api/app/models/user.py api/app/services/seed_service.py -> 通过。
  • rg -n "USER_PASSWORD_COLUMN|user_password_column" ... 命中配置、模型、compose、env 示例，映射链路完整。

• 风险与影响：

  • 影响面集中在 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。

Work Log - 修复 API 启动时报 users.create_user / users.update_user 列不存在（2026-05-01）

• 背景：

  • 发布部署日志报错 psycopg.errors.UndefinedColumn: column users.create_user does not exist，容器持续重启。
  • 触发点在 init_db -> seed_defaults，Role.users 关系预加载会查询 users 全字段；当历史库缺失 create_user/update_user 时，启动阶段直接失败。

• 本次改动（最小闭环）：

  • 文件：api/app/core/database.py
    • 新增 _ensure_user_audit_column_compatibility() 并在 init_db() 中接入（位于 Base.metadata.create_all() 前执行）。
    • 兼容策略：
      • 若存在历史列 create_by/created_by，自动重命名为 create_user。
      • 若存在历史列 update_by/updated_by，自动重命名为 update_user。
      • 若目标列仍缺失，自动补齐 nullable 列：
        • ALTER TABLE users ADD COLUMN IF NOT EXISTS create_user VARCHAR(64)
        • ALTER TABLE users ADD COLUMN IF NOT EXISTS update_user VARCHAR(64)

• 验证：

  • git diff 检查改动仅落在 api/app/core/database.py 与记忆文档。
  • 启动期兼容逻辑为 PostgreSQL 定向执行；仅在 users 表存在且列不一致时触发 DDL，已对齐环境不会产生变更。

• 风险与影响：

  • 影响面限定在 PostgreSQL 的 users 表审计字段兼容处理。
  • 该兼容动作为启动期一次性 DDL，可能短暂持有 users 表 DDL 锁；对已有规范列名的库无行为变化。

Work Log - 修复 /api/v1/admin/roles 在缺失 user_role 表时返回 500（2026-05-01）

• 背景：

  • 复现路径：登录后调用 GET /api/v1/admin/roles，接口返回 500。
  • 根因：legacy_admin_rbac_service.list_roles 固定查询 legacy 表 user_role，当库仅存在 modern RBAC 表（roles/user_roles/role_menus）时触发 psycopg.errors.UndefinedTable。

• 本次改动（最小闭环）：

  • 文件：api/app/services/legacy_admin_rbac_service.py
    • 新增 user_role 存在性探测：_legacy_role_table_exists()。
    • list_roles 增加双链路读取：
      • legacy 存在时保持原有 user_role + role_menu_rela + menu 查询；
      • legacy 缺失时自动回退 roles + role_menus + menus + role_permissions + permissions。
    • get_role_by_id 与 list_role_menu_ids 同步支持 modern 回退（兼容按 id 或 code 查角色）。
    • 新增辅助函数：
      • _load_role_rows(..., role_source=...)
      • _load_role_permission_codes_map(..., role_source=...)
    • 扩展辅助函数以支持 modern 回退：
      • _load_role_menu_ids_map(..., role_source=...)
      • _load_menus_map(..., role_source=...)

• 验证：

  • python3 -m py_compile api/app/services/legacy_admin_rbac_service.py -> 通过。
  • git push origin HEAD:dev -> 成功（提交 2c3ad31）。

• 风险与影响：

  • 影响范围限定在后台角色读取接口（/api/v1/admin/roles*）查询链路。
  • 对 legacy 表完整的数据库行为保持不变；仅在 user_role 缺失时触发 modern 回退逻辑。

Work Log - 用户管理优化（编辑/检索/分页）（2026-05-01）

• 背景：

  • Issue FL-121 要求用户管理支持：用户信息修改、用户检索、用户表格分页。

• 本次改动（最小闭环）：

  • 后端 users 列表接口增强（检索 + 分页参数联动）：
    • 文件：api/app/api/v1/users.py
    • GET /api/v1/users 新增查询参数：
      • keyword：按 user_id/email/username 模糊检索
      • status：按启用/禁用状态过滤
  • 后端用户服务增强：
    • 文件：api/app/services/user_service.py
    • list_users(...) 支持 keyword/status 条件查询并对 total 同步计数。
    • update_user(...) 支持修改 email 与 username：
      • 统一 trim/归一化
      • 重复值冲突校验
      • 空值保护
  • 用户更新请求模型补齐：
    • 文件：api/app/schemas/user.py
    • UserUpdateRequest 新增可选字段 email。
  • 前端用户管理页增强：
    • 文件：web/src/app/admin/users/page.tsx
    • 新增“用户检索”区：关键字输入 + 状态筛选 + 搜索/重置。
    • 用户列表请求改为受查询条件驱动（query key 包含分页/筛选参数）。
    • 表格接入分页器（页码、每页条数、总数联动后端）。
    • 新增“编辑用户”弹窗，支持修改邮箱/用户名/状态。
    • 编辑提交仅传变更字段，避免无效更新。

• 验证（未执行编译/构建，遵循当前任务约束）：

  • 代码走读与关键路径自检：
    • GET /api/v1/users -> 支持 limit/offset/keyword/status。
    • PATCH /api/v1/users/{id} -> 支持 email/username/status 更新。
    • 前端列表查询参数与分页状态联动一致。

• 风险与影响：

  • 影响范围集中在用户管理模块（/admin/users 与 /api/v1/users*）。
  • 旧调用方不传 keyword/status 时行为保持兼容。
  • 更新失败错误提示文案仍共用“not found or email/username exists”，后续如需更精确错误码可再拆分。