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。FFI/Go 更高层调用边界将在 CLI/SDK 阶段继续扩展。

交付物：

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

验收标准：

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。

验收标准：

1. 可在无 Web 的情况下通过 CLI 同步指定版本资源。
2. 断点续传和失败重试有可重复测试。
3. Manifest 解析失败时给出可定位的字段和偏移信息。
4. 同一资源跨版本复用同一 CAS 对象。

---

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 负责用户命令、服务编排、网络和 Provider。
3. FFI 只暴露粗粒度、安全、可测试 API。

过早做 Web

处理策略：

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

---

8. 当前完成度评估

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

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

---

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