mirror of
https://github.com/Yuyi-Oak/BlueArchiveToolkit.git
synced 2026-07-22 04:06:44 +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:
@@ -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