feat: add official resource sync pipeline

Add the production-facing official update service and bat-official-sync watch CLI for unattended resource synchronization.

Support launcher-resource discovery without installing the launcher, remote marker snapshots, local manifest audit and repair, official seed hash validation, bootstrap caching, richer Addressables coverage, SQLite resource persistence, and FFI JSON helpers.

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

@@ -13,26 +13,23 @@
 - `macOS`
 - `bluearchive.cafe` 或其他镜像域名
 - 任何本地客户端目录
+- 任何已安装的官方启动器或 Windows 客户端
 
 ## 1. 当前流程
 
-运行时链路只走官方日服：
+Linux 生产运行时链路只走官方日服 HTTP 资源，不安装、不启动、不依赖官方启动器二进制：
 
-1. 请求官方 launcher API。
-2. 从官方 launcher manifest 链路得到最新游戏包 ZIP。
-3. 解包 `resources.assets`。
-4. 解密 `GameMainConfig`。
-5. 从 `GameMainConfig` 自动读取 `server-info` URL 和默认 `connection-group`。
-6. 请求官方 `server-info`。
-7. 生成 Windows + Android 的官方资源 discovery 端点。
-8. 拉取 seed catalog，生成完整官方 pull plan。
-9. dry-run 只输出 URL；非 dry-run 下载全部官方 URL。
+1. 显式执行 `--auto-discover`，通过官方 HTTP metadata 自动发现 `app-version`、`server-info` URL 和默认 `connection-group`。
+2. 请求官方 `server-info`。
+3. 生成 Windows + Android 的官方资源 discovery 端点。
+4. 拉取 seed catalog，生成完整官方 pull plan。
+5. dry-run 只输出 URL；非 dry-run 下载全部官方 URL。
 
-`--server-info-file` 和 `--server-info-path` 都不是硬依赖。
+`--auto-discover` 会下载官方 metadata 所需的临时包并解析 `GameMainConfig`，但不会安装官方启动器，也不会执行官方启动器进程。`--launcher-bootstrap` 只是旧命名兼容别名，新流程不要再推荐使用。
 
-## 2. 先做 launcher bootstrap
+## 2. 可选 metadata 审计
 
-先确认 launcher API 和官方 ZIP 链路正常：
+如需单独审计官方 metadata API 和官方 ZIP 链路，可以手动运行：
 
 ```bash
 cargo run -p bat-infrastructure --example official_launcher_bootstrap -- \
@@ -54,17 +51,17 @@ cargo run -p bat-infrastructure --example official_launcher_bootstrap -- \
 
 ## 3. 先做 dry-run
 
-推荐默认流程是不提供本地 `server-info` 文件，也不提供本地客户端目录：
+推荐开发和生产自动化的默认流程是显式打开 `--auto-discover`：
 
 ```bash
 cargo run -p bat-infrastructure --example official_pull_plan -- \
-  --launcher-bootstrap \
+  --auto-discover \
   --platforms Windows,Android \
   --output /tmp/ba-official-pull \
   --dry-run
 ```
 
-如果你已经有官方 `server-info` 文件，也可以显式传入：
+如果你要复现某次已审计的 metadata snapshot，也可以显式传入官方 `server-info` 文件名：
 
 ```bash
 cargo run -p bat-infrastructure --example official_pull_plan -- \
@@ -76,6 +73,18 @@ cargo run -p bat-infrastructure --example official_pull_plan -- \
   --dry-run
 ```
 
+如果你已经把官方 `server-info` JSON 存成只读本地文件，也可以使用：
+
+```bash
+cargo run -p bat-infrastructure --example official_pull_plan -- \
+  --server-info-path /path/to/server-info.json \
+  --connection-group Prod-Audit \
+  --app-version 1.70.0 \
+  --platforms Windows,Android \
+  --output /tmp/ba-official-pull \
+  --dry-run
+```
+
 检查输出时，重点看：
 
 - `platforms=[Windows, Android]`
@@ -89,7 +98,7 @@ cargo run -p bat-infrastructure --example official_pull_plan -- \
 
 ```bash
 cargo run -p bat-infrastructure --example official_pull_plan -- \
