# BlueArchive Toolkit 架构设计

## 概述

BlueArchive Toolkit 采用 **Monorepo + 多语言混合** 架构，旨在构建一个可持续维护十年以上的工业级开源项目。

当前文档描述目标架构和已经落地的关键边界。它不是部署手册；当前可部署能力只有 Rust 官方资源同步任务。API Server、Web、Provider 编排和完整 Go CLI 仍未实现，实际实现状态以根目录 `CURRENT_STATUS.md` 和 `PROJECT_PLAN.md` 为准。

当前已经可用的官方资源入口包括：

- `infrastructure/src/bin/bat_official_sync.rs`：Linux 官方资源同步正式入口，构建为 `bat`，支持 one-shot、`--watch`、`--daemon`、`status`、`stop`、`restart`、`reload`、`refresh`、`logs`、`verify`、`repair`、`doctor` 和 `clean-stable`。
- `infrastructure/src/official_update.rs`：官方自动更新核心服务，负责 auto-discover、snapshot、marker diff、本地 audit/repair。
- `infrastructure/examples/official_pull_plan.rs`：开发/审计用 pull plan 入口。
- `infrastructure/examples/official_update_check.rs`：历史/开发入口，生产优先使用 `bat`。
- `infrastructure/examples/official_launcher_bootstrap.rs`：显式开发/审计辅助路径，用于核查官方 launcher metadata，不是生产运行依赖。
- `docs/guides/official-resource-test-pull.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 业务层 → bat --json / SDK → 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. 官方资源同步器 (Rust 当前实现，Go 后续编排)

**职责**：从官方日服 HTTP metadata 自动发现资源入口，下载 Windows + Android 官方资源，增量检查，完整性校验，保持本地状态。

**当前实现**：

- `OfficialUpdateService`：auto-discover、snapshot、marker diff、本地 manifest audit/repair。
- `OfficialResourcePullService`：官方 URL 校验、`.part` 断点续传、重试、下载 manifest、官方 seed `.hash` 校验。
- `bat`：正式 binary，支持 one-shot、`--watch`、`--daemon`、`status`、`stop`、`restart`、`reload`、`refresh`、`logs`、`verify`、`repair`、`doctor` 和 `clean-stable`。

**当前数据流**：

```
官方 metadata → GameMainConfig → server-info → discovery endpoints
     ↓
seed catalog → inventory → pull plan → staging → versions/<id>
     ↓
current symlink → official-sync-snapshot.json + official-download-manifest.json
```

**已具备特性**：

- 不安装、不执行官方 launcher。
- 默认平台 `Windows + Android`。
- `--auto-discover` 自动获取 `app-version`、`connection-group` 和 `server-info`。
- `--watch` / `--daemon` 常驻检查，正常检查默认 1 小时，失败重试默认 60 秒，每天北京时间（UTC+8）`03:00`、`16:00`、`18:00` 强制刷新一次。
- `refresh --force` 可手动强制刷新；`verify` 只读校验当前官方计划、本地 manifest 和官方 seed hash；`repair` 尝试修复异常资源。
- 非 dry-run 同步先写 `.staging/<id>`，校验完成后发布 `versions/<id>` 并原子切换 `current` symlink。
- `--daemon` 使用状态目录下的 `bat.sock` 作为 Unix socket JSON-RPC live control plane；PID、状态和日志文件是快照与 fallback，`bat-events.jsonl` 是结构化轮转日志。
- `status`、`logs`、`reload`、`stop` 和默认形态的 `refresh` 优先通过 RPC 管理后台进程；控制命令通过 `bat-control.lock` 串行化；`restart` 负责重启或替换启动参数；live daemon 会阻止前台写命令直接修改同一资源目录；`doctor` 做运行时诊断；`clean-stable` 清理临时文件和失效/损坏状态。
- 远端 marker 无变化且本地 manifest clean 时不下载。
- 本地文件损坏时 repair。
- 官方 seed `.hash` 强校验；Addressables `catalog_*.hash` 作为变更 marker。

**后续 Go 职责**：

- 提供最小稳定 CLI。
- 默认通过 `bat --json` 进程边界包装 Rust 同步入口，并转发结构化 report。
- `bat-ffi` 仅作为可选无状态 C ABI 兼容层，不承载官方同步 daemon、下载器或 CAS handle。
- 编排 API Server、任务队列、Provider 和用户配置。

---

### 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 bat 进程 / 未来 SDK
├── 可选 bat-ffi 兼容层
└── 连接 → 远程数据库服务器 (裸金属)
            ├── 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. **协作功能**：多人实时翻译、冲突解决

---

更多详细设计文档：

- [官方资源后端说明](./official-resource-backend.md)
- [API 设计](../api/README.md)

待创建的详细设计文档：

- `docs/architecture/cas.md`
- `docs/architecture/assetbundle.md`
- `docs/architecture/translation.md`