feat(resource): 增加历史 release 与 CAS 复用

Closes #47

docs/architecture/official-resource-backend.md

@@ -234,12 +234,12 @@ release 根目录写入 `translation-tasks.sqlite`，由版本化 `schema_migrat
 7. 如果远端 snapshot 未变化但输出目录没有任何当前 plan 的本地资源，仍按首次运行处理并执行全量拉取。
 8. 远端无变化且本地已有资源时执行 download manifest audit，检查路径、size、BLAKE3 和 ZIP 结构。
 9. 远端变化、本地 audit 发现 repair_needed，首次空目录运行，或缺少 `current` 原子发布指针时，进入下载/发布流程。
-10. 下载先写入 `<output>/.staging/<id>`；若已有 active release，会先 seed staging 以复用已验证文件；若 version-state 中存在同一版本的失败 staging，则优先复用该 staging 并跳过 active seed，避免旧 active 覆盖已下载的新文件。
+10. 下载先写入 `<output>/.staging/<id>`；若已有 active release，会先 seed staging 以复用已验证文件；若 version-state 中存在同一版本的失败 staging，则优先复用该 staging 并跳过 active seed，避免旧 active 覆盖已下载的新文件。新 staging 还会扫描已发布 release 的下载 manifest，按规范化 destination 查找候选并重新验证 size、BLAKE3 和 ZIP 结构；硬链接失败时回退到临时文件复制和原子 rename，历史 release 保持不可变。
 11. 下载、manifest、本地 BLAKE3、ZIP 和官方 `.hash` 校验完成后写入新的 snapshot，并在 staging 中写入 `official-launcher-bootstrap.json`（若本轮启用 `--auto-discover`）。
 12. 将 staging rename 为 `<output>/versions/<id>`，再原子替换 `<output>/current` symlink 指向该 versioned 目录。
 13. 发布完成后先对比上一完整 release 和当前 release 的 `official-download-manifest.json`，写出 `official-resource-changes.json` 和 `crowdin-translation-handoff.json`。同一 destination 只有 size 或 BLAKE3 变化才算 modified；新增+变更资源进入解析/翻译 handoff，删除资源只进入差异记录。当前只预留 Crowdin 本地 handoff，不发外部 API 请求。
 14. 随后刷新 active release 下的 `official-parse-cache.json` 和 `official-textunit-index.json`，并从 Added/Modified 资源、parse cache 与 TextUnit 明细索引派生 `official-textunit-tasks.json`、`crowdin-textunit-queue.json` 和版本化的 `translation-tasks.sqlite`；up-to-date 轮询在已有有效解析缓存、TextUnit 明细索引和 TextUnit 队列时只读取摘要，不重复解析，重新同步队列时保留已有 worker 状态。
-15. 若启用 `--import-repository`，已校验 release 会被导入 CAS + `ResourceRepository`，并可经 `resource.index` 查询。
+15. 若启用 `--import-repository`，已校验 release 会被导入 CAS + `ResourceRepository`，并可经 `resource.index` 查询。历史 release 候选失效时，已有 CAS 对象会先经过完整性和元数据校验，再增加 release 引用并原子物化；当前 release 在 `official-cas-reuse-references.json` 中记录引用，staging/release 清理时递减，失败则回退网络并保留诊断。
 16. 官方同步报告默认给出 `localized_release_status=not_localized`，表示原版资源已发布、汉化资源未发布；UnityFS TextAsset patch 发布成功并通过 `localized-patch-manifest.json`、current symlink 和 release ID 校验后，`localized.status` 才返回 `localized`，表示原版和汉化两套资源都已发布。`translation.proofread` 只会把 workflow 标记成 `manual_proofreading` / `translation.manual_proofreading`，不会回退已发布汉化 release 的发布状态。
 
 维护期特殊分支：如果官方 launcher/server-info 已经指向新资源根，但 client-patch seed marker 或必需 seed catalog 仍返回 403/404 等未开放状态，`bat` 返回 `waiting_for_official_resources`，保留现有 `current`，不创建失败 staging；若本轮启用 `--auto-discover`，会在 `<output>/official-launcher-bootstrap.pending.json` 写入待处理 launcher bootstrap 证据，供后续排障和自研客户端开发使用。

docs/architecture/resource-release-layout.md

@@ -37,6 +37,7 @@
     crowdin-textunit-queue.json     # Crowdin worker 离线输入队列
     official-sync-snapshot.json     # 常在 active root / current 下
     official-launcher-bootstrap.json # 官方 launcher 引导链版本化产物
+    official-cas-reuse-references.json # 当前 release 获取的 CAS 引用
     prod-clientpatch.bluearchiveyostar.com/
       <root_token>/
         TableBundles/
@@ -90,6 +91,17 @@
 | 发布完成 | rename 到 `versions/<id>`，再切换 `current` |
 | 生产读取 / bat-api | RPC 给出的 `version.resource_root`；通常等价于 `current` 解析后的 versioned 目录 |
 
+每个 release 的 `official-download-manifest.json` 是历史复用的索引。新 staging
+按规范化 destination 查找候选，并重新验证 manifest 中的 size、BLAKE3 和 ZIP
+结构；URL、CDN 根或 release ID 变化本身不构成失效条件。复用文件先尝试硬链接，
+跨文件系统时复制到 staging 内的临时文件并原子 rename，旧 `versions/<id>` 目录
+保持不可变。
+
+从 CAS 物化资源时，`official-cas-reuse-references.json` 记录每个获取的对象引用，
+文件带版本字段且允许重复 object ID。孤儿 staging 或显式 release 清理必须先按
+清单减少 CAS 引用，再删除目录；CAS 对象损坏、缺失或元数据不一致时只产生诊断，
+回退网络下载，不发布未经校验的文件。
+
 ---
 
 ## 3. URL → 磁盘映射（核心不变量）

docs/guides/development.md

@@ -238,6 +238,15 @@ Crowdin 队列当前只落本地文件，不发网络请求。
 `--download-concurrency 1`。本文档中的真实资源命令仅是隔离 runbook；本地轻量
 验证应使用 fake-curl/fixture，不要在开发机执行真实下载或 smoke run。
 
+新 release 会在网络下载前扫描已发布 release 的下载 manifest，按规范化
+destination 查找候选，并重新验证 size、BLAKE3 和 ZIP 结构。命中后优先硬链接，
+跨文件系统时回退为 staging 内临时文件复制和原子 rename；历史 release 保持不可变。
+历史候选不满足校验时才尝试既有 CAS 对象。CAS 复用会记录
+`official-cas-reuse-references.json`，清理 staging/release 时递减引用；损坏、缺失
+或元数据不一致会记录诊断并回退网络。报告和进度分别暴露
+`release_reused_count`、`cas_reused_count`、`reused_bytes`、
+`transferred_bytes` 以及 `release_reused` / `cas_reused` / `downloaded` 状态。
+
 需要把已校验官方 release 导入 CAS + `ResourceRepository` 时，显式启用：
 
 ```bash
