BlueArchiveToolkit/PROJECT_PLAN.md

# BlueArchiveToolkit 完整开发计划

- **项目名称**：BlueArchiveToolkit
- **文档版本**：2026-07-20 状态收口版
- **权威状态**：以本文档和 `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、进程边界和 REST/OpenAPI 接口，方便其他工具复用；FFI 仅保留为可选兼容层。
6. **插件系统**：允许新增解析器、翻译 Provider、存储后端、Patch 算法，而不修改核心代码。

---

## 2. 当前真实状态

本节来自 2026-07-20 的工作区盘点、本地验证和最新功能提交。

### 已具备

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-infrastructure` 已提供官方资源 pull/update 服务，正式入口是 Rust binary `bat`。
7. `bat` 支持 `--auto-discover`、`--watch`、`--daemon`、默认 1 小时间隔、本地 manifest audit/repair、官方 seed `.hash` 校验、snapshot/cache，以及基于 Unix socket JSON-RPC 的 `status/stop/restart/reload/refresh/logs/verify/repair/doctor/clean-stable` 运维命令。
8. `bat-ffi` 已提供 Manifest inspect 和官方 sync plan 的可选无状态粗粒度 JSON C ABI helper。
9. 文档已整理：根目录保留入口文档，历史报告进入 `docs/reports/historical/`，误嵌套的 `docs/docs` 已合并。

### 仍是骨架或占位

1. `bat-assetbundle` 仍是占位 crate；完整 UnityFS、压缩块、TypeTree 或对象表解析未完成。
2. `bat-patch` 的 Binary/JSON 模块仍返回明确的未实现错误，不具备真实补丁能力。
3. Go CLI/API/SDK 仍没有产品级入口；当前只有 `cmd/bat` 与 `internal/ffi` 的试验/兼容骨架。
4. Addressables parser 已覆盖当前真实形态 fixture/golden，但还不是完整 Unity Addressables/SBP catalog 兼容层。
5. 官方同步结果尚未作为用户级流程自动导入 CAS + ResourceRepository。
6. 真实官方网络全量下载 smoke 已固化为可重复脚本和 runbook（G-018 已关闭）；真实运行记录处于长期运行测试阶段，报告待后续提供。
7. Web、数据库迁移、OpenAPI、插件加载机制尚未实现。
8. 原 Git 历史未恢复；当前仓库以新初始化基线为准。

### 已验证

1. `cargo test --workspace --quiet` 通过。
2. `cargo clippy --workspace --all-targets -- -D warnings` 通过。
3. `go test ./...` 通过，但目前没有 Go 产品级测试覆盖。
4. `go vet ./...` 通过。
5. `go build -o /tmp/bat-go-cli ./cmd/bat` 通过。
6. `target/debug/bat --help` 可用。

---

## 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、完整资源拉取和更新检查核心逻辑；`bat --json` 进程边界是当前主集成路径，FFI 仅作为可选兼容层。
2. **Go**：用于最小稳定 CLI、服务编排、API Server、任务编排、Provider 集成；不强制要求 Rust 核心能力必须写成库供 Go 调用。
3. **PostgreSQL**：作为服务端主数据库，承载翻译记忆库、术语库、任务、审核和用户权限。
4. **SQLite**：仅作为本地 CLI 可选元数据后端，必须通过仓储抽象隔离，不能绑定业务逻辑。
5. **Redis**：用于服务端缓存、任务状态、限流和短期锁。
6. **Vue 3 + TypeScript**：用于 Web 管理后台。

### 3.3 质量门槛

每个生产模块必须满足：

1. 无占位返回、无静默吞错、无未说明的 `TODO`。
2. 公共接口具备文档、错误语义和兼容性说明。
3. 单元测试覆盖核心分支；跨模块能力补集成测试。
4. `cargo fmt`、`cargo clippy --workspace --all-targets -- -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 产品入口尚未完成，当前仅存在 `cmd/bat` 的试验骨架；Rust 继续承载完整资源拉取与更新检查核心逻辑；`bat-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 资源清单。

**当前状态**：部分完成。Rust 官方日服资源同步链路已经具备正式 one-shot 和 `--watch` 常驻入口；Go 产品入口、完整解析覆盖、CAS 导入编排和真实线上 smoke 仍待完成。

交付物：

1. Addressables Catalog 真实字段解析：**部分完成**。当前已覆盖 path、hash、size、address、dependencies、metadata 和真实形态 fixture/golden；仍需继续覆盖更多官方 catalog 结构变体。
2. 资源版本、区域、渠道、远端 URL、Hash、大小、依赖关系模型：**部分完成**。`Resource` 和官方 endpoint/snapshot 模型已扩展；仍需冻结 Go CLI/API 可见模型。
3. Rust 官方下载器：**已完成当前生产入口需要的核心能力**。包含官方 URL 校验、`.part` 续传、重试、本地 manifest size+BLAKE3 校验、官方 seed `.hash` 校验和 repair。
4. Rust 自动更新入口：**已完成当前生产入口**。`bat` 支持 snapshot、marker diff、bootstrap cache、one-shot、`--watch`、`--daemon`、默认 1 小时间隔、北京时间固定强制刷新，以及 Unix socket JSON-RPC 后台运维命令返回。
5. Go 产品入口：**未完成**。当前 `cmd/bat` 仅有 `doctor`、`manifest inspect`、`sync plan` 试验能力，尚不构成产品级 CLI；若要继续由 Go 承担用户入口，需要单独收敛命令集和调用边界。
6. 用户级 `sync`、`manifest inspect`、`cache status`：**未完成**。Rust `bat --json` 是当前稳定进程边界；`bat-ffi` 只提供可选兼容用的 Manifest inspect 和 sync plan JSON helper。
7. 下载结果写入 CAS + ResourceRepository：**部分完成**。CAS 和 SQLite ResourceRepository 已存在，官方同步入口尚未把完整下载结果自动作为用户级流程导入。
8. Linux 生产同步不依赖已安装官方启动器：**已完成当前 Rust 入口**。`--auto-discover` 只使用官方 HTTP metadata 和临时目录解析 `GameMainConfig`。
9. 真实官方网络全量下载 smoke test：**命令已固化（G-018 已关闭）**。`scripts/official-full-pull-smoke.sh` / `make official-smoke` 已固化 dry-run、首次下载、二次 up-to-date 和本地损坏 repair 的可重复流程；真实运行处于长期运行测试阶段，报告待后续提供。

