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 不证明官方网络可达或官方全量资源下载成功。

docs/guides/deployment.md

@@ -356,7 +356,7 @@ sudo -u bat tar -C /var/lib/bluearchive-toolkit/official \
 
 ## 模式 4：bat-api 资源 bootstrap / 分发服务
 
-适用场景：真实 Rust `bat` 长期运行在远程服务器，并且同一服务器/容器环境内运行 Go `bat-api`，给客户端、补丁器或上层工具提供启动前资源入口和 CDN path 只读分发。
+适用场景：真实 Rust `bat` 长期运行在生产主机，并且同一主机/容器环境内运行 Go `bat-api`，给客户端、补丁器或上层工具提供启动前资源入口和 CDN path 只读分发。
 
 核心约束：
 
@@ -364,7 +364,7 @@ sudo -u bat tar -C /var/lib/bluearchive-toolkit/official \
 2. 当前资源目录由 `bat.sock` RPC 返回的 `resource_root` 决定；生产不要在 `bat-api` 配置里写死 `BAT_API_RESOURCE_ROOT`。
 3. `BAT_API_RESOURCE_ROOT` 只用于本地 fixture、临时只读诊断或 RPC 不可用时的应急验证。
 4. `bat.sock` 只在服务器本机使用，不通过公网暴露；对外只发布 HTTP `bat-api`，生产建议放在反向代理和 TLS 后面。
-5. 本地开发环境不需要、也不应全量运行 `bat`；使用 Go 单测、fixture release 或远程服务器联调。
+5. 本地开发环境不需要官方全量下载；使用 Go 单测、fixture release 和 `make bat-api-local-live-smoke`。该 smoke 在本地 `/tmp` 隔离目录启动真实 Rust daemon，不连接远程服务器。
 
 ### 构建和安装 bat-api
 
@@ -388,7 +388,7 @@ sudo ln -sfn \
 
 ### bat 侧前置条件
 
-`bat-api` 依赖 live RPC，而不是直接读取 daemon 状态文件。部署 `bat-api` 前，远程服务器上应已有 socket 形态的 Rust `bat`：
+`bat-api` 依赖 live RPC，而不是直接读取 daemon 状态文件。部署 `bat-api` 前，部署所在生产主机上应已有 socket 形态的 Rust `bat`：
 
 ```bash
 sudo -u bat /opt/bluearchive-toolkit/bin/bat \
@@ -492,7 +492,7 @@ BAT_API_SKIP_ENV_FILE=1 go run ./cmd/bat-api \
   --refresh-interval 0
 ```
 
-这条本地命令只验证 HTTP 形态、server-info 改写、CDN path、Range/缓存语义和管理接口；真实全量 release 联调应在远程长期运行的 `bat` 环境里执行。
+这条本地命令只验证 HTTP 形态、server-info 改写、CDN path、Range/缓存语义和管理接口；同机 live 联调使用 `make bat-api-local-live-smoke`，真实官方网络下载则使用独立的 `make official-smoke`。
 
 ---
 

docs/guides/development.md

@@ -160,10 +160,11 @@ Go 边界与进度以 `docs/reports/GO_STATUS.md` 为准：
 - 试验 CLI 产物为 `bin/bat-go`（`make build-go-cli`），**禁止**与 Rust `bat` 重名
 - 修改 FFI 时再跑 `make test-go-ffi`
 
-开发环境不能本地全量运行 Rust `bat` 时，`bat-api` 不需要真实生产资源目录。用 fixture 或 mock RPC 验证服务面；生产联调再连接远程服务器上同环境运行的 `bat.sock`：
+`bat-api` 与 Rust `bat` 的生产拓扑是同一主机、同一容器或同一共享文件系统。开发时优先使用隔离 fixture 和本地 `bat.sock` live smoke，不连接远程服务器，也不读取现有客户端目录：
 
 ```bash
 make test-go-api
+make bat-api-local-live-smoke
 BAT_API_SKIP_ENV_FILE=1 go run ./cmd/bat-api \
   --listen 127.0.0.1:18080 \
   --public-base-url http://127.0.0.1:18080 \
@@ -171,6 +172,8 @@ BAT_API_SKIP_ENV_FILE=1 go run ./cmd/bat-api \
   --refresh-interval 0
 ```
 
