docs: 校正文档分类与当前边界

2026-09-18 11:56:23 +08:00 · 2026-09-04 19:58:07 +08:00
parent 34e2f0d907
commit d21c01a697
25 changed files with 727 additions and 985 deletions
@@ -4,7 +4,7 @@

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

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

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

@@ -25,9 +25,11 @@ BlueArchive Toolkit 采用 **Monorepo + 多语言混合** 架构，旨在构建

 已接受的架构决策：

- `adr/0001-engine-and-application-boundaries.md`：Rust 引擎与 Go 应用层边界。
+- `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`
+  的资源控制面边界。

 ---

@@ -41,16 +43,30 @@ BlueArchive Toolkit 采用 **Monorepo + 多语言混合** 架构，旨在构建

 ### 2. 语言选型

-| 模块 | 语言 | 理由 |
+| 模块 | 语言 | 当前定位 |
 |------|------|------|
-| CLI、API Server、服务编排 | Go | 并发模型优秀、部署简单、生态成熟 |
-| 官方资源同步核心、AssetBundle 解析、Patch 引擎、CAS 引擎 | Rust | 零成本抽象、内存安全、性能和二进制处理更可靠 |
-| Web 管理后台 | Vue 3 + TypeScript | 渐进式、类型安全、生态完善 |
+| 官方资源同步与运维 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. 数据流设计

+当前已落地的数据流：
+
 ```
-用户请求 → CLI/API → Go 业务层 → bat --json / SDK → Rust 核心/同步层 → CAS 存储 → 数据库
+官方 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)
 ```
@@ -99,7 +115,7 @@ cas/

 ---

-### 2. 官方资源同步器 (Rust 当前实现，Go 侧读取与编排)
+### 2. 官方资源同步器 (Rust 当前实现，Go 侧读取)

 **职责**：从官方日服 HTTP metadata 自动发现资源入口，下载 Windows + Android 官方资源，增量检查，完整性校验，保持本地状态。

@@ -133,20 +149,24 @@ current symlink → official-sync-snapshot.json + official-download-manifest.jso
 - 本地文件损坏时 repair。
 - 官方 seed `.hash` 强校验；Addressables `catalog_*.hash` 作为变更 marker。

-**后续 Go 职责**：
+**Go 当前职责**：

- 提供最小稳定 CLI。
- 默认通过 `bat --json` 进程边界包装 Rust 同步入口，并转发结构化 report。
- `bat-ffi` 仅作为可选无状态 C ABI 兼容层，不承载官方同步 daemon、下载器或 CAS handle。
- 编排 API Server、任务队列、Provider 和用户配置。
+- `bat-api` 通过 `bat.sock` RPC 读取 Rust 已发布 release、manifest、snapshot 和状态。
+- 提供资源 bootstrap、server-info 改写、只读 CDN path、readiness、OpenAPI 和白名单管理转发。
+- 不运行另一套同步器，不直接管理官方下载、staging、version-state、CAS 或解析状态。
+
+完整 API、服务编排、Provider 和用户配置属于目标扩展，不能从本节推断为当前已实现。

 ---

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

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

-**插件化架构**：
+以下插件注册和动态加载是目标扩展；当前实现以 `crates/bat-assetbundle`、
+`bat-adapters` 和真实 fixture 覆盖为准。
+
+**目标插件化架构**：
 ```rust
 pub trait AssetParser {
    fn name(&self) -> &str;
@@ -172,7 +192,11 @@ pub struct ParserRegistry {

 ---

-### 4. 翻译系统 (Go)
+### 4. 翻译系统 (目标设计，Go)
+
+当前已实现的是 Rust `bat` 的离线 TextUnit 队列、mock/Crowdin provider worker、
+lease/retry 和结果落库；Translation Memory、Glossary 和完整 Provider 体系仍属
+后续缺口。

 **架构**：
 ```
@@ -204,7 +228,7 @@ type TranslationProvider interface {

 ---

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

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

@@ -232,7 +256,10 @@ patch/

 ---

-### 6. API Server (Go)
+### 6. API Server (Go，目标设计)
+
+当前可用的 Go HTTP 服务是 `cmd/bat-api` 的资源 bootstrap、只读分发和 Rust 管理
+入口，不是下列完整游戏业务 API。

 **框架**：Gin 或 Echo

@@ -259,7 +286,9 @@ HTTP Request → Middleware (Auth, CORS, Logger) → Handler → Service → Rep

 ---

-### 7. Web 后台 (Vue 3)
+### 7. Web 后台 (Vue 3，目标设计)
+
+当前只有 `bat-api` 内嵌 dashboard MVP；登录、角色、术语管理和完整协作审核仍未实现。

 **技术栈**：
 - Vue 3 + Composition API
@@ -278,7 +307,10 @@ HTTP Request → Middleware (Auth, CORS, Logger) → Handler → Service → Rep

 ---

-## 数据库设计
+## 数据库设计（目标设计）
+
+当前 Rust 资源链路使用 SQLite 维护本地 CAS、ResourceRepository 和翻译任务状态；
+PostgreSQL/Redis 业务服务端方案尚未完整落地。

 ### PostgreSQL Schema

@@ -322,7 +354,11 @@ CREATE TABLE resource_versions (

 ---

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

 ### 本地开发模式

@@ -350,7 +386,7 @@ API Server (多实例)

 ---

-## 安全设计
+## 安全设计（目标设计）

 1. **认证**：JWT Token
 2. **授权**：RBAC (Role-Based Access Control)
@@ -361,7 +397,7 @@ API Server (多实例)

 ---

-## 性能优化
+## 性能优化（目标设计）

 1. **缓存策略**：
   - Redis 缓存热点数据
@@ -380,7 +416,7 @@ API Server (多实例)

 ---

-## 监控与日志
+## 监控与日志（目标设计）

 - **日志**：结构化日志（JSON 格式）
 - **指标**：Prometheus + Grafana
@@ -401,10 +437,6 @@ API Server (多实例)
 更多详细设计文档：

 - [官方资源后端说明](./official-resource-backend.md)
+- [资源 release 布局与分发契约](./resource-release-layout.md)
+- [AssetBundle 解析与发布路线图](./assetbundle.md)
 - [API 设计](../api/README.md)
-
-待创建的详细设计文档：
-
- `docs/architecture/cas.md`
- `docs/architecture/assetbundle.md`
- `docs/architecture/translation.md`