验收标准：

1. 可在无 Web 的情况下通过 CLI 同步指定版本资源。
2. 断点续传和失败重试有可重复测试。
3. Manifest 解析失败时给出可定位的字段和偏移信息。
4. 同一资源跨版本复用同一 CAS 对象。
5. 生产同步入口必须显式选择 `--auto-discover` 或显式提供官方 `server-info` URL、`connection-group` 和 `app-version`，不得安装或启动 launcher。
6. 自动更新入口必须做到无变化不下载，有变化下载成功后才写入新 snapshot。
7. `--watch` 模式必须在 Rust 内部保持持久检查能力，外部 supervisor 只负责进程守护。
8. 真实官方网络 smoke 必须记录输出目录、命令、结果摘要和未纳入仓库的大文件位置。

---

### 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. 发布验证：format、lint、test、build、security audit、release artifact 由本地可重复命令、自托管 Gitea linux-runner workflow 与脚本承担（决策：不引入 GitHub Workflows 等托管 CI，见 `docs/reports/CURRENT_GAPS.md` G-017）。
2. Docker Compose：本地开发、服务端部署。
3. 数据备份与恢复文档。
4. 用户文档、开发文档、故障排查文档。
5. 版本策略、迁移策略、兼容性策略。
6. Alpha 发布包。

验收标准：

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

---

## 5. 推荐执行顺序

近期不要直接跳到 Web 或 AI Provider。项目当前的真实瓶颈是 Go 产品入口边界、资源解析、同步结果进入 CAS/ResourceRepository，以及真实端到端验证。

建议顺序：

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

---

## 6. 近期具体任务

优先完善 Rust `bat` 后端，并同步收敛 Go 产品入口边界。当前事实是 Rust `bat` 已承担可用的资源同步/运维入口，Go `cmd/bat` 仍只是试验骨架，`bat-api` 是独立的 Go HTTP 服务目标（issue #19 / G-009）：

1. 对 issue #17 做验收并关闭或更新范围：多线程下载与指数退避实现已合入，但 GitHub issue 仍 open。
2. 继续逆向 Addressables catalog，扩大 bundle hash/size/CRC 等可校验字段覆盖（issue #2）。
3. 对 AssetBundle/UnityFS 做引擎级解析：header/block/directory/metadata/object table（issue #3 / G-005）。
4. 将官方同步下载结果接入 CAS + `SqliteResourceRepository` 的用户级流程（G-011）。
5. 收敛 Go 产品入口：明确继续推进最小 Go CLI，或把用户 CLI 固化为 Rust `bat` 并把 Go 侧集中到 `bat-api`。
6. 实现 `bat-api`（仿官方 API 的 Go HTTP 服务，含鉴权/签名验签，issue #19 / G-009）。
7. 为 CAS 增加 `doctor cas` 诊断入口。

---

## 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、watch 和 daemon。
2. Go 的长期职责包括用户命令、最小稳定 CLI、服务编排、网络和 Provider；当前 Go 产品入口尚未完成，不能把 `cmd/bat` 试验骨架视为完成。
3. 跨边界优先进程或 SDK，FFI 只作为可选的粗粒度、无状态、安全、可测试兼容 API。
4. Rust 不需要被强制写成 Go 调用库；当前 `bat --watch` / `bat --daemon` 是允许长期运行的 Rust 生产任务。

### 官方资源真实下载风险

处理策略：

1. 所有真实下载必须写入隔离输出目录。
2. 不允许把 `/home/wanye/D/BlueArchive` 或已安装客户端目录当作开发输出目录。
3. smoke test 只记录命令、状态和摘要，不把大体积官方资源纳入 Git。
4. 下载成功后必须通过 `official-download-manifest.json` audit 和官方 seed `.hash` 校验报告确认。

### 过早做 Web

处理策略：

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

---

## 8. 当前完成度评估

按最终目标计算，当前总体完成度不再固定写单一百分比，以模块状态和 issue 收敛情况为准。

已完成的是稳定基线、架构骨架、部分接口、CAS V1 和 Rust 官方资源同步闭环，不是完整产品能力。下一阶段的关键不是继续堆目录，而是把 Go 产品入口边界、官方同步端到端验证、CAS/ResourceRepository 编排和 AssetBundle 解析链路做实。

---

- **下一份应更新文档**：真实官方网络 smoke 记录
- **下一项工程任务**：收敛 Go 产品入口边界、执行官方同步端到端 smoke，并推进 CAS/ResourceRepository 与 AssetBundle 解析。