feat: implement production cas v1

2026-07-22 04:35:16 +08:00 · 2026-06-28 12:39:17 +08:00
parent dd53e3054e
commit b202d7b231
33 changed files with 1082 additions and 447 deletions
@@ -0,0 +1,50 @@
+# ADR 0003: CAS 核心接口与错误边界冻结
+
+**状态**：已接受  
+**日期**：2026-06-28  
+**关联实现**：`../../../core/src/repositories/cas_repository.rs`、`../../../crates/bat-cas-engine/src/repository.rs`、`../../../infrastructure/src/cas/filesystem.rs`
+
+---
+
+## 背景
+
+CAS 是资源同步、资源版本共享、AssetBundle 缓存、Patch 回滚和本地对象存储的基础能力。当前阶段需要冻结 CAS V1 对外接口，避免后续 Manifest、Resource Repository 和 CLI 开发时继续改动底层边界。
+
+---
+
+## 决策
+
+CAS V1 对外领域接口继续使用 `bat_core::repositories::cas_repository::CasRepository`，并冻结以下语义：
+
+1. `store(data)` 存储对象并增加引用计数。
+2. `get(id)` 读取对象并校验 Hash。
+3. `exists(id)` 只表达对象文件存在性，不增加引用。
+4. `add_reference(id)` 增加已存在对象引用。
+5. `remove_reference(id)` 减少引用计数，引用计数不得低于 0。
+6. `get_reference_count(id)` 返回持久化引用计数。
+7. `gc()` 删除引用计数为 0 的对象及其元数据。
+8. `store_from_file()` 和 `export_to_file()` 保留为领域接口默认便捷方法。
+
+---
+
+## 错误映射
+
+`bat-cas-engine::CasError` 在 infrastructure 适配层映射为 `bat_core::Error`：
+
+1. `Io` -> `Error::Io`
+2. `ObjectNotFound` -> `Error::NotFound`
+3. `HashMismatch` -> `Error::InvalidArgument`
+4. `InvalidHash` -> `Error::InvalidArgument`
+5. `ReferenceUnderflow` -> `Error::InvalidArgument`
+6. `Database` -> `Error::Other`
+7. `Other` -> `Error::Other`
+
+该映射保证应用层可以只依赖 `bat-core` 的错误边界，不直接泄漏 CAS 引擎内部错误类型。
+
+---
+
+## 后果
+
+1. 后续 Go CLI/API 只能通过领域仓储接口或稳定 FFI 调用 CAS，不直接依赖对象目录结构。
+2. CAS V1 后续可以替换元数据后端，但不能改变领域接口语义。
+3. 如果以后需要 dry-run GC、批量引用更新或流式存储，应作为新接口扩展，不破坏当前 trait。