mirror of
https://github.com/Yuyi-Oak/BlueArchiveToolkit.git
synced 2026-07-22 01:15:14 +08:00
feat: prepare experiment push package
This commit is contained in:
@@ -6,6 +6,12 @@ BlueArchive Toolkit 采用 **Monorepo + 多语言混合** 架构，旨在构建
|
||||
|
||||
当前文档描述目标架构。实际实现状态以根目录 `CURRENT_STATUS.md` 和 `PROJECT_PLAN.md` 为准。
|
||||
|
||||
当前已经可用的官方资源入口包括：
|
||||
|
||||
- `infrastructure/examples/official_launcher_bootstrap.rs`
|
||||
- `infrastructure/examples/official_pull_plan.rs`
|
||||
- `docs/guides/official-resource-test-pull.md`
|
||||
|
||||
已接受的架构决策：
|
||||
|
||||
- `adr/0001-engine-and-application-boundaries.md`：Rust 引擎与 Go 应用层边界。
|
||||
@@ -361,6 +367,7 @@ API Server (多实例)
|
||||
|
||||
更多详细设计文档：
|
||||
|
||||
- [官方资源后端说明](./official-resource-backend.md)
|
||||
- [CAS 存储引擎设计](./cas-storage.md)
|
||||
- [AssetBundle 解析器设计](./assetbundle-parser.md)
|
||||
- [翻译系统设计](./translation-system.md)
|
||||
|
||||
@@ -0,0 +1,193 @@
|
||||
# 官方资源后端说明
|
||||
|
||||
本文档说明 BlueArchiveToolkit 中“官方资源后端”的职责、数据流和工作原理，供审核使用。
|
||||
|
||||
## 1. 范围
|
||||
|
||||
这个后端只处理 **日服官方资源**，只接受官方 `.jp/.com` 域名下的资源链路。
|
||||
|
||||
明确排除：
|
||||
|
||||
- `bluearchive.cafe`
|
||||
- 任何镜像层、转写层、二次代理层
|
||||
- 人工拼接出来的样例 URL
|
||||
|
||||
当前默认平台集合是：
|
||||
|
||||
- `Windows`
|
||||
- `Android`
|
||||
|
||||
`iOS` 和 `macOS` 已从默认支持中移除。
|
||||
|
||||
## 2. 后端负责什么
|
||||
|
||||
| 层 | 任务 | 结果 |
|
||||
|---|---|---|
|
||||
| 发现层 | 读取官方 `server-info`，选择 connection group 和版本覆盖 | 得到官方资源根和种子端点 |
|
||||
| 清单层 | 解析 `BundlePackingInfo.bytes`、`TableCatalog.bytes`、`MediaCatalog.bytes` | 得到完整文件清单 |
|
||||
| 计划层 | 合并 discovery + inventory，去重并保序 | 得到全量 pull plan |
|
||||
| 下载层 | 校验官方 URL，调用下载器，落盘并记录字节数 | 得到本地资源副本 |
|
||||
| 导入层 | 将 bundle 写入 CAS 和 ResourceRepository | 得到可查询的资源索引 |
|
||||
| 同步层 | 比较当前快照和历史快照 | 决定下载、校验、发布 |
|
||||
|
||||
## 3. 工作原理
|
||||
|
||||
### 3.1 发现官方资源根
|
||||
|
||||
入口是 `YostarJpServerInfo`。
|
||||
|
||||
流程是：
|
||||
|
||||
1. 读取官方 `server-info` JSON。
|
||||
2. 按 `connection_group + app_version` 规则选择版本覆盖。
|
||||
3. 从 `AddressablesCatalogUrlRoot` 提取 `root token`。
|
||||
4. 校验该 root 只能落在官方 `prod-clientpatch.bluearchiveyostar.com` 之下。
|
||||
5. 基于 root token 生成 discovery 端点。
|
||||
|
||||
对应实现主要在：
|
||||
|
||||
- `adapters/src/official/yostar_jp.rs`
|
||||
|
||||
### 3.2 枚举完整资源清单
|
||||
|
||||
资源清单不是“猜几个文件”，而是从官方 catalog 字节里提取完整文件名列表。
|
||||
|
||||
当前做法：
|
||||
|
||||
1. 读取 `BundlePackingInfo.bytes`。
|
||||
2. 提取所有 `FullPatch_*.zip` 包名。
|
||||
3. 读取 `TableCatalog.bytes`。
|
||||
4. 提取所有表资源名，例如 `ExcelDB.db`。
|
||||
5. 读取 `MediaCatalog.bytes`。
|
||||
6. 提取所有媒体资源名，例如 `JP_Airi.zip`。
|
||||
|
||||
然后对 verified platforms 生成完整 URL 集：
|
||||
|
||||
- Windows patch pack
|
||||
- Android patch pack
|
||||
- TableBundles
|
||||
- MediaResources-Windows
|
||||
- MediaResources
|
||||
|
||||
对应实现主要在：
|
||||
|
||||
- `adapters/src/official/inventory.rs`
|
||||
- `adapters/src/official/yostar_jp.rs`
|
||||
|
||||
### 3.3 组装全量 pull plan
|
||||
|
||||
`OfficialResourcePullPlan` 是这个后端的关键对象。
|
||||
|
||||
它做三件事：
|
||||
|
||||
1. 保存 discovery 端点。
|
||||
2. 保存完整 inventory。
|
||||
3. 用默认平台集或指定平台集生成最终 URL 列表。
|
||||
|
||||
`all_urls()` 是执行层的权威输入：
|
||||
|
||||
- 先放 discovery URLs
|
||||
- 再放 content URLs
|
||||
- 统一去重
|
||||
- 保持顺序
|
||||
|
||||
这意味着后端拉取的是 **完整资源包集合**，不是抽样下载。
|
||||
|
||||
对应实现主要在：
|
||||
|
||||
- `infrastructure/src/official_pull.rs`
|
||||
|
||||
### 3.4 执行下载
|
||||
|
||||
`OfficialResourcePullService` 负责真正下载。
|
||||
|
||||
工作方式：
|
||||
|
||||
1. 检查 URL 是否属于官方 host。
|
||||
2. 把 URL 映射到本地输出路径。
|
||||
3. 通过系统 `curl` 下载。
|
||||
4. 记录文件大小和最终路径。
|
||||
5. 非官方 URL 直接拒绝。
|
||||
|
||||
路径映射时会做分段清理，避免把不安全路径写进输出目录。
|
||||
|
||||
对应实现主要在：
|
||||
|
||||
- `infrastructure/src/official_download.rs`
|
||||
|
||||
### 3.5 导入到 CAS 和资源仓储
|
||||
|
||||
资源下载后，导入层会：
|
||||
|
||||
1. 把 bundle 原始字节写入 CAS。
|
||||
2. 解析 UnityFS 基础摘要。
|
||||
3. 把资源条目写入 `ResourceRepository`。
|
||||
4. 记录资源路径、hash、大小和解析摘要。
|
||||
|
||||
这层的意义是把“下载到磁盘的文件”变成“可查询、可复用、可去重”的资源对象。
|
||||
|
||||
对应实现主要在：
|
||||
|
||||
- `infrastructure/src/import.rs`
|
||||
- `infrastructure/src/resources.rs`
|
||||
|
||||
### 3.6 同步决策
|
||||
|
||||
同步层只做判断，不做重业务。
|
||||
|
||||
它比较当前快照和历史快照，关注：
|
||||
|
||||
- root token 是否变化
|
||||
- addressables root 是否变化
|
||||
- endpoint 是否变化
|
||||
- bundle version 是否变化
|
||||
|
||||
判断结果分三类：
|
||||
|
||||
- `UpToDate`
|
||||
- `DownloadAndVerify`
|
||||
- `DownloadVerifyAndPublish`
|
||||
|
||||
对应实现主要在：
|
||||
|
||||
- `infrastructure/src/official_sync.rs`
|
||||
|
||||
## 4. 官方 bootstrap 与用户流程
|
||||
|
||||
当前已经提供的官方用户流程是：
|
||||
|
||||
1. `official_launcher_bootstrap` 获取官方 launcher 信息。
|
||||
2. `official_game_main_config` 从官方 ZIP 解出并解密 `GameMainConfig`。
|
||||
3. `official_pull_plan` 依据官方 `server-info`、catalog 和 verified platforms 生成全量拉取计划。
|
||||
|
||||
这些入口都只接受官方域名，不走 `bluearchive.cafe` 镜像链。
|
||||
|
||||
## 5. 已验证行为
|
||||
|
||||
当前代码已经验证：
|
||||
|
||||
- 默认平台是 `Windows + Android`
|
||||
- `iOS` 和 `macOS` 不再进入默认官方流程
|
||||
- verified inventory 会产出完整内容 URL 集
|
||||
- pull plan 会同时包含 discovery URLs 和 content URLs
|
||||
- 全量样本下是 `2` 个 discovery URL + `5` 个内容 URL = `7` 个 URL
|
||||
|
||||
相关验证主要来自：
|
||||
|
||||
- `cargo test -p bat-adapters`
|
||||
- `cargo test -p bat-infrastructure`
|
||||
- `cargo test -p bat-adapters --examples`
|
||||
- `cargo test -p bat-infrastructure --examples`
|
||||
- `cargo clippy -p bat-adapters -- -D warnings`
|
||||
- `cargo clippy -p bat-infrastructure -- -D warnings`
|
||||
|
||||
## 6. 审核重点
|
||||
|
||||
请重点检查这几件事：
|
||||
|
||||
1. 是否只接受官方 host。
|
||||
2. 是否默认只走 Windows + Android。
|
||||
3. 是否把完整 content URL 集都纳入 `all_urls()`。
|
||||
4. 是否拒绝镜像域名和手工拼接样例。
|
||||
5. 是否在下载前做了 URL 和路径安全校验。
|
||||
6. 是否能在官方客户端变动时只改适配层。
|
||||
@@ -0,0 +1,132 @@
|
||||
# 官方资源拉取用户指南
|
||||
|
||||
本文档描述当前可用的官方日服资源拉取流程。
|
||||
|
||||
默认平台：
|
||||
|
||||
- `Windows`
|
||||
- `Android`
|
||||
|
||||
不包含：
|
||||
|
||||
- `iOS`
|
||||
- `macOS`
|
||||
- `bluearchive.cafe` 或其他镜像域名
|
||||
- 任何本地客户端目录
|
||||
|
||||
## 1. 当前流程
|
||||
|
||||
运行时链路只走官方日服：
|
||||
|
||||
1. 请求官方 launcher API。
|
||||
2. 从官方 launcher manifest 链路得到最新游戏包 ZIP。
|
||||
3. 解包 `resources.assets`。
|
||||
4. 解密 `GameMainConfig`。
|
||||
5. 从 `GameMainConfig` 自动读取 `server-info` URL 和默认 `connection-group`。
|
||||
6. 请求官方 `server-info`。
|
||||
7. 生成 Windows + Android 的官方资源 discovery 端点。
|
||||
8. 拉取 seed catalog，生成完整官方 pull plan。
|
||||
9. dry-run 只输出 URL；非 dry-run 下载全部官方 URL。
|
||||
|
||||
`--server-info-file` 和 `--server-info-path` 都不是硬依赖。
|
||||
|
||||
## 2. 先做 launcher bootstrap
|
||||
|
||||
先确认 launcher API 和官方 ZIP 链路正常：
|
||||
|
||||
```bash
|
||||
cargo run -p bat-infrastructure --example official_launcher_bootstrap -- \
|
||||
--launcher-version 1.7.2 \
|
||||
--manifest
|
||||
```
|
||||
|
||||
这一步会输出：
|
||||
|
||||
- `game_latest_version`
|
||||
- `game_latest_file_path`
|
||||
- `primary_cdn`
|
||||
- `backup_cdn`
|
||||
- `manifest_url`
|
||||
- `manifest_source`
|
||||
- `manifest_file_count`
|
||||
|
||||
所有 URL 都应来自官方域名。
|
||||
|
||||
## 3. 先做 dry-run
|
||||
|
||||
推荐默认流程是不提供本地 `server-info` 文件，也不提供本地客户端目录：
|
||||
|
||||
```bash
|
||||
cargo run -p bat-infrastructure --example official_pull_plan -- \
|
||||
--launcher-bootstrap \
|
||||
--platforms Windows,Android \
|
||||
--output /tmp/ba-official-pull \
|
||||
--dry-run
|
||||
```
|
||||
|
||||
如果你已经有官方 `server-info` 文件，也可以显式传入：
|
||||
|
||||
```bash
|
||||
cargo run -p bat-infrastructure --example official_pull_plan -- \
|
||||
--server-info-file r93_70_xxxxxxxxxxxxxxxxxxxx.json \
|
||||
--connection-group Prod-Audit \
|
||||
--app-version 1.70.0 \
|
||||
--platforms Windows,Android \
|
||||
--output /tmp/ba-official-pull \
|
||||
--dry-run
|
||||
```
|
||||
|
||||
检查输出时，重点看：
|
||||
|
||||
- `platforms=[Windows, Android]`
|
||||
- `discovery_url_count` 大于 0
|
||||
- `content_url_count` 大于 0
|
||||
- 不出现 `bluearchive.cafe`
|
||||
|
||||
## 4. 执行真实拉取
|
||||
|
||||
确认 dry-run 正常后，去掉 `--dry-run`：
|
||||
|
||||
```bash
|
||||
cargo run -p bat-infrastructure --example official_pull_plan -- \
|
||||
--launcher-bootstrap \
|
||||
--platforms Windows,Android \
|
||||
--output /tmp/ba-official-pull
|
||||
```
|
||||
|
||||
程序会：
|
||||
|
||||
- 只接受官方 URL
|
||||
- 下载完整官方资源集合
|
||||
- 把结果写入 `--output`
|
||||
|
||||
## 5. 例外输入
|
||||
|
||||
如果必须使用本地 `server-info`，只接受：
|
||||
|
||||
- `--server-info-file <官方文件名>`
|
||||
- `--server-info-path <本地官方 JSON>`
|
||||
|
||||
但这两项不再是主流程依赖。
|
||||
|
||||
## 6. 代码入口
|
||||
|
||||
当前可用的用户入口：
|
||||
|
||||
- `infrastructure/examples/official_launcher_bootstrap.rs`
|
||||
- `infrastructure/examples/official_pull_plan.rs`
|
||||
- `adapters/examples/yostar_jp_client_bootstrap.rs`
|
||||
- `adapters/examples/yostar_jp_discovery.rs`
|
||||
- `adapters/examples/yostar_jp_inventory.rs`
|
||||
|
||||
## 7. 验证
|
||||
|
||||
推荐验证命令：
|
||||
|
||||
```bash
|
||||
cargo test -p bat-adapters
|
||||
cargo test -p bat-infrastructure
|
||||
cargo test -p bat-infrastructure --example official_launcher_bootstrap -- --nocapture
|
||||
cargo test -p bat-infrastructure --example official_pull_plan -- --nocapture
|
||||
```
|
||||
|
||||
@@ -274,6 +274,10 @@
|
||||
|
||||
- README 明确区分已实现、开发中、规划中。
|
||||
|
||||
状态：
|
||||
|
||||
- 已部分修正，当前 README 已明确列出已具备与未完成项，并增加当前阶段说明入口。
|
||||
|
||||
### G-016：架构文档需要更新为当前路线图
|
||||
|
||||
现象：
|
||||
@@ -285,6 +289,10 @@
|
||||
- 增加 ADR 或架构决策记录。
|
||||
- 明确 Rust/Go/DB/Plugin 边界。
|
||||
|
||||
状态：
|
||||
|
||||
- 已部分修正，`docs/architecture/README.md` 已增加当前可用官方资源入口，但仍保留目标架构描述，因此只算阶段性对齐完成。
|
||||
|
||||
### G-017：CI 未落地
|
||||
|
||||
影响：
|
||||
|
||||
@@ -0,0 +1,48 @@
|
||||
# 当前阶段说明
|
||||
|
||||
**更新时间**：2026-06-29
|
||||
**状态分支**：`experiment`
|
||||
**用途**：推送前核查与当前阶段交付说明。
|
||||
|
||||
## 1. 当前目标
|
||||
|
||||
当前阶段聚焦两件事：
|
||||
|
||||
1. 准备推送前的项目核查。
|
||||
2. 补齐当前阶段的文档说明。
|
||||
|
||||
## 2. 当前实现状态
|
||||
|
||||
已确认可用的内容：
|
||||
|
||||
- `bat-cas-engine` 的 CAS V1 已完成。
|
||||
- `bat-adapters` 的官方日服 URL 规则、官方 launcher bootstrap、官方 GameMainConfig bootstrap、官方 pull plan 已可用。
|
||||
- `bat-infrastructure` 的官方 bootstrap / pull integration 测试已通过。
|
||||
- 官方资源链路已经明确只接受官方 host，不依赖 `bluearchive.cafe` 镜像。
|
||||
|
||||
实验性处理内容：
|
||||
|
||||
- 官方 bootstrap / pull 测试夹具已收敛为 synthetic fixture，并单独留在 `experiment` 分支语义下。
|
||||
- 这些 fixture 只用于验证官方链路，不代表运行时真实线上值。
|
||||
|
||||
## 3. 当前核查结果
|
||||
|
||||
已执行的验证：
|
||||
|
||||
- `cargo test -p bat-infrastructure --test official_game_main_config_bootstrap -- --nocapture`
|
||||
- `cargo test -p bat-infrastructure`
|
||||
- `cargo test -p bat-adapters`
|
||||
|
||||
结果：
|
||||
|
||||
- 全部通过。
|
||||
|
||||
## 4. 当前结论
|
||||
|
||||
当前代码可以继续进入推送准备阶段，但仓库仍包含大量未整理的既有改动，暂不应把当前工作区视作“只剩最终提交”的干净状态。
|
||||
|
||||
下一步应当继续做：
|
||||
|
||||
- 归整实验性改动与主线改动的边界。
|
||||
- 按分支策略确认哪些内容允许进入 `dev`，哪些应保留在 `experiment`。
|
||||
- 再做一次提交前检查和差异审阅。
|
||||
Reference in New Issue
Block a user