# 官方全量拉取 Smoke Runbook

本文档固定真实官方网络全量拉取 smoke 的可重复命令。该流程会访问官方日服 HTTP 资源并下载完整 Windows + Android 资源集合，输出目录必须是隔离目录。

## 目标

验证当前 `bat` 能在真实官方网络环境下完成：

1. `--auto-discover --dry-run --plan`
2. 首次全量拉取并发布到 `current`
3. 第二次运行返回 `up_to_date`
4. 人工破坏 active release 中一个资源文件
5. `repair` 检出并重新下载损坏文件
6. `verify` 在 repair 后通过

## 一条命令

默认写入 `/tmp/bat-official-smoke-<UTC timestamp>/`：

```bash
scripts/official-full-pull-smoke.sh
```

也可以通过 Makefile 执行：

```bash
make official-smoke
```

脚本默认会先构建 release binary：

```bash
cargo build --release -p bat-infrastructure --bin bat
```

## 输出

默认目录结构：

```text
/tmp/bat-official-smoke-<timestamp>/
  resources/
    current -> versions/<id>
    versions/<id>/
    .staging/
  state/
  report/
    01-dry-run-plan.command.txt
    01-dry-run-plan.stdout.json
    01-dry-run-plan.stderr.log
    02-first-full-pull.command.txt
    02-first-full-pull.stdout.json
    02-first-full-pull.stderr.log
    03-second-up-to-date.command.txt
    03-second-up-to-date.stdout.json
    03-second-up-to-date.stderr.log
    04-repair-after-damage.command.txt
    04-repair-after-damage.stdout.json
    04-repair-after-damage.stderr.log
    05-verify-after-repair.command.txt
    05-verify-after-repair.stdout.json
    05-verify-after-repair.stderr.log
    damaged-file.txt
    damaged-file.before.txt
    SMOKE_REPORT.md
```

`damaged-file.before.txt` 只记录被破坏文件的路径、大小和 sha256，不复制原始资源文件。`SMOKE_REPORT.md` 记录本次 smoke 的实际输出目录、active release、文件数量、release 大小和被破坏的文件。大型资源文件不进入 Git。

脚本会在关键步骤后自动检查：

- 首次全量拉取 stderr log 包含总体下载进度、单文件进度和校验结果。
- 二次运行 stdout JSON 包含 `update_status=up_to_date`。
- repair stdout JSON 包含 `command=repair` 和 `status=completed`。
- repair stderr log 包含总体下载进度、单文件进度和校验结果。
- repair 后 verify stdout JSON 包含 `healthy=true`。

## 环境变量

- `BAT_SMOKE_ROOT`：覆盖默认根目录。
- `BAT_SMOKE_OUTPUT`：覆盖资源发布根目录。
- `BAT_SMOKE_STATE_DIR`：覆盖 daemon/status 目录。
- `BAT_SMOKE_REPORT_DIR`：覆盖报告目录。
- `BAT_BIN`：使用已有 `bat` binary。
- `BAT_SMOKE_SKIP_BUILD=1`：跳过 release 构建。
- `BAT_SMOKE_ALLOW_NON_TMP=1`：允许 `BAT_SMOKE_OUTPUT` 指向非 `/tmp` 路径。只可用于确认隔离的测试目录。

## 安全边界

脚本默认拒绝非 `/tmp` 输出目录，且拒绝复用非空输出目录。不要把输出目录指向已有客户端、官方启动器安装目录、生产资源目录或开发机人工维护资源目录。

## 成功判定

脚本全部步骤退出码为 0 即表示 smoke 通过。重点检查：

- `03-second-up-to-date.stdout.json` 中 `update_status` 为 `up_to_date`。
- `04-repair-after-damage.stdout.json` 中 repair 完成，且有重新下载或修复行为。
- `05-verify-after-repair.stdout.json` 中 `healthy` 为 `true`。
- `02-first-full-pull.stderr.log` 和 `04-repair-after-damage.stderr.log` 中包含下载总体进度、单文件进度和校验结果日志。