nyaKazuha/BlueArchiveToolkit

Fork 0

mirror of https://github.com/Yuyi-Oak/BlueArchiveToolkit.git synced 2026-09-18 06:34:54 +08:00

Files

T

nyaKazuha 0275a890bc

bat-rust / Build and test Rust (push) Canceled after 0s

Details

bat-rust / Build and test Go API (push) Canceled after 0s

Details

fix(glossary): 补齐术语删除和审核门禁

2026-09-08 20:59:27 +08:00

9.4 KiB

Raw Blame History

Go 侧进度与边界（权威）

更新时间：2026-09-04
用途：统一 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`、`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 调用；`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` + launcher 资源 metadata 兼容 + `/readyz` + CDN Range/缓存头 + 鉴权/限流/访问日志/反代适配 + OpenAPI + 管理控制白名单 + translation/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. 验证门禁

# 默认（提交前 / CI 建议）
make test-go-api
make build-go-api
go vet ./internal/api/... ./internal/backendrpc/... ./cmd/bat-api/...
make check-docs

# 可选：改 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.*`、翻译任务/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 完整安装包更新链 / 登录网关链（如需推进，应另立范围明确的后续需求）

9.4 KiB Raw Blame History Unescape Escape