refactor: unify data preparations and research input snapshots

docs/deployment-gitea.md

@@ -87,3 +87,30 @@ docker logs --tail=100 wq-alpha-production-web-1
 采用 compound 经验 1 中的生产/开发隔离、显式外部网络、必填凭据、固定项目名、独立迁移和部署健康检查。未照搬旧项目端口、业务 Job 或卷权限初始化：本应用后端不写 named volume，已有镜像使用 UID 10001。
 
 凭据存放在 Gitea Secrets，通过步骤级环境变量交给 Compose，不落地到配置文件。Docker 容器仍需持有运行时配置，因此拥有 Runner 或 Docker 管理权限的人仍可能读取它们。若此前手动创建了旧 `.env.production`，新流程不再读取它；确认配置已迁移到 Gitea 并妥善备份密钥后可自行移除旧文件。相关官方资料：[Compose 外部网络](https://docs.docker.com/reference/compose-file/networks/)、[环境变量插值](https://docs.docker.com/compose/how-tos/environment-variables/variable-interpolation/)、[Gitea Runner 标签](https://gitea.com/gitea/runner/src/branch/main/README.md)。
+
+## 5. 1Panel 夜间全量目录同步
+
+在 1Panel 的计划任务中建立 Shell 脚本任务，执行周期由 1Panel 设置，例如每天深夜执行。每次命令明确指定一个范围：
+
+```bash
+docker exec wq-alpha-production-backend-1 \
+  python -m app.cli catalog-sync \
+  --region USA --universe TOP3000 --delay 1
+```
+
+`--instrument-type` 默认 `EQUITY`，`--wait-timeout` 默认 `21600` 秒（六小时）。容器已持有部署时注入的环境，定时脚本无需再次填写数据库、密码或加密密钥；不要加 `-it`。容器命令继承环境的行为见 [Docker exec 官方文档](https://docs.docker.com/reference/cli/docker/container/exec/)。启动前在网页完成 WorldQuant 连接，人工验证仍在网页处理。
+
+CLI 只创建持久化任务并等待，不启动另一个同步执行器；后端必须正在运行。相同范围的活动全量任务复用同一任务 ID。任务先完整更新数据集清单，再逐个同步所有字段，每个数据集独立完整发布。普通单集失败保留上一版并继续其他数据集；鉴权和网络连接问题暂停全量任务。任务面板可查看阶段、当前数据集、字段分页位置、成功/失败统计，并取消或重试。
+
+1Panel 执行日志保存 CLI 输出的任务 ID、状态变化、检查点和最终汇总。也可使用 `docker logs --tail=100 wq-alpha-production-backend-1` 排查执行器；命令不输出平台认证信息。不要公开包含研究数据的日志。
+
+失败或部分失败时按日志中的任务 ID 从检查点继续，已成功发布的数据集不会重抓：
+
+```bash
+docker exec wq-alpha-production-backend-1 \
+  python -m app.cli catalog-sync --resume-job TASK_ID --wait-timeout 21600
+```
+
+退出码：`0` 全部成功，`1` 失败/部分失败/取消，`2` 参数错误，`3` 需要连接或人工验证，`4` 等待超时。超时只结束 CLI 等待，后台任务继续；重复执行同范围命令可继续等待活动任务。恢复前先处理连接或验证问题。服务重启后由原执行器恢复持久化检查点；定时调度仅由 1Panel 负责。
+
+真实平台协议和 1Panel 实际触发效果不属于模拟验收。