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

docs/reports/CURRENT_GAPS.md

@@ -1,6 +1,8 @@
 # 当前实现缺口清单
 
-- **更新时间**：2026-07-20
+- **更新时间**：2026-07-24
+- **Go 进度权威**：`GO_STATUS.md`
+- **资源布局 / 逆向契约**：`../architecture/resource-release-layout.md`
 - **用途**：集中跟踪当前代码中的占位实现、设计缺口和下一步验收项。
 - **权威计划**：`../../PROJECT_PLAN.md`
 
@@ -109,24 +111,40 @@
 
 ### G-005：AssetBundle 引擎解析器仍未完成
 
+状态：**部分完成**
+
 现象：
 
-- `crates/bat-assetbundle/src/parser.rs` 只有 `Parser::name`。
-- `types.rs` 只有 `AssetType::TextAsset`。
-- `adapters/src/unity/unity_2021_3.rs` 已能解析 UnityFS header、block info、directory，并校验 directory `offset+size` 不越界；这属于 adapter 层基础摘要能力，不等于 `bat-assetbundle` 引擎已完成。
-- 仍没有对象表、TypeTree、TextAsset、MonoBehaviour、ScriptableObject 或可扩展提取入口。
+- `crates/bat-assetbundle` 已接管 UnityFS 解析，提供 `UnityFsParser`、`UnityFsBundle`、header、block info、directory、压缩模式、block info at end、LZ4/LZMA block info 解压、数据 block 解压、directory 文件提取和边界诊断。
+- `crates/bat-assetbundle::serialized` 已提供 Unity serialized file header、type table、TypeTree node 元数据、object table 和 `TextAsset` bytes 提取。
+- `adapters/src/unity/unity_2021_3.rs` 已降为 Unity 版本选择薄层，复用 `bat-assetbundle`，不再维护第二套 UnityFS parser。
+- `ResourceImportService` 的 UnityFS 摘要已经能暴露解包文件数、serialized file 数、TextAsset 数量和名称。
+- 仍没有 `MonoBehaviour`、`ScriptableObject` 的 TypeTree 字段级反序列化和可编辑重打包入口。
 
 影响：
 
-- 可以对部分 UnityFS 样本做基础结构校验，但无法完成真实资源对象解析和文本提取。
-- 无法提取 TextAsset 或配置文本。
+- 可以对 UnityFS 容器做结构校验、解包 directory 文件，并提取 serialized file 中的 TextAsset 原始 bytes。
+- 对日语汉化最关键的 TextAsset 索引和 bytes 提取已有基础入口，但还不能直接解析 `MonoBehaviour`/`ScriptableObject` 自定义字段或完成修改后重打包。
 
-验收：
+当前验收证据：
 
 - `crates/bat-assetbundle` 能解析结构化测试样本和隔离真实样本。
-- 支持 UnityFS header、blocks、directory、metadata、object table。
+- 支持 UnityFS header、blocks、directory、metadata 摘要、directory 文件提取。
+- 支持 Unity serialized file object table、TypeTree node 元数据和 TextAsset 提取的合成 fixture。
 - 错误包含偏移和字段上下文。
 
+关闭前仍需：
+
+- 完成 TypeTree 字段 reader：bool、integer、float、string、bytes、array、map、PPtr 和 managed reference 诊断占位。
+- 支持 MonoBehaviour、ScriptableObject 字段级遍历，形成可扩展文本提取入口。
+- 输出可追溯文本定位：bundle path、archive entry、serialized file、path id、class id、field path。
+- 用真实资源 fixture 覆盖对象级解析、TextAsset 提取和字段级文本提取。
+- 将解析结果作为 Patch 输入；真正的重打包、Patch 生成和 `localized` 发布切换归 G-006/G-011D。
+
+解析补全路线图：
+
+- 见 `docs/architecture/assetbundle.md` 的 P2/P3/P5。
+
 ### G-006：Patch 引擎仍是占位
 
 现象：
