BlueArchiveToolkit/docs/reports/GO_STATUS.md

# Go 侧进度与边界（权威）

- **更新时间**：2026-09-12
- **用途**：统一 Go module `bat-api` 的产品边界、既有约定和组件进度；其他文档与此冲突时以本文为准。
- **关联缺口**：G-009（资源 bootstrap/分发）；相关契约见 `docs/architecture/official-resource-backend.md` §7 和 `docs/guides/bat-api-local-live-smoke.md`

---

## 1. 三个入口分别是什么

| 名称 | 路径 / 产物 | 角色 | 是否产品入口 |
|---|---|---|---|
| **Rust `bat`** | `infrastructure` bin → 正式同步二进制 | 官方资源**自动**发现 / 拉取 / 校验 / 发布 / watch·daemon / 运维子命令 | **是（同步与运维命令行）** |
| **Go `bat-api`** | `cmd/bat-api` → `bin/bat-api` | **资源 bootstrap + 分发 HTTP 服务**（官方 CDN path 形态）+ release 观察 API + 内嵌 dashboard | **是（bootstrap/分发服务与管理入口）** |
| **Go 试验 CLI** | `cmd/bat` → `bin/bat-go`（不得再叫 `bin/bat`） | FFI 演示骨架 | **否** |

### 1.1 「同步命令行 = Rust `bat`」的含义

人类做资源同步与运维时，正式命令行是 **Rust 编译的 `bat`**（近乎全自动：`--auto-discover`、`--watch` / `--daemon` 后只需偶发 `status` / `refresh` / `repair`，不需要持久手操维护）。

这**不是**说整个项目只有 Rust，也**不是**取消 Go 入口：

- Go 的正式产品入口是 **`bat-api` 服务进程**（给客户端/工具提供启动前资源 bootstrap、server-info 改写、已发布资源字节和内嵌管理 dashboard），不是再做一套同步 CLI。
- Go `cmd/bat` 仅试验，禁止与 Rust `bat` 二进制重名。

### 1.2 `bat` 与 `bat-api` 的关系

`bat` 是资源生产者和状态拥有者；`bat-api` 是资源读侧和 HTTP 入口。

| 关系面 | Rust `bat` / daemon | Go `bat-api` |
|---|---|---|
| 资源发现 | 读取官方 launcher/resource metadata，解析 `GameMainConfig`、server-info 和 Addressables root | 通过 `bat.sock` 读取已发布版本摘要，不重新探测官方 metadata |
| 下载与发布 | 下载、校验、staging、原子发布 `current -> versions/<id>`，维护 manifest/snapshot/version-state | 不下载、不写 staging、不改 version-state；生产资源根来自 RPC 返回的 `resource_root` |
| 启动前资源入口 | 暴露 `catalog.status` / `resource.manifest` 等 RPC 数据 | 提供 `/v1/bootstrap`、`/v1/launcher/bootstrap`、launcher 资源 metadata 兼容端点、`/v1/server-info`、CDN path 和 `/admin/dashboard/`，组织给客户端/补丁器/维护者使用 |
| 长期状态 | watch/daemon、任务队列、日志、错误码、repair/sync/verify | 周期性经 RPC 刷新内存索引；认证 Web 控制面仅白名单转发 reload/refresh/restart/sync/verify/repair/catalog-refresh、schedule/task/log/parse/translation/TM/localized 方法，不持有或写入同步状态 |

这条边界允许 `bat-api` 做资源 bootstrap 兼容，但不允许它复制 Rust 下载器或伪装完整游戏业务服务。

### 1.3 决策（已核验）

1. **Go 同步 CLI 边界已确定**：不另做产品级 Go 同步/运维 CLI，正式入口是 Rust `bat`。
2. **G-009**：资源 bootstrap/分发 MVP 部分完成；非完整游戏业务 API。
3. **USERGUIDE 的 bat-api 基础章节已补**；同机 live 联调 runbook 和内嵌 dashboard MVP 已补，真实官方网络下载仍由独立 smoke 负责。

---

## 2. 既有约定核对表（不可丢）

### 职责

| ID | 约定 |
|---|---|
| A | **自动发现 / 下载 / 校验 / 发布 / watch·daemon** 只在 **Rust `bat`** |
| 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 基础章节和同机 live smoke 实战样例已补 |

### 发现与数据

| ID | 约定 |
|---|---|
| F | 版本/清单经 **`bat.sock` JSON-RPC**（`--socket`）；不读 daemon 内部状态文件 |
| G | RPC 顺序：先 **`daemon.status`**，再 **`daemon.doctor`**，再 **`release.status`**，再 catalog/manifest |
| H | 生产文件字节从 RPC 返回的 `resource_root` 读盘；`bat-api` 与 daemon 同服务器/同容器/共享文件系统部署；`--resource-root` 仅 fixture 或应急只读诊断 |
| I | 生产中 Rust `bat` 与 `bat-api` 在同一主机/容器/共享文件系统；开发用 `/tmp` fixture 和真实本地 `bat.sock` smoke，不依赖远程连接 |
| J | Go 索引以 **manifest + 磁盘 Present/size** 建立可读快照，但不将其当作 release integrity |
| J2 | RPC 状态以 Rust 返回的 `status` / `status_code` 为准；`release.status.official_distribution_ready` 是普通 current 分发的 whole-release 授权事实，`bat-api` 只读消费，不自行推导 verifier |

### 进程配置

