# 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 设计边界。
- `adr/0003-cas-core-interface-and-error-boundary.md`：CAS 核心接口与错误边界冻结。

---

## 设计原则

### 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)