docs: align project status with official sync pipeline

Update the authoritative docs, guides, architecture notes, gap list, deployment guidance, handoff notes, and changelog to reflect the current Rust official resource sync boundary.
2026-07-22 00:55:15 +08:00 · 2026-07-06 00:34:22 +08:00
parent 789402c887
commit 5e76ea4ae3
15 changed files with 661 additions and 345 deletions
@@ -2,64 +2,97 @@

 **BlueArchiveToolkit** 是一个面向长期维护的 Blue Archive 资源管理、解析、翻译和补丁工具套件。

-当前项目仍处于早期开发阶段：Rust 领域模型、适配器框架和生产级 CAS V1 已经存在；资源同步、完整 AssetBundle 解析、翻译系统、Patch、CLI、API Server 和 Web 后台仍在持续完善。当前官方资源实验与推送准备在 `experiment` 分支进行。
+当前仓库仍不是完整产品，但 Rust 侧已经具备一条可运行的官方日服资源同步链路：可以在 Linux 上通过官方 HTTP metadata 自动发现资源入口，拉取 Windows + Android 官方资源，保存同步 snapshot，校验本地下载清单，并用 `--watch` 常驻定期检查更新。Go CLI、API Server、Web、完整 AssetBundle 解析、翻译系统和 Patch 系统仍在后续阶段。

 ---

-## 项目目标
-
-最终系统计划支持：
-
- 资源同步：Manifest、版本管理、增量同步、Hash 校验、断点续传、重试、缓存。
- CAS 存储：内容寻址、去重、引用计数、垃圾回收、多版本共享、完整性校验。
- Unity AssetBundle：插件化解析 TextAsset、Localization、MonoBehaviour、ScriptableObject 等资源。
- 文本提取：剧情、UI、系统文本、配置文本的标准化导出。
- 翻译系统：Translation Memory、Glossary、AI Provider、审核流、历史记录。
- Patch 系统：增量 Patch、Binary Patch、JSON Patch、Rollback、Integrity Check。
- CLI / API / Web / SDK：提供本地工具、服务端接口、管理后台和外部集成能力。
-
---
-
-## 当前状态
-
-已具备：
+## 当前可用

 - Rust workspace 和 monorepo 结构。
 - `bat-core` 领域对象和仓储接口骨架。
- `bat-adapters` Unity、Manifest、Client 集成框架。
- `bat-cas-engine` CAS V1：原子写入、Hash 校验、引用计数、GC、并发写入测试、损坏检测。
- `bat-infrastructure` CAS 仓储适配层。
- `bat-ffi` 基础 crate 边界。
- 官方日服资源 auto-discover、pull plan、update check 用户流程；launcher bootstrap 仅作为底层显式开发/审计辅助路径。
- 文档路线图和当前缺口清单。
- 当前阶段说明与推送前核查文档。
+- `bat-adapters` Unity、Manifest、Client 集成框架，以及当前真实形态 Addressables catalog 解析覆盖。
+- `bat-cas-engine` CAS V1：原子写入、BLAKE3 校验、引用计数、GC、并发写入测试、损坏检测。
+- `bat-infrastructure` CAS 适配层、SQLite Resource Repository、官方资源 pull/update 服务。
+- `bat-official-sync`：官方资源自动发现、全量拉取、本地 manifest audit/repair、`.part` 断点续传、官方 seed `.hash` 校验、snapshot/cache、`--watch` 常驻更新。
+- `bat-ffi` 粗粒度 JSON 接口：Manifest inspect 和官方 sync plan。
+- 文档路线图、当前状态、缺口清单、官方资源运行指南。

-未完成：
+仍未完成：

- 真实 AssetBundle 解析。
+- Go CLI 最小可用入口。
+- 完整 UnityFS / AssetBundle 解析。
 - 真实 Patch apply/diff。
- Go CLI、API Server、SDK。
- Web 管理后台。
 - Translation Memory、Glossary、AI Provider。
+- API Server、SDK、Web 管理后台。
+- 真实官方网络全量下载 smoke test 尚未在本仓库记录。

 详细状态见：

 - [当前状态](CURRENT_STATUS.md)
 - [完整开发计划](PROJECT_PLAN.md)
- [当前缺口清单](docs/reports/CURRENT_GAPS.md)
 - [文档索引](DOCS_INDEX.md)
