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 服务层**：负责资源分发 API、服务编排、任务调度和外部集成；官方资源同步/运维命令行当前由 Rust `bat` 承担，Go 通过 RPC 调用。
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 的 live control/backend 方法（`daemon.status/logs/stop/restart/reload/refresh/doctor`、`resource.sync/verify/repair/state/manifest/list/index`、`parse.status/text_units/errors`、`localized.status`、`catalog.*`、`task.*`）；`daemon.restart` 通过 Rust lifecycle controller 复用 CLI restart 路径，`clean-stable` 仍由 CLI 侧按进程生命周期显式执行。
8. `bat-ffi` 已提供 Manifest inspect 和官方 sync plan 的可选无状态粗粒度 JSON C ABI helper。
9. 官方原版资源默认发布到 `./bat-resources`，汉化产物默认发布到独立的 `./bat-localized`；当前官方同步报告会标记 `localized_release_status=not_localized`，表示原版资源已发布、汉化资源未发布。
10. 官方同步校验完成并发布新 release 后会生成 `official-resource-changes.json`、`crowdin-translation-handoff.json`、`official-parse-cache.json`、`official-textunit-index.json`、`official-textunit-tasks.json` 和 `crowdin-textunit-queue.json`，用 Added/Modified 资源驱动后续解析/翻译增量；up-to-date 轮询在已有有效缓存、TextUnit 明细索引和队列时只读取摘要，不重复解析。
11. 文档已整理：根目录保留入口文档，历史报告进入 `docs/reports/historical/`，误嵌套的 `docs/docs` 已合并。

### 仍是骨架或占位

1. `bat-assetbundle` 已具备 UnityFS 解包和 TextAsset 提取基础能力（header/block info/directory、LZ4/LZMA block info 与数据 block、directory 文件提取、serialized file object table、TypeTree node 元数据、TextAsset bytes、TypeTree-covered managed reference payload TextUnit 上下文），并已有 UnityFS TextAsset patch 前置能力；MonoBehaviour/ScriptableObject 复杂字段级解析、重打包和通用 Patch 仍未完成。
2. `bat-patch` 已具备确定性 Binary hunk diff/apply、RFC 6902 JSON Patch apply、UTF-8 Text Patch、通用 Patch manifest、BLAKE3/size 完整性校验和 rollback 元数据；文件级 `patch.apply` RPC / `patch-apply` CLI 与 UnityFS TextAsset / TypeTree string / TypeTree 语义字段写入入口已开放，当前发布级可用的是 `bat-assetbundle` + `LocalizedPatchService` 的 UnityFS TextAsset patch 前置链路。
3. Go 侧边界已冻结（见 `docs/reports/GO_STATUS.md`）：同步/运维命令行 = Rust `bat`；资源分发 = `cmd/bat-api` MVP；`internal/backendrpc` 完成；`cmd/bat` 仅为试验（`bin/bat-go`）。完整游戏业务 API / Web / SDK 仍未完成。
4. Addressables parser 已覆盖当前真实形态 fixture/golden，但还不是完整 Unity Addressables/SBP catalog 兼容层。
5. 官方同步结果可配置为发布后自动导入 CAS + ResourceRepository，并通过 `resource.index` RPC/CLI 查询；Resource metadata 已保存 release、平台、bundle path、parse status、TextAsset 名称和 TextUnit 摘要，资源级查询已覆盖 release、平台、destination、archive entry、parse status 和 TextUnit format；单条 TextUnit 明细和解析错误已持久化到 `official-textunit-index.json`，可通过 `parse.text_units` / `parse.errors` 查询；离线 TextUnit 翻译任务状态和跳过/失败原因可通过 `translation.tasks` 查询，真实 worker 状态写回仍需继续推进。
6. 汉化 Patch 发布前置已具备 UnityFS TextAsset manifest/apply/diff/rollback/完整性校验和 `localized.status` 严格校验；真实 Crowdin worker、翻译记忆到完整汉化文件集合的构建仍未完成。
7. 真实官方网络全量下载 smoke 已固化为可重复脚本和 runbook（G-018 已关闭）；真实运行记录处于长期运行测试阶段，报告待后续提供。
8. Web、数据库迁移、OpenAPI、插件加载机制尚未实现。
9. 原 Git 历史未恢复；当前仓库以新初始化基线为准。

### 已验证

1. `cargo test --workspace --quiet` 通过。
2. `cargo clippy --workspace --all-targets -- -D warnings` 通过。
3. `make test-go-api` / `make build-go-api` 覆盖 `internal/api` 与 `internal/backendrpc`。
4. `go vet` 覆盖 bat-api 相关包。
5. `target/debug/bat --help`（Rust）可用。

---