@@ -153,8 +171,9 @@
 
 - `AddressablesCatalogDriver` 已能解析当前真实形态 JSON catalog fixture/golden。
 - 已输出 path、hash、size、resource_type、address、dependencies、metadata，并已提取 `m_Crc` 到 `crc` 字段。
+- compact catalog 解析已补充 hash/size/CRC 的非 0 回归、资源计数 metadata，以及 blob 解码失败时的明确错误；不再在 compact 字段损坏时静默退回低保真 `m_InternalIds`。
 - `bat-core` 已提供 `crc32_ieee` 和 `ResourceEntry::verify_downloaded_bytes`，SQLite `ResourceRepository` 已有 `crc` 列迁移。
-- 仍需覆盖更多官方 catalog 结构变体、二进制/压缩字段组合和更明确的失败诊断。
+- 仍需覆盖更多官方 catalog 结构变体、provider/bundle name 持久化字段，以及真实 Windows/Android catalog 样本集合。
 
 影响：
 
@@ -165,54 +184,53 @@
 - 能解析项目目标版本的真实 Catalog 样本集合。
 - 解析结果包含资源 key、provider、dependency、hash、size、path、CRC。
 - 对不支持的 catalog 结构返回明确错误，而不是静默丢字段。
+- 解析结果能反查 bundle 文件、依赖链和本地下载 manifest 条目。
+- Windows/Android 样本集合需要覆盖 JSON、compact JSON 和后续二进制 catalog 入口。
+
+解析补全路线图：
+
+- 见 `docs/architecture/assetbundle.md` 的 P1。
 
 ---
 
 ## 3. 应用层缺口
 
-### G-008：Go CLI 产品入口尚未完成
+### G-008：Go 同步/运维 CLI 产品入口
 
-状态：**未完成（此前“并入 G-009”只是短期跟踪调整，不代表能力完成）**
+状态：**已决策关闭（wontfix）**
 
-现象：
+决策（2026-07-24，见 `GO_STATUS.md`）：
 
-- 当前可用的用户同步/运维入口是 Rust `bat` binary。
-- `internal/backendrpc` 已提供 Go 到 Rust daemon 的 typed JSON-RPC client；`cmd/bat` 已存在，但仅有 `doctor`、`manifest inspect`、`sync plan` 试验能力；`doctor` 只输出固定 `ok`，`manifest`/`sync` 依赖可选 CGO/FFI helper。
-- Go 侧尚未实现通过 Rust `bat --json` 或 daemon RPC 包装官方同步命令、稳定 human/json 输出、真实 doctor 检查和端到端测试。
-- 如果项目决策改为“用户 CLI 永久由 Rust `bat` 承担，Go 只做 `bat-api`/服务层”，必须同步更新 `AGENTS.md`、`PROJECT_PLAN.md` 和 issue 跟踪；在完成该决策前，不能把 Go CLI 写成已完成。
+- **正式同步/运维命令行 = Rust `bat`**（近乎全自动：auto-discover + watch/daemon，无需持久手操维护）。
+- **不另做**产品级 Go 同步 CLI，避免与 Rust `bat` 双轨。
+- Go 试验入口 `cmd/bat` 可保留为 experimental，产物必须为 `bin/bat-go`，**禁止**再构建为 `bin/bat`。
+- Go 正式产品入口集中在 **`bat-api` 资源分发服务** + `internal/backendrpc`（G-009）。
 
-验收：
+原验收（真实 doctor / Go sync 包装）**不再作为当前里程碑**。
 
-- `cmd/bat doctor` 做真实环境诊断，而不是固定字符串。
-- `cmd/bat sync` 能通过 `internal/backendrpc` daemon RPC 或 Rust `bat --json` one-shot/fallback 触发/查询官方同步，不走 FFI 控制下载器或 daemon。
-- human/json 输出、退出码和错误码与 Rust `bat` 契约一致。
-- `go test ./...`、`go vet ./...` 覆盖命令解析、错误输出和至少一个 mocked Rust 边界。
+### G-009：API Server（`bat-api`，资源分发）部分完成
 
