# BlueArchive Toolkit 架构设计

## 概述

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

当前文档描述目标架构和已经落地的关键边界。它不是部署手册；当前可部署能力包括 Rust 官方资源同步任务和 Go `cmd/bat-api` 资源 bootstrap/分发服务。完整游戏业务 API、Web、Provider 编排和 SDK 仍未完成，实际实现状态以源码、测试和根目录 `CURRENT_STATUS.md` 为准；`PROJECT_PLAN.md` 只描述目标和路线图。

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

- `infrastructure/src/bin/bat_official_sync.rs`：Linux 官方资源同步薄入口，构建为 `bat`；控制面组合与实现位于 `infrastructure/src/bin/bat/`，支持 one-shot、`--watch`、`--daemon`、`status`、`stop`、`restart`、`reload`、`refresh`、`logs`、`verify`、`repair`、`doctor` 和 `clean-stable`。
- `infrastructure/src/bin/bat/app.rs`：CLI/env、daemon/watch、RPC dispatch 与顶层流程组合。
- `infrastructure/src/bin/bat/report_output.rs`：人类可读报告、JSON 查询结果和报告格式化。
- `infrastructure/src/bin/bat/terminal_output.rs`：前台错误、帮助、启动提示、进度和结构化日志输出。
- `infrastructure/src/bin/bat/task_registry.rs`：任务注册表、任务持久化、取消和 daemon worker。
- `infrastructure/src/bin/bat/readonly_query.rs`：parse/resource/translation/localized 只读查询及 RPC 选择。
- `infrastructure/src/bin/bat/translation_query.rs`：翻译任务与 handoff 查询、worker 状态更新。
- `infrastructure/src/bin/bat/patch_commands.rs`：文件 patch 与 UnityFS 写入命令参数校验和执行。
- `infrastructure/src/bin/bat/app_tests.rs`：控制面回归测试，避免测试代码继续堆积在入口实现中。
- `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`：历史语言/层次边界决策；资源同步职责已由 ADR 0004 取代。
- `adr/0002-cas-v1-design-boundary.md`：CAS V1 设计边界。
- `adr/0003-cas-core-interface-and-error-boundary.md`：CAS 核心接口与错误边界冻结。
- `adr/0004-rust-bat-go-bat-api-resource-boundary.md`：当前 Rust `bat` 与 Go `bat-api`
  的资源控制面边界。

---

## 设计原则

### 1. 模块化与解耦

- **高内聚、低耦合**：每个模块职责明确，依赖关系清晰
- **接口优先**：通过接口定义模块边界，支持多种实现
- **插件化**：核心功能稳定，扩展功能通过插件实现

### 2. 语言选型

| 模块 | 语言 | 当前定位 |
|------|------|------|
| 官方资源同步与运维 CLI、同步核心 | Rust | **当前实现**；`bat` 负责生产资源和长期状态 |
| 资源 bootstrap、只读分发和 Rust 管理入口 | Go | **当前实现**；`cmd/bat-api` 通过 `bat.sock` RPC 工作 |
| AssetBundle 解析、Patch 引擎、CAS 引擎 | Rust | **当前已有基础，复杂覆盖仍按路线图推进** |
| 完整 API、服务编排和 Provider | Go | **目标设计，尚未完整实现** |
| 完整 Web 协作后台 | Vue 3 + TypeScript | **目标设计**；当前只有内嵌 dashboard MVP |

### 3. 数据流设计

当前已落地的数据流：

```
官方 metadata → Rust bat / daemon → release + current + manifest
                         ↓
                  bat.sock JSON-RPC
                         ↓
              Go bat-api → bootstrap / CDN / dashboard
```

目标扩展数据流（其中 Go 业务层、SDK、数据库和 Redis 尚未全部实现）：

```
用户请求 → CLI/API → Go 业务层 → bat.sock RPC / 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`、`restart`、`reload`、`stop` 和默认形态的 `refresh` 优先通过 RPC 管理后台进程；控制命令通过 `bat-control.lock` 串行化；`restart` 通过 Rust lifecycle controller 复用 CLI restart 路径重启或替换启动参数；live daemon 会阻止前台写命令直接修改同一资源目录；`doctor` 做运行时诊断；`clean-stable` 清理临时文件和失效/损坏状态。
- 远端 marker 无变化且本地 manifest clean 时不下载。
- 本地文件损坏时 repair。
- 官方 seed `.hash` 强校验；Addressables `catalog_*.hash` 作为变更 marker。

