feat(assetbundle): 完善官方资源解析与双目录发布

docs/guides/deployment.md

@@ -227,10 +227,11 @@ systemctl status bluearchive-toolkit-official-sync.service
 journalctl -u bluearchive-toolkit-official-sync.service -f
 sudo -u bat /opt/bluearchive-toolkit/bin/bat doctor \
   --output /var/lib/bluearchive-toolkit/official \
+  --localized-output /var/lib/bluearchive-toolkit/localized \
   --state-dir /run/bluearchive-toolkit
 ```
 
-`--watch` 是 Rust 内部持久检查模式，正常情况下默认每 1 小时执行一次检查，并且每天北京时间（UTC+8）`03:00`、`16:00`、`18:00` 会强制执行一次自动刷新。固定时间刷新会中断普通 interval 的 sleep，该轮注入 `force=true`；如果失败，会按失败重试周期继续重试。远端和本地一致时默认静默；有远端变化或本地文件损坏时自动下载或 repair，并输出人类可读摘要。下载、发现或校验失败时默认 60 秒后重试，可显式加 `BAT_ERROR_RETRY=60s` 或调整 service `ExecStart`。默认平台是 `Windows,Android`，无需显式传 `--platforms`；需要覆盖时用 systemd drop-in 重写 `ExecStart`。默认资源目录是 `./bat-resources`，生产 service 显式使用 `/var/lib/bluearchive-toolkit/official`。生产读取方应读取 `/var/lib/bluearchive-toolkit/official/current`；同步中的文件只会进入 `.staging/<id>`，校验完成后才发布为 `versions/<id>` 并切换 `current`。
+`--watch` 是 Rust 内部持久检查模式，正常情况下默认每 1 小时执行一次检查，并且每天北京时间（UTC+8）`03:00`、`16:00`、`18:00` 会强制执行一次自动刷新。固定时间刷新会中断普通 interval 的 sleep，该轮注入 `force=true`；如果失败，会按失败重试周期继续重试。远端和本地一致时默认静默；有远端变化或本地文件损坏时自动下载或 repair，并输出人类可读摘要。下载、发现或校验失败时默认 60 秒后重试，可显式加 `BAT_ERROR_RETRY=60s` 或调整 service `ExecStart`。默认平台是 `Windows,Android`，无需显式传 `--platforms`；需要覆盖时用 systemd drop-in 重写 `ExecStart`。默认官方原版资源目录是 `./bat-resources`，默认汉化产物目录是 `./bat-localized`；生产 service 显式使用 `/var/lib/bluearchive-toolkit/official` 和 `/var/lib/bluearchive-toolkit/localized`，两者不能相同或互相嵌套。生产读取方应读取 `/var/lib/bluearchive-toolkit/official/current`；同步中的原版文件只会进入 `.staging/<id>`，校验完成后才发布为 `versions/<id>` 并切换 `current`。官方同步报告 `localized_release_status=not_localized` 表示汉化资源尚未发布；后续 Patch 发布才切换 `/var/lib/bluearchive-toolkit/localized/current`。
 
 ### 可选模式：CLI 自托管 `--daemon`
 
@@ -240,6 +241,7 @@ sudo -u bat /opt/bluearchive-toolkit/bin/bat doctor \
 sudo -u bat /opt/bluearchive-toolkit/bin/bat \
   --auto-discover \
   --output /var/lib/bluearchive-toolkit/official \
+  --localized-output /var/lib/bluearchive-toolkit/localized \
   --state-dir /var/lib/bluearchive-toolkit/daemon-state \
   --daemon
 
@@ -262,9 +264,11 @@ systemd 模式：
 - 当前可读 release：`/var/lib/bluearchive-toolkit/official/current`
 - 资源状态：`/var/lib/bluearchive-toolkit/official/current/official-sync-snapshot.json`
 - 下载 manifest：`/var/lib/bluearchive-toolkit/official/current/official-download-manifest.json`
+- 解析缓存：`/var/lib/bluearchive-toolkit/official/current/official-parse-cache.json`
 - 历史 release：`/var/lib/bluearchive-toolkit/official/versions/<id>`
 - 同步 staging：`/var/lib/bluearchive-toolkit/official/.staging/<id>`
 - 资源写锁：`/var/lib/bluearchive-toolkit/official/.official-sync.lock`
+- 汉化 release（Patch 发布后）：`/var/lib/bluearchive-toolkit/localized/current`
 - 运行期目录：`/run/bluearchive-toolkit/`
 
 standalone `--daemon` 模式：
@@ -279,10 +283,10 @@ standalone `--daemon` 模式：
 ### 生产维护命令
 
 ```bash