-### G-009：API Server（`bat-api`，仿官方 API）尚未实现
+状态：**资源 CDN MVP 已落地；非完整官方游戏 API**
 
-现象：
+目标（对应 issue #19，**按资源面收窄**）：
 
-- `api/` 只有目录结构，无 handler、service、路由。
-- Go 侧尚无对接 daemon RPC / `current/` 发布布局的服务端入口。
+- `cmd/bat-api`：只读分发 Rust `bat` 已发布 release（官方 CDN host/path 形态）。
+- **拉取归属 Rust `bat`**；`bat-api` 不做下载器。
+- 发现经 `bat.sock`：先 `daemon.status`，再 `daemon.doctor`，再 `catalog.status` / `resource.manifest`。
+- `.env` 配置端口 / public base / RPC socket；预留 database/redis。
+- launcher 全链、完整业务 API **非关闭条件**；USERGUIDE bat-api 专章延后。
 
-目标（对应 issue #19）：
+已完成：
 
-- 新建 `cmd/bat-api`：**完全仿照 BlueArchive 官方 API** 的 Go HTTP 服务，把 Rust `bat` 后端发布的 `current/` release 按官方接口形态对外提供，使真实客户端/工具可将其当作官方服务端。
-- 仿真面：资源 CDN 面（TableCatalog/MediaCatalog/BundlePackingInfo、bundle、seed `.hash`）、server-info 面、launcher API 面。
-- 鉴权/签名**完全仿照**官方实现，服务端做验签（对齐 `adapters/src/official/launcher.rs` 的签名逻辑）。
-- 版本/状态经 daemon RPC（`catalog.*` / `resource.manifest`）发现，资源字节从 `current/` 读取；不读写 daemon 状态文件内部。
+- `cmd/bat-api`、`internal/api`、fixture 单测、`make build-go-api` / `test-go-api`
+- 进度权威：`docs/reports/GO_STATUS.md`
 
-影响：
+验收（剩余）：
 
-- 客户端、工具和第三方集成无服务端入口。
+- 与全量 release / 服务器 daemon 联调（SSH 实勘可后置）
+- 文档与 GO_STATUS 持续一致
 
-验收：
-
-- Go 单测覆盖路由、签名验签、错误响应形态。
-- 真机 e2e：daemon 发布 fixture release → 启动 `bat-api` → 按官方 URL 与鉴权头请求 server-info / catalog / bundle / launcher 链，断言字节与形态正确、验签生效（缺签/错签被拒）。
-- 统一错误结构与官方响应 envelope 对齐；Makefile 增加 Go 构建/测试目标。
-
-排期：P2，排在 issue #17 验收收口以及 issue #2 / #3 的解析能力继续推进之后启动；可与 G-008 的 Go 产品入口边界收敛并行。
+排期：P2 主体可联调；持久化 API 层与 launcher 另议。
 
 ### G-010：Web 管理后台尚未实现
 
@@ -248,6 +266,11 @@
 - schema 和迁移可重复执行。
 - 可按版本、类型、hash、路径查询资源。
 - 官方同步后的资源可通过 CLI 查询并能追溯到 CAS 对象。
+- `official-parse-cache.json` 的 bundle、zip entry、TextAsset 摘要能进入 ResourceRepository 查询面。
+
+解析补全路线图：
+
+- 见 `docs/architecture/assetbundle.md` 的 P4。
 
 ### G-011A：资源导入链路基础能力不足
 
@@ -294,6 +317,30 @@
 - `cargo test -p bat-infrastructure version_state`
 - `cargo test -p bat-infrastructure --test official_game_main_config_bootstrap`
 
