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

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）