BlueArchiveToolkit/docs/architecture/official-resource-backend.md

官方资源后端说明

本文档说明 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. 是否能在官方客户端变动时只改适配层。