- [当前阶段说明](docs/reports/current-stage-prepush.md)
+- [当前缺口清单](docs/reports/CURRENT_GAPS.md)
+- [官方资源拉取与自动更新指南](docs/guides/official-resource-test-pull.md)
+- [官方资源后端说明](docs/architecture/official-resource-backend.md)
+
+---
+
+## 快速验证
+
+前置要求：
+
+- Rust 1.75+
+- Go 1.22+
+- `curl`
+- `unzip`，仅 `--auto-discover` 在 launcher metadata 变化并需要解析 `GameMainConfig` 时使用
+
+运行当前主要测试：
+
+```bash
+cargo test -p bat-adapters -- --nocapture
+cargo test -p bat-ffi -- --nocapture
+cargo test -p bat-infrastructure -- --nocapture
+cargo test -p bat-infrastructure --bin bat-official-sync -- --nocapture
+```
+
+查看官方同步命令：
+
+```bash
+cargo run -p bat-infrastructure --bin bat-official-sync -- --help
+```
+
+只做官方资源更新判断，不写同步状态：
+
+```bash
+cargo run -p bat-infrastructure --bin bat-official-sync -- \
+  --auto-discover \
+  --platforms Windows,Android \
+  --output /tmp/ba-official-update \
+  --dry-run
+```
+
+常驻自动更新，默认每 1 小时检查一次；远端和本地一致时静默：
+
+```bash
+cargo run -p bat-infrastructure --bin bat-official-sync -- \
+  --auto-discover \
+  --platforms Windows,Android \
+  --output /tmp/ba-official-update \
+  --watch
+```
+
+生产输出目录必须使用独立状态目录，不要指向已有客户端目录，也不要指向 `/home/wanye/D/BlueArchive` 这类人工维护或开发资源目录。

 ---

 ## 技术栈

- Rust：CAS、AssetBundle、Patch、FFI 等核心引擎。
- Go：CLI、资源同步、API Server、任务编排、SDK。
- PostgreSQL：服务端主数据库。
- Redis：缓存、队列状态、限流和短期锁。
- Vue 3 + TypeScript：Web 管理后台。
- Docker / Docker Compose：本地开发和部署。
+- Rust：CAS、官方资源同步核心、AssetBundle/Patch 引擎、FFI。
+- Go：计划中的最小 CLI、服务编排、API Server、SDK；当前仅有 FFI 包骨架。
+- PostgreSQL：计划中的服务端主数据库。
+- Redis：计划中的缓存、队列状态、限流和短期锁。
+- Vue 3 + TypeScript：计划中的 Web 管理后台。
+- Docker / Docker Compose：数据库和后续服务部署配置。

 ---

@@ -68,15 +101,15 @@
 ```text
 BlueArchiveToolkit/
 ├── core/                  # Rust 领域模型和仓储接口
-├── adapters/              # Rust 适配器框架
-├── infrastructure/        # Rust 基础设施适配层
+├── adapters/              # Rust 适配器框架与官方资源规则
+├── infrastructure/        # Rust 基础设施、官方同步、CAS/ResourceRepository 适配
 ├── crates/                # Rust 引擎 crate
 │   ├── bat-cas-engine/
 │   ├── bat-assetbundle/
 │   ├── bat-patch/
 │   └── bat-ffi/
+├── internal/ffi/          # Go 调用 Rust FFI 的早期包装
 ├── cmd/                   # Go CLI 入口，尚未实现
-├── internal/              # Go 内部包，尚未实现
 ├── pkg/                   # Go SDK 包，尚未实现
 ├── api/                   # API 定义，尚未实现
 ├── web/                   # Web 管理后台，尚未实现
@@ -89,42 +122,17 @@ BlueArchiveToolkit/

 ---

-## 本地验证
-
-前置要求：
-
- Rust 1.75+
- Go 1.22+
- Docker 与 Docker Compose，后续数据库开发需要
-
-当前可运行的主要验证命令：
-
-```bash
-cargo test --workspace
-```
-
-也可以使用 Makefile：
-
-```bash
-make help
-make test
-make check
-```
-
-说明：Go CLI/API 尚未实现，因此 Makefile 中的 Go build/test/check/fmt/lint 会在没有 Go package 时明确跳过。
-
---
-
 ## 开发优先级

 近期优先级：

-1. 完成 Manifest 真实解析。
-2. 启动 Go CLI 的 `doctor` 和基础命令框架。
-3. 设计 Resource Repository 的持久化 schema。
-4. 开始 AssetBundle 解析框架实装。
+1. 落地 Go CLI 最小可用入口：`bat doctor`、`bat sync --help`、Rust 同步命令包装。
+2. 补齐 AssetBundle UnityFS header/block/directory 解析。
+3. 扩展 Addressables catalog 解析覆盖，继续用真实形态 fixture/golden 锁定行为。
+4. 将官方同步结果接入 CAS + ResourceRepository 的用户级工作流。
+5. 执行并记录一次真实官方网络全量下载 smoke test。

-不建议在 Manifest、AssetBundle 和文本提取基础能力完成前优先开发 Web UI。
+不建议在 Go CLI、资源解析和文本提取基础能力完成前优先开发 Web UI。

 ---