MEMORY.md - fquiz 工程长期记忆

项目基线

在未明确项目技术栈、目录结构、部署方式前，避免把其他工程（如 quiz / nquiz）的具体规则直接套用到 fquiz。
后续若 fquiz 绑定真实仓库或明确职责，应在此文件补充长期有效口径。
API 镜像构建阶段支持通过 PIP_INDEX_URL（Secrets/Variables）和 PIP_DEFAULT_TIMEOUT（Variables）调优 pip 拉包稳定性；默认索引为 https://pypi.org/simple。
web 目录用于 Docker 独立构建时，web/package.json 与 web/package-lock.json 必须保持同步；否则 web/Dockerfile 中的 npm ci 会因锁文件不一致直接失败（EUSAGE）。

文件管理一期采用三层模型：
- file_storage_backends（后端定义：VFS/S3）
- file_storage_mounts（挂载点）
- file_index_entries（目录索引快照）
后台 API 入口统一在 /api/v1/admin/files 前缀，权限码为：
- file.read：浏览挂载点和目录列表
- file.manage：创建目录、删除路径
存储驱动抽象位于 api/app/services/storage_driver.py，VFS/S3 必须通过同一工厂分发，避免业务层直接耦合具体存储 SDK。
VFS 默认根目录由 FILE_VFS_ROOT 控制（默认 ./data/vfs）。

SQLAlchemy 关联加载选项（selectinload/joinedload）避免在模块导入期以全局常量初始化，优先在函数内惰性构建，防止导入顺序导致 mapper 提前配置失败。
app.models 包初始化需预加载全部模型模块，确保字符串关系（如 "AuditLog"）在启动阶段可解析。
部署 compose 中 DB 镜像应通过 POSTGRES_IMAGE 可配置，默认使用镜像站的 pgvector 镜像（docker.m.daocloud.io/pgvector/pgvector:pg16）。
宿主机 DB 暴露端口统一走 POSTGRES_PORT（默认 5433），用于规避与宿主机已有 PostgreSQL（常见 5432）冲突；容器内连接仍保持 db:5432。
CORS 来源控制采用“双轨配置”：API_CORS_ORIGINS（精确列表）+ API_CORS_ORIGIN_REGEX（正则，可选）；API_CORS_ORIGINS 支持 * 和通配符域名并在后端转换为 allow_origin_regex。
GitHub Actions 使用 appleboy/ssh-action 部署时，慢网环境需显式设置 command_timeout（建议 45m）并为 docker compose pull 增加重试，避免出现 Run Command Timeout 直接中断发布。

NEXT_PUBLIC_API_BASE_URL 若误配为 loopback（127.0.0.1/localhost），前端运行时会在浏览器端自动改写为“当前页面主机 + 同端口（默认 8000）”，避免公网页面触发 PNA（Private Network Access）阻断。
认证请求与 WebSocket 连接均统一复用该运行时 API 基址解析逻辑。