BlueArchiveToolkit/docs/reports/CURRENT_GAPS.md

# 当前实现缺口清单

- **更新时间**：2026-09-13
- **文档角色**：只记录尚未完成、仍需验证或仍需设计的工作，不重复维护完整实现状态。
- **当前事实**：以源码、测试、稳定契约和 `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`。新 official release 还持久化独立的
`official-distribution-publication.json`，把 release ID、完整 mapping identity、manifest
content identity 和 entry count 绑定到发布事实；publication 缺失或 manifest 变化时
official/localized distribution 均被阻断，普通查询不会自动重建。legacy release 仍可
列出和清理，但不视为 distribution-ready。本轮已关闭两个 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。