BlueArchiveToolkit/docs/reports/CURRENT_GAPS.md

当前实现缺口清单

• 更新时间：2026-09-12
• 文档角色：只记录尚未完成、仍需验证或仍需设计的工作，不重复维护完整实现状态。
• 当前事实：以源码、测试、稳定契约和 CURRENT_STATUS.md 为准。
• Go 进度：GO_STATUS.md
• 资源布局契约：../architecture/resource-release-layout.md
• 权威计划：../../PROJECT_PLAN.md
• 历史资料：docs/archive/ 和 docs/reports/historical/ 只用于追溯。

1. 当前工程缺口

G-005：AssetBundle V1 已完成，完整兼容仍未完成

状态：V1 已完成（仅限已验证结构），继续推进真实版本和复杂结构

当前已具备 UnityFS 容器校验、directory 文件提取、serialized file object/type table/TypeTree 元数据、TextAsset、基础 MonoBehaviour 和 ScriptableObject 字段读取、TextUnit 提取，以及受支持字段的文件级 parse→modify→rebuild→reparse。重建会保留已识别的 block 压缩、alignment、 directory 形态和未修改对象/字段，并明确拒绝未知压缩或无法证明保真的输入。

仍需完成：

• 用真实资源 fixture 覆盖更多 MonoBehaviour、ScriptableObject、Unity 版本差异、 复杂容器和 managed reference registry/map entry 变体。
• 为未知字段补充结构语义；不能把低保真猜测当作已支持格式。
• 扩大真实 Unity 版本、复杂容器、未知字段和 managed-reference/map 变体覆盖； 当前 V1 不等价于任意 AssetBundle 结构的通用重打包。

现有证据：crates/bat-assetbundle 的单元/压缩/对齐/变长重建测试、隔离真实 UnityFS 回归和 bat-infrastructure 的解析缓存、ZIP 内 bundle 发布测试。新增格式覆盖必须 同时补真实 fixture、回归测试和文档。

G-006：通用 Patch 的复杂格式和运维扩展仍未完成

状态：V1 已完成（当前支持类型），复杂格式和运维扩展继续推进

bat-patch 已提供 Binary/JSON/Text Patch、manifest builder、BLAKE3/size 校验和 rollback 元数据；LocalizedPatchService 已使用同一有序 generic manifest 驱动 Binary/JSON/Text 与当前支持的 UnityFS TextAsset、TypeTree string/semantic field 写入及 localized publish/rollback。发布会在独立 staging 中校验 source/target identity、 逐操作 precondition、ZIP 内层重解析和实际字段替换，并保留 TextUnit/TM/Glossary/review provenance；UnityFS 目标身份至少包含 archive entry、serialized file、path ID 和实际 field path，同对象 sibling field 可并存，重复、父子、whole-object/field 结构重叠会拒绝； localized.publish、i18n publish 和 bat-api typed forwarding 均已接入。

仍需完成：

• 任意复杂 AssetBundle 重打包和完整翻译文件集合构建；当前 localized publish 已支持 可验证 ZIP 内 bundle 的外层 ZIP 重写，但不扩大 UnityFS 结构支持范围。
• generic manifest 已冻结为当前支持类型的 V1；复杂 AssetBundle 结构仍需真实样本驱动， 不在本项中扩展 Patch 格式。

所有发布产物必须先进入独立 staging，通过完整性校验后再原子发布；失败不得改变 已发布的 bat-resources/current 或 bat-localized/current。

G-007：Addressables 完整兼容仍未完成

状态：当前 JSON/compact 目标字段完成，独立二进制格式待后续

当前 JSON/compact catalog 已覆盖 path、hash、size、address、dependencies、 provider、bundle name、resource type 和 CRC，并有 fixture/golden 回归。

仍需完成：

• 更多 Windows/Android 真实 catalog 形态和失败诊断。
• 独立二进制 catalog 入口；在未支持前必须明确拒绝，不得静默丢字段。

G-009：bat-api 仍是资源服务，不是完整官方游戏 API

状态：资源 bootstrap/分发和管理控制面已可用，业务 API 未完成

当前 cmd/bat-api 通过 bat.sock 读取 Rust 已发布 release，提供 bootstrap、 launcher 资源引导兼容、只读 CDN path、readiness、OpenAPI、鉴权管理入口和内嵌 dashboard；翻译任务和 Rust-owned TM 的 summary/query/confirm 也通过 typed RPC 转发。Rust bat 继续拥有资源发现、下载、校验、staging、发布、任务和长期状态。

仍需完成：

• 完整游戏业务 API、账号/登录/网关链和完整 launcher 安装包更新链。
• 更丰富的 Resource/TextUnit/翻译记忆查询面。
• 真实官方网络长期运行报告；运行使用 make official-smoke，产物留在隔离目录。

bat-api 不得复制 Rust 下载器、CAS、AssetBundle 解析、Patch 核心算法或同步状态机。

G-010：完整 Web 协作后台仍未完成

状态：内嵌 dashboard MVP 已完成，完整后台未开始

当前页面可以调用已有资源、调度、任务、解析、翻译和 localized 控制接口。

仍需完成：

• 独立登录、角色权限和协作式翻译审核。
• Glossary/术语管理、批量审核、搜索和完整历史版本视图。
• 构建型前端工程、浏览器 E2E 和完整错误态交互门禁。

G-011：ResourceRepository 查询面仍不完整

状态：部分完成

当前已支持 CAS + SQLite 导入、资源类型/release/平台/path/parse status/TextUnit format 等资源级过滤，parse.text_units / parse.errors 和翻译任务查询也已可用。

仍需完成：

• 更丰富的 TextUnit、翻译记忆和 Patch 发布资源视图。
• 从同一 manifest fingerprint 追溯资源、解析缓存、翻译任务和发布产物。
• 更多 schema 迁移、权限、并发和损坏恢复场景验证。

