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 未记录

状态：**未关闭**

现象：

- 本地测试覆盖 mock、fixture、synthetic import 和 CLI 参数。
- 尚未在隔离输出目录记录一次真实官方网络全量下载。

影响：

- 无法用文档证明当前 `bat-official-sync` 在真实官方网络环境下完成首次下载、二次静默 up-to-date 和本地损坏 repair。

验收：

- 使用独立目录执行 dry-run。
- 执行真实首次下载，不指向任何现有客户端或人工维护资源目录。
- 二次运行返回 `up_to_date`，watch 模式在 up-to-date 时静默。
- 人工破坏一个本地文件后，audit 检出并 repair。
- 记录命令、摘要、输出目录和未纳入 Git 的大文件位置。

---

## 6. 当前关闭顺序建议

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

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