BlueArchiveToolkit/docs/architecture/adr/0003-cas-core-interface-and-error-boundary.md

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 只能通过领域仓储接口、稳定 SDK 或进程边界调用 CAS，不直接依赖对象目录结构；FFI 仅作为可选实现方式。
2. CAS V1 后续可以替换元数据后端，但不能改变领域接口语义。
3. 如果以后需要 dry-run GC、批量引用更新或流式存储，应作为新接口扩展，不破坏当前 trait。