docs: 补 RPC Backend API 与 Go/FFI 边界章节,同步 issue #1 进展

- 架构文档新增 §7「RPC Backend API 与 Go 调用边界」:协议契约
  (envelope、ApiError、任务模型、方法命名空间与实现状态,细节指向
  USERGUIDE §6)、Go 层职责边界(HTTP/鉴权/分发 + RPC client,不嵌
  FFI、不直接读 daemon 内部状态)、FFI 降级说明(bat-ffi 保留为可选
  历史兼容边界,新能力一律先落 RPC)。对应 issue #1 文档要求第 8 项。
- CURRENT_STATUS:issue #1 条目由"待实现"改为"主体已实现 + 剩余清单",
  下一步清单同步。

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
2026-07-17 10:27:44 -07:00
co-authored by Claude Fable 5
parent eac1edd455
commit d22f9258ad
2 changed files with 41 additions and 2 deletions
@@ -275,3 +275,42 @@ Linux 生产路径:
4. 是否拒绝镜像域名和手工拼接样例。
5. 是否在下载前做了 URL 和路径安全校验。
6. 是否能在官方客户端变动时只改适配层。
## 7. RPC Backend API 与 Go 调用边界
daemon`bat --daemon`)在 `<state-dir>/bat.sock` 上提供 Unix socket
JSON-RPC 2.0 服务,是面向上层服务(Go 层)的**主要跨语言边界**。
### 7.1 协议契约
- 应用层统一 envelope(装入 JSON-RPC `result`):`ok` / `status` /
`data` / `error` / `request_id`;传输层解析失败走 JSON-RPC 顶层
`error`-32700)。
- `error` 为统一 `ApiError``code``BAT-ERR-<6 位>`)、`kind`
`domain``location``message``retryable`。码表以
`core/src/error_code.rs` 为准。
- 长任务(`resource.sync` / `resource.verify` / `catalog.refresh`
入队即返回 `task_id`,经 `task.status` / `task.list` / `task.logs`
轮询,`task.cancel` 协作式取消。任务执行器是单 worker FIFO,与
watch 循环经进程内锁互斥。
- 方法命名空间与实现状态、请求/响应示例见 `USERGUIDE.md` §6
`daemon.*` / `resource.*` / `catalog.*` / `task.*` 已实现;
`patch.*` / `unityfs.*` 待引擎;`task.create` / `resource.repair`
按设计暂缓。
### 7.2 Go 层职责边界
- Go 层负责:BlueArchive 客户端请求处理、HTTP API、鉴权、内容分发,
以及作为 RPC client 调用本机 daemon(连接 `bat.sock`,每行一个
JSON-RPC 请求/响应)。
- Rust daemon 负责:官方资源自动拉取与校验、catalog 更新检查、
版本状态与发布、任务队列/日志/错误/进度管理等长期状态型工作。
- Go 层**不**直接嵌入 Rust FFI,不直接读写 daemon 的状态文件与资源
目录内部结构;跨语言交互只经 RPC 契约。
### 7.3 FFI 的定位(降级说明)
`bat-ffi` crate(cgo 头文件 + 静态/动态库链接,见 `Makefile`
`build-ffi` / `build-go`)**降级为可选的历史兼容边界**:保留用于既有
cgo 试验路径与本地工具,不再作为 Go 服务层的主要集成方式,也不会按
RPC 契约的节奏扩展。新能力一律先落 RPC 方法。