## 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。Rust 承载完整资源拉取与更新检查；Go 以 `bat-api` 资源分发 MVP + `backendrpc` 为服务入口（`GO_STATUS.md`）；`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，以及默认 8、范围 `1..=256` 的有界并发 scheduler；worker 动态领取任务，进度按完成数单调上报，report 保持 plan 顺序。
4. Rust 自动更新入口：**已完成当前生产入口**。`bat` 支持 snapshot、marker diff、bootstrap cache、one-shot、`--watch`、`--daemon`、默认 1 小时间隔、北京时间固定强制刷新，以及 Unix socket JSON-RPC 后台运维命令返回。
5. Go 入口边界：**已冻结**。同步命令行 = Rust `bat`（G-008 关闭）；资源分发 = `bat-api` MVP（G-009 部分完成）。详见 `docs/reports/GO_STATUS.md`。
6. 用户级 `sync`、`manifest inspect`、`cache status`：**未完成**。Rust `bat --json` 是当前稳定进程边界；`bat-ffi` 只提供可选兼容用的 Manifest inspect 和 sync plan JSON helper。
7. 下载结果写入 CAS + ResourceRepository：**部分完成**。CAS 和 SQLite ResourceRepository 已存在，官方同步入口可用 `--import-repository` / `BAT_IMPORT_REPOSITORY=1` 在已校验 release 发布后导入；`resource.index` 可按资源级 release、平台、destination、archive entry、parse status 和 TextUnit format 查询现有索引和资源 metadata；`parse.text_units` / `parse.errors` 可查询当前 release 的 TextUnit 明细与解析错误；`translation.tasks` 可查询离线 TextUnit 翻译任务状态和跳过/失败原因。剩余工作是真实 worker 状态写回、CAS 诊断入口和面向大索引的查询优化。
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 的可重复流程；真实运行处于长期运行测试阶段，报告待后续提供。
10. 官方发布后的增量 handoff 与解析缓存：**已完成基础入口**。新 release 发布后先生成 `official-resource-changes.json` 和 `crowdin-translation-handoff.json`，新增+变更资源进入解析/翻译候选；`official-parse-cache.json` 基于下载 manifest 覆盖直接 UnityFS bundle、zip 内 UnityFS 条目和非候选资源记录；随后生成 `official-textunit-index.json`、`official-textunit-tasks.json` 与 `crowdin-textunit-queue.json`，本地文件未变化且缓存/索引有效时跳过重复解析。
11. 汉化发布状态：**已完成前置闭环**。官方同步默认报告 `not_localized`，表示只发布原版资源；UnityFS TextAsset patch 发布成功并通过 `localized-patch-manifest.json`、current symlink 和 release ID 校验后才切换为 `localized`。

验收标准：

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 必须记录输出目录、命令、结果摘要和未纳入仓库的大文件位置。
9. 官方原版资源目录和汉化产物目录必须物理分离，不能相同或互相嵌套。
10. 官方同步完成后必须能区分 `not_localized` 和 `localized`，不能把原版资源发布状态与汉化产物发布状态混为一谈。
11. 新 release 发布后必须能产出可审计的资源变更集，新增+变更资源进入解析/翻译 handoff，Crowdin 调用由后续翻译 worker 消费本地 handoff 决定。

---

### Milestone 4：Unity AssetBundle 解析

维护冻结细则见 [`docs/reports/PARSER_FREEZE.md`](docs/reports/PARSER_FREEZE.md)；冻结期只接受稳定性、诊断、真实回归和文档一致性修复。

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

交付物：

1. **解析缓存闭环**：官方同步发布后生成 `official-parse-cache.json`，覆盖 manifest 全部条目、直接 bundle、zip 内 bundle、非候选资源和解析失败诊断；未变化文件按 URL、相对路径、size 和 BLAKE3 复用解析结果。
2. **Addressables 完整化**：覆盖 Windows/Android JSON、compact JSON 和后续二进制 catalog 入口，解析 provider、internal id、primary key、dependency、bundle name、hash、size、CRC 和资源类型。
3. **UnityFS 容器层**：继续完善 header、block info、directory、data block、压缩、alignment、边界错误、directory 文件提取和真实样本回归。
4. **Serialized file 层**：稳定 Unity serialized file header、type table、TypeTree node、object table、path id、class id 和 raw object bytes 表示。
5. **字段级解析层**：实现 TypeTree 字段 reader，支持 bool、integer、float、string、bytes、array、vector/staticvector 嵌套 `Array`、`List<T>` / `HashSet<T>` 集合 alias、map、PPtr、enum `value__` backing field、`LayerMask` / `BitField` 的 `m_Bits` backing field、常见固定 Unity float/int/hash 值类型的 leaf/direct-child 形态、unknown fixed-size raw bytes 保留和同长度替换、TypeTree-covered managed reference / `SerializedReference` alias 和 TypeTree-covered managed reference registry 记录；managed-reference full typename 可拆为 assembly/namespace/class，常见 `m_ManagedReferences` / `RefIds` / verbose type 字段命名、`managedReference*` / `serializedReference*` metadata 和 `data` / `value` / `payload` / `object` / `managedReferencePayload` / `referencePayload` / `serializedReferencePayload` / `managedReferenceValue` / `referenceValue` / `serializedReferenceValue` / `managedReferenceObject` / `referenceObject` / `serializedReferenceObject` / `managedReferenceData` / `referenceData` / `serializedData` / `serializedReferenceData` payload 命名已有回归覆盖，TextUnit 只提取 payload 字符串并按结构化 record、`RefIds[n]` 等记录前缀或子字段保留类型上下文；array/vector/List/HashSet/map 元素与 registry payload 字段保留独立 field path、offset 和 byte size，可支撑字符串元素、managed-reference registry payload 字段、基础语义字段 patch、enum/bit_field 语义 patch、固定值类型 patch、unknown fixed-size bytes patch、object 字段组合和 TypeTree schema 支撑的 array/vector/List/HashSet/map 整体变长替换，`first/second` 与 `key/value` map entry schema 已有回归覆盖；解析模块当前处于维护冻结，未见样本驱动的完整 managed reference registry / map entry 变体和 unknown 字段结构语义暂不继续扩展，除非属于冻结规则允许的稳定性修复。
6. **文本对象入口**：实现 TextAsset、MonoBehaviour、ScriptableObject 的可扩展提取入口，输出可追溯到 bundle、serialized file、path id 和 field path 的文本定位。
7. **工具与接口**：编写 `bundle inspect`、`bundle extract`、`text extract` 的最小稳定入口；CLI/RPC/API 使用解析器输出，不直接耦合解析内部结构。
8. **汉化发布前置**：解析结果必须能作为 Patch 输入；Patch 发布阶段才写入 `--localized-output` / `BAT_LOCALIZED_OUTPUT` 配置的汉化输出目录并切换 `localized` 状态。