+其中 `make bat-api-local-live-smoke` 会在 `/tmp` 中启动真实 Rust daemon 和 Go API，覆盖 release 切换、清单不完整、无 release、RPC 断开、server-info、CDN Range/缓存和路径越界；报告保留在该次 smoke 的临时目录。单独的 `--resource-root` 命令只验证 fixture HTTP 形态，不替代 live socket 联调。
+
 生产默认路径仍是 `--socket` / `BAT_API_SOCKET`，资源根由 Rust `bat` RPC 返回；`--resource-root` 只用于上述 fixture 或应急只读诊断。
 
 ### 常用聚焦命令

docs/reference/rpc-backend-api.md

@@ -447,8 +447,9 @@ Rust dispatch、Go transport 和 bat-api 接口的权威实现位置分别是
 Go mirror contract fixture 固化在 `internal/api/testdata/contract/`，覆盖
 `catalog.status` available/unavailable、`resource.manifest` page0 和对应
 `official-sync-snapshot.json`。这些 fixture 由 Rust 输出归一化而来，只用于
-schema / mirror 回归；live daemon socket 和完整 release 切换仍需在允许 smoke 的
-隔离环境中验证。
+schema / mirror 回归；live daemon socket 和完整 fixture release 切换由
+`make bat-api-local-live-smoke` 在同机 `/tmp` 隔离环境中验证。该 smoke 不替代
+`make official-smoke` 的官方网络全量下载验证。
 
 禁止事项：
 

docs/reports/BAT_API_CONTRACT_FIXTURE_HANDOFF.md

@@ -1,6 +1,6 @@
 # bat-api / Rust bat Contract Fixture Handoff
 
-更新时间：2026-08-03
+更新时间：2026-08-29
 
 本文用于两个 Codex 窗口之间间接联调 `bat-api` 与 Rust `bat` 的跨语言 contract fixture。
 仓库内归一化 fixture 已交付；本文保留生成、审核和后续扩展的协作协议。
@@ -18,8 +18,8 @@
 - 联调不要求本地运行全量长期服务端 `bat`；允许 Rust 侧使用 fixture root 或临时目录走真实代码路径导出 JSON。
 - fixture 审核前只能放在 `/tmp/bat-contract-fixture/`，不能直接提交到仓库。
 - Go 侧已经实现 player-facing HTTP 鉴权、限流、访问日志、反代适配、OpenAPI 和
-  `/admin/` 控制入口；仓库内 contract fixture 已完成，剩余是 live daemon socket
-  和完整 release 切换联调。
+  `/admin/` 控制入口；仓库内 contract fixture 和同机 live daemon socket / 完整
+  fixture release 切换联调均已完成，命令为 `make bat-api-local-live-smoke`。
 - Go 侧当前相关代码入口：
   - `internal/api/rpc_release.go`
   - `internal/api/release_index.go`
@@ -206,6 +206,9 @@ contract fixture 工作只有在以下条件同时满足时才算完成：
   - `internal/api/testdata/contract/catalog-status.unavailable.json`
   - `internal/api/testdata/contract/resource-manifest.page0.json`
   - `internal/api/testdata/contract/official-sync-snapshot.json`
-- 原始交接产物仍位于 `/tmp/bat-contract-fixture/`；当前受本地 sandbox 限制，live socket daemon 无法启动，原始 JSON 通过临时 Rust 测试调用同一 dispatch/report 代码路径生成。
+- 原始交接产物仍位于 `/tmp/bat-contract-fixture/`；仓库内归一化 fixture 用于 schema/mirror 回归，
+  同机 live socket 验证使用 `make bat-api-local-live-smoke`，不依赖该交接目录。
 - Go contract 测试读取仓库内归一化 fixture，不依赖 `/tmp/bat-contract-fixture/`、开发机资源目录或远端长期运行的 `bat`。
-- 仍未覆盖真实长期 daemon socket 的端到端调用和完整发布切换；该项需要在允许 live daemon / smoke 的隔离环境中单独验证。
+- 真实长期 daemon 的生产部署仍需由部署环境持续运行；仓库已在本地隔离环境通过真实
+  daemon socket 完成端到端调用、版本切换、无 release、RPC 断线和恢复验证。真实官方
+  网络全量下载仍由 `make official-smoke` 独立负责。

docs/reports/CURRENT_GAPS.md

@@ -1,6 +1,6 @@
 # 当前实现缺口清单
 