G-011D：双 release 查询、分发与安全清理

状态：V1 已完成

官方原版和 localized release 已分离，受支持 patch 可独立 staging、校验、发布和 rollback。Rust release.status 提供统一 current/source/match、manifest contract、 artifact/distribution integrity、历史 release、legacy/stale/damaged 摘要； release.list 查询两个 namespace，release.distribution 只允许当前或显式历史且已 验证的 official/localized release，默认仍为 official；release.cleanup 提供 dry-run plan_id 和执行前重验证，只删除确定未被 current、rollback、staging、source、状态、 manifest、CAS 或未知归属引用的普通目录。localized.status 还区分 schema/contract 与 artifact integrity，损坏产物返回 degraded/corrupt，不自动回滚或删除。

rollback 与 cleanup 保持独立；缺少 generic manifest 的旧 localized release 仍可读， 明确标记 legacy/unknown，不会被自动重写。

本轮 P1 一致性修复已完成：CAS repository 的 store/get/reference/GC 使用跨进程操作锁， release-local CAS 引用通过持久化 ownership_id + ordinal ledger 幂等释放；没有 ownership_id 的旧清单按持久化 output-root scope、source mapping 和 generation identity 迁移，已有 basename ledger 的部分 cleanup 保持 legacy compatibility key，完成后同名新 generation 使用新的 ownership，不随机迁移已开始的 cleanup。官方历史复用只对不可变文件使用 hard link，translation-tasks.sqlite 及 WAL/SHM 始终独立复制； localized output 使用单写者锁和事务日志恢复 publish/rollback，publish 只有最终 verified phase 才能 roll-forward，并在发布时写入实际 localized bytes/BLAKE3 的 distribution manifest。official/localized distribution manifest 还持久化 deterministic source/localized mapping identity 和 destination index；release.distribution(destination=...) 是单条 lookup，返回 exactly one entry，source identity mismatch 会阻断 localized distribution，完整 identity 校验只在 publish/status/audit 路径执行；分发读取保留 path ownership、symlink 和文件完整性检查；release.cleanup execute 与 official sync 共用 .official-sync.lock。本轮已关闭两个 Release/CAS P2。其他 P2 尚未由本轮处理：ResourceRepository 更完整的查询/权限/损坏恢复、模糊 TM、bat.sock peer credential/perms、FFI 生命周期、 资源大小/限额与更强的持久化 fsync 语义仍按后续专项推进。

G-012：Translation Memory V1 已实现，扩展能力仍缺失

Rust bat 已提供独立项目级 SQLite TM，记录 raw source/hash、完整 context、release/TextUnit/provider/run provenance，区分 candidate/trusted，只有显式 confirm 才能建立 trusted 记录；worker 只自动复用 trusted 的 raw source + 完整 context exact match，并在复用前执行已批准 Glossary 的确定性 QA。Go bat-api 已提供鉴权的 summary/query 只读接口和 confirm 转发，但 Go 不持有 TM 状态。仍缺少模糊匹配和更丰富的导入导出历史能力。

G-013：Glossary V1 已实现，协作视图仍缺失

Rust bat 已提供独立项目级 glossary.sqlite：term/alias/recommended/allowed/category/priority、全局与 TextUnit scope、source history、approved review、冲突诊断、provider-neutral constraints 和确定性 QA 均由 Rust 持有。trusted TM 复用会先经过 Glossary QA；provider、TM、人工 task/workbench 结果都记录 QA，blocking deviation 必须显式提交与当前 QA 精确绑定的 qa_identity 及 reviewer/reason/provenance。localized publish 会把发布时重算的 QA 写入 manifest。translation.glossary.* 已通过 bat.sock 暴露，Go 仅提供鉴权后的 typed forwarding。剩余缺口是完整 Web 术语协作视图和更丰富的导入/搜索能力。

G-014：完整 Provider 扩展体系未实现

当前已有 mock/Crowdin provider worker、lease、重试和 TextUnit 结果落库；仍需建立 可替换的 Provider 扩展体系，以及批处理、限流、成本统计和质量检查。

2. 已确定的架构边界

以下内容不是待实现的重复任务：

1. 正式资源同步和运维命令行是 Rust bat；不另做产品级 Go 同步 CLI。
2. Rust bat / daemon 是资源生产者和状态拥有者；Go bat-api 只读取已发布资源， 通过 bat.sock 提供 bootstrap、分发和受限管理入口。
3. bat-api 是资源 bootstrap/分发服务，不是完整官方游戏 API。
4. bat-ffi 只保留无状态兼容 helper，不承载 daemon、下载器、CAS handle 或主控制面。
5. 官方原版 release 和 localized release 使用独立目录、staging、manifest、current 和 rollback 生命周期。
6. daemon.clean-stable 是 CLI 生命周期清理入口，不在 live RPC 内执行在线清理； task.create 也不作为通用 RPC 入口开放。
7. status / status_code 描述生命周期，BAT-ERR-* 描述错误；两者不混用。

详细阶段报告仍保留在 docs/reports/historical/，不作为当前实现依据。

3. 后续推进顺序

1. 继续 G-005：更多真实 AssetBundle 样本、复杂字段解析、版本差异和任意结构重打包。
2. 继续 G-006：复杂 AssetBundle 兼容和真实样本覆盖；G-011D 的双 release 运维 V1 已完成，后续 retention scheduler 不属于本次闭环。
3. 继续 G-011/G-012/G-013/G-014：资源查询、TM/Glossary 扩展和 Provider 扩展体系。
4. 在隔离环境执行 make official-smoke，补充真实网络长期运行报告。
5. 最后推进完整 Web 协作后台和完整游戏业务 API。