Files
BlueArchiveToolkit/docs/architecture/adr/0004-rust-bat-go-bat-api-resource-boundary.md
T
nyaKazuha 8fc93b8f39
bat-rust / Build and test Rust (push) Canceled after 0s
bat-rust / Build and test Go API (push) Canceled after 0s
docs: document Translation Memory and config contracts
2026-09-06 22:52:10 +08:00

2.5 KiB
Raw Blame History

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/batbat-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/