BlueArchiveToolkit/CHANGELOG.md

# 变更日志

所有重要的项目变更都将记录在此文件中。

本项目遵循 [语义化版本](https://semver.org/lang/zh-CN/)。

## [未发布]

### 新增
- Addressables catalog 提取 `m_Crc`（bundle IEEE CRC-32）：`ResourceEntry` 新增 `crc` 字段（compact/expanded 两种形态均解析），SQLite 持久化并对旧库幂等迁移补列；core 新增 `crc32_ieee` 与 `ResourceEntry::verify_downloaded_bytes`（按声明的 size/CRC 校验字节）（issue #2）
- UnityFS 解析新增目录条目越界校验：directory 的 `offset+size` 必须落在解压数据区内，截断/损坏 bundle 的越界目录条目不再被静默接受（issue #3）
- 官方资源下载使用默认 8 个独立 worker；每个 worker 完成当前 URL 后立即从共享计划队列领取下一个任务，manifest/quarantine 簿记与 seed `.hash` 校验逐项保持一致，`fail-fast` 与「不发布不完整资源」不变量不变（issue #17 的历史决定不代表当前并发实现）
- 新增 `cmd/bat-api` 资源 bootstrap/分发 HTTP 服务（issue #19 / G-009 资源面）：与 Rust `bat` 同环境运行，经 `bat.sock` RPC（`daemon.status` → `daemon.doctor` → catalog/manifest）发现已发布 release 和 `resource_root`，按官方 CDN host/path 只读提供资源；管理面 `/healthz` `/v1/release` `/v1/resources`；可选 server-info 仅改写 Addressables root；`.env` 配置监听端口/RPC socket/刷新周期/预留数据库键。资源自动拉取仍由 Rust `bat` 负责
- `cmd/bat-api` 新增 `/v1/bootstrap`：把 Rust `bat` 的 RPC 健康、已发布 release 摘要、server-info URL、client-patch base 和改写后的 Addressables root 组织成启动前资源发现响应，固定 `bat` 是资源生产者、`bat-api` 是只读 bootstrap/分发层的关系
- `bat-api` CDN 分发补齐 Range / HEAD / 条件请求语义：基于 manifest BLAKE3 生成 ETag，返回 Last-Modified、Accept-Ranges 和长期缓存头，`.hash` 以 `text/plain` 返回
- `bat-api` 增加 RPC 周期刷新（`BAT_API_REFRESH_INTERVAL` / `--refresh-interval`），用于跟随远程长期运行的 Rust `bat` 发布新 release；生产不应写死 `BAT_API_RESOURCE_ROOT`
- `bat-api` 增加 refresh 诊断和 `/readyz`：`/healthz` 暴露最近一次 RPC refresh 的时间、耗时、warning 和错误，`/readyz` 在无可分发 release 时返回 `503`
- `bat-api` 增加 launcher 资源引导兼容：`/v1/launcher/bootstrap`、`/api/launcher/game/config`、`/api/launcher/game/config/json`、`/api/launcher/advanced/game/download/cdn` 及 `/api-launcher-jp.yo-star.com/...` host 形状入口，响应来自 Rust `bat` 已发布 snapshot/RPC，明确不提供登录、网关、鉴权或完整 package update manifest
- `bat-api` 增加玩家-facing HTTP 控制面：token 鉴权、进程内限流、访问日志、反代 IP 适配、安全响应头、动态 JSON `Cache-Control: no-store`、`/v1/resources` 分页上限、统一 JSON error、OpenAPI (`/openapi.yaml`) 和 `/admin/` 管理面板预留
- 新增 `deployments/systemd/bluearchive-toolkit-bat-api.service` 和 `deployments/systemd/bat-api.env.example`，固定 bat-api 通过本机 `bat.sock` 获取资源根的部署契约
- USERGUIDE 补充 `bat-api` 资源 bootstrap / 分发章节，说明与 Rust `bat` 的运行关系、接口、CDN 响应语义和不仿造业务 API 的边界
- 官方同步新增 `official-parse-cache.json`：校验发布后从下载 manifest 覆盖直接 UnityFS bundle、zip 内 UnityFS 条目和非候选资源记录；URL、相对路径、size 和 BLAKE3 未变化时跳过重复解析
- 官方原版资源和汉化产物目录分离：`BAT_OUTPUT`/`--output` 默认 `./bat-resources`，`BAT_LOCALIZED_OUTPUT`/`--localized-output` 默认 `./bat-localized`；同步报告新增 `localized_release_status=not_localized`，后续 Patch 发布完成后才切换为 `localized`

### 修复
- 官方下载失败重试之间加入指数退避（网络类失败 200ms→400ms→800ms…，上限 5s）

### 计划
- [ ] `bat-api` 后续：全量 release 联调、refresh mtime/size 增量缓存、完整 launcher 安装包更新链（若需要，新 issue）、API 持久化层接入预留 database/redis 配置；Rust/Go snapshot contract fixture 已落仓库
- [ ] 官方同步结果接入 CAS + ResourceRepository 的用户级工作流
- [ ] 官方下载/导入路径接入 CRC/size 校验（复用 `verify_downloaded_bytes`）
- [ ] 汉化 Patch 发布：维护 `localized-output/current`、`localized-version-state`、`localized` 状态切换和回滚
- [ ] 实现翻译系统
- [ ] 完成发布级 Patch build/rollback、复杂 AssetBundle 重打包和汉化发布统一
- [ ] 实现 Web 管理后台

## [0.2.0] - 2026-07-17

### 新增
- 引入统一 `BAT-ERR` 错误码模型（`ErrorCode` / `ApiError`：数字码、kind、域、位置、可重试标记），接入下载、launcher/metadata、server-info/marker 与配置校验路径；新增 `USERGUIDE.md` 用户指南（命令、选项、退出码、错误码参考、RPC 接口）
- daemon 的 `bat.sock` Unix socket JSON-RPC 扩展为面向 Go 服务层的 Rust Resource Backend API：统一应用层 envelope（`ok`/`status`/`data`/`error`/`request_id`），方法覆盖 `daemon.*`（status/logs/stop/reload/refresh）、`resource.*`（state/sync/verify/manifest）、`catalog.*`（status/versions/diff/refresh）、`task.*`（status/list/cancel/logs）
- 新增异步任务执行器：`resource.sync` / `resource.verify` / `catalog.refresh` 入队即返回 `task_id`，单 worker FIFO 串行执行并与 watch 循环互斥，支持进度日志与协作式取消
- 任务历史文件态持久化 `<state-dir>/bat-tasks.json`（版本化、`0600` 原子写）：daemon 重启后任务历史仍可查，中断任务标记 `task_interrupted`（`BAT-ERR-700005`）
- 新增 `.env` 无参启动：`bat` 首次启动在二进制所在目录释放配置模板（`0600`）并自动加载，优先级为命令行参数 > 进程环境变量 > `.env` > 内置默认值，Redis 配置键预留
- 初始化 Monorepo 项目结构
- 创建 Rust workspace (bat-cas-engine, bat-assetbundle, bat-patch, bat-ffi)
- 创建 Go module 结构
- 配置 Docker Compose 支持本地和远程数据库
- 添加 Makefile 统一构建入口
- 创建架构文档和开发指南
- 完成 CAS V1：原子写入、BLAKE3 校验、SQLite 引用计数、GC、并发写入测试和损坏检测
- 新增官方日服资源同步链路：auto-discover、pull plan、snapshot、marker diff、本地 manifest audit/repair
- 新增 Rust 官方同步 binary，当前正式入口为 `bat`，支持 one-shot、`--watch`、默认 1 小时间隔、人类可读默认输出和 `--json` 结构化 report
- 官方同步正式入口统一为 `bat`，新增 `--daemon` 后台模式和基于 `bat.sock` 的 Unix socket JSON-RPC 控制面，管理命令覆盖 `status`、`stop`、`restart`、`reload`、`refresh`、`logs`、`verify`、`repair`、`doctor`、`clean-stable`
- 新增 daemon 控制锁 `bat-control.lock`、daemon 与前台同资源目录写入互斥，以及失效/损坏 PID 和锁文件恢复逻辑
- 新增官方同步路径安全边界：拒绝危险输出目录和 snapshot 路径逃逸，下载目标、manifest、daemon PID/status/log/control 文件不跟随 symlink，daemon 状态文件默认使用 `0600` 权限
- 新增官方资源原子发布布局：非 dry-run 下载先进入 `.staging/<id>`，校验和 manifest/snapshot 写入完成后发布到 `versions/<id>`，再原子切换 `current` symlink
- 新增 daemon 可观测性：`bat-events.jsonl` 结构化 JSONL 日志、日志轮转、status 中的当前下载进度、最后成功时间、下次检查时间和最后错误摘要
- 新增运行时下载与校验 progress log：下载已完成计数、单文件开始/完成状态、官方 `.hash`、本地 BLAKE3、需修复项和 ZIP 结构校验摘要
- 新增官方资源同步生产部署模板：release binary symlink 路径、systemd unit、运行用户、日志位置、升级和回滚流程
- 新增真实官方网络全量拉取 smoke：`scripts/official-full-pull-smoke.sh`、`make official-smoke` 和 `docs/guides/official-full-pull-smoke.md`
- 新增官方资源下载校验：官方 URL 拒绝、`.part` 续传、重试、本地 size+BLAKE3、官方 seed `.hash` 校验
- 新增下载失败分类与 quarantine：403/404/普通 4xx 不重试，5xx/429/网络类错误重试，最终失败写入 `official-download-quarantine.json` 并阻止发布不完整资源；旧 launcher 包支持官方 primary/backup CDN 切换
- 新增官方版本状态管理：`official-version-state.json` 持久化当前已完成版本、正在拉取版本、上一个可用版本和失败版本，并在 `bat status` 中暴露状态摘要
- 优化资源导入链路：CAS 导入会写入 `ResourceRepository`，AssetBundle 记录 UnityFS 摘要，TextAsset/Table/Media 按资源类型分类并可被索引
- 新增离线回归 fixture：当前 catalog、上一个版本 catalog、catalog 结构变化、403、404 和官方 seed hash mismatch 样本
- 新增 Addressables 当前真实形态 fixture/golden 测试
- 新增 SQLite Resource Repository 和粗粒度 FFI JSON 接口
- 补齐官方资源运行、架构、状态、缺口和交接文档

### 修复
- 修正 Unity 版本范围比较：改为按 `(major, minor, patch)` 数值比较，`2021.3.9f1` 等带发布后缀的正式版本号不再被字典序误判越界
- 将 curl 进程启动时的 `ETXTBSY`（可执行文件忙）归为可重试的瞬时竞态并加短退避，消除多线程测试环境下的偶发失败
- 修正对抗性审查发现的 launcher 链错误码误归类：非官方 CDN 根归 `non_official_url`、远端 manifest/包内容缺陷归 `launcher_response_invalid`、解压失败归完整性域
- 串行化 `bat-status.json` 的读-改-写，消除 daemon 状态文件并发写竞态

### 安全
- 代理凭据不再落入世界可读位置：传给 curl 子进程时经 `ALL_PROXY` 环境变量而非 `--proxy` 参数，不进 curl 的 `/proc/<pid>/cmdline`；`--daemon` 模式下代理凭据经环境变量下传后台子进程，不进子进程 argv 或 `bat-status.json`，复用凭据单独存于 `0600` 的 `bat-proxy.secret` 并在 `clean-stable` 后台停止后清除；日志与 `status` 输出对带凭据代理 URL 脱敏（含无 `scheme` 形式）；推荐带凭据代理用 `HTTPS_PROXY` 等环境变量配置

## [0.1.0] - 2026-06-27

### 新增
- 项目初始化
- 基础架构搭建