-sudo -u bat /opt/bluearchive-toolkit/bin/bat refresh --output /var/lib/bluearchive-toolkit/official
-sudo -u bat /opt/bluearchive-toolkit/bin/bat refresh --force --output /var/lib/bluearchive-toolkit/official
-sudo -u bat /opt/bluearchive-toolkit/bin/bat verify --output /var/lib/bluearchive-toolkit/official
-sudo -u bat /opt/bluearchive-toolkit/bin/bat repair --output /var/lib/bluearchive-toolkit/official
+sudo -u bat /opt/bluearchive-toolkit/bin/bat refresh --output /var/lib/bluearchive-toolkit/official --localized-output /var/lib/bluearchive-toolkit/localized
+sudo -u bat /opt/bluearchive-toolkit/bin/bat refresh --force --output /var/lib/bluearchive-toolkit/official --localized-output /var/lib/bluearchive-toolkit/localized
+sudo -u bat /opt/bluearchive-toolkit/bin/bat verify --output /var/lib/bluearchive-toolkit/official --localized-output /var/lib/bluearchive-toolkit/localized
+sudo -u bat /opt/bluearchive-toolkit/bin/bat repair --output /var/lib/bluearchive-toolkit/official --localized-output /var/lib/bluearchive-toolkit/localized
 sudo -u bat /opt/bluearchive-toolkit/bin/bat doctor --output /var/lib/bluearchive-toolkit/official --state-dir /run/bluearchive-toolkit
 sudo -u bat /opt/bluearchive-toolkit/bin/bat clean-stable --output /var/lib/bluearchive-toolkit/official --state-dir /run/bluearchive-toolkit
 ```

docs/guides/development.md

@@ -141,11 +141,18 @@ git push origin feature/your-feature-name
 cargo fmt --check
 cargo test --workspace
 cargo clippy --workspace --all-targets -- -D warnings
-go test ./...
-go vet ./...
+make test-go-api
+make build-go-api
+go vet ./internal/api/... ./internal/backendrpc/... ./cmd/bat-api/...
 ```
 
-Go 产品入口尚未完成，但仓库已有 `internal/backendrpc` Rust daemon RPC client、`cmd/bat` 试验骨架与 `internal/ffi` 兼容包装。提交前应运行 `go test ./...` 和 `go vet ./...`；`internal/backendrpc` 使用 fake transport 覆盖 JSON-RPC envelope、错误和 typed helper，不能把这些测试误认为 Go 产品级 CLI/API 已完成。
+Go 边界与进度以 `docs/reports/GO_STATUS.md` 为准：
+
+- **同步/运维命令行** = Rust `bat`（近乎全自动）
+- **资源分发服务** = `cmd/bat-api`（`make build-go-api`）
+- **默认 Go 门禁** = `make test-go-api`（无 FFI）
+- 试验 CLI 产物为 `bin/bat-go`（`make build-go-cli`），**禁止**与 Rust `bat` 重名
+- 修改 FFI 时再跑 `make test-go-ffi`
 
 ### 常用聚焦命令
 
@@ -160,7 +167,7 @@ cargo clippy -p bat-core -p bat-adapters -p bat-infrastructure --all-targets --
 
 官方资源同步、下载、daemon、status、verify 或 repair 相关改动必须至少覆盖 `bat-infrastructure` 和 `bat` 二进制测试。
 
-`bat-ffi` 只是可选无状态 C ABI 兼容层。修改 FFI 导出、JSON schema、错误返回或 `internal/ffi` CGO 包装时必须运行 `cargo test -p bat-ffi -- --nocapture`；未来 Go 产品入口和生产同步默认应通过 `internal/backendrpc` 调用 daemon RPC，或在 one-shot/fallback 场景使用 Rust `bat --json` 进程边界。
+`bat-ffi` 只是可选无状态 C ABI 兼容层。修改 FFI 时必须运行 `cargo test -p bat-ffi -- --nocapture`。Go 服务层默认经 `internal/backendrpc` 调 daemon；同步任务由 Rust `bat` 执行，不由 Go 试验 CLI 承担。
 
 ### 集成测试
 
@@ -186,7 +193,7 @@ cargo run -p bat-infrastructure --bin bat -- \
   --dry-run
 ```
 
-开发环境真实下载默认写入 `./bat-resources`；如果要覆盖，必须使用 `/tmp` 或其他隔离目录，不要写入现有资源目录。
+开发环境真实官方资源下载默认写入 `./bat-resources`；汉化产物默认写入独立的 `./bat-localized`。如果要覆盖，官方原版资源使用 `--output` / `BAT_OUTPUT`，汉化产物使用 `--localized-output` / `BAT_LOCALIZED_OUTPUT`。两者都必须使用 `/tmp` 或其他隔离目录，不要写入现有资源目录，也不要把汉化输出覆盖到官方原版资源目录。
 
 生产或 CI 环境不得依赖安装官方启动器。需要启动器信息时，只能分析启动器资源、官方 manifest 或公开更新数据，并将解析结果固化为可验证流程。
 

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

@@ -45,7 +45,7 @@ target/release/bat \
   --watch
 ```
 
