chore: establish development baseline

docs/architecture/README.md

@@ -0,0 +1,366 @@
+# BlueArchive Toolkit 架构设计
+
+## 概述
+
+BlueArchive Toolkit 采用 **Monorepo + 多语言混合** 架构，旨在构建一个可持续维护十年以上的工业级开源项目。
+
+当前文档描述目标架构。实际实现状态以根目录 `CURRENT_STATUS.md` 和 `PROJECT_PLAN.md` 为准。
+
+已接受的架构决策：
+
+- `adr/0001-engine-and-application-boundaries.md`：Rust 引擎与 Go 应用层边界。
+- `adr/0002-cas-v1-design-boundary.md`：CAS V1 设计边界。
+
+---
+
+## 设计原则
+
+### 1. 模块化与解耦
+
+- **高内聚、低耦合**：每个模块职责明确，依赖关系清晰
+- **接口优先**：通过接口定义模块边界，支持多种实现
+- **插件化**：核心功能稳定，扩展功能通过插件实现
+
+### 2. 语言选型
+
+| 模块 | 语言 | 理由 |
+|------|------|------|
+| CLI、API Server、下载器 | Go | 并发模型优秀、部署简单、生态成熟 |
+| AssetBundle 解析、Patch 引擎、CAS 引擎 | Rust | 零成本抽象、内存安全、性能极致 |
+| Web 管理后台 | Vue 3 + TypeScript | 渐进式、类型安全、生态完善 |
+
+### 3. 数据流设计
+
+```
+用户请求 → CLI/API → Go 业务层 → Rust 核心层 → CAS 存储 → 数据库
+         ↓                    ↓
+      Web UI              缓存层 (Redis)
+```
+
+---
+
+## 核心模块
+
+### 1. CAS 存储引擎 (Rust)
+
+**职责**：内容寻址存储，实现去重、引用计数、垃圾回收
+
+**接口**：
+```rust
+pub trait Storage {
+    fn put(&self, data: &[u8]) -> Result<Hash>;
+    fn get(&self, hash: &Hash) -> Result<Vec<u8>>;
+    fn exists(&self, hash: &Hash) -> bool;
+    fn delete(&self, hash: &Hash) -> Result<()>;
+}
+
+pub trait RefCounter {
+    fn incr(&self, hash: &Hash) -> Result<u64>;
+    fn decr(&self, hash: &Hash) -> Result<u64>;
+    fn get_count(&self, hash: &Hash) -> Result<u64>;
+}
+```
+
+**存储结构**：
+```
+cas/
+├── objects/
+│   ├── ab/
+│   │   └── cdef1234... (内容)
+│   └── cd/
+│       └── ef567890...
+├── refs.db (SQLite: 引用计数)
+└── metadata.db (元数据)
+```
+
+**特性**：
+- 基于 BLAKE3 的快速 Hash 计算
+- 使用 SQLite 管理引用计数和元数据
+- 支持并发读写（通过文件锁）
+- 自动垃圾回收（引用计数为 0 的对象）
+
+---
+
+### 2. 资源同步器 (Go)
+
+**职责**：从游戏服务器下载资源、增量更新、完整性校验
+
+**架构**：
+```
+Manifest Parser → Version Manager → Downloader → CAS Storage
+                                   ↓
+                              Task Queue (多线程)
+                                   ↓
+                              Progress Reporter
+```
+
+**特性**：
+- 多线程并发下载
+- 断点续传（Range 请求）
+- 自动重试机制（指数退避）
+- 限速支持
+- Hash 校验（下载后立即验证）
+
+---
+
+### 3. AssetBundle 解析器 (Rust)
+
+**职责**：解析 Unity AssetBundle，提取资源
+
+**插件化架构**：
+```rust
+pub trait AssetParser {
+    fn name(&self) -> &str;
+    fn supported_types(&self) -> Vec<AssetType>;
+    fn parse(&self, bundle: &AssetBundle) -> Result<Vec<Asset>>;
+}
+
+// 插件注册
+pub struct ParserRegistry {
+    parsers: HashMap<AssetType, Box<dyn AssetParser>>,
+}
+```
+
+**内置解析器**：
+- TextAsset Parser
+- Localization Parser
+- MonoBehaviour Parser
+- ScriptableObject Parser
+
+**扩展机制**：
+- 动态加载 `.so`/`.dll` 插件
+- 通过配置文件注册自定义解析器
+
+---
+
+### 4. 翻译系统 (Go)
+
+**架构**：
+```
+Text Extractor → Translation Memory (查询) → AI Provider → Glossary (术语替换) → Output
+                       ↓                          ↓
+                   PostgreSQL                  审核队列
+```
+
+**Provider 抽象**：
+```go
+type TranslationProvider interface {
+    Name() string
+    Translate(ctx context.Context, req *TranslateRequest) (*TranslateResponse, error)
+    SupportedLanguages() []Language
+}
+```
+
+**实现**：
+- DeepL Provider
+- OpenAI Provider
+- Anthropic Provider
+- Google Translate Provider
+- Azure Translator Provider
+
+**翻译记忆库**：
+- 精确匹配：100% 匹配直接使用
+- 模糊匹配：使用相似度算法（Levenshtein Distance）
+- 上下文匹配：根据前后文提高匹配准确度
+
+---
+
+### 5. Patch 引擎 (Rust)
+
+**职责**：生成和应用补丁
+
+**支持的 Patch 类型**：
+1. **Binary Patch**：使用 bsdiff 算法
+2. **JSON Patch**：RFC 6902 标准
+3. **Text Patch**：基于 diff 算法
+
+**Patch 结构**：
+```
+patch/
+├── metadata.json (版本信息、文件列表)
+├── binary/
+│   ├── file1.bpatch
+│   └── file2.bpatch
+└── json/
+    └── config.jpatch
+```
+
+**特性**：
+- 增量更新（只传输差异）
+- 完整性校验（Hash 验证）
+- 回滚支持（保留历史版本）
+- 压缩传输（gzip/zstd）
+
+---
+
+### 6. API Server (Go)
+
+**框架**：Gin 或 Echo
+
+**架构**：
+```
+HTTP Request → Middleware (Auth, CORS, Logger) → Handler → Service → Repository → Database
+                    ↓
+                 Cache (Redis)
+```
+
+**API 设计原则**：
+- RESTful 风格
+- 版本控制（/api/v1/...）
+- 统一错误码
+- 统一响应结构
+- OpenAPI 文档自动生成
+
+**核心 API**：
+- `/api/v1/translations` - 翻译管理
+- `/api/v1/glossary` - 术语管理
+- `/api/v1/sync` - 资源同步
+- `/api/v1/patches` - 补丁管理
+- `/api/v1/assets` - 资源查询
+
+---
+
+### 7. Web 后台 (Vue 3)
+
+**技术栈**：
+- Vue 3 + Composition API
+- TypeScript
+- Pinia (状态管理)
+- Vue Router
+- Axios
+- Element Plus / Ant Design Vue
+
+**模块**：
+- Dashboard（统计概览）
+- 翻译审核（Translation Review）
+- 术语管理（Glossary Manager）
+- 资源浏览（Asset Browser）
+- 用户管理（User Management）
+
+---
+
+## 数据库设计
+
+### PostgreSQL Schema
+
+```sql
+-- 翻译记忆库
+CREATE TABLE translation_memory (
+    id BIGSERIAL PRIMARY KEY,
+    source_text TEXT NOT NULL,
+    target_text TEXT NOT NULL,
+    source_lang VARCHAR(10) NOT NULL,
+    target_lang VARCHAR(10) NOT NULL,
+    provider VARCHAR(50),
+    status VARCHAR(20) DEFAULT 'pending',
+    reviewed_at TIMESTAMP,
+    created_at TIMESTAMP DEFAULT NOW()
+);
+
+-- 术语库
+CREATE TABLE glossary (
+    id BIGSERIAL PRIMARY KEY,
+    term VARCHAR(255) NOT NULL,
+    translation VARCHAR(255) NOT NULL,
+    source_lang VARCHAR(10) NOT NULL,
+    target_lang VARCHAR(10) NOT NULL,
+    category VARCHAR(50),
+    priority INT DEFAULT 0,
+    created_at TIMESTAMP DEFAULT NOW()
+);
+
+-- 资源版本管理
+CREATE TABLE resource_versions (
+    id BIGSERIAL PRIMARY KEY,
+    version VARCHAR(50) NOT NULL UNIQUE,
+    manifest_hash VARCHAR(64) NOT NULL,
+    released_at TIMESTAMP,
+    created_at TIMESTAMP DEFAULT NOW()
+);
+
+-- 更多表结构见 migrations/
+```
+
+---
+
+## 部署架构
+
+### 本地开发模式
+
+```
+开发机器 (本地)
+├── CLI (Go)
+├── Rust 库
+└── 连接 → 远程数据库服务器 (裸金属)
+            ├── PostgreSQL
+            └── Redis
+```
+
+### 生产部署模式
+
+```
+负载均衡器
+    ↓
+API Server (多实例)
+    ↓
+├── PostgreSQL (主从)
+├── Redis (Sentinel/Cluster)
+└── CAS 存储 (分布式文件系统)
+```
+
+---
+
+## 安全设计
+
+1. **认证**：JWT Token
+2. **授权**：RBAC (Role-Based Access Control)
+3. **数据传输**：HTTPS/TLS
+4. **数据库连接**：SSL 加密
+5. **密码存储**：bcrypt/argon2
+6. **API 限流**：基于 Redis 的 Token Bucket
+
+---
+
+## 性能优化
+
+1. **缓存策略**：
+   - Redis 缓存热点数据
+   - 浏览器缓存静态资源
+   - CAS 内容天然去重
+
+2. **并发控制**：
+   - Go 协程池
+   - Rust Tokio 异步运行时
+   - 数据库连接池
+
+3. **数据库优化**：
+   - 索引优化
+   - 查询优化
+   - 分区表
+
+---
+
+## 监控与日志
+
+- **日志**：结构化日志（JSON 格式）
+- **指标**：Prometheus + Grafana
+- **追踪**：OpenTelemetry
+- **告警**：Alertmanager
+
+---
+
+## 未来扩展
+
+1. **支持更多游戏**：插件化架构便于扩展
+2. **分布式存储**：CAS 可扩展到对象存储（S3/MinIO）
+3. **机器学习**：翻译质量评估、自动术语提取
+4. **协作功能**：多人实时翻译、冲突解决
+
+---
+
+更多详细设计文档：
+
+- [CAS 存储引擎设计](./cas-storage.md)
+- [AssetBundle 解析器设计](./assetbundle-parser.md)
+- [翻译系统设计](./translation-system.md)
+- [API 设计](../api/README.md)

