BlueArchiveToolkit/PROJECT_PLAN.md

# BlueArchiveToolkit 完整开发计划

**项目名称**：BlueArchiveToolkit  
**文档版本**：2026-06-28 重制版  
**权威状态**：以本文档和 `CURRENT_STATUS.md` 为准，旧阶段报告仅作历史参考。  
**最终目标**：构建一个可长期维护、可扩展、可审计的 Blue Archive 资源管理、文本提取、翻译和补丁平台。

---

## 1. 产品边界

BlueArchiveToolkit 不是一次性脚本，也不是演示项目。最终交付形态包含：

1. **CLI 工具**：面向本地用户和自动化任务，覆盖 `doctor`、`sync`、`manifest`、`bundle`、`extract`、`translate`、`patch`、`verify`、`cache`、`serve` 等命令。
2. **Rust 核心引擎**：负责 CAS、AssetBundle 解析、Patch、二进制安全处理和性能敏感逻辑。
3. **Go 服务层**：负责 CLI 编排、资源同步、下载器、API Server、任务调度和外部集成。
4. **Web 管理后台**：负责翻译审核、术语管理、全文搜索、历史版本、Diff 和 Dashboard。
5. **SDK/API**：提供稳定的 Go SDK、进程边界或必要时的 FFI 边界和 REST/OpenAPI 接口，方便其他工具复用。
6. **插件系统**：允许新增解析器、翻译 Provider、存储后端、Patch 算法，而不修改核心代码。

---

## 2. 当前真实状态

本节来自 2026-06-28 的工作区盘点和本地验证。

### 已具备

1. Rust workspace 已存在，包含 `core`、`adapters`、`infrastructure`、`crates/bat-cas-engine`、`crates/bat-assetbundle`、`crates/bat-patch`、`crates/bat-ffi`。
2. `bat-core` 已定义领域对象和仓储接口。
3. `bat-adapters` 已实现 Unity、Manifest、Client 集成的框架和注册表。
4. `bat-cas-engine` 已完成 CAS V1：原子写入、BLAKE3 Hash、SQLite 引用计数、GC、并发测试、损坏检测。
5. `bat-infrastructure` 已改为 CAS 仓储适配层，不再重复实现对象存储。
6. `bat-ffi` 已能引用 CAS、AssetBundle、Patch crates。
7. 文档已整理：根目录保留入口文档，历史报告进入 `docs/reports/historical/`，误嵌套的 `docs/docs` 已合并。

### 仍是骨架或占位

1. AssetBundle 解析器仍是占位 trait，未解析 UnityFS、压缩块、TypeTree 或对象表。
2. Patch 的 Binary/JSON 模块仍返回空结果，不具备真实补丁能力。
3. Go CLI/API/SDK 目录目前没有实际 package。
4. Manifest 真实复杂字段解析尚未完成。
5. Web、数据库迁移、OpenAPI、插件加载机制尚未实现。
6. 原 Git 历史未恢复；当前仓库以新初始化基线为准。

### 已验证

1. `cargo test --workspace` 通过。
2. `go test ./...` 当前无 Go package；`Makefile` 已调整为在 Go 未实现阶段明确跳过。

---

## 3. 架构原则

### 3.1 分层边界

1. **Domain/Core**：只表达业务模型、领域服务、仓储接口和稳定错误类型，不依赖数据库、文件系统、网络或 UI。
2. **Engine**：Rust 实现性能敏感和安全敏感能力，包括 CAS、AssetBundle、Patch、二进制格式校验。
3. **Infrastructure**：实现数据库、文件系统、缓存、对象存储、HTTP 客户端、任务队列。
4. **Application**：编排用例，例如同步资源、提取文本、生成补丁、审核翻译。
5. **Interface**：CLI、REST API、Web UI、SDK、FFI。

### 3.2 技术决策

1. **Rust**：保留为核心引擎语言，用于 CAS、AssetBundle、Patch、完整资源拉取和更新检查核心逻辑，FFI 仅作为可选边界。
2. **Go**：用于 CLI、同步器、API Server、任务编排、Provider 集成。
3. **PostgreSQL**：作为服务端主数据库，承载翻译记忆库、术语库、任务、审核和用户权限。
4. **SQLite**：仅作为本地 CLI 可选元数据后端，必须通过仓储抽象隔离，不能绑定业务逻辑。
5. **Redis**：用于服务端缓存、任务状态、限流和短期锁。
6. **Vue 3 + TypeScript**：用于 Web 管理后台。