-默认资源输出目录是 `./bat-resources`，默认后台状态目录是 `/tmp/bat-pid`。资源输出目录是发布根目录：非 dry-run 同步先写 `<output>/.staging/<id>`，校验完成后移动到 `<output>/versions/<id>`，再原子切换 `<output>/current` symlink；生产读取方应读取 `current`。后台状态目录会保存 `bat.sock`、`bat.pid`、`bat-status.json`、`bat-daemon.log`、`bat-events.jsonl` 和短生命周期的 `bat-control.lock`；其中 `bat.sock` 是 live daemon 的 Unix socket JSON-RPC 控制通道，`bat-events.jsonl` 是带轮转的结构化 JSONL 事件日志，`bat-status.json` 保存最后成功时间、下次检查时间、最后错误摘要和当前下载进度，`bat-control.lock` 串行化 `status/stop/restart/reload/logs/refresh/repair` 等控制命令。生产资源输出目录必须是独立目录；需要覆盖时用 `--output <资源目录>`，不要使用已有游戏客户端目录、官方启动器安装目录、人工维护资源目录，或开发机上的 `/home/wanye/D/BlueArchive`。
+默认官方原版资源输出目录是 `./bat-resources`，默认汉化产物目录是 `./bat-localized`，默认后台状态目录是 `/tmp/bat-pid`。官方资源输出目录是发布根目录：非 dry-run 同步先写 `<output>/.staging/<id>`，校验完成后移动到 `<output>/versions/<id>`，再原子切换 `<output>/current` symlink；生产读取方应读取 `current`。后台状态目录会保存 `bat.sock`、`bat.pid`、`bat-status.json`、`bat-daemon.log`、`bat-events.jsonl` 和短生命周期的 `bat-control.lock`；其中 `bat.sock` 是 live daemon 的 Unix socket JSON-RPC 控制通道，`bat-events.jsonl` 是带轮转的结构化 JSONL 事件日志，`bat-status.json` 保存最后成功时间、下次检查时间、最后错误摘要和当前下载进度，`bat-control.lock` 串行化 `status/stop/restart/reload/logs/refresh/repair` 等控制命令。生产官方资源目录和汉化产物目录都必须是独立目录；需要覆盖官方目录时用 `--output <资源目录>`，需要覆盖汉化目录时用 `--localized-output <目录>` 或 `BAT_LOCALIZED_OUTPUT`，不要使用已有游戏客户端目录、官方启动器安装目录、人工维护资源目录，或开发机上的 `/home/wanye/D/BlueArchive`。
 
 同步流程会拒绝危险输出目录、路径逃逸和现有 symlink 路径组件；下载目标、`.part`、manifest、snapshot、PID、status、log 和控制锁文件不会跟随 symlink，daemon 状态类文件默认以 `0600` 权限创建。
 
@@ -210,6 +210,8 @@ cargo run -p bat-infrastructure --example official_pull_plan -- \
 - 真实更新会输出 `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`。
 - 下载阶段复用同一套本地清单、ZIP 结构校验和 `.part` 续传逻辑；没有清单或校验不匹配的文件会重新下载。
+- 校验和发布完成后会刷新 `<output>/current/official-parse-cache.json`。解析缓存从 `official-download-manifest.json` 的全部条目出发，处理直接 UnityFS bundle 和 zip 内 UnityFS 条目；catalog、hash、媒体等非 UnityFS 文件记录为不支持，不视为同步失败。本地 URL、相对路径、size 和 BLAKE3 未变化时复用缓存并跳过重复解析。
+- 官方同步报告中的 `localized_release_status=not_localized` 表示原版资源已发布、汉化资源未发布，这是当前官方同步阶段的正常完成状态；后续 Patch 发布完成后才应切换为 `localized`，表示原版和汉化两套资源都已发布。
 
 资源同步状态文件默认分布如下：
 
@@ -217,6 +219,7 @@ cargo run -p bat-infrastructure --example official_pull_plan -- \
 - `<output>/official-bootstrap-cache.json`：`--auto-discover` 的 `GameMainConfig` 解析缓存。launcher metadata 未变时复用缓存；metadata 变化时才通过官方 HTTP 按 manifest 下载必要 `resources.assets` 或旧版 game zip 到临时目录解析。
 - `<output>/official-version-state.json`：资源发布根目录的持久版本状态，包含当前已完成版本、正在拉取版本、上一个可用版本和失败版本。
 - `<output>/current/official-download-manifest.json`：本地下载强校验清单，记录 URL、相对路径、size 和 BLAKE3。
