docs: 对齐 RPC 接口文档

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 安装包更新链
+当前不属于已实现接口。

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 侧按进程生命周期显式执行。

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 和对应

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` |