@@ -334,3 +334,224 @@
- 风险与影响：
- 影响范围仅文件管理上传链路与认证上下文类型定义，不涉及后端接口契约变更。
- 上传改为 XHR 后仍保留 `withCredentials + Bearer token` ，与现有认证模式兼容。
## Work Log - 修复 Docker Flower 容器重启异常（2026-05-02）
- 背景：
- `docker compose ps` 显示 `fquiz-flower` 持续 `Restarting` 。
- `docker compose logs flower` 报错：`Error: No such command 'flower'.`
- 根因：
- `flower` 服务命令使用 `celery ... flower` ，但 `api` 镜像依赖中未安装 `flower` 包。
- 同时 `docker compose` 在解析阶段对 `minio-init.command` 中的 `$MINIO_*` 进行了提前插值，导致每次执行出现变量未设置 warning。
- 本次改动（最小闭环）：
- 文件：`api/requirements.txt`
- 新增依赖：`flower==2.0.1` 。
- 文件：`api/pyproject.toml`
- 新增依赖：`flower>=2.0.0,<3.0.0` ，与 requirements 口径一致。
- 文件：`docker-compose.yml`
- `minio-init` 启动脚本中的变量引用改为 `$$MINIO_*` ，避免 compose 提前展开：
- `"$MINIO_ENDPOINT" -> "$$MINIO_ENDPOINT"`
- `"$MINIO_ACCESS_KEY" -> "$$MINIO_ACCESS_KEY"`
- `"$MINIO_SECRET_KEY" -> "$$MINIO_SECRET_KEY"`
- `"$MINIO_BUCKET" -> "$$MINIO_BUCKET"`
- 验证：
- 执行：`docker compose up -d --build flower`
- `docker compose ps flower` ： `Up` ，不再重启。
- `docker compose logs flower` ：
- 出现 `Visit me at http://0.0.0.0:5555`
- 出现 `Connected to redis://redis:6379/0`
- 执行：`docker compose logs --since=10m ... | rg "ERROR|Traceback|Exception|No such command|CRITICAL|FATAL|UndefinedColumn|relation \"|failed|denied|permission"`
- 结果：近 10 分钟内无命中。
- 风险与影响：
- 影响面：`api` 镜像新增 `flower` 依赖，镜像体积与构建时长略有增加。
- 当前运行中的 `api/celery-worker/celery-beat/scheduler/web` 仍为既有镜像；本次仅重建并替换了 `flower` 。
## Work Log - 固定 workflow WEB 端口为 3000（ ）
- 背景：
- 发布后 `fquiz-web` 宿主机端口出现 `13000->3000` ，与 Nginx 固定代理 `127.0.0.1:3000` 不一致。
- 根因是 workflow 的 `ensure_web_port_available` 在 3000 冲突时会自动回退到 13000+ 并写回 `.env` 。
- 本次改动（最小闭环）：
- 文件：`.github/workflows/main.yml`
- 调整 `ensure_web_port_available` ：
- 每次部署前强制写入 `WEB_PORT=3000` （存在则覆盖，不存在则追加）。
- 移除自动回退到 `13000+` 逻辑。
- 若 `3000` 被其它容器占用，直接输出错误并终止部署。
- 预期效果：
- workflow 部署后，`fquiz-web` 宿主机端口稳定为 `3000` ，避免与 Nginx 前端代理端口漂移。
- 风险与影响：
- 若服务器上已有其他容器占用 `3000` ，本次部署会失败（可预期失败），需先释放端口或手动调整冲突容器。
## Work Log - 移除 scheduler 服务并统一任务调度为 API 直连 Celery（ ）
- 背景：
- 用户明确要求“去掉 scheduler”。
- 当前仓库默认调度本就为 `celery_direct` ， `scheduler` 仅作为可选分支与独立容器存在。
- 本次改动（最小闭环）：
- 后端任务派发收敛为直连 Celery：
- `api/app/services/elevation_service.py`
- 删除 `dispatch_mode` 分支与 `_enqueue_via_scheduler_api` 转发实现。
- 保留单一路径：`apply_elevation_for_line_job.delay(job_id)` 。
- `api/app/api/v1/elevation.py`
- 删除 `dispatchMode` 查询参数透传。
- 后端路由与配置清理：
- `api/app/api/router.py`
- 移除 `scheduler` 路由注册。
- `api/app/core/config.py`
- 删除 `scheduler_api_token` / `scheduler_default_queue` / `scheduler_api_base_url` 及其 `resolved_*` 属性。
- 保留 `scheduler_expire_interval_seconds` 作为 Celery Beat 定时任务间隔配置。
- 删除 scheduler 相关源文件：
- `api/app/api/v1/scheduler.py`
- `api/app/services/scheduler_service.py`
- `api/app/schemas/scheduler.py`
- `api/app/scheduler_main.py`
- 运行与部署配置同步：
- `docker-compose.yml`
- 删除 `scheduler` 服务。
- 删除 `api` / `celery-worker` / `celery-beat` 的 `SCHEDULER_API_BASE_URL` 、`SCHEDULER_API_TOKEN` 、`SCHEDULER_DEFAULT_QUEUE` 。
- `.env.example`
- 删除 `SCHEDULER_API_BASE_URL` 、`SCHEDULER_API_TOKEN` 、`SCHEDULER_DEFAULT_QUEUE` 、`SCHEDULER_PORT` 。
- `.github/workflows/main.yml`
- 删除生产 compose 模板中的 `scheduler` 服务块。
- 删除部署模板与默认 `.env` 中的 `SCHEDULER_API_*` / `SCHEDULER_PORT` 。
- 删除故障诊断日志中的 `fquiz-scheduler` 。
- 长期记忆更新：
- `MEMORY.md`
- 将“调度与监控口径”更新为“API 直连 Celery，不再保留 scheduler 服务”。
- 验证：
- 语法检查通过：
- `python3 -m py_compile api/app/api/router.py api/app/api/v1/elevation.py api/app/services/elevation_service.py api/app/core/config.py`
- 关键残留检查：
- `rg -n "scheduler_main|services/scheduler_service|api/v1/scheduler|SCHEDULER_API_BASE_URL|SCHEDULER_API_TOKEN|SCHEDULER_DEFAULT_QUEUE|scheduler_api|fquiz-scheduler|SCHEDULER_PORT|resolved_scheduler_" .`
- 仅命中文档历史记录，不再命中运行代码与部署配置。
- 风险与影响：
- 影响范围：任务调度入口、部署编排与环境模板。
- 行为变化：不再支持 `dispatchMode=scheduler_api` 与独立 scheduler HTTP 网关调用。
- 保持不变：默认任务链路（API 直连 Celery）与 Flower 监控链路。
## Work Log - 切换部署入口到 deploy 目录并删除根 docker-compose.yml（ ）
- 背景：
- 用户要求将部署结构统一到 `deploy/dev-deploy` 与 `deploy/pro-deploy` ，并删除根目录 `docker-compose.yml` 。
- 本次改动：
- 新增目录结构：
- `deploy/dev-deploy/{compose.yml,.env,.env.dev}`
- `deploy/pro-deploy/{compose.yml,.env,.env.prod}`
- 本地开发入口切换：
- `package.json` 的 `docker:up/down/logs` 改为显式使用 `deploy/dev-deploy/compose.yml` + `deploy/dev-deploy/.env` 。
- `README.md` Docker 部署说明改为基于 `deploy/dev-deploy` 。
- `AGENTS.md` 根脚本说明改为指向 `deploy/dev-deploy` 。
- 部署流水线切换：
- `.github/workflows/main.yml` 改为使用 `deploy/pro-deploy` 结构进行生产部署（不再依赖根 compose）。
- 长期记忆口径更新：
- `MEMORY.md` 中 Docker 命令口径改为 `deploy/dev-deploy` 方案。
- 删除：
- 根目录 `docker-compose.yml` 。
- 验证：
- 目录校验：`find deploy -maxdepth 3 -type f | sort` 命中 dev/pro 全套文件。
- 入口校验：`rg` 检查脚本/文档，已无根 compose 作为默认入口。
- 风险与影响：
- 旧习惯直接执行 `docker compose up -d` （仓库根目录）将失效，必须改为显式 `-f deploy/.../compose.yml` 。
- workflow 远端部署改为写入并使用 `deploy/pro-deploy` ，对旧服务器目录结构有一次性迁移要求。
## Work Log - 移除 deploy 中的 nginx 服务（2026-05-02）
- 背景：
- 用户确认原工程不需要 nginx 服务，仅需保留 deploy 双目录与 compose/env 结构。
- 本次改动：
- 删除 `deploy/dev-deploy/compose.yml` 与 `deploy/pro-deploy/compose.yml` 中的 `nginx` 服务定义。
- 删除 `deploy/dev-deploy/.env` 与 `deploy/pro-deploy/.env` 中 `NGINX_*` 变量。
- 删除 `deploy/dev-deploy/nginx/` 与 `deploy/pro-deploy/nginx/` 目录。
- 更新 `.github/workflows/main.yml` ，移除 nginx 相关生成、变量与日志采集逻辑。
- 验证：
- `docker compose --env-file deploy/dev-deploy/.env -f deploy/dev-deploy/compose.yml config` -> 通过。
- `docker compose --env-file deploy/pro-deploy/.env -f deploy/pro-deploy/compose.yml config` -> 通过。
- 风险与影响：
- 部署后不再提供内置反向代理与 HTTPS 终止能力，如需网关需由外部 LB/Nginx/Ingress 承接。
## Work Log - deploy 目录统一托管组件配置与数据挂载（2026-05-02）
- 背景：
- 用户目标是将各组件配置与数据文件集中挂载到 `deploy` 目录，便于统一管理；`nginx` 仅为示例并非必需。
- 本次改动：
- `deploy/dev-deploy/compose.yml` 与 `deploy/pro-deploy/compose.yml` 改为目录挂载：
- DB： `./data/postgres -> /var/lib/postgresql/data`
- Redis： `./data/redis -> /data`
- MinIO： `./data/minio -> /data`
- API/Worker/Beat： `./data/app -> /app/data`
- Celery Beat 调度文件持久化：
- `--schedule=/app/data/celery/beat-schedule`
- 删除命名卷定义，改为显式 bind mount。
- 新增目录骨架（含 `.gitkeep` ）：
- `deploy/dev-deploy/data/{postgres,redis,minio,app/celery}`
- `deploy/pro-deploy/data/{postgres,redis,minio,app/celery}`
- 验证：
- `docker compose --env-file deploy/dev-deploy/.env -f deploy/dev-deploy/compose.yml config` -> 通过。
- `docker compose --env-file deploy/pro-deploy/.env -f deploy/pro-deploy/compose.yml config` -> 通过。
- 风险与影响：
- 宿主机目录权限需允许容器读写（尤其 PostgreSQL/Redis/MinIO）。
- 生产环境若采用只读部署目录，需单独放开 `deploy/*/data/**` 写权限。
## Work Log - dev-deploy 环境注入文件更名（2026-05-02）
- 背景：
- `dev-deploy` 使用 `.env.prod` 命名语义不清晰。
- 本次改动：
- 将 `deploy/dev-deploy/.env.prod` 重命名为 `deploy/dev-deploy/.env.dev` 。
- 将 `deploy/dev-deploy/compose.yml` 中 `env_file` 引用同步改为 `.env.dev` 。
- 将 `README.md` 中相关命令与说明同步改为 `.env.dev` 。
- 验证：
- `docker compose --env-file deploy/dev-deploy/.env -f deploy/dev-deploy/compose.yml config` -> 通过。
- 风险与影响：
- 本地若仍保留旧文件名 `.env.prod` ，将不再被 dev compose 自动读取。
## Work Log - 直接更新 users 管理员账号（2026-05-02）
- 背景：
- 用户要求将 users 表中的管理员账号改为：
- `user_id=admin`
- `username=管理员`
- 密码更新为 `tiandiyisuren` 。
- 执行过程（仅数据库数据变更，无代码改动）：
- 先检查 `public.users` 表结构与外键引用，确认 `user_roles.user_id -> users.user_id` 为外键，且约束不带 `ON UPDATE CASCADE` 。
- 因此未采用直接 `UPDATE users.user_id` （会触发外键失败），改为单事务迁移：
1. 临时改写旧用户 email（规避唯一键冲突）。
2. 插入新用户行（`user_id=admin` ， `username=管理员` ，密码为 Argon2 哈希）。
3. 将 `user_roles.user_id` 从旧值迁移到 `admin` 。
4. 删除旧用户行。
- 密码哈希通过运行中的 `fquiz-api` 容器使用 Argon2 生成，保持与后端鉴权逻辑一致。
- 验证：
- `SELECT user_id,email,username,status FROM public.users;` -> 仅剩 1 条：`admin / admin@example.com / 管理员 / ENABLED` 。
- `SELECT user_id, role_id FROM public.user_roles;` -> 角色绑定已迁移为 `admin` 。
- `password_hash` 前缀校验：`$argon2id$...` 。
- 风险与影响：
- 影响面：`users` 与 `user_roles` 的标识数据。
- 登录标识变化：后端 JWT 的 `sub` 将从旧 user_id 变为 `admin` ；历史会话令牌若仍在使用，可能需要重新登录。
- 本次未改动 `email` ，仍为 `admin@example.com` 。
chengkml