BlueArchiveToolkit/docs/reports/CURRENT_GAPS.md

当前实现缺口清单

• 更新时间：2026-07-06
• 用途：集中跟踪当前代码中的占位实现、设计缺口和下一步验收项。
• 权威计划：../../PROJECT_PLAN.md

---

1. 基线缺口

G-001：Git 元数据不可用

状态：已关闭，采用新初始化基线

原现象：

• .git/ 是空目录。
• git status 报 not a git repository。

处理结果：

• 已执行 git init。
• 已将初始分支调整为 main。
• 已配置当前路径为 Git safe directory。
• git status --short --branch 已可用。
• 本轮创建首次基线提交。

限制：

• 原项目历史未恢复。
• 后续历史从当前基线提交开始。

验收：

• git log --oneline -1 能看到基线提交。

G-002：CAS 有两套实现边界

状态：已关闭

原现象：

• crates/bat-cas-engine/src/storage.rs 有文件系统存储。
• infrastructure/src/cas/filesystem.rs 也实现了文件系统 CAS repository。

处理结果：

• crates/bat-cas-engine 新增 repository 组合层，成为 CAS 核心实现。
• infrastructure/src/cas/filesystem.rs 已改为 bat-core::CasRepository 适配层。
• infrastructure 不再直接写对象文件，不再维护自己的引用计数逻辑。

验收证据：

• bat-cas-engine::repository::FileSystemCasRepository
• bat_infrastructure::FileSystemCasRepository
• cargo test --workspace

G-003：CAS 引用计数和 GC 未实现

状态：已关闭

原现象：

• FileSystemCasRepository::add_reference 返回固定 1。
• remove_reference 返回固定 0。
• get_reference_count 返回固定 1。
• gc 返回固定 0。
• crates/bat-cas-engine/src/refcount.rs 是占位。

处理结果：

• crates/bat-cas-engine/src/refcount.rs 使用 SQLite 保存对象元数据和引用计数。
• store() 会存储对象并增加引用计数。
• add_reference()、remove_reference()、get_reference_count() 已持久化。
• gc() 删除引用计数为 0 的对象和元数据。
• gc_candidates() 提供 dry-run 能力。

验收证据：

• 引用计数增减有持久化测试。
• GC 不删除仍被引用对象。
• 并发引用更新测试通过。

---

2. 核心功能缺口

G-004：CAS 写入不是生产级原子流程

状态：已关闭

原现象：

• 当前写入直接写目标路径。
• 缺少临时文件、fsync、原子 rename、并发冲突处理。

处理结果：

• FileSystemStorage::put() 使用临时文件写入、文件 sync、原子 rename、目录 sync。
• 读取对象时强制 Hash 校验。
• 并发写入相同内容只保留一个对象，引用计数按调用次数递增。
• 损坏对象读取返回 HashMismatch。

验收证据：

• 写入失败不会留下可见半成品对象。
• 并发写入相同内容只产生一个对象。
• 读取时 Hash 不匹配会返回明确错误。

G-005：AssetBundle 解析器仍是占位

现象：

• crates/bat-assetbundle/src/parser.rs 只有 Parser::name。
• types.rs 只有 AssetType::TextAsset。

影响：

• 无法解析真实 UnityFS。
• 无法提取 TextAsset 或配置文本。

验收：

• 能解析结构化测试样本。
• 支持 UnityFS header、blocks、directory、metadata。
• 错误包含偏移和字段上下文。

G-006：Patch 引擎仍是占位

现象：

• binary::apply_patch 返回空 Vec。
• json::apply_json_patch 返回空字符串。

影响：

• 无法生成或应用补丁。
• 回滚和完整性校验无法落地。

验收：

• Binary patch 能完成 diff/apply 往返。
• JSON patch 能应用 RFC 6902 patch。
• Patch manifest 包含 hash、版本和回滚信息。

G-007：Addressables Catalog 解析不完整

状态：部分关闭

现象：

• AddressablesCatalogDriver 已能解析当前真实形态 JSON catalog fixture/golden。
• 已输出 path、hash、size、resource_type、address、dependencies、metadata。
• 仍需覆盖更多官方 catalog 结构变体、二进制/压缩字段组合和更明确的失败诊断。

影响：

• 当前解析能力可以服务 Manifest inspect 和部分资源索引，但还不能宣称完整兼容所有 Unity Addressables/SBP catalog 形态。

验收：

• 能解析项目目标版本的真实 Catalog 样本集合。
• 解析结果包含资源 key、provider、dependency、hash、size、path。
• 对不支持的 catalog 结构返回明确错误，而不是静默丢字段。

---

3. 应用层缺口

G-008：Go CLI 尚未实现

现象：

• cmd/bat 目录存在，但无 main.go。
• internal/ffi/ffi.go 已存在，但还不是用户可运行 CLI。
• go test ./... 当前没有产品级 Go package 覆盖。

影响：

• 用户没有统一入口。
• 同步、提取、补丁流程无法从命令行串联。