验收标准：

1. 能解析结构化测试样本、离线回归 fixture 和隔离真实样本。
2. 错误报告包含 URL/路径、archive entry、UnityFS directory、object path id、class id、field path、offset 和 Unity 版本。
3. 解析器和业务流程解耦；解析器不直接写 `bat-resources` 或 `bat-localized`。
4. 不支持的 Unity 版本或 TypeTree 结构返回明确错误，不做隐式猜测。
5. `official-parse-cache.json` 能跳过未变化资源的重复解析，且不会影响官方原版资源发布。
6. 文本提取结果能追溯到原始资源位置，并可作为后续 Patch manifest 输入。

详细分层路线图见 `docs/architecture/assetbundle.md`。

---

### 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 hunk diff/apply、RFC 6902 JSON Patch apply 和 UTF-8 Text Patch。
2. 已定义 Patch manifest 基础：目标版本、文件列表、BLAKE3、size 和 rollback 元数据；签名后置。
3. 实现客户端发现、路径校验、备份、应用、回滚。
4. 实现 `patch build`、`patch apply`、`patch rollback`、`verify`。
5. 实现 dry-run 和安全检查。
6. 将通用 Patch manifest 与汉化发布流程进一步统一。

验收标准：

1. 应用补丁前后都能校验完整性。
2. 任一步失败都能回滚到补丁前状态。
3. 不直接覆盖未经备份的客户端文件。
4. Patch 生成与应用有端到端测试。
5. 汉化产物写入 `--localized-output` / `BAT_LOCALIZED_OUTPUT` 配置的独立目录，保留官方相对目录结构；只有完整 Patch 发布并通过校验后才切换为 `localized`。

---

### 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。项目当前的真实瓶颈是资源解析、增量变更集进入文本提取/翻译队列、`bat-api` 与全量 release 联调，以及真实端到端验证。

建议顺序：

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

---

## 6. 近期具体任务

优先完善 Rust 解析与资源库接入，并联调 Go 资源分发。边界见 `docs/reports/GO_STATUS.md`：

1. issue #17 已关闭（顺序下载 + 指数退避）。
2. G-008 已决策关闭：同步/运维命令行 = 近乎全自动的 Rust `bat`。
3. G-009 / issue #19：`bat-api` 资源分发 MVP 已落地；优先服务器联调；拉取仍在 Rust `bat`。
4. 继续 Addressables（issue #2）与 UnityFS（issue #3 / G-005）。
5. 将 `crowdin-textunit-queue.json` 接入真实 Crowdin worker、翻译记忆和 Patch 构建。
6. 继续扩展 G-011 剩余查询面：真实 worker 状态写回、`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 的长期职责包括资源分发 HTTP（`bat-api`）、服务编排、网络和 Provider；同步/运维命令行由近乎全自动的 Rust `bat` 承担。不能把试验性 `cmd/bat` 视为产品 CLI。
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 官方资源同步闭环、可配置 CAS/ResourceRepository 导入、TextUnit 明细索引/查询、增量 Crowdin 离线队列、通用 Binary/JSON/Text Patch 基础、UnityFS TextAsset patch 发布前置，以及 Go `bat-api` 资源分发 MVP。下一阶段的关键是真实 Crowdin worker、翻译记忆、复杂 AssetBundle 解析/重打包，以及 bat-api 与全量 release 联调。

---

- **下一份应更新文档**：真实官方网络 smoke 记录
- **下一项工程任务**：执行官方同步端到端 smoke，推进真实 Crowdin worker / 翻译记忆、复杂 AssetBundle 解析和 bat-api 全量 release 联调。