+- `<output>/current/official-parse-cache.json`：官方资源发布后的派生解析缓存，记录 bundle/zip 条目解析摘要和缓存复用情况；它不是汉化产物。
 - `<output>/current/official-download-quarantine.json` 或当前 staging 下同名文件：下载最终失败的 URL 诊断记录，包含失败类型、HTTP 状态、是否可重试、尝试次数和最后错误。
 
 先 dry-run：
@@ -251,7 +254,7 @@ cargo run -p bat-infrastructure --bin bat -- \
   --watch
 ```
 
-后台自动运行使用 `--daemon`。它会启动一个脱离终端的 watch 子进程，资源默认写入 `./bat-resources`，后台控制和状态默认写入 `/tmp/bat-pid`：
+后台自动运行使用 `--daemon`。它会启动一个脱离终端的 watch 子进程，官方原版资源默认写入 `./bat-resources`，汉化产物默认写入 `./bat-localized`，后台控制和状态默认写入 `/tmp/bat-pid`：
 
 ```bash
 cargo run -p bat-infrastructure --bin bat -- \
@@ -310,7 +313,7 @@ cargo run -p bat-infrastructure --bin bat -- \
 
 默认平台是 `Windows,Android`，无需显式传 `--platforms`；只有要覆盖默认平台时才传。`--interval` 是正常检查周期，默认 `1h`；watch/daemon 模式还会在每天北京时间（UTC+8）`03:00`、`16:00`、`18:00` 强制执行一次自动刷新，该轮会注入 `force=true`，并且会中断普通 interval 的 sleep。`--error-retry` 是下载、发现或校验失败后的重试周期，默认 `60s`，也可以用 `--error-retry-seconds 60`。CLI 默认启动时向 stderr 打印 `BlueArchiveToolkit` ASCII banner，并把阶段进度日志写到 stderr，包括自动发现、proxy、server-info、marker、catalog、audit、download、snapshot 和 publish 阶段；download 阶段会输出已完成计数和单文件开始/完成状态，下载执行保持顺序处理，已完成计数保持单调不倒退，audit 阶段会输出官方 `.hash`、本地 BLAKE3、需修复项和 ZIP 结构校验结果摘要。daemon 还会写 `bat-events.jsonl` 结构化日志并按大小轮转。命令结果默认以人类可读摘要写到 stdout。需要纯机器输出时加 `--json --no-progress`，需要显式开启进度日志则用 `--progress`；只想关闭横幅但保留日志时可加 `--no-banner`。错误时 stderr 输出 JSON error，watch 模式下错误 JSON 的 `next_retry_seconds` 使用失败重试周期；如果未关闭 progress，错误 JSON 前可能已有 banner 和进度日志。普通错误 exit `1`，资源目录锁冲突 exit `75`，`verify` 或 `doctor` 发现问题也返回非 0。
 
-生产可以直接运行 `--watch`，也可以用 `--daemon` 后台运行，或者用 systemd service、容器或 Go 进程守护它。cron/systemd timer 仍可调用单次模式，但不再是 Rust 自动更新的唯一方式。项目是否热更新、热重载或重启进程，由上层业务集成决定。生产资源目录应使用独立输出目录，不要指向现有客户端或人工维护的资源目录；上层读取资源时应读取 `--output/current`，不要读取 `.staging` 或 `versions` 中未切换的目录。非 dry-run 每轮会创建 `--output/.official-sync.lock`，防止并发写同一资源目录；live daemon 还会阻止前台写命令直接修改它正在管理的同一目录。
+生产可以直接运行 `--watch`，也可以用 `--daemon` 后台运行，或者用 systemd service、容器或 Go 进程守护它。cron/systemd timer 仍可调用单次模式，但不再是 Rust 自动更新的唯一方式。项目是否热更新、热重载或重启进程，由上层业务集成决定。生产官方资源目录应使用独立输出目录，不要指向现有客户端或人工维护的资源目录；上层读取原版资源时应读取 `--output/current`，不要读取 `.staging` 或 `versions` 中未切换的目录。汉化 Patch/导出应写入 `--localized-output`，并保留官方相对目录结构，不能写回 `--output/current`。发布状态分两档：`not_localized` 只发布原版资源、不发布汉化资源；`localized` 发布原版和汉化两套资源。非 dry-run 每轮会创建 `--output/.official-sync.lock`，防止并发写同一官方资源目录；live daemon 还会阻止前台写命令直接修改它正在管理的同一目录。
 
 需要只做探测时可以加 `--dry-run`。需要关闭本地 audit 或 repair 时可以显式使用 `--no-audit-local` 或 `--no-repair`，但生产同步默认应保持开启。