验收：

• bat doctor 可运行。
• bat --help 命令结构稳定。
• 命令支持默认人类可读输出和 --json 机器输出。

G-009：API Server 和 OpenAPI 尚未实现

现象：

• api/ 只有目录结构。
• 无 handler、service、OpenAPI schema。

影响：

• Web 和第三方集成无服务端入口。

验收：

• /api/v1/health 可用。
• 统一错误结构落地。
• OpenAPI 与实际路由同步。

G-010：Web 管理后台尚未实现

现象：

• web/ 只有目录结构。

影响：

• 翻译审核、术语管理、Dashboard 无 UI。

验收：

• 登录、权限、翻译审核、术语管理基础流程可用。

---

4. 数据与翻译缺口

G-011：Resource Repository 未持久化

状态：部分关闭

影响：

• SqliteResourceRepository 已存在，可按领域 repository 接口保存资源元数据。
• 官方同步下载结果尚未作为用户级流程自动写入 CAS + ResourceRepository。
• 迁移、版本化 schema 和 CLI 查询入口仍需补齐。

验收：

• schema 和迁移可重复执行。
• 可按版本、类型、hash、路径查询资源。
• 官方同步后的资源可通过 CLI 查询并能追溯到 CAS 对象。

G-012：Translation Memory 未实现

影响：

• 无法复用人工翻译和 AI 翻译历史。

验收：

• 精确匹配、模糊匹配、上下文匹配可用。
• 记录 Provider、模型、审核状态和历史版本。

G-013：Glossary 未实现

影响：

• 无法保证术语一致性。
• AI 翻译无法强制遵守术语。

验收：

• 术语优先级高于 AI。
• 支持别名、分类、冲突检测、审核。

G-014：AI Provider 抽象未实现

影响：

• 无法接入 DeepL/OpenAI/Anthropic/Google/Azure。

验收：

• Provider 可替换。
• 支持批处理、限流、重试、成本统计和质量检查。

---

5. 文档与发布缺口

G-015：README 与当前真实状态不完全一致

状态：已关闭

现象：

• 旧 README 描述了最终架构，但部分功能尚未实现。

验收：

• README 明确区分已实现、开发中、规划中。

处理结果：

• README 已明确区分当前可用能力、未完成模块、官方同步运行命令和近期优先级。

G-016：架构文档需要更新为当前路线图

状态：已关闭当前阶段

现象：

• 旧 docs/architecture/README.md 偏目标架构，容易让读者误以为 Go 同步器和 API/Web 已经可用。

验收：

• 增加 ADR 或架构决策记录。
• 明确 Rust/Go/DB/Plugin 边界。

处理结果：

• 架构 README 已明确当前 Rust 官方同步入口、Go 计划边界和目标架构差异。
• 官方资源后端说明由 docs/architecture/official-resource-backend.md 承载。

G-017：CI 未落地

影响：

• 无自动验证质量门槛。

验收：

• GitHub Actions 或等价 CI 执行 format、lint、test、build。

G-018：真实官方网络全量下载 smoke test 已固化为可重复命令

状态：已关闭（已固化可重复 smoke 命令；真实下载产物不纳入 Git）

历史现象：

• 本地测试覆盖 mock、fixture、synthetic import 和 CLI 参数。
• 曾缺少真实官方网络全量下载的固定 runbook 和可重复命令。

处理结果：

• 新增 scripts/official-full-pull-smoke.sh，默认在 /tmp/bat-official-smoke-<UTC timestamp>/ 下创建隔离资源目录、状态目录和报告目录。
• 新增 make official-smoke 统一入口。
• 新增 docs/guides/official-full-pull-smoke.md，记录目标、命令、输出结构、环境变量、安全边界和成功判定。
• smoke 流程覆盖 dry-run plan、首次全量拉取、二次 up_to_date、人工破坏 active release 文件后的 repair、repair 后 verify。
• 脚本会检查二次 up_to_date、repair 完成、verify healthy=true，并检查首次拉取和 repair 的 stderr log 中存在总体下载进度、单文件进度和校验结果日志。
• 运行报告 SMOKE_REPORT.md 记录实际输出目录、active release、文件数量、release 大小和被破坏文件；大型官方资源文件保留在隔离输出目录，不纳入 Git。

验收：

• 使用 scripts/official-full-pull-smoke.sh 或 make official-smoke。
• 默认输出目录必须是独立 /tmp 目录；非 /tmp 路径需要显式设置 BAT_SMOKE_ALLOW_NON_TMP=1，且输出目录必须为空。
• 脚本退出码为 0 即表示 runbook 验收通过。
• 真实网络执行需要外部网络和足够磁盘空间；本仓库只保存 runbook、脚本和测试，不保存官方大文件。

---

6. 当前关闭顺序建议

1. G-008
2. G-018
3. G-011
4. G-007
5. G-005
6. G-012
7. G-006

这个顺序优先补齐用户入口和真实端到端验证，再推进资源索引、解析、翻译和补丁。