From a2e2ae8ac51264c63d7dd63e57750a8d03694f00 Mon Sep 17 00:00:00 2001 From: Yuyi-Oak <1722157266@qq.com> Date: Mon, 3 Aug 2026 11:47:51 +0800 Subject: [PATCH] =?UTF-8?q?docs:=20=E5=AF=B9=E9=BD=90=20RPC=20=E6=8E=A5?= =?UTF-8?q?=E5=8F=A3=E6=96=87=E6=A1=A3?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/api/README.md | 60 +++++++------------ .../architecture/official-resource-backend.md | 7 ++- docs/reference/rpc-backend-api.md | 43 +++++++++++-- docs/reports/GO_STATUS.md | 2 +- 4 files changed, 64 insertions(+), 48 deletions(-) diff --git a/docs/api/README.md b/docs/api/README.md index 8f09a9d..563e3c1 100644 --- a/docs/api/README.md +++ b/docs/api/README.md @@ -1,48 +1,30 @@ # API 文档 -本目录包含 BlueArchive Toolkit 的 API 文档。 +本目录是 API 文档入口。当前实现分为两层，不能把 Rust daemon RPC +和 Go HTTP 服务混写成一个接口： -当前 API Server 尚未实现，本文件只记录规划边界，不代表已有可运行 HTTP 服务或 OpenAPI 产物。 +## Rust daemon RPC -## OpenAPI 规范 +Rust `bat` 通过 `/tmp/bat-pid/bat.sock` 提供换行分隔的 JSON-RPC 2.0 +Resource Backend。方法、参数、envelope、错误码、Go 调用白名单以 +[`rpc-backend-api.md`](../reference/rpc-backend-api.md) 为准。 -OpenAPI 文档将在 API Server 落地后生成，目标使用 OpenAPI 3.0 标准。当前仓库尚未提供 `openapi/` 生成产物。 +## Go bat-api HTTP -## 文档生成 +Go `cmd/bat-api` 是资源 bootstrap、已发布资源分发和鉴权控制服务，不是完整 +游戏业务 API。已实现的 HTTP surface 包括： -API 文档将在开发过程中自动生成和更新。 +- `/healthz`、`/readyz` +- `/v1/bootstrap`、`/v1/launcher/bootstrap`、`/v1/release`、`/v1/resources` +- `/v1/server-info` 和 CDN 形状资源路径 +- `/api/launcher/game/config` 兼容端点 +- `/admin/` 与白名单 `/admin/control/{action}` +- `/openapi.yaml` -**计划**： -- 使用 `swag` (Go) 从代码注释生成 OpenAPI 文档 -- 提供 Swagger UI 在线查看 -- 支持导出为 Markdown、HTML 等格式 +HTTP 路由的 OpenAPI 文本由 `internal/api/openapi.go` 提供，运行中的服务也可 +通过 `GET /openapi.yaml` 获取。配置、鉴权、部署边界和示例见 +[`USERGUIDE.md`](../../USERGUIDE.md) 与 +[`GO_STATUS.md`](../reports/GO_STATUS.md)。 ---- - -## 核心 API 端点（规划中） - -### 认证 -- `POST /api/v1/auth/login` - 用户登录 -- `POST /api/v1/auth/logout` - 用户登出 -- `POST /api/v1/auth/refresh` - 刷新 Token - -### 翻译管理 -- `GET /api/v1/translations` - 获取翻译列表 -- `POST /api/v1/translations` - 创建翻译 -- `PUT /api/v1/translations/:id` - 更新翻译 -- `DELETE /api/v1/translations/:id` - 删除翻译 - -### 术语管理 -- `GET /api/v1/glossary` - 获取术语列表 -- `POST /api/v1/glossary` - 创建术语 -- `PUT /api/v1/glossary/:id` - 更新术语 -- `DELETE /api/v1/glossary/:id` - 删除术语 - -### 资源同步 -- `POST /api/v1/sync/start` - 启动同步 -- `GET /api/v1/sync/status` - 查询同步状态 -- `POST /api/v1/sync/cancel` - 取消同步 - ---- - -更多详细文档将在 API Server 实现后补充。 +账号登录、完整翻译管理、术语库、游戏业务协议和完整 launcher 安装包更新链 +当前不属于已实现接口。 diff --git a/docs/architecture/official-resource-backend.md b/docs/architecture/official-resource-backend.md index f97ff4c..ee103b5 100644 --- a/docs/architecture/official-resource-backend.md +++ b/docs/architecture/official-resource-backend.md @@ -283,7 +283,7 @@ Linux 生产路径： - pull plan 会同时包含 discovery URLs 和 content URLs - 全量样本下是 `2` 个 discovery URL + `5` 个内容 URL = `7` 个 URL - `OfficialUpdateService` 能持久化 v2 snapshot，并在远端 marker 内容变化时触发下载决策 -- `bat` 默认向 stderr 输出 `BlueArchiveToolkit` ASCII banner 和 progress log，stdout 默认输出人类可读摘要；progress log 覆盖代理决策、下载已完成计数、单文件开始/完成状态、下载中断失败分类和校验结果摘要；支持 `--proxy` / `--no-proxy` 控制 curl 传输代理，支持 `--json` 输出稳定 JSON，支持 `--no-progress` 关闭进度日志，支持 `--no-banner` 只关闭横幅，支持 `--watch --interval 1h --error-retry 60s` 常驻运行，支持 `--daemon` Unix socket JSON-RPC live control/backend（`daemon.status/logs/stop/restart/reload/refresh/doctor`、`resource.sync/verify/repair/state/manifest/list/index`、`parse.status/text_units/errors`、`translation.tasks`、`localized.status`、`catalog.*`、`task.*`）；`restart` 通过 Rust lifecycle controller 复用 CLI restart 路径，`clean-stable` 仍由 CLI 侧按进程生命周期显式执行，非 dry-run 使用 `.official-sync.lock` 防止并发写资源目录，控制命令使用 `bat-control.lock` 防止并发状态修改，资源发布使用 `.staging`、`versions` 和 `current` 原子切换，daemon 写 `bat-events.jsonl` 结构化日志并在 `status` 中暴露下载进度、失败类型、HTTP 状态和调度状态 +- `bat` 默认向 stderr 输出 `BlueArchiveToolkit` ASCII banner 和 progress log，stdout 默认输出人类可读摘要；progress log 覆盖代理决策、下载已完成计数、单文件开始/完成状态、下载中断失败分类和校验结果摘要；支持 `--proxy` / `--no-proxy` 控制 curl 传输代理，支持 `--json` 输出稳定 JSON，支持 `--no-progress` 关闭进度日志，支持 `--no-banner` 只关闭横幅，支持 `--watch --interval 1h --error-retry 60s` 常驻运行，支持 `--daemon` Unix socket JSON-RPC live control/backend（`daemon.status/logs/stop/restart/reload/refresh/doctor`、`resource.sync/verify/repair/state/manifest/list/index`、`parse.status/text_units/errors`、`translation.tasks/handoff/task.update`、`localized.status`、`catalog.*`、`task.*`、文件级 `patch.apply` / `unityfs.patch_*`）；`restart` 通过 Rust lifecycle controller 复用 CLI restart 路径，`clean-stable` 仍由 CLI 侧按进程生命周期显式执行，非 dry-run 使用 `.official-sync.lock` 防止并发写资源目录，控制命令使用 `bat-control.lock` 防止并发状态修改，资源发布使用 `.staging`、`versions` 和 `current` 原子切换，daemon 写 `bat-events.jsonl` 结构化日志并在 `status` 中暴露下载进度、失败类型、HTTP 状态和调度状态 - curl 失败分类和重试策略已覆盖 404 不重试、5xx 重试耗尽后 quarantine、launcher primary CDN 失败后切换 official backup CDN - `official-version-state.json` 已覆盖当前完成版本、正在拉取版本、上一个可用版本和失败版本；同一 app version、bundle version 和 Addressables root 的失败只保留最新一条，重新拉取或成功发布后清理同版本失败记录，同版本失败 staging 会在路径安全且未发布时复用，`bat status` 会暴露版本状态摘要和最近历史失败原因 - 资源导入链路已覆盖可配置 CAS 写入、`ResourceRepository` 索引、`metadata_json` release/平台/bundle/TextAsset/TextUnit 摘要，以及 TextAsset/Table/Media 分类；`resource.index` 可只读查询现有索引 @@ -337,8 +337,9 @@ JSON-RPC 2.0 服务，是面向上层服务（Go 层）的**主要跨语言边 - 方法命名空间与实现状态、请求/响应示例见 `docs/reference/rpc-backend-api.md`：`daemon.status/logs/stop/restart/reload/refresh/doctor`、 `resource.state/sync/verify/repair/manifest/list/index`、`parse.status/text_units/errors`、 - `localized.status`、`catalog.*` 与 `task.status/list/cancel/logs` 已实现； - 文件级 `patch.apply` / `unityfs.patch_*` 已实现，发布级 patch 与复杂 UnityFS 语义编辑待引擎； + `translation.tasks/handoff/task.update`、`localized.status`、`catalog.*` 与 + `task.status/list/cancel/logs` 已实现；文件级 `patch.apply` / `unityfs.patch_*` + 已实现，发布级 patch 与复杂 UnityFS 语义编辑待引擎； `task.create` 按设计暂不开放通用任务入口； `daemon.restart` 通过 Rust lifecycle controller 复用 CLI restart 路径； `daemon.clean-stable` 仍由 CLI 侧按进程生命周期显式执行。 diff --git a/docs/reference/rpc-backend-api.md b/docs/reference/rpc-backend-api.md index 1486570..7d1f423 100644 --- a/docs/reference/rpc-backend-api.md +++ b/docs/reference/rpc-backend-api.md @@ -353,14 +353,47 @@ CLI 对应关系： | `bat parse-status` | `parse.status` | | `bat parse-text-units` | `parse.text_units` | | `bat parse-errors` | `parse.errors` | +| `bat translation-tasks` | `translation.tasks` | +| `bat translation-handoff` | `translation.handoff` | | `bat localized-status` | `localized.status` | | `bat resource-index` | `resource.index` | -`bat resource-index` 支持 `--offset`、`--limit`、`--resource-type`、`--hash` -和 `--path-pattern`；`bat parse-text-units` / `bat parse-errors` 支持 -`--offset`、`--limit`、`--destination`、`--archive-entry`、`--path-id`、 -`--class-id`、`--field-path` 和 `--format`；这些过滤参数不适用于 -`parse-status` 或 `localized-status`。 +`bat resource-index` 支持 `--offset`、`--limit`、`--resource-type`、`--hash`、 +`--path-pattern`、`--release-id`、`--platform`、`--destination`、 +`--bundle-path`、`--archive-entry`、`--parse-status` 和 `--format`； +`bat parse-text-units` / `bat parse-errors` 支持 `--offset`、`--limit`、 +`--destination`、`--path-pattern`、`--archive-entry`、`--path-id`、 +`--class-id`、`--field-path` 和 `--format`；`bat translation-tasks` 支持 +`--offset`、`--limit`、`--task-id`、`--release-id`、`--destination`、 +`--path-pattern`、`--archive-entry`、`--task-status`、`--worker-status`、 +`--parse-status`、`--format`、`--has-reason` 和 `--has-failure-reason`。这些过滤参数不适用于 +`parse-status`、`translation-handoff` 或 `localized-status`。 + +### Go 客户端表面 + +`internal/backendrpc.Client` 是 Unix socket JSON-RPC 传输客户端： + +- `Call` 可发送本文档中的任意已记录方法，并负责 JSON-RPC transport、 + envelope 和 `ApiError` 解码；它不是 bat-api 的 HTTP 任意 RPC proxy。 +- typed helper 已覆盖 daemon 已实现方法（`status/logs/stop/restart/reload/refresh/doctor`）、 + `resource.state/sync/verify/repair/manifest/list`、`catalog.*`、`parse.*`、 + `localized.status`、`task.*` 和三个 + `unityfs.patch_*` 方法。 +- `resource.index`、`translation.tasks`、`translation.handoff`、 + `translation.task.update` 和 `patch.apply` 当前没有专用 typed helper； + 需要直接使用 `Call`，并仍须遵守本契约的参数和响应定义。 + +`internal/api` 对 bat-api 生产路径进一步收窄接口： + +| Go 接口 | 允许调用的 RPC | 用途 | +|---|---|---| +| `Backend` | `daemon.status`、`daemon.doctor`、`resource.state`、`catalog.status`、`resource.manifest` | 启动发现、周期刷新和资源分发 | +| `ControlBackend` | `daemon.restart`、`daemon.reload`、`daemon.refresh`、`resource.sync`、`resource.verify`、`resource.repair`、`catalog.refresh` | 鉴权后的管理控制白名单 | + +`daemon.stop`、`daemon.clean-stable` 和任意通用 RPC 不属于 bat-api 管理控制面。 +Rust dispatch、Go transport 和 bat-api 接口的权威实现位置分别是 +`infrastructure/src/bin/bat/app.rs`、`internal/backendrpc/client.go` 和 +`internal/api/rpc_release.go`；修改方法、字段或 allowlist 时必须同步更新本文档。 Go mirror contract fixture 固化在 `internal/api/testdata/contract/`，覆盖 `catalog.status` available/unavailable、`resource.manifest` page0 和对应 diff --git a/docs/reports/GO_STATUS.md b/docs/reports/GO_STATUS.md index 152cdda..2430a49 100644 --- a/docs/reports/GO_STATUS.md +++ b/docs/reports/GO_STATUS.md @@ -95,7 +95,7 @@ | 组件 | 路径 | 状态 | 说明 | |---|---|---|---| | Module | `go.mod` → `bat-api` | 已用 | 服务层模块名 | -| RPC client | `internal/backendrpc` | **完成** | typed JSON-RPC；覆盖 daemon restart、resource/catalog/task、parse/localized 和文件级 UnityFS patch 调用；fake transport 单测，配合 `internal/api/testdata/contract/` 固化 Rust 输出 mirror | +| 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`、`task.*` 和文件级 UnityFS patch 调用；`resource.index`、`translation.*`、`patch.apply` 仍通过通用 `Call` 走同一 contract；fake transport 单测，配合 `internal/api/testdata/contract/` 固化 Rust 输出 mirror | | 资源 bootstrap/分发 | `cmd/bat-api` + `internal/api` | **MVP+生产控制面** | RPC 发现 + 周期刷新/诊断 + `/v1/bootstrap` + `/v1/launcher/bootstrap` + launcher 资源 metadata 兼容 + `/readyz` + CDN Range/缓存头 + 鉴权/限流/访问日志/反代适配 + OpenAPI + 管理控制白名单 + `.env` | | 试验 CLI | `cmd/bat` | **试验** | doctor 固定 ok；manifest/sync 走 FFI | | FFI | `internal/ffi` | **可选** | 需 `build-ffi` |