BlueArchiveToolkit/docs/architecture/adr/0004-rust-bat-go-bat-api-resource-boundary.md

# ADR 0004: Rust bat 与 Go bat-api 当前资源控制面边界

**状态**：已接受
**日期**：2026-09-04
**关联文档**：`../../../CURRENT_STATUS.md`、`../../../docs/reports/GO_STATUS.md`

---

## 背景

项目同时包含 Rust 资源引擎和 Go HTTP 服务。历史设计曾把资源同步、下载器
和任务调度归入 Go 应用层，但当前实现已经由 Rust `bat` 统一持有这些长期状态。
如果继续沿用旧职责描述，会让 Go、Web 或其他入口重复实现资源状态机。

---

## 决策

1. **Rust `bat` 是官方资源生产者和状态拥有者**：
   - 负责官方 metadata 发现、下载、校验、staging、release 发布和 `current` 切换；
   - 负责 watch/daemon、`bat.sock` JSON-RPC、任务、日志、版本状态、解析、
     翻译 worker 和 localized release 状态；
   - 负责 CAS、AssetBundle 解析、Patch 核心算法及其文件安全边界。

2. **Go `bat-api` 是资源读侧和管理入口**：
   - 通过 `bat.sock` RPC 发现 Rust 已发布的 `resource_root`、snapshot、manifest
     和状态；
   - 提供资源 bootstrap、server-info 改写、只读 CDN path、readiness、OpenAPI
     以及鉴权后的白名单管理转发；翻译任务和 TM 管理面只转发 Rust RPC；
   - 不下载官方资源、不写 staging、不维护 version-state，不复制 CAS、解析器、
     Patch 核心算法或同步状态机。

3. **Go `cmd/bat` 和 `bat-ffi` 不是主集成边界**：
   - `cmd/bat` 只保留试验 CLI；
   - `bat-ffi` 只保留无状态、粗粒度、一次调用一次输入输出的兼容 helper；
   - 新的跨语言控制和查询能力优先增加 Rust RPC contract，再由
     `internal/backendrpc` 消费。

4. **完整游戏业务 API、完整 Web 协作后台、Glossary 和 Provider 扩展体系仍是后续目标**；
   Translation Memory V1 已由 Rust `bat` 持有，不能从目标架构图推断 Go 侧拥有第二份状态。

---

## 后果

- 资源同步只有一个长期状态拥有者，`bat-api` 可以安全地横向扩展为只读服务。
- Rust RPC、release layout、manifest 和 `status/status_code` 成为跨语言稳定契约。
- Go 侧新增控制接口必须经过白名单和 RPC schema 复核。
- 完整业务 API 和协作后台未来落地时，仍需遵守 Rust `bat` 对资源状态的所有权。

---

## 当前验证依据

- `infrastructure/src/bin/bat/`
- `infrastructure/src/official_update.rs`
- `internal/backendrpc/`
- `cmd/bat-api/`
- `docs/reference/rpc-backend-api.md`
- `internal/api/testdata/contract/`