+### G-011D：汉化发布状态与 Patch 发布流程未完成
+
+状态：**新建，未关闭**
+
+当前已完成：
+
+- 官方原版资源发布根为 `./bat-resources`，汉化产物发布根为 `./bat-localized`。
+- CLI 支持 `--localized-output` / `BAT_LOCALIZED_OUTPUT`，并拒绝官方目录和汉化目录相同或互相嵌套。
+- 官方同步报告新增 `localized_release_status=not_localized`，明确表示原版资源已发布、汉化资源未发布。
+
+仍未完成：
+
+- Patch 发布阶段尚未生成 `localized-output/versions/<id>`。
+- 尚未维护 `localized-output/current` 原子指针和汉化版本状态文件。
+- 尚未实现 `localized` 状态切换、回滚和汉化产物完整性校验。
+- 尚未实现原版资源与汉化资源双发布后的查询、分发和清理策略。
+
+验收：
+
+- 原版资源同步成功后保持 `not_localized`，不发布半成品汉化资源。
+- Patch 构建和校验成功后，汉化产物按官方相对路径写入 `localized-output/versions/<id>`。
+- 汉化发布必须原子切换 `localized-output/current`，失败时不影响已发布原版资源。
+- `localized` 状态能证明原版和汉化两套资源都可发布，并能被 CLI/RPC/API 查询。
+
 ### G-011C：真实 fixture 与回归样本不足
 
 状态：**已关闭当前阶段**
@@ -470,13 +517,15 @@
 
 ## 6. 当前关闭顺序建议
 
-1. issue #24：失败 staging 复用已补离线回归；继续核对 issue 口径、状态与后续是否仍有真实场景无法复现的残余。
-2. issue #1：Rust daemon/backend API 边界收口；`resource.repair`、`resource.list`、`daemon.doctor`、`internal/backendrpc` Go client 和稳定 RPC reference 已补齐，剩余确认 `patch.*` / `unityfs.*`（待引擎）、`task.create`（暂不开放通用入口）以及 `daemon.restart` / `daemon.clean-stable`（CLI 生命周期入口）的 issue 验收口径。
-3. issue #17/#20/#21/#22：多线程下载入口已按最新决定移除，下载回归顺序执行并保留指数退避与单调进度上报；daemon 子进程不再透传并发参数，但 GitHub issue 仍 open。
-4. issue #2 / G-007：继续扩大 Addressables 可校验字段和结构变体覆盖。
-5. issue #3 / G-005：把 UnityFS 基础摘要推进到 `bat-assetbundle` 引擎级解析。
-6. G-011：官方同步结果接入 CAS + ResourceRepository 用户级工作流。
-7. G-008 / G-009：收敛 Go 产品入口边界，并实现 `bat-api`（issue #19）。
-8. G-012 / G-006：翻译系统、Patch 引擎。
+1. issue #24：失败 staging 复用回归已补；核对残余场景。
+2. issue #1：RPC 主体已落地；剩余 `patch.*` / `unityfs.*`、设计边界确认。
+3. issue #17 及子 issue：已按 wontfix 关闭多线程下载（顺序下载 + 指数退避）。
+4. **G-008：已决策关闭**（同步 CLI = Rust `bat`；见 `GO_STATUS.md`）。
+5. **G-009 / issue #19**：资源分发 MVP 已编码；优先服务器联调与索引实勘，非「从零实现」。
+6. issue #2 / G-007（P1）：Addressables 可校验字段。
+7. issue #3 / G-005（P1）：UnityFS 容器基础解析已落地；对象级引擎解析继续跟踪 G-005。
+8. G-011：官方同步结果接入 CAS + ResourceRepository 用户级工作流。
+9. G-011D / G-006：汉化发布状态持久化、Patch 发布和回滚。
+10. G-012 / G-006：翻译系统、Patch 引擎。
 
-这个顺序优先把 Rust `bat` 后端做扎实（解析能力 + 下载性能），再把官方同步结果进入可查询资源库，之后收敛 Go 入口和仿官方 API 服务端，最后推进翻译和补丁。G-018 已固化为可重复 smoke 命令并关闭；G-017 已按“不引入托管 CI”决策关闭。
+Go 进度以 `docs/reports/GO_STATUS.md` 为准。G-018 / G-017 已关闭。