BlueArchiveToolkit/docs/reports/CURRENT_GAPS.md

当前实现缺口清单

更新时间：2026-06-28
用途：集中跟踪当前代码中的占位实现、设计缺口和下一步验收项。
权威计划：../../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 解析不完整

现象：

• 复杂压缩字段解析仍标记 TODO。

影响：

• 真实 Manifest 解析可能只能覆盖简单样本。

验收：

• 能解析项目目标版本的真实 Catalog 样本。
• 解析结果包含资源 key、provider、dependency、hash、size、path。

---

3. 应用层缺口

G-008：Go CLI 尚未实现

现象：

• cmd/bat 目录存在，但无 main.go。
• go test ./... 当前无 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 未持久化

影响：

• 无法可靠记录资源版本、资源路径、依赖和 CAS hash 映射。

验收：

• schema 和迁移可重复执行。
• 可按版本、类型、hash、路径查询资源。

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 明确区分已实现、开发中、规划中。

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

现象：

• docs/architecture/README.md 仍描述理想架构，缺少当前状态和边界冻结记录。

验收：

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

G-017：CI 未落地

影响：

• 无自动验证质量门槛。

验收：

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

---

6. 当前关闭顺序建议

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

这个顺序优先建立可信工作区和基础存储，再推进资源同步、解析、翻译和补丁。