mirror of
https://github.com/Yuyi-Oak/BlueArchiveToolkit.git
synced 2026-07-22 01:15:14 +08:00
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.
This commit is contained in:
+4
-2
@@ -2,9 +2,11 @@
|
||||
|
||||
本目录包含 BlueArchive Toolkit 的 API 文档。
|
||||
|
||||
当前 API Server 尚未实现，本文件只记录规划边界，不代表已有可运行 HTTP 服务或 OpenAPI 产物。
|
||||
|
||||
## OpenAPI 规范
|
||||
|
||||
OpenAPI 文档位于 `openapi/` 目录，使用 OpenAPI 3.0 标准。
|
||||
OpenAPI 文档将在 API Server 落地后生成，目标使用 OpenAPI 3.0 标准。当前仓库尚未提供 `openapi/` 生成产物。
|
||||
|
||||
## 文档生成
|
||||
|
||||
@@ -43,4 +45,4 @@ API 文档将在开发过程中自动生成和更新。
|
||||
|
||||
---
|
||||
|
||||
更多详细文档将在 Phase 6 实现 API Server 时补充。
|
||||
更多详细文档将在 API Server 实现后补充。
|
||||
|
||||
+44
-23
@@ -4,12 +4,14 @@
|
||||
|
||||
BlueArchive Toolkit 采用 **Monorepo + 多语言混合** 架构，旨在构建一个可持续维护十年以上的工业级开源项目。
|
||||
|
||||
当前文档描述目标架构。实际实现状态以根目录 `CURRENT_STATUS.md` 和 `PROJECT_PLAN.md` 为准。
|
||||
当前文档描述目标架构和已经落地的关键边界。实际实现状态以根目录 `CURRENT_STATUS.md` 和 `PROJECT_PLAN.md` 为准。
|
||||
|
||||
当前已经可用的官方资源入口包括：
|
||||
|
||||
- `infrastructure/examples/official_pull_plan.rs`：Linux 生产资源拉取路径，显式读取官方 `server-info` 输入。
|
||||
- `infrastructure/examples/official_update_check.rs`：Linux 自动更新检查入口，保存 snapshot 并按需拉取。
|
||||
- `infrastructure/src/bin/bat_official_sync.rs`：Linux 官方资源同步正式入口，支持 one-shot 和 `--watch` 常驻更新。
|
||||
- `infrastructure/src/official_update.rs`：官方自动更新核心服务，负责 auto-discover、snapshot、marker diff、本地 audit/repair。
|
||||
- `infrastructure/examples/official_pull_plan.rs`：开发/审计用 pull plan 入口。
|
||||
- `infrastructure/examples/official_update_check.rs`：历史/开发入口，生产优先使用 `bat-official-sync`。
|
||||
- `infrastructure/examples/official_launcher_bootstrap.rs`：显式开发/审计辅助路径，用于核查官方 launcher metadata，不是生产运行依赖。
|
||||
- `docs/guides/official-resource-test-pull.md`
|
||||
|
||||
@@ -33,14 +35,14 @@ BlueArchive Toolkit 采用 **Monorepo + 多语言混合** 架构，旨在构建
|
||||
|
||||
| 模块 | 语言 | 理由 |
|
||||
|------|------|------|
|
||||
| CLI、API Server、下载器 | Go | 并发模型优秀、部署简单、生态成熟 |
|
||||
| AssetBundle 解析、Patch 引擎、CAS 引擎 | Rust | 零成本抽象、内存安全、性能极致 |
|
||||
| CLI、API Server、服务编排 | Go | 并发模型优秀、部署简单、生态成熟 |
|
||||
| 官方资源同步核心、AssetBundle 解析、Patch 引擎、CAS 引擎 | Rust | 零成本抽象、内存安全、性能和二进制处理更可靠 |
|
||||
| Web 管理后台 | Vue 3 + TypeScript | 渐进式、类型安全、生态完善 |
|
||||
|
||||
### 3. 数据流设计
|
||||
|
||||
```
|
||||
用户请求 → CLI/API → Go 业务层 → Rust 核心层 → CAS 存储 → 数据库
|
||||
用户请求 → CLI/API → Go 业务层 → Rust 核心/同步层 → CAS 存储 → 数据库
|
||||
↓ ↓
|
||||
Web UI 缓存层 (Redis)
|
||||
```
|
||||
@@ -89,25 +91,41 @@ cas/
|
||||
|
||||
---
|
||||
|
||||
### 2. 资源同步器 (Go)
|
||||
### 2. 官方资源同步器 (Rust 当前实现，Go 后续编排)
|
||||
|
||||
**职责**：从游戏服务器下载资源、增量更新、完整性校验
|
||||
**职责**：从官方日服 HTTP metadata 自动发现资源入口，下载 Windows + Android 官方资源，增量检查，完整性校验，保持本地状态。
|
||||
|
||||
**当前实现**：
|
||||
|
||||
- `OfficialUpdateService`：auto-discover、snapshot、marker diff、本地 manifest audit/repair。
|
||||
- `OfficialResourcePullService`：官方 URL 校验、`.part` 断点续传、重试、下载 manifest、官方 seed `.hash` 校验。
|
||||
- `bat-official-sync`：正式 binary，支持 one-shot 和 `--watch`。
|
||||
|
||||
**当前数据流**：
|
||||
|
||||
**架构**：
|
||||
```
|
||||
Manifest Parser → Version Manager → Downloader → CAS Storage
|
||||
↓
|
||||
Task Queue (多线程)
|
||||
↓
|
||||
Progress Reporter
|
||||
官方 metadata → GameMainConfig → server-info → discovery endpoints
|
||||
↓
|
||||
seed catalog → inventory → pull plan → downloader → output directory
|
||||
↓
|
||||
official-sync-snapshot.json + official-download-manifest.json
|
||||
```
|
||||
|
||||
**特性**：
|
||||
- 多线程并发下载
|
||||
- 断点续传（Range 请求）
|
||||
- 自动重试机制（指数退避）
|
||||
- 限速支持
|
||||
- Hash 校验（下载后立即验证）
|
||||
**已具备特性**：
|
||||
|
||||
- 不安装、不执行官方 launcher。
|
||||
- 默认平台 `Windows + Android`。
|
||||
- `--auto-discover` 自动获取 `app-version`、`connection-group` 和 `server-info`。
|
||||
- `--watch` 常驻检查，默认 1 小时。
|
||||
- 远端 marker 无变化且本地 manifest clean 时不下载。
|
||||
- 本地文件损坏时 repair。
|
||||
- 官方 seed `.hash` 强校验；Addressables `catalog_*.hash` 作为变更 marker。
|
||||
|
||||
**后续 Go 职责**：
|
||||
|
||||
- 提供最小稳定 CLI。
|
||||
- 包装或调用 Rust 同步入口，转发 JSON report。
|
||||
- 编排 API Server、任务队列、Provider 和用户配置。
|
||||
|
||||
---
|
||||
|
||||
@@ -369,7 +387,10 @@ API Server (多实例)
|
||||
更多详细设计文档：
|
||||
|
||||
- [官方资源后端说明](./official-resource-backend.md)
|
||||
- [CAS 存储引擎设计](./cas-storage.md)
|
||||
- [AssetBundle 解析器设计](./assetbundle-parser.md)
|
||||
- [翻译系统设计](./translation-system.md)
|
||||
- [API 设计](../api/README.md)
|
||||
|
||||
待创建的详细设计文档：
|
||||
|
||||
- `docs/architecture/cas.md`
|
||||
- `docs/architecture/assetbundle.md`
|
||||
- `docs/architecture/translation.md`
|
||||
|
||||
@@ -233,16 +233,15 @@ Linux 生产路径：
|
||||
- 下载层能在本地文件 size/BLAKE3/path 或 manifest 不匹配时重新下载
|
||||
- 官方 seed `.hash` mismatch 会导致下载失败，而不是降级为本地 BLAKE3 猜测
|
||||
- 非官方 URL 会在 fetch/download 入口被拒绝
|
||||
- 尚未在仓库中记录真实官方网络全量下载 smoke test
|
||||
|
||||
相关验证主要来自：
|
||||
|
||||
- `cargo test -p bat-adapters`
|
||||
- `cargo test -p bat-infrastructure`
|
||||
- `cargo test -p bat-adapters --examples`
|
||||
- `cargo test -p bat-infrastructure --examples`
|
||||
- `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`
|
||||
- `cargo clippy -p bat-adapters -- -D warnings`
|
||||
- `cargo clippy -p bat-infrastructure -- -D warnings`
|
||||
- `cargo run -p bat-infrastructure --bin bat-official-sync -- --help`
|
||||
|
||||
## 6. 审核重点
|
||||
|
||||
|
||||
+14
-9
@@ -1,7 +1,7 @@
|
||||
# 稳定工程基线指南
|
||||
|
||||
**更新时间**：2026-06-28
|
||||
**目标**：让工作区处于可继续开发核心功能的可信状态。
|
||||
- **更新时间**：2026-07-06
|
||||
- **目标**：让工作区处于可继续开发核心功能的可信状态。
|
||||
|
||||
---
|
||||
|
||||
@@ -17,6 +17,7 @@
|
||||
6. 当前缺口有集中清单和关闭顺序。
|
||||
7. 架构边界有 ADR 记录。
|
||||
8. 基础验证命令通过。
|
||||
9. Rust 官方资源同步入口有明确运行文档和生产边界。
|
||||
|
||||
---
|
||||
|
||||
@@ -40,9 +41,10 @@ cargo clippy --workspace -- -D warnings
|
||||
|
||||
说明：
|
||||
|
||||
1. 当前没有 Go package，因此 Go build/test/check/fmt/lint 会明确跳过。
|
||||
1. 当前没有 Go 产品入口，因此 Go build/test/check/fmt/lint 会在空 Go 阶段明确跳过。
|
||||
2. 如果后续新增 Go package，必须让 `go test ./...` 和 `go vet ./...` 纳入硬性验证。
|
||||
3. 当前 `golangci-lint` 可选；当 Go 代码进入主要开发阶段后，应纳入 CI。
|
||||
4. 官方同步相关修改必须额外运行 `cargo test -p bat-infrastructure --bin bat-official-sync -- --nocapture`。
|
||||
|
||||
---
|
||||
|
||||
@@ -84,16 +86,19 @@ git check-ignore -v Cargo.lock CLAUDE.md
|
||||
|
||||
## 5. 下一阶段入口
|
||||
|
||||
CAS V1 完成后，下一阶段优先推进：
|
||||
CAS V1 和 Rust 官方同步闭环完成后，下一阶段优先推进：
|
||||
|
||||
1. Manifest 真实解析。
|
||||
2. Go CLI 的 `doctor` 和基础命令框架。
|
||||
3. Resource Repository 持久化 schema。
|
||||
1. Go CLI 的 `doctor` 和基础命令框架。
|
||||
2. 真实官方网络全量下载 smoke 记录。
|
||||
3. 官方同步结果接入 CAS + ResourceRepository。
|
||||
4. AssetBundle UnityFS 解析。
|
||||
|
||||
优先阅读：
|
||||
|
||||
1. `PROJECT_PLAN.md`
|
||||
2. `CURRENT_STATUS.md`
|
||||
3. `docs/reports/CURRENT_GAPS.md`
|
||||
4. `docs/architecture/adr/0001-engine-and-application-boundaries.md`
|
||||
5. `docs/architecture/adr/0002-cas-v1-design-boundary.md`
|
||||
4. `docs/guides/official-resource-test-pull.md`
|
||||
5. `docs/architecture/official-resource-backend.md`
|
||||
6. `docs/architecture/adr/0001-engine-and-application-boundaries.md`
|
||||
7. `docs/architecture/adr/0002-cas-v1-design-boundary.md`
|
||||
|
||||
@@ -2,11 +2,11 @@
|
||||
|
||||
## 架构概览
|
||||
|
||||
BlueArchive Toolkit 支持多种部署模式：
|
||||
BlueArchive Toolkit 的部署文档分为当前可用模式和目标模式：
|
||||
|
||||
1. **本地开发模式**：代码在本地，连接远程数据库
|
||||
2. **单机部署**：所有组件运行在一台服务器
|
||||
3. **分布式部署**：多实例 API Server + 独立数据库服务器
|
||||
1. **本地开发模式**：代码在本地，连接本地或远程数据库。
|
||||
2. **官方资源同步生产任务**：当前可用，运行 Rust `bat-official-sync --watch`。
|
||||
3. **完整单机/分布式部署**：目标模式，等待 API Server、数据库迁移和 Web 实现后补齐。
|
||||
|
||||
---
|
||||
|
||||
@@ -98,9 +98,98 @@ REDIS_PORT=6379
|
||||
|
||||
---
|
||||
|
||||
## 模式 3：生产环境部署
|
||||
## 模式 3：官方资源同步生产任务
|
||||
|
||||
待补充（Phase 6 实现 API Server 后）
|
||||
当前可部署的生产任务是 Rust 官方资源同步 binary。API Server 和 Web 尚未实现，不能按完整服务端产品部署。
|
||||
|
||||
### 构建
|
||||
|
||||
```bash
|
||||
cargo build --release -p bat-infrastructure --bin bat-official-sync
|
||||
```
|
||||
|
||||
产物：
|
||||
|
||||
```text
|
||||
target/release/bat-official-sync
|
||||
```
|
||||
|
||||
### 目录约定
|
||||
|
||||
推荐生产状态目录：
|
||||
|
||||
```text
|
||||
/var/lib/bluearchive-toolkit/official/
|
||||
```
|
||||
|
||||
该目录会保存：
|
||||
|
||||
- `official-sync-snapshot.json`
|
||||
- `official-bootstrap-cache.json`
|
||||
- `official-download-manifest.json`
|
||||
- `.official-sync.lock`
|
||||
- 下载得到的官方资源文件
|
||||
|
||||
不要把输出目录设为：
|
||||
|
||||
- 已安装游戏客户端目录
|
||||
- 官方启动器安装目录
|
||||
- 开发机现有资源目录，例如 `/home/wanye/D/BlueArchive`
|
||||
- Git 工作区目录
|
||||
|
||||
### 一次性检查
|
||||
|
||||
```bash
|
||||
/opt/bluearchive-toolkit/bin/bat-official-sync \
|
||||
--auto-discover \
|
||||
--platforms Windows,Android \
|
||||
--output /var/lib/bluearchive-toolkit/official \
|
||||
--dry-run
|
||||
```
|
||||
|
||||
### 常驻自动更新
|
||||
|
||||
```bash
|
||||
/opt/bluearchive-toolkit/bin/bat-official-sync \
|
||||
--auto-discover \
|
||||
--platforms Windows,Android \
|
||||
--output /var/lib/bluearchive-toolkit/official \
|
||||
--watch
|
||||
```
|
||||
|
||||
`--watch` 是 Rust 内部持久检查模式，默认每 1 小时执行一次检查。远端和本地一致时默认静默；有远端变化或本地文件损坏时自动下载或 repair，并输出 JSON report。
|
||||
|
||||
### systemd service 示例
|
||||
|
||||
systemd 只负责进程守护，不负责定时逻辑：
|
||||
|
||||
```ini
|
||||
[Unit]
|
||||
Description=BlueArchiveToolkit official resource sync
|
||||
After=network-online.target
|
||||
Wants=network-online.target
|
||||
|
||||
[Service]
|
||||
Type=simple
|
||||
User=bat
|
||||
Group=bat
|
||||
ExecStart=/opt/bluearchive-toolkit/bin/bat-official-sync --auto-discover --platforms Windows,Android --output /var/lib/bluearchive-toolkit/official --watch
|
||||
Restart=on-failure
|
||||
RestartSec=30
|
||||
StateDirectory=bluearchive-toolkit
|
||||
NoNewPrivileges=true
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
如果业务层需要热更新、热重载或发布新资源，应该由上层服务在观察到 JSON report 或 snapshot 变化后决定。Rust 同步进程只负责拉取、校验和维护本地状态。
|
||||
|
||||
---
|
||||
|
||||
## 模式 4：完整生产环境部署
|
||||
|
||||
待补充（API Server、数据库迁移和 Web 实现后）
|
||||
|
||||
---
|
||||
|
||||
@@ -172,4 +261,4 @@ docker exec bat-redis redis-cli ping
|
||||
|
||||
---
|
||||
|
||||
更多问题请查看 [故障排查指南](./troubleshooting.md)（待创建）
|
||||
更多当前状态请查看 `CURRENT_STATUS.md`、`docs/reports/CURRENT_GAPS.md` 和本文件中的健康检查命令。
|
||||
|
||||
+32
-16
@@ -104,26 +104,45 @@ git push origin feature/your-feature-name
|
||||
|
||||
## 测试
|
||||
|
||||
### 单元测试
|
||||
### 当前必跑测试
|
||||
|
||||
```bash
|
||||
# Go
|
||||
go test ./...
|
||||
|
||||
# Rust
|
||||
cargo test
|
||||
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
|
||||
```
|
||||
|
||||
Go CLI 尚未实现时，`go test ./...` 可能没有产品级 package 可运行；Makefile 会在空 Go 阶段清晰跳过。
|
||||
|
||||
### 集成测试
|
||||
|
||||
```bash
|
||||
# 需要先启动数据库
|
||||
make dev
|
||||
|
||||
# 运行集成测试
|
||||
go test -tags=integration ./...
|
||||
cargo test --workspace
|
||||
```
|
||||
|
||||
带真实本地资源的测试默认不应启用。只有在明确需要时，才通过对应 `BAT_REAL_*` 环境变量读取隔离样本路径。不要默认读取 `/home/wanye/D/BlueArchive` 或任何已有客户端目录。
|
||||
|
||||
### 官方资源同步手动检查
|
||||
|
||||
查看参数：
|
||||
|
||||
```bash
|
||||
cargo run -p bat-infrastructure --bin bat-official-sync -- --help
|
||||
```
|
||||
|
||||
dry-run：
|
||||
|
||||
```bash
|
||||
cargo run -p bat-infrastructure --bin bat-official-sync -- \
|
||||
--auto-discover \
|
||||
--platforms Windows,Android \
|
||||
--output /tmp/ba-official-dev \
|
||||
--dry-run
|
||||
```
|
||||
|
||||
开发环境真实下载必须使用 `/tmp` 或其他隔离目录，不要写入现有资源目录。
|
||||
|
||||
### 基准测试
|
||||
|
||||
```bash
|
||||
@@ -161,10 +180,7 @@ cargo fetch
|
||||
|
||||
### 2. 测试失败
|
||||
|
||||
确保数据库已启动：
|
||||
```bash
|
||||
make dev
|
||||
```
|
||||
先确认失败是否来自真实网络或本地资源路径。默认测试应使用 fixture/mock，不应依赖官方线上资源或开发机已有资源目录。
|
||||
|
||||
### 3. FFI 绑定问题
|
||||
|
||||
@@ -176,4 +192,4 @@ cargo build
|
||||
|
||||
---
|
||||
|
||||
更多问题请查看 [FAQ](./faq.md)（待创建）或提交 Issue。
|
||||
更多当前状态请查看 [当前状态](../../CURRENT_STATUS.md) 和 [当前缺口清单](../reports/CURRENT_GAPS.md)。
|
||||
|
||||
@@ -15,6 +15,42 @@
|
||||
- 任何本地客户端目录
|
||||
- 任何已安装的官方启动器或 Windows 客户端
|
||||
|
||||
## 0. 快速入口
|
||||
|
||||
查看命令参数：
|
||||
|
||||
```bash
|
||||
cargo run -p bat-infrastructure --bin bat-official-sync -- --help
|
||||
```
|
||||
|
||||
构建生产 binary：
|
||||
|
||||
```bash
|
||||
cargo build --release -p bat-infrastructure --bin bat-official-sync
|
||||
```
|
||||
|
||||
使用 release binary 做一次 dry-run：
|
||||
|
||||
```bash
|
||||
target/release/bat-official-sync \
|
||||
--auto-discover \
|
||||
--platforms Windows,Android \
|
||||
--output /var/lib/bluearchive-toolkit/official \
|
||||
--dry-run
|
||||
```
|
||||
|
||||
常驻自动更新：
|
||||
|
||||
```bash
|
||||
target/release/bat-official-sync \
|
||||
--auto-discover \
|
||||
--platforms Windows,Android \
|
||||
--output /var/lib/bluearchive-toolkit/official \
|
||||
--watch
|
||||
```
|
||||
|
||||
生产输出目录必须是独立状态目录。不要使用已有游戏客户端目录、官方启动器安装目录、人工维护资源目录，或开发机上的 `/home/wanye/D/BlueArchive`。
|
||||
|
||||
## 1. 当前流程
|
||||
|
||||
Linux 生产运行时链路只走官方日服 HTTP 资源，不安装、不启动、不依赖官方启动器二进制：
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
# 当前实现缺口清单
|
||||
|
||||
**更新时间**：2026-06-28
|
||||
**用途**：集中跟踪当前代码中的占位实现、设计缺口和下一步验收项。
|
||||
**权威计划**：`../../PROJECT_PLAN.md`
|
||||
- **更新时间**：2026-07-06
|
||||
- **用途**：集中跟踪当前代码中的占位实现、设计缺口和下一步验收项。
|
||||
- **权威计划**：`../../PROJECT_PLAN.md`
|
||||
|
||||
---
|
||||
|
||||
@@ -145,18 +145,23 @@
|
||||
|
||||
### G-007：Addressables Catalog 解析不完整
|
||||
|
||||
状态：**部分关闭**
|
||||
|
||||
现象：
|
||||
|
||||
- 复杂压缩字段解析仍标记 TODO。
|
||||
- `AddressablesCatalogDriver` 已能解析当前真实形态 JSON catalog fixture/golden。
|
||||
- 已输出 path、hash、size、resource_type、address、dependencies、metadata。
|
||||
- 仍需覆盖更多官方 catalog 结构变体、二进制/压缩字段组合和更明确的失败诊断。
|
||||
|
||||
影响：
|
||||
|
||||
- 真实 Manifest 解析可能只能覆盖简单样本。
|
||||
- 当前解析能力可以服务 Manifest inspect 和部分资源索引，但还不能宣称完整兼容所有 Unity Addressables/SBP catalog 形态。
|
||||
|
||||
验收：
|
||||
|
||||
- 能解析项目目标版本的真实 Catalog 样本。
|
||||
- 能解析项目目标版本的真实 Catalog 样本集合。
|
||||
- 解析结果包含资源 key、provider、dependency、hash、size、path。
|
||||
- 对不支持的 catalog 结构返回明确错误，而不是静默丢字段。
|
||||
|
||||
---
|
||||
|
||||
@@ -167,7 +172,8 @@
|
||||
现象：
|
||||
|
||||
- `cmd/bat` 目录存在，但无 `main.go`。
|
||||
- `go test ./...` 当前无 package。
|
||||
- `internal/ffi/ffi.go` 已存在，但还不是用户可运行 CLI。
|
||||
- `go test ./...` 当前没有产品级 Go package 覆盖。
|
||||
|
||||
影响：
|
||||
|
||||
@@ -217,14 +223,19 @@
|
||||
|
||||
### G-011：Resource Repository 未持久化
|
||||
|
||||
状态：**部分关闭**
|
||||
|
||||
影响：
|
||||
|
||||
- 无法可靠记录资源版本、资源路径、依赖和 CAS hash 映射。
|
||||
- `SqliteResourceRepository` 已存在，可按领域 repository 接口保存资源元数据。
|
||||
- 官方同步下载结果尚未作为用户级流程自动写入 CAS + ResourceRepository。
|
||||
- 迁移、版本化 schema 和 CLI 查询入口仍需补齐。
|
||||
|
||||
验收：
|
||||
|
||||
- schema 和迁移可重复执行。
|
||||
- 可按版本、类型、hash、路径查询资源。
|
||||
- 官方同步后的资源可通过 CLI 查询并能追溯到 CAS 对象。
|
||||
|
||||
### G-012：Translation Memory 未实现
|
||||
|
||||
@@ -266,32 +277,37 @@
|
||||
|
||||
### G-015：README 与当前真实状态不完全一致
|
||||
|
||||
状态：**已关闭**
|
||||
|
||||
现象：
|
||||
|
||||
- README 描述了最终架构，但部分功能尚未实现。
|
||||
- 旧 README 描述了最终架构，但部分功能尚未实现。
|
||||
|
||||
验收：
|
||||
|
||||
- README 明确区分已实现、开发中、规划中。
|
||||
|
||||
状态：
|
||||
处理结果：
|
||||
|
||||
- 已部分修正，当前 README 已明确列出已具备与未完成项，并增加当前阶段说明入口。
|
||||
- README 已明确区分当前可用能力、未完成模块、官方同步运行命令和近期优先级。
|
||||
|
||||
### G-016：架构文档需要更新为当前路线图
|
||||
|
||||
状态：**已关闭当前阶段**
|
||||
|
||||
现象：
|
||||
|
||||
- `docs/architecture/README.md` 仍描述理想架构，缺少当前状态和边界冻结记录。
|
||||
- 旧 `docs/architecture/README.md` 偏目标架构，容易让读者误以为 Go 同步器和 API/Web 已经可用。
|
||||
|
||||
验收：
|
||||
|
||||
- 增加 ADR 或架构决策记录。
|
||||
- 明确 Rust/Go/DB/Plugin 边界。
|
||||
|
||||
状态：
|
||||
处理结果：
|
||||
|
||||
- 已部分修正，`docs/architecture/README.md` 已增加当前可用官方资源入口，但仍保留目标架构描述，因此只算阶段性对齐完成。
|
||||
- 架构 README 已明确当前 Rust 官方同步入口、Go 计划边界和目标架构差异。
|
||||
- 官方资源后端说明由 `docs/architecture/official-resource-backend.md` 承载。
|
||||
|
||||
### G-017：CI 未落地
|
||||
|
||||
@@ -303,15 +319,37 @@
|
||||
|
||||
- GitHub Actions 或等价 CI 执行 format、lint、test、build。
|
||||
|
||||
### G-018：真实官方网络全量下载 smoke test 未记录
|
||||
|
||||
状态：**未关闭**
|
||||
|
||||
现象：
|
||||
|
||||
- 本地测试覆盖 mock、fixture、synthetic import 和 CLI 参数。
|
||||
- 尚未在隔离输出目录记录一次真实官方网络全量下载。
|
||||
|
||||
影响：
|
||||
|
||||
- 无法用文档证明当前 `bat-official-sync` 在真实官方网络环境下完成首次下载、二次静默 up-to-date 和本地损坏 repair。
|
||||
|
||||
验收：
|
||||
|
||||
- 使用独立目录执行 dry-run。
|
||||
- 执行真实首次下载，不指向任何现有客户端或人工维护资源目录。
|
||||
- 二次运行返回 `up_to_date`，watch 模式在 up-to-date 时静默。
|
||||
- 人工破坏一个本地文件后，audit 检出并 repair。
|
||||
- 记录命令、摘要、输出目录和未纳入 Git 的大文件位置。
|
||||
|
||||
---
|
||||
|
||||
## 6. 当前关闭顺序建议
|
||||
|
||||
1. G-007
|
||||
2. G-008
|
||||
3. G-005
|
||||
4. G-011
|
||||
5. G-012
|
||||
6. G-006
|
||||
1. G-008
|
||||
2. G-018
|
||||
3. G-011
|
||||
4. G-007
|
||||
5. G-005
|
||||
6. G-012
|
||||
7. G-006
|
||||
|
||||
这个顺序优先建立可信工作区和基础存储，再推进资源同步、解析、翻译和补丁。
|
||||
这个顺序优先补齐用户入口和真实端到端验证，再推进资源索引、解析、翻译和补丁。
|
||||
|
||||
@@ -1,50 +1,72 @@
|
||||
# 当前阶段说明
|
||||
|
||||
**更新时间**：2026-06-29
|
||||
**状态分支**：`experiment`
|
||||
**用途**：推送前核查与当前阶段交付说明。
|
||||
- **更新时间**：2026-07-06
|
||||
- **状态分支**：`experiment`
|
||||
- **最新功能提交**：`789402c feat: add official resource sync pipeline`
|
||||
- **用途**：当前阶段交付说明、推送前核查和下一步依据。
|
||||
|
||||
## 1. 当前目标
|
||||
|
||||
当前阶段聚焦两件事：
|
||||
当前阶段的目标已经从“验证官方资源链路”推进到“让 Rust 官方资源同步具备可运行闭环，并为 Go CLI 最小入口做准备”。
|
||||
|
||||
1. 准备推送前的项目核查。
|
||||
2. 补齐当前阶段的文档说明。
|
||||
已完成的阶段目标：
|
||||
|
||||
1. Rust 官方资源拉取入口不依赖已安装官方启动器。
|
||||
2. 自动发现官方 `app-version`、`connection-group`、`server-info`。
|
||||
3. 拉取 Windows + Android 官方资源集合。
|
||||
4. 保存 snapshot，按远端 marker 和本地 manifest 判断是否需要更新。
|
||||
5. 支持 `bat-official-sync --watch` 常驻检查，默认每 1 小时运行一次。
|
||||
6. 通过文档明确生产目录不能指向已有客户端或开发资源目录。
|
||||
|
||||
## 2. 当前实现状态
|
||||
|
||||
已确认可用的内容：
|
||||
已确认可用：
|
||||
|
||||
- `bat-cas-engine` 的 CAS V1 已完成。
|
||||
- `bat-adapters` 的官方日服 URL 规则和官方 pull plan / update check 已可用。
|
||||
- Linux 生产资源拉取路径已明确为显式 `--auto-discover` 或已审计 metadata snapshot，不安装、不执行官方启动器。
|
||||
- 官方 launcher bootstrap、官方 GameMainConfig bootstrap 保留为底层显式开发/审计辅助路径。
|
||||
- `bat-infrastructure` 的官方 bootstrap / pull integration 测试已通过。
|
||||
- 官方资源链路已经明确只接受官方 host，不依赖 `bluearchive.cafe` 镜像。
|
||||
- `bat-cas-engine` CAS V1。
|
||||
- `bat-adapters` 官方日服 URL 规则、server-info 解析、平台 discovery、inventory 枚举。
|
||||
- `AddressablesCatalogDriver` 对当前真实形态 fixture/golden 的解析。
|
||||
- `OfficialResourcePullService` 的官方 URL 拒绝、`.part` 续传、重试、本地 manifest、官方 seed `.hash` 校验。
|
||||
- `OfficialUpdateService` 的 auto-discover、bootstrap cache、v2 snapshot、remote marker diff、本地 audit/repair。
|
||||
- `bat-official-sync` one-shot 和 `--watch`。
|
||||
- `bat-ffi` 的 Manifest inspect 和 sync plan JSON API。
|
||||
- `SqliteResourceRepository`。
|
||||
|
||||
实验性处理内容：
|
||||
仍未完成：
|
||||
|
||||
- 官方 bootstrap / pull 测试夹具已收敛为 synthetic fixture，并单独留在 `experiment` 分支语义下。
|
||||
- 这些 fixture 只用于验证官方链路，不代表运行时真实线上值。
|
||||
- Go CLI 最小可用入口。
|
||||
- 官方同步下载结果自动导入 CAS + ResourceRepository 的用户级流程。
|
||||
- 真实官方网络全量下载 smoke 记录。
|
||||
- 完整 AssetBundle 解析。
|
||||
- Patch、翻译系统、API Server、Web。
|
||||
|
||||
## 3. 当前核查结果
|
||||
|
||||
已执行的验证：
|
||||
已执行并通过：
|
||||
|
||||
- `cargo test -p bat-infrastructure --test official_game_main_config_bootstrap -- --nocapture`
|
||||
- `cargo test -p bat-infrastructure`
|
||||
- `cargo test -p bat-adapters`
|
||||
```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
|
||||
cargo run -p bat-infrastructure --bin bat-official-sync -- --help
|
||||
git diff --cached --check
|
||||
```
|
||||
|
||||
结果：
|
||||
提交后确认：
|
||||
|
||||
- 全部通过。
|
||||
```bash
|
||||
git status --short
|
||||
```
|
||||
|
||||
结果：工作区干净。
|
||||
|
||||
## 4. 当前结论
|
||||
|
||||
当前代码可以继续进入推送准备阶段，但仓库仍包含大量未整理的既有改动，暂不应把当前工作区视作“只剩最终提交”的干净状态。
|
||||
当前 Rust 官方资源同步链路已经具备可运行闭环，但仓库还不是完整产品。下一步不应继续只扩展 example，而应补齐 Go CLI 最小入口、真实网络 smoke、CAS/ResourceRepository 编排和 AssetBundle 解析。
|
||||
|
||||
下一步应当继续做：
|
||||
## 5. 下一步
|
||||
|
||||
- 归整实验性改动与主线改动的边界。
|
||||
- 按分支策略确认哪些内容允许进入 `dev`，哪些应保留在 `experiment`。
|
||||
- 再做一次提交前检查和差异审阅。
|
||||
1. 实现 Go CLI：`bat doctor`、`bat sync --help`、`bat official sync --help`。
|
||||
2. 为 `bat-official-sync` 做真实官方网络 smoke，输出目录必须隔离。
|
||||
3. 将官方同步下载结果接入 CAS + `SqliteResourceRepository`。
|
||||
4. 开始 AssetBundle UnityFS header/block/directory 解析。
|
||||
|
||||
@@ -1,50 +1,60 @@
|
||||
# 当前进度交接
|
||||
|
||||
**更新时间**：2026-06-30
|
||||
**状态分支**：`experiment`
|
||||
**用途**：给下一次对话快速恢复上下文，优先以当前工作区与已验证结果为准。
|
||||
- **更新时间**：2026-07-06
|
||||
- **状态分支**：`experiment`
|
||||
- **最新功能提交**：`789402c feat: add official resource sync pipeline`
|
||||
- **用途**：给下一次对话快速恢复上下文，优先以当前工作区和已验证结果为准。
|
||||
|
||||
## 1. 现在处在什么阶段
|
||||
|
||||
当前项目已经完成基础整理和 CAS V1，官方资源链路也已经验证过，下一阶段重点是把“资源同步”从验证推进到可继续扩展的真实实现。
|
||||
项目已经完成基础整理、CAS V1 和 Rust 官方资源同步闭环。下一阶段重点是 Go CLI 最小可用、真实官方网络 smoke、同步结果进入 CAS/ResourceRepository，以及 AssetBundle 解析起步。
|
||||
|
||||
已确认的事实：
|
||||
|
||||
- `cargo test --workspace` 通过。
|
||||
- `git status --short --branch` 可用，当前分支为 `experiment`。
|
||||
- 当前分支为 `experiment`。
|
||||
- `bat-cas-engine` 的 CAS V1 已完成。
|
||||
- 官方资源链路已收敛到只接受官方 host，默认验证平台是 `Windows` + `Android`。
|
||||
- 真实下载相关测试目前是通过 mock / fixture 验证，不是自动去拉线上全量资源。
|
||||
- `bat-official-sync` 是当前官方资源同步正式入口。
|
||||
- Linux 生产链路不安装、不启动、不依赖官方启动器。
|
||||
- `--auto-discover` 通过官方 HTTP metadata 和临时目录解析 `GameMainConfig`。
|
||||
- 默认平台是 `Windows + Android`。
|
||||
- 真实下载会维护 `official-download-manifest.json`，并使用 size + BLAKE3、本地 audit/repair 和官方 seed `.hash` 校验。
|
||||
- `--watch` 是 Rust 内部常驻检查模式，默认 1 小时；外部 systemd/container 只负责守护进程。
|
||||
|
||||
## 2. 现在不要误解的点
|
||||
|
||||
- `cargo test --workspace` 只会跑测试，不等于自动开始真实下载。
|
||||
- 仓库里确实有几个本地实样本测试，但它们是 `#[ignore]`，只有显式启用对应 `BAT_REAL_*` 环境变量才会读本地文件。
|
||||
- `cargo test` 不会自动开始真实全量下载。
|
||||
- 仓库里的本地实样本测试仍应显式启用，不应默认读取 `/home/wanye/D/BlueArchive`。
|
||||
- `bluearchive.cafe` 不是官方资源域名，不能当成官方链路使用。
|
||||
- 当前运行时不应依赖“本地客户端一定存在”的假设。
|
||||
- 生产输出目录必须独立，不要指向已有客户端目录、官方启动器安装目录或开发资源目录。
|
||||
- Go CLI 尚未实现；当前可运行同步入口是 Rust binary。
|
||||
- `catalog_*.hash` 当前作为 Addressables marker，不按官方 seed `.hash` 的 `xxHash32(seed=0)` 规则做内容强校验。
|
||||
|
||||
## 3. 当前还没做完什么
|
||||
|
||||
仍待实现的主线工作：
|
||||
|
||||
1. `Manifest` / Addressables 的真实解析。
|
||||
2. `sync`、`manifest inspect`、`cache status` 这些 CLI 入口。
|
||||
3. 资源持久化 schema，以及下载结果写入 CAS + ResourceRepository。
|
||||
4. 端到端的真实同步测试。
|
||||
5. 之后再推进 AssetBundle 解析、文本提取、翻译库、补丁系统。
|
||||
1. Go CLI 最小入口：`bat doctor`、`bat sync --help`、`bat official sync --help`。
|
||||
2. 真实官方网络 smoke：dry-run、首次下载、二次 up-to-date、本地损坏 repair。
|
||||
3. 官方同步下载结果进入 CAS + `SqliteResourceRepository` 的用户级流程。
|
||||
4. Addressables parser 覆盖更多真实 catalog 结构。
|
||||
5. AssetBundle UnityFS header/block/directory 解析。
|
||||
6. Patch、翻译库、API Server、Web。
|
||||
|
||||
## 4. 下一次对话最合适的起点
|
||||
|
||||
建议直接从 `Milestone 3：Manifest 与资源同步` 开始，先把这条链路收紧：
|
||||
建议从 Go CLI 最小可用开始：
|
||||
|
||||
1. 真实 `Manifest` 字段解析。
|
||||
2. 资源版本、平台、URL、Hash、大小模型确认。
|
||||
3. 下载器和缓存落地。
|
||||
4. 端到端验证能否从官方入口跑通同步。
|
||||
1. 读取 `README.md`、`CURRENT_STATUS.md`、`PROJECT_PLAN.md`。
|
||||
2. 读取 `docs/guides/official-resource-test-pull.md` 和 `docs/architecture/official-resource-backend.md`。
|
||||
3. 实现 `cmd/bat` 和最小命令树。
|
||||
4. 将 `bat-official-sync` 的 JSON report 作为 Go CLI 输出的稳定来源。
|
||||
|
||||
## 5. 相关入口
|
||||
|
||||
- `README.md`
|
||||
- `PROJECT_PLAN.md`
|
||||
- `CURRENT_STATUS.md`
|
||||
- `docs/reports/current-stage-prepush.md`
|
||||
- `DOCS_INDEX.md`
|
||||
- `docs/reports/CURRENT_GAPS.md`
|
||||
- `docs/guides/official-resource-test-pull.md`
|
||||
- `docs/architecture/official-resource-backend.md`
|
||||
|
||||
Reference in New Issue
Block a user