fix(bat-api): 完成 issue #19 同机 live 联调

docs/guides/bat-api-local-live-smoke.md

@@ -0,0 +1,40 @@
+# bat-api 同机 live 联调
+
+## 目的
+
+该 runbook 验证生产拓扑的本地形态：Rust `bat` 与 Go `bat-api` 在同一主机上运行，二者通过同一个 `bat.sock` Unix socket 和同一个已发布资源文件系统协作。
+
+测试使用仓库内完整 release fixture，并把所有 daemon、HTTP 服务、release 目录和报告写入一个新的 `/tmp` 隔离目录。它不访问官方网络，不读取现有客户端目录，也不写入开发机生产资源目录。
+
+## 命令
+
+```bash
+make bat-api-local-live-smoke
+```
+
+脚本会按需构建 `bat` 和 `bat-api`，然后在同一临时目录中：
+
+1. 创建版本化 release、`official-version-state.json` 和 `current` symlink。
+2. 启动真实 Rust `bat --daemon`，验证 live `bat.sock` RPC。
+3. 启动 Go `bat-api`，通过 RPC 发现 `resource_root` 和 manifest；Go 不读取 daemon 状态文件。
+4. 验证 `/healthz`、`/readyz`、`/v1/bootstrap`、server-info 和 launcher resource bootstrap。
+5. 验证 CDN `GET`、`HEAD`、`Range`、ETag、Last-Modified、缓存头、未索引路径和编码 dot-segment 越界路径。
+6. 切换 `current` 到下一个已发布版本，确认 API 索引跟随 RPC 返回的版本变化。
+7. 清空已发布版本，确认旧索引不会继续分发，`/readyz` 返回 `503`。
+8. 停止并重启 Rust daemon，确认 RPC 断开时 API 返回未 ready，重连后恢复 ready。
+
+成功时脚本输出 `LOCAL_BAT_API_LIVE_SMOKE_OK`，并打印类似以下报告路径：
+
+```text
+/tmp/bat-api-local-live-<UTC timestamp>/report/SMOKE_REPORT.md
+```
+
+报告目录不提交 Git；需要审阅时应保存该次命令输出和报告目录位置。
+
+## 生产边界
+
+- Rust `bat` 负责官方发现、下载、校验、发布、版本状态和 `bat.sock` RPC。
+- Go `bat-api` 只通过 RPC 发现已发布 `resource_root` 和 manifest，并提供 HTTP bootstrap/CDN 读服务。
+- 生产中两者必须使用同一主机、同一容器或同一共享文件系统；`bat.sock` 不应暴露到公网。
+- `--resource-root` / `BAT_API_RESOURCE_ROOT` 只用于 fixture 或应急只读诊断，不能替代生产 RPC 发现。
+- `make official-smoke` 是独立的官方网络全量拉取 runbook；本文件的本地 fixture smoke 不证明官方网络可达或官方全量资源下载成功。