当前文档描述目标架构和已经落地的关键边界。它不是部署手册；当前可部署能力包括 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)

职责：内容寻址存储，实现去重、引用计数、垃圾回收

接口：

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 覆盖为准。

目标插件化架构：

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

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 类型：

Binary Patch：确定性 Binary hunk diff/apply（当前实现）
JSON Patch：RFC 6902 标准
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 V1 已实现，登录、角色、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

-- 翻译记忆库
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 存储 (分布式文件系统)

安全设计（目标设计）

认证：JWT Token
授权：RBAC (Role-Based Access Control)
数据传输：HTTPS/TLS
数据库连接：SSL 加密
密码存储：bcrypt/argon2
API 限流：基于 Redis 的 Token Bucket

性能优化（目标设计）

缓存策略：
- Redis 缓存热点数据
- 浏览器缓存静态资源
- CAS 内容天然去重
并发控制：
- Go 协程池
- Rust Tokio 异步运行时
- 数据库连接池
数据库优化：
- 索引优化
- 查询优化
- 分区表

监控与日志（目标设计）

日志：结构化日志（JSON 格式）
指标：Prometheus + Grafana
追踪：OpenTelemetry
告警：Alertmanager

未来扩展

支持更多游戏：插件化架构便于扩展
分布式存储：CAS 可扩展到对象存储（S3/MinIO）
机器学习：翻译质量评估、自动术语提取
协作功能：多人实时翻译、冲突解决

更多详细设计文档：

README.md Unescape Escape

BlueArchive Toolkit 架构设计

概述