BlueArchiveToolkit/docs/architecture/README.md

BlueArchive Toolkit 架构设计

概述

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

当前文档描述目标架构和已经落地的关键边界。实际实现状态以根目录 CURRENT_STATUS.md 和 PROJECT_PLAN.md 为准。

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

• infrastructure/src/bin/bat_official_sync.rs：Linux 官方资源同步正式入口，支持 one-shot 和 --watch 常驻更新。
• 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-official-sync。
• 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 业务层 → Rust 核心/同步层 → CAS 存储 → 数据库
         ↓                    ↓
      Web UI              缓存层 (Redis)

---

核心模块

1. CAS 存储引擎 (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-official-sync：正式 binary，支持 one-shot 和 --watch。

当前数据流：

官方 metadata → GameMainConfig → server-info → discovery endpoints
     ↓
seed catalog → inventory → pull plan → downloader → output directory
     ↓
official-sync-snapshot.json + official-download-manifest.json

已具备特性：

• 不安装、不执行官方 launcher。
• 默认平台 Windows + Android。
• --auto-discover 自动获取 app-version、connection-group 和 server-info。
• --watch 常驻检查，默认 1 小时。
• 远端 marker 无变化且本地 manifest clean 时不下载。
• 本地文件损坏时 repair。
• 官方 seed .hash 强校验；Addressables catalog_*.hash 作为变更 marker。

后续 Go 职责：

• 提供最小稳定 CLI。
• 包装或调用 Rust 同步入口，转发 JSON report。
• 编排 API Server、任务队列、Provider 和用户配置。

---

3. AssetBundle 解析器 (Rust)

职责：解析 Unity AssetBundle，提取资源

插件化架构：

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 抽象：

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

-- 翻译记忆库
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. 协作功能：多人实时翻译、冲突解决

---

更多详细设计文档：

• 官方资源后端说明
• API 设计

待创建的详细设计文档：

• docs/architecture/cas.md
• docs/architecture/assetbundle.md
• docs/architecture/translation.md