### 3.3 质量门槛

每个生产模块必须满足：

1. 无占位返回、无静默吞错、无未说明的 `TODO`。
2. 公共接口具备文档、错误语义和兼容性说明。
3. 单元测试覆盖核心分支；跨模块能力补集成测试。
4. `cargo fmt`、`cargo clippy --workspace -- -D warnings`、`cargo test --workspace` 通过。
5. Go 模块落地后，`go test ./...`、`go vet ./...` 通过。
6. 用户可见命令必须有 `doctor` 检查和失败恢复建议。

---

## 4. 总体里程碑

### Milestone 0：工作区基线修复

**目标**：让项目状态可信、入口清晰、验证命令不会误报。

交付物：

1. 整理根目录报告和历史文档。
2. 建立 `PROJECT_PLAN.md`、`CURRENT_STATUS.md`、`DOCS_INDEX.md` 三个权威入口。
3. 显式列出 Rust workspace 成员。
4. 修复 Makefile 在 Go 空目录阶段的行为。
5. 恢复或重新初始化 Git 元数据。
6. 建立 ADR 和稳定基线指南。

验收标准：

1. 根目录不再堆放阶段报告。
2. `cargo test --workspace` 通过。
3. `make test` 在 Go 尚未实现时能清晰跳过 Go 测试。
4. `git status` 可用。
5. 架构边界和 CAS V1 边界有文档记录。

当前状态：已完成。

---

### Milestone 1：核心模型和接口冻结

**目标**：冻结第一版稳定领域模型，为后续实现提供不反复摇摆的边界。

交付物：

1. 审查 `bat-core` 中的 `GameClient`、`GameVersion`、`Resource`、`Translation`。
2. 完成领域服务模块，不再保留空占位。
3. 固化仓储接口：CAS、Resource、Translation、Glossary、Provider、Patch、Manifest。
4. 统一错误模型和错误码映射策略。
5. 编写架构决策记录：Rust/Go 边界、SQLite/PostgreSQL 边界、插件边界。

验收标准：

1. 公共接口能支撑后续阶段，不暴露具体数据库和文件系统。
2. 领域层不依赖 `tokio::fs`、SQL、HTTP、UI。
3. 所有领域对象有序列化、校验和测试。

---

### Milestone 2：生产级 CAS 与本地元数据

**目标**：完成可长期使用的 Content Addressable Storage。

**当前状态**：已完成 CAS V1。Go CLI 以最小稳定入口优先，Rust 继续承载完整资源拉取与更新检查核心逻辑；FFI 边界保持可选。

交付物：

1. 合并 `infrastructure` CAS 与 `bat-cas-engine` 的重复职责。
2. 实现对象写入的临时文件、fsync、原子 rename 和并发安全。
3. 实现引用计数、对象元数据、完整性校验、GC、统计信息。
4. 实现本地元数据后端：优先 SQLite，但必须隔离在 repository adapter 中。
5. 编写迁移、恢复、损坏检测和 `doctor cas`。
6. 提供稳定的 Go 调用边界，优先进程或 SDK，必要时再补 FFI。

验收标准：

1. 重复写入相同内容只保存一个对象。
2. 对象损坏能被检测并返回明确错误。
3. GC 删除引用计数为 0 的对象。
4. 并发写入和并发读取测试通过。
5. CAS 测试覆盖正常路径、损坏路径、权限路径和并发路径。

---

### Milestone 3：Manifest 与资源同步

**目标**：能够获取、解析和同步 Blue Archive 资源清单。

交付物：

1. 完成 Addressables Catalog 的真实字段解析。
2. 定义资源版本、区域、渠道、远端 URL、Hash、大小、依赖关系模型。
3. 实现 Go 下载器：并发、断点续传、限速、重试、校验、缓存。
4. 实现 `sync`、`manifest inspect`、`cache status`。
5. 将下载结果写入 CAS，并写入 Resource Repository。
6. Linux 生产同步支持显式 `--auto-discover` 或已审计 metadata snapshot，不依赖已安装官方启动器。
7. 实现自动更新检查：保存上次官方 snapshot，定期 discovery，对比变化后按需拉取。

验收标准：

