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 决策（已核验）
- Go 同步 CLI 边界已确定：不另做产品级 Go 同步/运维 CLI，正式入口是 Rust
bat。
- G-009：资源 bootstrap/分发 MVP 部分完成；非完整游戏业务 API。
- 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，再 catalog/manifest |
| H |
生产文件字节从 RPC 返回的 resource_root 读盘；bat-api 与 daemon 同服务器/同容器/共享文件系统部署；--resource-root 仅 fixture 或应急只读诊断 |
| I |
生产中 Rust bat 与 bat-api 在同一主机/容器/共享文件系统；开发用 /tmp fixture 和真实本地 bat.sock smoke，不依赖远程连接 |
| J |
索引以 manifest + 磁盘 Present/size 为准 |
| J2 |
RPC 状态以 Rust 返回的 status / status_code 为准；bat-api 只读消费，不自行推导同步状态 |
进程配置
| 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 test-go-api + make build-go-api + make check-docs（无 FFI） |
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-apibat-api/cmd/batbat-api/internal/apibat-api/internal/backendrpcbat-api/internal/ffi
4. 验证门禁
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. 后续（不在进度统一范围内）
- 预留 database/redis 的接入时机另议
- 真实官方网络全量下载长期运行报告（使用
make official-smoke，与同机 live 联调独立）
- launcher 完整安装包更新链 / 登录网关链（如需推进，应另立范围明确的后续需求）