@@ -264,6 +273,14 @@ cargo run -p bat-infrastructure --bin bat -- resource-index --limit 50
 cargo run -p bat-infrastructure --bin bat -- resource-index --release-id <ID> --platform windows --archive-entry <PATH> --format json --limit 50
 ```
 
+issue 47 的隔离回归测试：
+
+```bash
+cargo test -p bat-infrastructure official_download::tests::reuses_verified_historical_release_when_cdn_root_changes -- --nocapture
+cargo test -p bat-infrastructure official_download::tests::falls_back_to_cas_after_corrupt_historical_release -- --nocapture
+cargo test -p bat-infrastructure official_download::tests::corrupted_cas_falls_back_to_network_with_diagnostic -- --nocapture
+```
+
 `parse-status` 会额外显示 TextUnit 明细索引和队列摘要；`parse-text-units` /
 `parse-errors` 可按 destination、archive entry、path id、class id、field path
 和 format 分页查询当前官方 release 的 TextUnit 明细与解析错误；

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

@@ -184,6 +184,8 @@ cargo run -p bat-infrastructure --example official_pull_plan -- \
 - 存在 `.part` 临时文件时会尝试断点续传
 - 新下载先写 `.part`，成功并通过必要校验后再替换为最终文件；如果断点续传后的 `.zip` 结构校验失败，会删除 `.part` 并重新全量下载
 - 如果上一轮非 dry-run 已进入 staging 但未发布成功，下一轮会优先查找 `<output>/official-version-state.json` 中同一 app version、bundle version 和 Addressables root 的失败版本；只有对应 `<output>/.staging/<id>` 仍存在、路径安全且 `versions/<id>` 尚未发布时，才复用该 staging，并继续按 manifest 校验复用或重下单个 URL
+- 新 release 的 staging 在访问网络前会扫描已发布 release 的 `official-download-manifest.json`。候选必须同时满足 manifest 记录的 destination、size、BLAKE3 和适用的 ZIP 结构校验；URL、CDN 根和 release ID 的变化本身不会阻止复用。命中后优先用硬链接，跨文件系统时回退为临时文件复制并原子 rename，旧 release 不会被修改
+- 历史 release 候选失效时，如果配置的 CAS 根已有对应 BLAKE3 对象，会先通过 CAS 读取完整性和元数据，再增加当前 release 的引用并原子物化；当前 release 会写 `official-cas-reuse-references.json`，清理孤儿 staging 或显式清理 release 时递减这些引用。CAS 损坏、缺对象或元数据不一致会写入复用诊断并继续走网络下载，不会静默使用缓存
 - 把结果发布到 `--output/current`
 
 ## 5. 自动更新检查
@@ -210,6 +212,7 @@ cargo run -p bat-infrastructure --example official_pull_plan -- \
 - `--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`。
+- 复用统计还包括 `release_reused_count`、`cas_reused_count`、`reused_bytes` 和 `reuse_warnings`；单文件 progress 状态区分 `release_reused`、`cas_reused`、`downloaded`，`transferred_bytes` 不包含复用文件。
 - 校验报告分层输出 `official_seed_hash_verified_count`、`local_manifest_verified_count`、`addressables_marker_checked_count`、`unverified_marker_count`。
 - 下载阶段复用同一套本地清单、ZIP 结构校验和 `.part` 续传逻辑；没有清单或校验不匹配的文件会重新下载。
 - 非 dry-run 且启用 `--auto-discover` 时，成功发布的 release 会包含 `official-launcher-bootstrap.json`；up-to-date 轮询发现当前 release 缺少该文件时会补写。官方 launcher/server-info 已更新但 client-patch 资源尚未开放时，不切换 `current`，只在输出根写入 `official-launcher-bootstrap.pending.json` 作为维护期证据。
@@ -226,6 +229,7 @@ cargo run -p bat-infrastructure --example official_pull_plan -- \
 - `<output>/official-bootstrap-cache.json`：`--auto-discover` 的 `GameMainConfig` 解析缓存。launcher metadata 与 remote manifest 文件列表 digest 都未变时复用缓存；任一变化时才通过官方 HTTP 按 manifest 下载必要 `resources.assets` 或旧版 game zip 到临时目录解析。
 - `<output>/official-version-state.json`：资源发布根目录的持久版本状态，包含当前已完成版本、正在拉取版本、上一个可用版本和失败版本。
 - `<output>/current/official-download-manifest.json`：本地下载强校验清单，记录 URL、相对路径、size 和 BLAKE3。
+- `<output>/current/official-cas-reuse-references.json`：当前 release 获取的 CAS 引用清单；每个复用项占一条记录，release 清理或孤儿 staging GC 时据此递减引用。
 - `<output>/current/official-resource-changes.json`：当前 release 相对上一完整 release 的资源差异，记录新增、变更、删除以及解析/翻译候选计数。
 - `<output>/current/crowdin-translation-handoff.json`：为后续 Crowdin worker 预留的本地队列，只包含新增+变更资源；它不是 Crowdin API 调用结果。
 - `<output>/current/official-parse-cache.json`：官方资源发布后的派生解析缓存，记录 bundle/zip 条目解析摘要和缓存复用情况；它不是汉化产物。
@@ -320,7 +324,7 @@ cargo run -p bat-infrastructure --bin bat -- \
   --error-retry 60s
 ```
 