| ID | 约定 |
|---|---|
| K | `.env` / 环境变量 / CLI：端口、public base、RPC socket、RPC 刷新周期；**预留** database/redis |
| L | 管理面 / bootstrap：`/healthz`、`/readyz`、`/v1/bootstrap`、`/v1/release`、`/v1/resources`、`/openapi.yaml`、`/admin/` 控制入口 |
| M | CDN：`GET/HEAD /prod-clientpatch.bluearchiveyostar.com/...`，支持 Range、ETag、Last-Modified、长期缓存头 |
| N | server-info 可选；**只改 AddressablesCatalogUrlRoot** |
| N2 | launcher 兼容仅限资源引导：`/v1/launcher/bootstrap` 与 `/api/launcher/...` 形状端点输出已发布 release、launcher metadata 和 GameMainConfig 摘要；不下载 launcher 包、不生成完整 PC package update manifest、不仿造登录/网关 |
| N3 | 玩家-facing HTTP 控制面：可配置 token 鉴权、进程内限流、访问日志、反代 IP 适配、动态 JSON `no-store`、`/v1/resources` 分页上限 |
| N4 | `/admin/control/{action}` 白名单控制面；`restart` 通过 Rust live RPC 启动 lifecycle controller，Go 不直接执行 `bat` binary |

### 工程

| ID | 约定 |
|---|---|
| O | 权威文档与 `go list` 一致，禁止「API 完全没有」等过时句 |
| P | 试验 CLI 产物 **`bin/bat-go`**，禁止 `bin/bat` |
| Q | 空目录标明 reserved empty |
| R | 默认门禁：`make ci-check`；其中 Go 使用纯 API test/vet/build（无 FFI），`golangci-lint` 为明确报告的 optional gate |

---

## 3. 组件进度

| 组件 | 路径 | 状态 | 说明 |
|---|---|---|---|
| Module | `go.mod` → `bat-api` | 已用 | 服务层模块名 |
| RPC client | `internal/backendrpc` | **完成** | Unix socket JSON-RPC transport + typed helper；typed helper 覆盖 daemon 已实现控制/查询、`resource.state/sync/verify/repair/manifest/list`、`release.status/list/distribution/cleanup`、`catalog.*`、`parse.*`、`localized.status/publish/rollback`、`task.*`、`translation.tasks`、`translation.handoff`、`translation.task.update`、`translation.worker.run`、`translation.proofread`、`translation.memory.summary/query/confirm`、`translation.glossary.summary/query/diagnose/add/update/approve/deprecate/delete` 和文件级 UnityFS patch 调用；`localized.publish` 的 typed params 支持 `translation_file`、`from_worker` 或 `patch_manifest` 三选一；`resource.index`、`patch.apply` 仍通过通用 `Call` 走同一 contract；fake transport 单测和 `internal/api/testdata/contract/` mirror test 固化 Rust 输出字段 |
| 资源 bootstrap/分发 | `cmd/bat-api` + `internal/api` | **MVP+生产控制面** | RPC 发现 + 周期刷新/诊断 + `/v1/bootstrap` + `/v1/launcher/bootstrap` + `/v1/releases` + `/v1/distribution` + launcher 资源 metadata 兼容 + `/readyz` + CDN Range/缓存头 + 鉴权/限流/访问日志/反代适配 + OpenAPI + 管理控制白名单 + release/localized/TM/Glossary admin forwarding + 内嵌 dashboard + `.env` |
| 试验 CLI | `cmd/bat` | **试验** | doctor 固定 ok；manifest/sync 走 FFI |
| FFI | `internal/ffi` | **可选** | 需 `build-ffi` |
| 空骨架 | `api/`、`pkg/*`、部分 `internal/*` | **空** | 见各目录 README |
| Web | `web/` | **内嵌 dashboard MVP** | 完整协作后台、登录/角色和术语管理仍属 G-010 剩余 |

`go list ./...` 当前包：

- `bat-api/cmd/bat-api`
- `bat-api/cmd/bat`
- `bat-api/internal/api`
- `bat-api/internal/backendrpc`
- `bat-api/internal/ffi`

---

## 4. 验证门禁

```bash
# 默认（提交前 / CI 建议）
make ci-check

# 可选：改 FFI 或试验 CLI 时
make build-ffi
make test-go-ffi
make build-go-cli   # 产出 bin/bat-go
```

---

## 5. 与缺口对应

| 项 | 状态 |
|---|---|
| Go 同步 CLI | **边界已确定**（正式同步 CLI = Rust `bat`） |
| G-009 bat-api 资源 bootstrap/分发 | **资源面完成（非完整官方游戏 API）**；已含资源 bootstrap、launcher resource metadata 兼容、HTTP 鉴权/限流/日志/反代适配、RPC 周期刷新/诊断、readiness、OpenAPI、管理控制白名单、Rust-owned `schedule.*`、`task.*`、`parse.*`、`release.*` 双 release 查询/分发/cleanup 转发、翻译任务/TM 状态查询与显式确认代理、内嵌 dashboard、同机 live smoke 和部署模板；持久化仍另议 |
| G-010 Web | 内嵌 dashboard MVP 已完成；完整协作后台、登录/角色、术语管理和构建型前端未开始 |

---

## 6. 资源布局与逆向

- **Release / URL / 分发契约（权威）**：`docs/architecture/resource-release-layout.md`
- 真机全量实勘、seed inventory diff 和样本采集按该文档 §9–§10 执行

## 7. 后续（不在进度统一范围内）

1. 预留 database/redis 的接入时机另议
2. 真实官方网络全量下载长期运行报告（使用 `make official-smoke`，与同机 live 联调独立）
3. launcher 完整安装包更新链 / 登录网关链（如需推进，应另立范围明确的后续需求）