feat: prepare experiment push package

docs/architecture/official-resource-backend.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. 是否能在官方客户端变动时只改适配层。