-默认平台是 `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。
+默认平台是 `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 阶段会输出已完成计数和单文件开始/完成状态，worker 从共享队列独立领取任务并在完成后立即领取下一项，完成计数保持单调不倒退，最终 report 的 `items` 仍按 pull plan 顺序排列，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 自动更新的唯一方式。下载默认并发 8，可用 `--download-concurrency` / `BAT_DOWNLOAD_CONCURRENCY` 配置为 `1..=256`；worker 动态领取共享 plan，finished 进度即时按完成数统计，发布 report 仍按 plan 顺序。项目是否热更新、热重载或重启进程，由上层业务集成决定。生产官方资源目录应使用独立输出目录，不要指向现有客户端或人工维护的资源目录；上层读取原版资源时应读取 `--output/current`，不要读取 `.staging` 或 `versions` 中未切换的目录。汉化 Patch/导出应写入 `--localized-output`，并保留官方相对目录结构，不能写回 `--output/current`。发布状态分两档：`not_localized` 只发布原版资源、不发布汉化资源；`localized` 发布原版和汉化两套资源。非 dry-run 每轮会创建 `--output/.official-sync.lock`，防止并发写同一官方资源目录；live daemon 还会阻止前台写命令直接修改它正在管理的同一目录。
 

docs/reports/CURRENT_GAPS.md