-  --launcher-bootstrap \
+  --auto-discover \
   --platforms Windows,Android \
   --output /tmp/ba-official-pull
 ```
@@ -98,28 +107,121 @@ cargo run -p bat-infrastructure --example official_pull_plan -- \
 
 - 只接受官方 URL
 - 下载完整官方资源集合
+- 下载成功后在输出目录维护 `official-download-manifest.json`
+- 已存在目标文件只有在本地下载清单中的 size 和 BLAKE3 校验通过时才会跳过
+- `TableCatalog.bytes`、`BundlePackingInfo.bytes`、`MediaCatalog.bytes` 会用官方 `.hash` 做强校验；该 `.hash` 是 `xxHash32(seed=0)` 的十进制文本
+- `catalog_*.hash` 是 Unity Addressables/SBP 写出的 catalog 变更标记，来源是 `HashingMethods.Calculate(json/bin catalog)` 生成的 `Hash128` 文本；它不是 seed catalog 的 `xxHash32` 规则，目前不作为 zip/JSON 内容强校验
+- 存在 `.part` 临时文件时会尝试断点续传
+- 新下载先写 `.part`，成功后再替换为最终文件
 - 把结果写入 `--output`
 
-## 5. 例外输入
+## 5. 自动更新检查
 
-如果必须使用本地 `server-info`，只接受：
+正式自动更新入口是 `bat-official-sync`。它会保存上一次成功同步的 snapshot，下次运行时先自动发现当前官方 metadata，再和 snapshot 对比：
 
+- 每轮都会先拉取轻量官方 metadata 和 `.hash` marker。
+- URL 没变但 `.hash` / marker 内容变更时，也会判定为需要更新。
+- 远端无变化时，默认执行本地 `official-download-manifest.json` audit。
+- 本地文件缺失、路径不一致、size 不一致或 BLAKE3 不一致时，默认进入 repair 并重下必要文件。
+- 远端和本地都一致：单次模式输出 `update_status=up_to_date`，watch 模式默认静默并等待下次检查。
+- 有远端变化或本地 repair：生成 pull plan，下载完整官方资源，成功后更新 snapshot。
+- `--dry-run`：只报告本次是否会下载，不写 snapshot；如果 cache miss，也不会写入新的 bootstrap cache。
+- `--dry-run --plan`：除更新判断外，还会解析 seed catalog 并打印完整下载 URL。
+- 真实更新会输出 `downloaded_count`、`resumed_count`、`skipped_count`、`transferred_bytes`、`official_seed_hash_verified_count`。
+- 校验报告分层输出 `official_seed_hash_verified_count`、`local_manifest_verified_count`、`addressables_marker_checked_count`、`unverified_marker_count`。
+- 下载阶段复用同一套本地清单和 `.part` 续传逻辑；没有清单或校验不匹配的文件会重新下载。
+
+状态文件默认位于 `--output` 下：
+
+- `official-sync-snapshot.json`：上一次成功同步的 v2 snapshot，包含 app version、connection group、bundle version、addressables root、endpoint URL、官方 seed `.hash` 内容、Addressables `catalog_*.hash` marker、launcher metadata 摘要和 `GameMainConfig` 摘要。
+- `official-bootstrap-cache.json`：`--auto-discover` 的 `GameMainConfig` 解析缓存。launcher metadata 未变时复用缓存；metadata 变化时才通过官方 HTTP 下载必要 game zip 到临时目录解析。
+- `official-download-manifest.json`：本地下载强校验清单，记录 URL、相对路径、size 和 BLAKE3。
+
+先 dry-run：
+
+```bash
+cargo run -p bat-infrastructure --bin bat-official-sync -- \
+  --auto-discover \
+  --platforms Windows,Android \
+  --output /tmp/ba-official-update \
+  --snapshot /tmp/ba-official-update/official-sync-snapshot.json \
+  --dry-run
+```
+
+如果需要在 dry-run 阶段审阅完整下载 URL，加 `--plan`：
+
+```bash
+cargo run -p bat-infrastructure --bin bat-official-sync -- \
+  --auto-discover \
+  --platforms Windows,Android \
+  --output /tmp/ba-official-update \
+  --snapshot /tmp/ba-official-update/official-sync-snapshot.json \
+  --dry-run \
+  --plan
+```
+
+确认后执行真实更新：
+
+```bash
+cargo run -p bat-infrastructure --bin bat-official-sync -- \
+  --auto-discover \
+  --platforms Windows,Android \
+  --output /tmp/ba-official-update \
+  --snapshot /tmp/ba-official-update/official-sync-snapshot.json
+```
+
+Rust 常驻更新模式默认每 1 小时执行一次检查，符合则静默，不符合则自动拉取/repair 并输出 JSON report：
+
+```bash
+cargo run -p bat-infrastructure --bin bat-official-sync -- \
+  --auto-discover \
+  --platforms Windows,Android \
+  --output /tmp/ba-official-update \
+  --snapshot /tmp/ba-official-update/official-sync-snapshot.json \
+  --watch
+```
+
+如需调整间隔：
+
+```bash
+cargo run -p bat-infrastructure --bin bat-official-sync -- \
+  --auto-discover \
+  --platforms Windows,Android \
+  --output /tmp/ba-official-update \
+  --watch \
+  --interval 30m
+```
+
+命令成功时 stdout 输出稳定 JSON report；错误时 stderr 输出 JSON error。普通错误 exit `1`，状态目录锁冲突 exit `75`。
+
+生产可以直接运行 `--watch`，也可以用 systemd service、容器或 Go 进程守护它。cron/systemd timer 仍可调用单次模式，但不再是 Rust 自动更新的唯一方式。项目是否热更新、热重载或重启进程，由上层业务集成决定。生产目录应使用独立输出目录，不要指向现有客户端或人工维护的资源目录。非 dry-run 每轮会创建 `--output/.official-sync.lock`，防止并发写同一状态目录。
+
+需要只做探测时可以加 `--dry-run`。需要关闭本地 audit 或 repair 时可以显式使用 `--no-audit-local` 或 `--no-repair`，但生产同步默认应保持开启。
+
+## 6. 例外输入
+
+可接受的 `server-info` 输入是：
+
+- `--auto-discover`
+- `--server-info-url <官方 URL>`
 - `--server-info-file <官方文件名>`
 - `--server-info-path <本地官方 JSON>`
 
-但这两项不再是主流程依赖。
+如果没有显式 `server-info` 输入，必须手动加 `--auto-discover` 才会走官方 metadata / `GameMainConfig` 辅助发现链路。不要在 Linux 生产任务里依赖已安装启动器或本地客户端目录。
 
-## 6. 代码入口
+## 7. 代码入口
 
 当前可用的用户入口：
 
 - `infrastructure/examples/official_launcher_bootstrap.rs`
 - `infrastructure/examples/official_pull_plan.rs`
+- `infrastructure/src/bin/bat_official_sync.rs`
+- `infrastructure/examples/official_update_check.rs`（历史/开发入口；生产优先使用 `bat-official-sync`）
 - `adapters/examples/yostar_jp_client_bootstrap.rs`
 - `adapters/examples/yostar_jp_discovery.rs`
 - `adapters/examples/yostar_jp_inventory.rs`
 
-## 7. 验证
+## 8. 验证
 
 推荐验证命令：
 
@@ -128,5 +230,5 @@ cargo test -p bat-adapters
 cargo test -p bat-infrastructure
 cargo test -p bat-infrastructure --example official_launcher_bootstrap -- --nocapture
 cargo test -p bat-infrastructure --example official_pull_plan -- --nocapture
+cargo test -p bat-infrastructure --bin bat-official-sync -- --nocapture
 ```
-