1. 可在无 Web 的情况下通过 CLI 同步指定版本资源。
2. 断点续传和失败重试有可重复测试。
3. Manifest 解析失败时给出可定位的字段和偏移信息。
4. 同一资源跨版本复用同一 CAS 对象。
5. 生产同步入口必须显式选择 `--auto-discover` 或显式提供官方 `server-info` URL、`connection-group` 和 `app-version`，不得隐式启动 launcher/bootstrap 链路。
6. 自动更新入口必须做到无变化不下载，有变化下载成功后才写入新 snapshot。

---

### Milestone 4：Unity AssetBundle 解析

**目标**：建立可扩展 AssetBundle 解析框架，并首先支持文本相关资源。

交付物：

1. 解析 UnityFS header、blocks、directory、metadata、objects。
2. 支持 LZ4/LZMA 解压，记录压缩块校验。
3. 实现 TypeTree/ObjectInfo 读取。
4. 实现 TextAsset、MonoBehaviour、ScriptableObject 的可扩展解析入口。
5. 增加解析器注册表和版本适配器。
6. 编写 `bundle inspect`、`bundle extract`。

验收标准：

1. 能解析真实样本或明确结构化测试样本。
2. 错误报告包含 bundle 名称、偏移、字段和 Unity 版本。
3. 解析器和业务流程解耦。
4. 不支持的 Unity 版本返回明确错误，不做隐式猜测。

---

### Milestone 5：文本提取与标准导出

**目标**：从资源中提取可翻译文本，并形成稳定中间格式。

交付物：

1. 定义 `TextUnit`、上下文、来源路径、资源 ID、语言、版本。
2. 实现剧情、UI、系统文本、配置文本的分类规则。
3. 支持 JSONL、CSV、XLIFF 或项目自定义标准格式导出。
4. 实现重复文本合并和上下文保留。
5. 编写 `extract text`、`extract stats`。

验收标准：

1. 提取过程不修改原始资源。
2. 同一文本在不同上下文中可区分。
3. 导出格式可往返导入，不丢失资源定位信息。
4. 大资源批量提取有性能基准。

---

### Milestone 6：Translation Memory 与 Glossary

**目标**：建立翻译资产的核心数据库。

交付物：

1. PostgreSQL schema：source_text、translation、translation_memory、glossary、review、history。
2. 实现精确匹配、模糊匹配、上下文匹配。
3. 实现术语优先级、别名、分类、冲突检测和审核状态。
4. 实现导入导出和版本历史。
5. 实现 `translate memory`、`glossary` CLI 子命令。

验收标准：

1. 术语优先级高于 AI Provider。
2. 翻译记录保留 Provider、模型、时间、审核人和历史。
3. 模糊匹配阈值可配置且有测试。
4. 数据库迁移可重复执行。

---

### Milestone 7：AI 翻译工作流

**目标**：实现可审计、可替换、可控成本的 AI 翻译流程。

交付物：

1. Provider 抽象：DeepL、OpenAI、Anthropic、Google、Azure、自定义 Provider。
2. 批处理、速率限制、重试、熔断、成本统计。
3. Prompt 模板、术语注入、上下文注入。
4. 自动质量检查：术语一致性、空翻译、占位符保留、长度异常。
5. 人工审核队列和状态流转。

验收标准：

1. Provider 可替换，不影响上层业务。
2. 失败任务可重试且不会重复扣账或覆盖人工审核结果。
3. 每条 AI 翻译可追溯到 Provider、模型和请求配置。
4. 质量检查失败的翻译不会直接进入可发布状态。

---

### Milestone 8：Patch 与客户端集成

**目标**：生成、应用、验证和回滚翻译补丁。

交付物：

1. 实现 Binary Patch、JSON Patch、Text Patch。
2. 定义 Patch manifest：目标版本、文件列表、Hash、签名、回滚信息。
3. 实现客户端发现、路径校验、备份、应用、回滚。
4. 实现 `patch build`、`patch apply`、`patch rollback`、`verify`。
5. 实现 dry-run 和安全检查。

验收标准：

1. 应用补丁前后都能校验完整性。
2. 任一步失败都能回滚到补丁前状态。
3. 不直接覆盖未经备份的客户端文件。
4. Patch 生成与应用有端到端测试。

---

### Milestone 9：CLI、SDK 与 API Server

**目标**：提供稳定可用的操作入口和集成入口。

交付物：

1. Go CLI 主入口和命令体系。
2. 配置系统：项目级、用户级、环境变量、密钥管理。
3. Go SDK：Manifest、Sync、CAS、Extract、Translate、Patch。
4. REST API Server：认证、权限、统一错误码、OpenAPI。
5. 后台任务系统：同步、提取、翻译、补丁构建。

