mirror of
https://github.com/Yuyi-Oak/BlueArchiveToolkit.git
synced 2026-07-22 01:15:14 +08:00
77 lines
2.3 KiB
Markdown
77 lines
2.3 KiB
Markdown
# ADR 0002: CAS V1 设计边界
|
||
|
||
**状态**：已接受
|
||
**日期**：2026-06-28
|
||
**关联缺口**：`../../reports/CURRENT_GAPS.md`
|
||
|
||
---
|
||
|
||
## 背景
|
||
|
||
当前代码中存在两处 CAS 相关实现：
|
||
|
||
1. `crates/bat-cas-engine/src/storage.rs`
|
||
2. `infrastructure/src/cas/filesystem.rs`
|
||
|
||
两者都触及文件系统对象存储。随着引用计数、GC、并发安全、元数据和 FFI 接入推进，如果继续保留双实现，会导致行为不一致和维护成本上升。
|
||
|
||
---
|
||
|
||
## 决策
|
||
|
||
CAS V1 采用以下边界：
|
||
|
||
1. `bat-cas-engine` 是唯一 CAS 核心引擎。
|
||
2. `infrastructure` 只负责把 CAS 引擎适配到 `bat-core` 定义的仓储接口。
|
||
3. CAS 对象地址使用 BLAKE3 内容 Hash。
|
||
4. 文件系统后端采用分片目录结构，避免单目录文件过多。
|
||
5. 元数据后端必须抽象，初期可以使用 SQLite，本地 CLI 不直接依赖 PostgreSQL。
|
||
6. 服务端 Resource/Translation 等业务数据使用 PostgreSQL，不和 CAS 对象元数据混在一起。
|
||
|
||
---
|
||
|
||
## CAS V1 必须支持
|
||
|
||
1. 内容写入和去重。
|
||
2. 内容读取和 Hash 校验。
|
||
3. 对象存在性检查。
|
||
4. 对象大小和统计信息。
|
||
5. 引用计数增加、减少、查询。
|
||
6. GC dry-run 和执行模式。
|
||
7. 原子写入：临时文件、flush、fsync、rename。
|
||
8. 并发写入同一对象不会产生损坏文件。
|
||
9. 损坏对象读取时返回 Hash mismatch。
|
||
|
||
---
|
||
|
||
## CAS V1 暂不支持
|
||
|
||
1. 分布式对象存储。
|
||
2. 远端 CAS 后端。
|
||
3. 加密对象存储。
|
||
4. 跨机器 GC 协议。
|
||
|
||
这些能力以后通过 storage backend trait 扩展。
|
||
|
||
---
|
||
|
||
## 验收标准
|
||
|
||
CAS V1 不以“能通过简单 put/get 测试”为完成标准。必须满足：
|
||
|
||
1. 单元测试覆盖 put/get/exists/delete/list/stats。
|
||
2. 引用计数有持久化测试。
|
||
3. GC 不删除仍被引用对象。
|
||
4. 并发写入相同内容测试通过。
|
||
5. 损坏对象读取返回明确错误。
|
||
6. 权限或路径错误有清晰错误类型。
|
||
7. `cargo test --workspace` 和 `cargo clippy --workspace -- -D warnings` 通过。
|
||
|
||
---
|
||
|
||
## 后续迁移要求
|
||
|
||
1. 将 `infrastructure/src/cas/filesystem.rs` 中的直接文件写入逻辑迁移为调用 `bat-cas-engine`。
|
||
2. 移除固定返回值的引用计数和 GC 占位逻辑。
|
||
3. 在 `docs/reports/CURRENT_GAPS.md` 中逐项关闭 G-002、G-003、G-004。
|