@@ -301,6 +301,7 @@ issue 43 例外说明：新增的 `parse repack` 只编排已有 TextAsset、Typ
 - `translation-tasks.sqlite` 由 `schema_migrations` 管理 durable task state、attempt count、provider run ID 和 failure reason；重复同步会保留已有 worker 状态。
 - `translation.tasks` RPC/CLI 优先查询 `translation-tasks.sqlite`，旧 release 没有状态库时回退到 `official-textunit-tasks.json`；返回队列 `status`、worker `task_status`、failure reason 和时间/尝试次数。
 - `translation.tasks` / `translation.handoff` 已提供 Go typed helper 和 bat-api 鉴权查询端点；`translation.task.update` 已提供 queued/running/failed/completed/skipped 状态回写契约，并已通过 `bat i18n task update`、Go typed helper 和 bat-api 鉴权控制面暴露；`translation.worker.run` 已提供 Rust provider worker，支持 mock/Crowdin、独立 claim、lease、失败分类、重试和 TextUnit 级译文结果落库；`translation.proofread` 已提供人工校对状态标记契约。
+- issue #47 已补齐官方资源同步的历史 release 与 CAS 前置复用：按计划顺序生成结果、按共享队列动态领取任务、对复用源执行 size/BLAKE3/ZIP 校验，失败时保留诊断并回退网络；CAS release 引用写入版本化清单，staging GC 会先释放引用再删除目录。更丰富的 Resource 查询、翻译记忆和通用 Patch 发布仍属于后续缺口。
 - `i18n get/set/unset` 可查看、修改或清空单条工作台译文，`i18n validate` 可在发布前校验工作台 release、source text、重复 patch 目标，并区分可直接发布的 TextAsset 与必须进入 `parse repack` 的条目；`i18n proofread` 可把当前汉化 workflow 标记为人工校对中，且不会遮蔽已发布汉化 release；`parse clear-cache` 只删除可再生解析/队列 JSON，保留 `translation-tasks.sqlite` 的 worker 状态。
 - 翻译记忆和完整 localized repack 仍属于后续翻译系统工作，不在当前 provider worker 状态闭环范围内。
 
@@ -572,12 +573,13 @@ issue 43 例外说明：新增的 `parse repack` 只编排已有 TextAsset、Typ
 3. issue #17 的历史顺序/重试契约仍保留；当前 issue #33/#35 已补有界 downloader
    scheduler 和默认并发 8，范围 `1..=256`，worker 完成后立即领取下一个任务，
    进度即时按完成数上报，最终 report 保持 plan 顺序。
-4. **G-008：已决策关闭**（同步 CLI = Rust `bat`；见 `GO_STATUS.md`）。
-5. **G-009 / issue #19**：资源 bootstrap/分发和同机 live 联调已完成；非「从零实现」。后续真实官方网络长期运行、持久化和完整 launcher/业务链不属于本 issue 关闭条件。
-6. issue #2 / G-007（P1）：Addressables 可校验字段。
-7. issue #3 / G-005（P1）：UnityFS 容器基础解析已落地；对象级引擎解析继续跟踪 G-005。
-8. G-011：更丰富的 TextUnit 查询、翻译记忆查询和通用 Patch 发布所需资源视图。
-9. G-012 / G-006：Crowdin/翻译系统、复杂 AssetBundle 重打包和 Patch 发布流程统一。
-10. G-011D：原版/汉化双发布后的查询、分发和清理策略。
+4. **issue #47：官方资源历史 release/CAS 复用已完成**；后续只跟踪真实官方长期运行和更丰富的版本清理策略。
+5. **G-008：已决策关闭**（同步 CLI = Rust `bat`；见 `GO_STATUS.md`）。
+6. **G-009 / issue #19**：资源 bootstrap/分发和同机 live 联调已完成；非「从零实现」。后续真实官方网络长期运行、持久化和完整 launcher/业务链不属于本 issue 关闭条件。
+7. issue #2 / G-007（P1）：Addressables 可校验字段。
+8. issue #3 / G-005（P1）：UnityFS 容器基础解析已落地；对象级引擎解析继续跟踪 G-005。
+9. G-011：更丰富的 TextUnit 查询、翻译记忆查询和通用 Patch 发布所需资源视图。
+10. G-012 / G-006：Crowdin/翻译系统、复杂 AssetBundle 重打包和 Patch 发布流程统一。
+11. G-011D：原版/汉化双发布后的查询、分发和清理策略。
 
 Go 进度以 `docs/reports/GO_STATUS.md` 为准。G-018 / G-017 已关闭。