# 当前实现缺口清单 - **更新时间**：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` 已存在，但只是可选 CGO 兼容包装，不是用户可运行 CLI，也不是默认 Go/Rust 集成边界。 - `go test ./...` 当前没有产品级 Go package 覆盖。 影响： - 用户没有统一入口。 - 同步、提取、补丁流程无法从命令行串联。 验收： - `bat doctor` 可运行。 - `bat --help` 命令结构稳定。 - 命令支持默认人类可读输出和 `--json` 机器输出。 - Go CLI 默认通过 Rust `bat --json` 进程边界获取同步 report；除非明确兼容需求，不依赖 FFI。 ### 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 接口保存资源元数据。 - `ResourceImportService` 已能把 manifest 中有数据的资源写入 CAS + `ResourceRepository`，AssetBundle 会记录 UnityFS 摘要，TextAsset/Table/Media 会分类索引。 - 官方同步下载结果尚未作为用户级流程自动触发导入 CAS + ResourceRepository。 - 迁移、版本化 schema 和 CLI 查询入口仍需补齐。 验收： - schema 和迁移可重复执行。 - 可按版本、类型、hash、路径查询资源。 - 官方同步后的资源可通过 CLI 查询并能追溯到 CAS 对象。 ### G-011A：资源导入链路基础能力不足 状态：**已关闭** 历史现象： - 资源导入链路只导入 AssetBundle。 - 非 AssetBundle manifest 条目只会被跳过。 - 导入报告只包含 UnityFS 基础摘要，不包含稳定分类统计。 处理结果： - `ResourceImportService` 会把有数据的 manifest 条目导入 CAS 并写入 `ResourceRepository`。 - AssetBundle 仍执行 UnityFS header/block/directory 摘要解析。 - TextAsset、TableBundle、Media 会按资源类型分类，缺少数据时记录为 skipped，便于渐进导入。 - `ResourceImportReport` 增加 `category_counts`，`ImportedResource` 增加 `resource_type`、`category` 和可选 UnityFS 摘要。 验收： - `cargo test -p bat-infrastructure import::tests::` - `cargo test -p bat-infrastructure --test synthetic_phase2_import` ### G-011B：官方版本状态管理不明确 状态：**已关闭** 历史现象： - 当前可用版本主要靠 `current` symlink 和 release 内 snapshot 推断。 - 未显式保存“正在拉取版本”和“失败版本”。 - 上一个可用版本需要从目录状态间接判断。 处理结果： - 新增 `/official-version-state.json`。 - 开始下载后写入 `in_progress_version`。 - 发布成功后写入 `current_completed_version` 和 `previous_available_version`。 - 失败或中断后写入 `failed_versions` 并清空 in-progress。 - `bat status` 会读取并展示版本状态摘要。 验收： - `cargo test -p bat-infrastructure version_state` - `cargo test -p bat-infrastructure --test official_game_main_config_bootstrap` ### G-011C：真实 fixture 与回归样本不足 状态：**已关闭当前阶段** 历史现象： - 已有 Addressables real-shape fixture/golden，但缺少按问题类型命名的当前/上一版本/结构变化样本。 - 403/404 和 hash mismatch 主要依赖单测内联构造，不便于后续回归扩展。 处理结果： - 新增 `adapters/tests/fixtures/addressables_regression/current_catalog.json`。 - 新增 `adapters/tests/fixtures/addressables_regression/previous_catalog.json`。 - 新增 `adapters/tests/fixtures/addressables_regression/structure_changed_catalog.json`。 - 新增 `infrastructure/tests/fixtures/official_regression/http_403.json`。 - 新增 `infrastructure/tests/fixtures/official_regression/http_404.json`。 - 新增 `infrastructure/tests/fixtures/official_regression/hash_mismatch_catalog.json`。 - 对应测试会解析这些 fixture，防止样本只存在但不参与验证。 验收： - `cargo test -p bat-adapters --test addressables_regression` - `cargo test -p bat-infrastructure regression_fixture` ### 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` 承载。 - `bat-ffi` 已降级为可选无状态兼容层，主集成边界明确为 `bat --json` 进程边界或未来稳定 SDK。 ### 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-/` 下创建隔离资源目录、状态目录和报告目录。 - 新增 `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、脚本和测试，不保存官方大文件。 ### G-019：下载失败重试策略不够精细 状态：**已关闭** 历史现象： - curl 失败只按固定次数重试，错误信息主要保留最后一次 stderr。 - 403/404 和 5xx 没有不同处理。 - 单个 URL 长期失败时缺少可查询的 quarantine 诊断状态。 - 旧 launcher 包下载虽然有 primary/backup CDN 路径，但失败信息没有统一分类。 处理结果： - 新增统一 curl 失败分类：`http_forbidden`、`http_not_found`、`http_client_error`、`http_too_many_requests`、`http_server_error`、`dns`、`connect`、`timeout`、`tls`、`interrupted`、`network` 等。 - 403/404/普通 4xx 视为不可重试并提前停止；5xx、429、DNS、连接、超时、中断和网络类错误按尝试次数重试。 - 单个资源 URL 最终失败会写入 `official-download-quarantine.json`，记录失败类型、HTTP 状态、是否可重试、尝试次数和最后错误。 - 失败 URL 会发出 Failed progress，daemon status 和 `bat-events.jsonl` 暴露失败类型、HTTP 状态、重试属性和 quarantine 状态。 - quarantine 会中断同步并阻止发布不完整 staging；下一轮成功下载或复用后清理对应 quarantine 条目。 - 旧 launcher 包或 `resources.assets` 下载在 primary CDN 失败后会切换官方 backup CDN。 验收： - HTTP 404 不重试，写入 quarantine，manifest 不写失败项。 - HTTP 5xx 重试到上限后写入 quarantine。 - launcher primary CDN 失败后会尝试官方 backup CDN。 --- ## 6. 当前关闭顺序建议 1. G-008 2. G-018 3. G-011 4. G-007 5. G-005 6. G-012 7. G-006 这个顺序优先补齐用户入口和真实端到端验证，再推进资源索引、解析、翻译和补丁。