docs/architecture/adr/0001-engine-and-application-boundaries.md

@@ -0,0 +1,78 @@
+# ADR 0001: Rust 引擎与 Go 应用层边界
+
+**状态**：已接受  
+**日期**：2026-06-28  
+**关联计划**：`../../../PROJECT_PLAN.md`
+
+---
+
+## 背景
+
+BlueArchiveToolkit 的最终目标覆盖资源同步、CAS、AssetBundle 解析、文本提取、翻译、Patch、CLI、API Server、Web 和 SDK。项目天然包含二进制解析、文件完整性、网络同步、任务编排、数据库、用户界面等不同类型的问题。
+
+如果所有能力都堆在一种语言或一个模块里，后续会出现以下问题：
+
+1. 性能敏感和安全敏感代码难以隔离测试。
+2. CLI/API/Web 编排逻辑容易污染底层解析器。
+3. FFI 和 SDK 边界无法稳定。
+4. 插件系统没有清晰接入点。
+
+---
+
+## 决策
+
+采用明确的语言和层次边界：
+
+1. **Rust 引擎层**
+   - 负责 CAS、AssetBundle、Patch、二进制格式解析、Hash、完整性校验。
+   - 只暴露粗粒度、可测试、稳定的 API。
+   - 不承担 CLI 命令解析、HTTP 路由、AI Provider 编排或 Web 状态管理。
+
+2. **Rust 领域/适配层**
+   - `core` 保存领域模型、仓储接口和领域错误。
+   - `adapters` 保存 Unity、Manifest、Client 等适配器接口和注册机制。
+   - `infrastructure` 将引擎实现适配到领域仓储接口。
+
+3. **Go 应用层**
+   - 负责 CLI、资源同步、下载器、API Server、任务调度、配置、日志、Provider 编排。
+   - 通过 FFI、进程边界或稳定 SDK 调用 Rust 引擎能力。
+   - 不重复实现 AssetBundle 解析、Patch 算法或 CAS 对象存储核心逻辑。
+
+4. **Web 层**
+   - 通过 REST API 访问服务端能力。
+   - 不直接读取本地 CAS 或游戏资源文件。
+
+---
+
+## 约束
+
+1. Rust 引擎 API 必须保持业务无关，不出现 CLI 命令、HTTP 状态码、Web 页面状态。
+2. Go 应用层不得复制 Rust 引擎中的 Hash、Patch、AssetBundle 核心算法。
+3. FFI 边界必须避免暴露大量细粒度内部结构，优先暴露批量和事务语义。
+4. 所有跨语言错误必须能映射到统一错误码和可读诊断信息。
+
+---
+
+## 后果
+
+正面影响：
+
+1. 核心引擎可以独立测试和基准测试。
+2. CLI/API/Web 可以复用同一套底层能力。
+3. 后续新增 Provider、Parser、Storage backend 时边界更清晰。
+
+代价：
+
+1. 需要维护 FFI 或 SDK 边界。
+2. 错误类型、数据结构和版本兼容性需要更早设计。
+3. 集成测试必须覆盖跨语言调用，而不能只看单 crate 单元测试。
+
+---
+
+## 当前执行要求
+
+近期实现 CAS 时必须遵守：
+
+1. `crates/bat-cas-engine` 是 CAS 核心实现位置。
+2. `infrastructure` 不再复制 CAS 存储算法，只做 `bat-core::repositories::CasRepository` 适配。
+3. Go CLI 后续通过稳定边界调用 CAS，不直接操作 CAS 内部目录结构。

docs/architecture/adr/0002-cas-v1-design-boundary.md

@@ -0,0 +1,76 @@
+# 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。