-- **更新时间**：2026-08-03
+- **更新时间**：2026-08-29
 - **Go 进度权威**：`GO_STATUS.md`
 - **资源布局 / 逆向契约**：`../architecture/resource-release-layout.md`
 - **用途**：集中跟踪当前代码中的占位实现、设计缺口和下一步验收项。
@@ -248,11 +248,12 @@ issue 43 例外说明：新增的 `parse repack` 只编排已有 TextAsset、Typ
 - `cmd/bat-api`、`internal/api`、`/v1/bootstrap`、`/v1/launcher/bootstrap`、launcher 资源 metadata 兼容端点、HTTP token 鉴权、限流、访问日志、反代 IP 适配、动态 JSON `no-store`、`/v1/resources` 分页上限、OpenAPI、`/admin/` 管理控制白名单、RPC 周期刷新/诊断、`/readyz`、CDN Range/缓存头、fixture 单测、USERGUIDE 基础章节、systemd bat-api 模板、`make build-go-api` / `test-go-api`
 - 进度权威：`docs/reports/GO_STATUS.md`
 - Rust snapshot schema 与 Go mirror struct 的仓库内 contract fixture 已完成，文件位于
-  `internal/api/testdata/contract/`；剩余是 live daemon socket 和完整 release 切换联调。
+  `internal/api/testdata/contract/`；同机 live daemon socket 和完整 fixture release 切换已由
+  `make bat-api-local-live-smoke` 验证。
 
-验收（剩余）：
+后续跟踪（不影响 issue #19 关闭）：
 
-- 与远程长期运行的 `bat` / 全量 release 联调（覆盖 bootstrap、server-info、CDN path；SSH 实勘可后置）
+- 同机 live 联调已完成（覆盖 bootstrap、server-info、CDN path、release 切换、无 release、RPC 断线/恢复）；真实官方网络全量下载由 `make official-smoke` 独立跟踪
 - refresh 中 manifest 磁盘校验的 mtime/size 增量缓存优化（真实全量 release 观测后决定）
 - 文档与 GO_STATUS 持续一致
 
@@ -565,7 +566,7 @@ issue 43 例外说明：新增的 `parse repack` 只编排已有 TextAsset、Typ
    scheduler 和默认并发 8，范围 `1..=256`，worker 完成后立即领取下一个任务，
    进度即时按完成数上报，最终 report 保持 plan 顺序。
 4. **G-008：已决策关闭**（同步 CLI = Rust `bat`；见 `GO_STATUS.md`）。
-5. **G-009 / issue #19**：资源 bootstrap/分发 MVP 已编码；优先服务器联调与索引实勘，非「从零实现」。
+5. **G-009 / issue #19**：资源 bootstrap/分发和同机 live 联调已完成；非「从零实现」。后续真实官方网络长期运行、持久化和完整 launcher/业务链不属于本 issue 关闭条件。
 6. issue #2 / G-007（P1）：Addressables 可校验字段。
 7. issue #3 / G-005（P1）：UnityFS 容器基础解析已落地；对象级引擎解析继续跟踪 G-005。
 8. G-011：翻译任务状态、CAS 诊断和 ResourceRepository 查询面扩展。

docs/reports/GO_STATUS.md

@@ -1,8 +1,8 @@
 # Go 侧进度与边界（权威）
 
-- **更新时间**：2026-08-03
+- **更新时间**：2026-08-29
 - **用途**：统一 Go module `bat-api` 的产品边界、既有约定和组件进度；其他文档与此冲突时以本文为准。
-- **关联**：issue #19 / G-009（资源 bootstrap/分发）、G-008（已决策关闭）、`docs/architecture/official-resource-backend.md` §7
+- **关联**：issue #19 / G-009（资源 bootstrap/分发）、G-008（已决策关闭）、`docs/architecture/official-resource-backend.md` §7、`docs/guides/bat-api-local-live-smoke.md`
 
 ---
 
@@ -40,7 +40,7 @@
 
 1. **G-008 决策关闭（wontfix）**：不另做产品级 Go 同步/运维 CLI。
 2. **G-009**：资源 bootstrap/分发 MVP 部分完成；非完整游戏业务 API。
-3. **USERGUIDE 的 bat-api 基础章节已补**；全量 release 联调后继续补充生产参数和排障样例。
+3. **USERGUIDE 的 bat-api 基础章节已补**；同机 live 联调 runbook 已补，真实官方网络下载仍由独立 smoke 负责。
 
 ---
 
