mirror of
https://github.com/Yuyi-Oak/BlueArchiveToolkit.git
synced 2026-07-22 01:15:14 +08:00
chore: establish development baseline
This commit is contained in:
+422
@@ -0,0 +1,422 @@
|
||||
# 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` 已有最小文件系统存储、BLAKE3 Hash、基础测试。
|
||||
5. `bat-ffi` 已能引用 CAS、AssetBundle、Patch crates。
|
||||
6. 文档已整理：根目录保留入口文档，历史报告进入 `docs/reports/historical/`，误嵌套的 `docs/docs` 已合并。
|
||||
|
||||
### 仍是骨架或占位
|
||||
|
||||
1. CAS 引用计数、GC、并发写入安全、对象校验任务、事务化元数据尚未完成。
|
||||
2. `infrastructure/src/cas/filesystem.rs` 与 `crates/bat-cas-engine` 存在职责重叠，需要合并边界。
|
||||
3. AssetBundle 解析器仍是占位 trait，未解析 UnityFS、压缩块、TypeTree 或对象表。
|
||||
4. Patch 的 Binary/JSON 模块仍返回空结果，不具备真实补丁能力。
|
||||
5. Go CLI/API/SDK 目录目前没有实际 package。
|
||||
6. Web、数据库迁移、OpenAPI、插件加载机制尚未实现。
|
||||
7. `.git/` 当前是空目录，无法读取分支和变更状态；后续需要恢复真实 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。
|
||||
|
||||
交付物：
|
||||
|
||||
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 0 的 Git 恢复。
|
||||
2. 完成 Milestone 1，冻结领域模型和接口。
|
||||
3. 完成 Milestone 2，建立可靠 CAS。
|
||||
4. 完成 Milestone 3 和 4，让资源能被同步和解析。
|
||||
5. 完成 Milestone 5，再开始翻译系统。
|
||||
6. 完成 Milestone 6 和 7，建立可审计翻译流程。
|
||||
7. 完成 Milestone 8，形成可交付补丁。
|
||||
8. 最后补齐 CLI/API/Web/发布工程。
|
||||
|
||||
---
|
||||
|
||||
## 6. 近期 10 个具体任务
|
||||
|
||||
1. 设计并冻结 CAS trait、对象元数据、引用计数模型。
|
||||
2. 删除或合并重复 CAS 实现，只保留一个 Rust 引擎和一个仓储适配层。
|
||||
3. 实现 CAS 原子写入、Hash 校验、引用计数和 GC。
|
||||
4. 为 CAS 增加并发、损坏、权限、迁移测试。
|
||||
5. 设计 Resource Repository 的持久化 schema 和迁移策略。
|
||||
6. 完成 Manifest 真实解析字段和资源模型映射。
|
||||
7. 落地 Go CLI 的最小生产入口：`bat doctor`、`bat sync --help`。
|
||||
8. 更新 README 和开发指南，使安装、测试、当前限制一致。
|
||||
|
||||
---
|
||||
|
||||
## 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. 当前完成度评估
|
||||
|
||||
按最终目标计算，当前总体完成度约为 **15%**。
|
||||
|
||||
已完成的是架构骨架和部分接口，不是完整产品能力。下一阶段的关键不是继续堆目录，而是把 CAS、Manifest、AssetBundle 这三条基础链路做实。
|
||||
|
||||
---
|
||||
|
||||
**下一份应更新文档**：`CURRENT_STATUS.md`
|
||||
**下一项工程任务**：恢复 Git 元数据并完成 CAS 设计冻结。
|
||||
Reference in New Issue
Block a user