fix: harden official resource sync retries

docs/architecture/README.md

@@ -116,7 +116,7 @@ official-sync-snapshot.json + official-download-manifest.json
 - 不安装、不执行官方 launcher。
 - 默认平台 `Windows + Android`。
 - `--auto-discover` 自动获取 `app-version`、`connection-group` 和 `server-info`。
-- `--watch` 常驻检查，默认 1 小时。
+- `--watch` 常驻检查，正常检查默认 1 小时，失败重试默认 60 秒。
 - 远端 marker 无变化且本地 manifest clean 时不下载。
 - 本地文件损坏时 repair。
 - 官方 seed `.hash` 强校验；Addressables `catalog_*.hash` 作为变更 marker。

docs/architecture/official-resource-backend.md

@@ -190,7 +190,7 @@
 7. 远端变化或本地 audit 发现 repair_needed 时生成 pull plan，下载并校验官方 URL。
 8. 下载成功后写回新的 snapshot。
 
-该入口不安装、不执行官方启动器，也不读取生产外的本地客户端目录。Rust 正式 binary 支持 `--watch` 常驻模式，默认每 1 小时执行一次检查；远端和本地一致时静默等待下次检查，不一致时自动下载或 repair。单次运行仍保留为核心幂等路径，systemd service、容器或 Go 进程可以只负责守护该常驻进程；cron/systemd timer 调单次模式只是可选集成方式。项目是否热更新、热重载或重启进程，由上层业务集成决定。
+该入口不安装、不执行官方启动器，也不读取生产外的本地客户端目录。Rust 正式 binary 支持 `--watch` 常驻模式，正常情况下默认每 1 小时执行一次检查；远端和本地一致时静默等待下次检查，不一致时自动下载或 repair。下载、发现或校验失败时不等待完整正常周期，默认 60 秒后重试，可用 `--error-retry` 或 `--error-retry-seconds` 调整。单次运行仍保留为核心幂等路径，systemd service、容器或 Go 进程可以只负责守护该常驻进程；cron/systemd timer 调单次模式只是可选集成方式。项目是否热更新、热重载或重启进程，由上层业务集成决定。
 
 对应实现主要在：
 
@@ -228,7 +228,7 @@ Linux 生产路径：
 - pull plan 会同时包含 discovery URLs 和 content URLs
 - 全量样本下是 `2` 个 discovery URL + `5` 个内容 URL = `7` 个 URL
 - `OfficialUpdateService` 能持久化 v2 snapshot，并在远端 marker 内容变化时触发下载决策
-- `bat-official-sync` 输出稳定 JSON report，支持 `--watch --interval 1h` 常驻运行，非 dry-run 使用 `.official-sync.lock` 防止并发写状态目录
+- `bat-official-sync` 输出稳定 JSON report，支持 `--watch --interval 1h --error-retry 60s` 常驻运行，非 dry-run 使用 `.official-sync.lock` 防止并发写状态目录
 - `OfficialUpdateService` 能读写 `official-bootstrap-cache.json`，并支持默认开启的 `audit_local` / `repair` CLI 行为
 - 下载层能在本地文件 size/BLAKE3/path 或 manifest 不匹配时重新下载
 - 官方 seed `.hash` mismatch 会导致下载失败，而不是降级为本地 BLAKE3 猜测

docs/guides/deployment.md

@@ -157,7 +157,7 @@ target/release/bat-official-sync
   --watch
 ```
 
-`--watch` 是 Rust 内部持久检查模式，默认每 1 小时执行一次检查。远端和本地一致时默认静默；有远端变化或本地文件损坏时自动下载或 repair，并输出 JSON report。
+`--watch` 是 Rust 内部持久检查模式，正常情况下默认每 1 小时执行一次检查。远端和本地一致时默认静默；有远端变化或本地文件损坏时自动下载或 repair，并输出 JSON report。下载、发现或校验失败时默认 60 秒后重试，可显式加 `--error-retry 60s` 或 `--error-retry-seconds 60` 调整。
 
 ### systemd service 示例
 
@@ -173,7 +173,7 @@ Wants=network-online.target
 Type=simple
 User=bat
 Group=bat
-ExecStart=/opt/bluearchive-toolkit/bin/bat-official-sync --auto-discover --platforms Windows,Android --output /var/lib/bluearchive-toolkit/official --watch
+ExecStart=/opt/bluearchive-toolkit/bin/bat-official-sync --auto-discover --platforms Windows,Android --output /var/lib/bluearchive-toolkit/official --watch --error-retry 60s
 Restart=on-failure
 RestartSec=30
 StateDirectory=bluearchive-toolkit

docs/guides/official-resource-test-pull.md

@@ -225,10 +225,11 @@ cargo run -p bat-infrastructure --bin bat-official-sync -- \
   --platforms Windows,Android \
   --output /tmp/ba-official-update \
   --watch \
-  --interval 30m
+  --interval 30m \
+  --error-retry 60s
 ```
 
-命令成功时 stdout 输出稳定 JSON report；错误时 stderr 输出 JSON error。普通错误 exit `1`，状态目录锁冲突 exit `75`。
+`--interval` 是正常检查周期，默认 `1h`；`--error-retry` 是下载、发现或校验失败后的重试周期，默认 `60s`，也可以用 `--error-retry-seconds 60`。命令成功时 stdout 输出稳定 JSON report；错误时 stderr 输出 JSON error，watch 模式下错误 JSON 的 `next_retry_seconds` 使用失败重试周期。普通错误 exit `1`，状态目录锁冲突 exit `75`。
 
 生产可以直接运行 `--watch`，也可以用 systemd service、容器或 Go 进程守护它。cron/systemd timer 仍可调用单次模式，但不再是 Rust 自动更新的唯一方式。项目是否热更新、热重载或重启进程，由上层业务集成决定。生产目录应使用独立输出目录，不要指向现有客户端或人工维护的资源目录。非 dry-run 每轮会创建 `--output/.official-sync.lock`，防止并发写同一状态目录。
 

docs/reports/current-status-handoff.md

@@ -18,7 +18,7 @@
 - `--auto-discover` 通过官方 HTTP metadata 和临时目录解析 `GameMainConfig`。
 - 默认平台是 `Windows + Android`。
 - 真实下载会维护 `official-download-manifest.json`，并使用 size + BLAKE3、本地 audit/repair 和官方 seed `.hash` 校验。
-- `--watch` 是 Rust 内部常驻检查模式，默认 1 小时；外部 systemd/container 只负责守护进程。
+- `--watch` 是 Rust 内部常驻检查模式，正常检查默认 1 小时，失败重试默认 60 秒；外部 systemd/container 只负责守护进程。
 
 ## 2. 现在不要误解的点