@@ -54,7 +54,7 @@
 | B | **`bat-api` 只读分发**已发布 release，不实现下载器，不写 staging/version-state |
 | C | 仿真范围 = **资源拉取相关**（resource bootstrap + CDN path + 可选 server-info）；**不是**完整游戏业务 API |
 | D | launcher 资源 metadata 可作为 bootstrap 输入/输出兼容；账号、登录、网关和鉴权全链 **非 G-009 关闭条件** |
-| E | USERGUIDE bat-api 基础章节已补；联调后补充实战样例 |
+| E | USERGUIDE bat-api 基础章节和同机 live smoke 实战样例已补 |
 
 ### 发现与数据
 
@@ -63,7 +63,7 @@
 | F | 版本/清单经 **`bat.sock` JSON-RPC**（`--socket`）；不读 daemon 内部状态文件 |
 | G | RPC 顺序：先 **`daemon.status`**，再 **`daemon.doctor`**，再 catalog/manifest |
 | H | 生产文件字节从 RPC 返回的 `resource_root` 读盘；`bat-api` 与 daemon 同服务器/同容器/共享文件系统部署；`--resource-root` 仅 fixture 或应急只读诊断 |
-| I | 真数据在**已全量拉取且长期运行 Rust `bat` 的远程服务器**；开发机不跑全量 `bat`，用 fixture、mock RPC 和 Go 门禁验证；远程联调等连接信息 |
+| I | 生产中 Rust `bat` 与 `bat-api` 在同一主机/容器/共享文件系统；开发用 `/tmp` fixture 和真实本地 `bat.sock` smoke，不依赖远程连接 |
 | J | 索引以 **manifest + 磁盘 Present/size** 为准 |
 | J2 | RPC 状态以 Rust 返回的 `status` / `status_code` 为准；`bat-api` 只读消费，不自行推导同步状态 |
 
@@ -134,8 +134,8 @@ make build-go-cli   # 产出 bin/bat-go
 | 项 | 状态 |
 |---|---|
 | G-008 Go 同步 CLI | **已决策关闭**（正式同步 CLI = Rust `bat`） |
-| G-009 bat-api 资源 bootstrap/分发 | **部分完成**（MVP+生产控制面）；已含资源 bootstrap 关系面、launcher 资源 metadata 兼容、HTTP 鉴权/限流/日志/反代适配、RPC 周期刷新/诊断、readiness、OpenAPI、管理控制白名单、Rust-owned `schedule.*` dashboard 代理、`translation.task.update` 状态回写代理、`translation.proofread` 状态标记代理和部署模板，后续远程服务器联调/可选持久化 |
-| issue #19 | 资源面 MVP 与 USERGUIDE 基础章节已编码；真机联调后继续补充实战样例；**未自动关 issue** |
+| G-009 bat-api 资源 bootstrap/分发 | **资源面完成（非完整官方游戏 API）**；已含资源 bootstrap、launcher resource metadata 兼容、HTTP 鉴权/限流/日志/反代适配、RPC 周期刷新/诊断、readiness、OpenAPI、管理控制白名单、Rust-owned `schedule.*` dashboard 代理、翻译状态回写代理、同机 live smoke 和部署模板；持久化仍另议 |
+| issue #19 | **验收完成，本提交关闭**；`make bat-api-local-live-smoke` 已在同机隔离环境覆盖 live RPC、release 切换、清单不完整、未 ready、server-info 和 CDN path |
 | G-010 Web | 未开始 |
 
 ---
@@ -147,8 +147,6 @@ make build-go-cli   # 产出 bin/bat-go
 
 ## 7. 后续（不在进度统一范围内）
 
-1. 服务器 SSH 只读实勘（连接信息到位后）
-2. bat-api 与远程长期运行的 `bat` / 全量 release 联调（含 `/v1/bootstrap`、server-info 和 CDN path）
-3. 预留 database/redis 的接入时机另议
-4. USERGUIDE bat-api 联调排障样例（全量 release 验证后）
-5. launcher 完整安装包更新链 / 登录网关链（若需要，新 issue）
+1. 预留 database/redis 的接入时机另议
+2. 真实官方网络全量下载长期运行报告（使用 `make official-smoke`，与 issue #19 同机 live 联调独立）
+3. launcher 完整安装包更新链 / 登录网关链（若需要，新 issue）