**Go 当前职责**：

- `bat-api` 通过 `bat.sock` RPC 读取 Rust 已发布 release、manifest、snapshot 和状态。
- 提供资源 bootstrap、server-info 改写、只读 CDN path、readiness、OpenAPI 和白名单管理转发；
  翻译任务与 TM 管理接口只通过 Rust RPC 代理，不在 Go 侧持有状态。
- 不运行另一套同步器，不直接管理官方下载、staging、version-state、CAS 或解析状态。

完整 API、服务编排、Provider 和用户配置属于目标扩展，不能从本节推断为当前已实现。

---

### 3. AssetBundle 解析器 (Rust，当前基础与目标扩展)

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

以下插件注册和动态加载是目标扩展；当前实现以 `crates/bat-assetbundle`、
`bat-adapters` 和真实 fixture 覆盖为准。

**目标插件化架构**：
```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；当前 worker 由 Rust `bat` 承担）

当前已实现的是 Rust `bat` 的离线 TextUnit 队列、mock/Crowdin provider worker、
lease/retry、结果落库、项目级 Translation Memory V1 和独立 Glossary V2。TM 位于独立
SQLite，按 raw source + 完整 context 做 trusted exact reuse，candidate 必须显式 confirm；
Glossary 只有 approved term 进入 provider/TM 自动流程，并在结果上执行确定性 QA；模糊
匹配和完整 Provider 体系仍属后续缺口。

**架构**：
```
Text Extractor → Glossary constraints + TM exact query → AI Provider → Glossary QA → Output
                       ↓                          ↓
                   PostgreSQL                  审核队列
```

**Provider 抽象**：
```go
type TranslationProvider interface {
    Name() string
    Translate(ctx context.Context, req *TranslateRequest) (*TranslateResponse, error)
    SupportedLanguages() []Language
}
```

**当前实现**：
- Rust `bat` 的 mock provider worker
- Rust `bat` 的 Crowdin provider worker

**目标 Provider**：
- DeepL Provider
- OpenAI Provider
- Anthropic Provider
- Google Translate Provider
- Azure Translator Provider

**翻译记忆库**：
- 当前 V1：raw source 完全相同、完整 context 完全相同且记录为 trusted 时自动复用。
- provider 输出写入先是 candidate；manual task result 不会自动建立 TM 或 trusted。`bat i18n memory confirm` 显式确认单条记录后才可自动复用。
- source、context、release、TextUnit、provider 和 run provenance 保存在 Rust TM SQLite 中。
- 模糊匹配、术语优先级和 PostgreSQL 服务化仍不是当前实现。

---

### 5. Patch 引擎 (Rust，当前基础与目标扩展)

**职责**：生成和应用补丁

**支持的 Patch 类型**：
1. **Binary Patch**：确定性 Binary hunk diff/apply（当前实现）
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，目标设计)

当前可用的 Go HTTP 服务是 `cmd/bat-api` 的资源 bootstrap、只读分发和 Rust 管理
入口，不是下列完整游戏业务 API。

**框架**：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，目标设计)

当前只有 `bat-api` 内嵌 dashboard MVP；Rust `bat` 的 Glossary V2 已实现，登录、角色、Web 术语管理和完整协作审核仍未实现。

**技术栈**：
- Vue 3 + Composition API
- TypeScript
- Pinia (状态管理)
- Vue Router
- Axios
- Element Plus / Ant Design Vue

**模块**：
- Dashboard（统计概览）
- 翻译审核（Translation Review）
- Web 术语管理（Glossary Manager）
- 资源浏览（Asset Browser）
- 用户管理（User Management）

---

## 数据库设计（目标设计）

当前 Rust 资源链路使用 SQLite 维护本地 CAS、ResourceRepository 和翻译任务状态；
PostgreSQL/Redis 业务服务端方案尚未完整落地。

### 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/
```

---

## 部署架构（目标设计）

当前可部署形态是 Rust `bat` 官方资源同步任务和同机/共享文件系统的 Go
`bat-api` 资源 bootstrap/分发服务。以下多实例 API、PostgreSQL 主从和 Redis
集群属于目标部署形态。

### 本地开发模式

```
开发机器 (本地)
├── 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)
- [资源 release 布局与分发契约](./resource-release-layout.md)
- [AssetBundle 解析与发布路线图](./assetbundle.md)
- [API 设计](../api/README.md)