验收标准：

1. CLI 命令风格统一，支持 JSON 输出和人类可读输出。
2. `doctor` 能检查依赖、目录权限、数据库连接、资源路径。
3. OpenAPI 与实际 Handler 同步。
4. SDK 不依赖 CLI，不把命令行行为泄漏到库接口。

---

### Milestone 10：Web 管理后台

**目标**：为翻译协作和资源管理提供可用后台。

交付物：

1. 登录、权限、用户角色。
2. Dashboard：同步状态、翻译进度、质量问题、队列状态。
3. 翻译审核：列表、详情、Diff、批量操作。
4. 术语管理：搜索、冲突提示、审核。
5. 资源浏览：版本、资源、Bundle、文本定位。
6. 历史版本和回滚入口。

验收标准：

1. 常用审核流程不需要通过数据库手工操作。
2. 页面状态和 API 错误能被用户理解。
3. 权限隔离覆盖关键写操作。
4. Web 构建、类型检查、基础 E2E 通过。

---

### Milestone 11：发布工程与 Alpha

**目标**：达到可分发、可升级、可诊断的 Alpha 版本。

交付物：

1. CI：format、lint、test、build、security audit、release artifact。
2. Docker Compose：本地开发、服务端部署。
3. 数据备份与恢复文档。
4. 用户文档、开发文档、故障排查文档。
5. 版本策略、迁移策略、兼容性策略。
6. Alpha 发布包。

验收标准：

1. 新环境能按文档完成安装、同步、提取、翻译、补丁流程。
2. 升级不会破坏已有数据。
3. 关键路径有端到端测试。
4. 发布物包含版本号、校验和、变更说明。

---

## 5. 推荐执行顺序

近期不要直接跳到 Web 或 AI Provider。项目当前的真实瓶颈是基础存储和解析能力。

建议顺序：

1. 完成 Milestone 3 和 4，让资源能被同步和解析。
2. 完成 Milestone 5，再开始翻译系统。
3. 完成 Milestone 6 和 7，建立可审计翻译流程。
4. 完成 Milestone 8，形成可交付补丁。
5. 最后补齐 CLI/API/Web/发布工程。

---

## 6. 近期 10 个具体任务

1. 完成 Manifest 真实解析字段和资源模型映射。
2. 落地 Go CLI 的最小生产入口：`bat doctor`、`bat sync --help`。
3. 设计 Resource Repository 的持久化 schema 和迁移策略。
4. 开始 AssetBundle UnityFS header/block/directory 解析。
5. 为 CLI 和 CAS 增加 `doctor cas` 诊断入口。
6. 更新开发指南，使安装、测试、当前限制一致。

---

## 7. 风险与处理策略

### SQLite 权限问题

旧 Week 3 报告提到 SQLite 文件权限导致测试失败。处理策略：

1. 本地元数据后端必须使用临时目录和明确权限测试。
2. SQLite 只作为 adapter，不进入领域层。
3. 服务端主库使用 PostgreSQL。
4. 任何数据库测试都必须覆盖路径不存在、只读目录、并发连接和迁移失败。

### Blue Archive 资源格式变化

处理策略：

1. Manifest 和 AssetBundle 解析器版本化。
2. 新格式通过 adapter/plugin 增量接入。
3. 样本测试必须记录来源版本和 Unity 版本。

### Rust/Go 边界膨胀

处理策略：

1. Rust 提供稳定引擎能力，不承担 CLI 编排，但负责完整资源拉取和更新检查的核心逻辑。
2. Go 负责用户命令、最小稳定 CLI、服务编排、网络和 Provider。
3. 跨边界优先进程或 SDK，FFI 只作为可选的粗粒度、安全、可测试 API。

### 过早做 Web

处理策略：

1. Web 依赖可用 API 和数据库，不应早于核心同步、提取、翻译模型。
2. 先完成 CLI 和 API，再构建 Web。

---

## 8. 当前完成度评估

按最终目标计算，当前总体完成度约为 **18%**。

已完成的是稳定基线、架构骨架、部分接口和 CAS V1，不是完整产品能力。下一阶段的关键不是继续堆目录，而是把 Manifest、CLI 基础入口和 AssetBundle 解析链路做实。

---

**下一份应更新文档**：`CURRENT_STATUS.md`  
**下一项工程任务**：完成 Manifest 真实解析和 Go CLI 基础入口。