fix(api): 补齐 bat-api 控制与后端 RPC

USERGUIDE.md

@@ -109,13 +109,14 @@ BAT_API_SKIP_ENV_FILE=1 go run ./cmd/bat-api \
 | `GET /yostar-serverinfo.bluearchiveyostar.com/server-info.json` | 官方 host/path 形态的 server-info |
 | `GET/HEAD /prod-clientpatch.bluearchiveyostar.com/...` | 官方 CDN path 形态资源字节 |
 | `GET /openapi.yaml` | bat-api OpenAPI 文档 |
-| `GET /admin/` | 管理面板预留入口；当前返回 JSON 链接，未来接入 Web UI |
+| `GET /admin/` | 管理控制入口与允许操作列表 |
+| `POST /admin/control/{action}` | 经白名单转发 Rust `bat` 控制请求；见下文 |
 
 launcher 兼容端点只服务启动前资源发现。它们复用 Rust `bat` snapshot 中的 `launcher_metadata` 和 `game_main_config_bootstrap`，显式标记 `scope=resource_bootstrap_only` / `package_update_manifest=false`。`bat-api` 不下载 launcher 包，不生成官方 PC package update manifest，也不仿造登录、账号、网关、鉴权或游戏业务协议。
 
 生产面对玩家分发时，应启用 HTTP token 鉴权、限流和访问日志：
 
-- `BAT_API_AUTH_TOKEN`：启用 `Authorization: Bearer <token>`、`X-BAT-Token` 或 query fallback 鉴权；token 推荐由 secret manager 或进程环境提供，不建议写入提交文件。
+- `BAT_API_AUTH_TOKEN`：启用 `Authorization: Bearer <token>`、`X-BAT-Token` 或 query fallback 鉴权；token 推荐由 secret manager 或进程环境提供，不建议写入提交文件。`/admin/control/*` 需要此 token。
 - `BAT_API_AUTH_QUERY_PARAM`：query fallback 参数名，默认 `bat_token`；兼容不能写 header 的客户端，访问日志不会记录 query。
 - `BAT_API_AUTH_EXEMPT_PATHS`：逗号分隔的免鉴权 path 或 slash-prefix，例如 `/healthz,/readyz`。
 - `BAT_API_RATE_LIMIT_RPS` / `BAT_API_RATE_LIMIT_BURST`：按客户端 IP 的进程内 token bucket 限流；边缘反代/CDN 仍应配置独立限流。
@@ -123,7 +124,21 @@ launcher 兼容端点只服务启动前资源发现。它们复用 Rust `bat` sn
 - `BAT_API_ACCESS_LOG`：结构化访问日志，记录 method/path/status/bytes/duration/client_ip/request_id/user_agent，不记录 query string。
 - `BAT_API_MAX_RESOURCE_LIMIT`：`/v1/resources` 最大分页上限，默认 `1000`。
 
-所有动态 JSON（bootstrap、health、ready、release、resources、launcher 兼容、server-info、OpenAPI、admin placeholder 和错误响应）显式返回 `Cache-Control: no-store`。资源字节 CDN path 仍返回长期 immutable cache header。
+`POST /admin/control/{action}` 只转发固定白名单内的 Rust RPC，不是任意 RPC proxy：
+
+| action | Rust RPC | 参数 | 返回 |
+|---|---|---|---|
+| `reload` | `daemon.reload` | 无 | `202` accepted |
+| `refresh` | `daemon.refresh` | 可选 `{ "force": true }` | `202` accepted |
+| `restart` | `daemon.restart` | 无 | `202` accepted |
+| `sync` | `resource.sync` | 可选 `{ "force": true }` | `202` + task |
+| `verify` | `resource.verify` | 无 | `202` + task |
+| `repair` | `resource.repair` | 无 | `202` + task |
+| `catalog-refresh` | `catalog.refresh` | 可选 `{ "force": true }` | `202` + task |
+
+`stop`、`clean-stable`、patch 和 UnityFS 写入命令不会经 HTTP 暴露。
+
+所有动态 JSON（bootstrap、health、ready、release、resources、launcher 兼容、server-info、OpenAPI、admin 和错误响应）显式返回 `Cache-Control: no-store`。资源字节 CDN path 仍返回长期 immutable cache header。
 
 CDN path 只服务 manifest 索引内且磁盘存在、size 匹配的文件。响应支持 `GET`、`HEAD`、`Range`、条件请求、ETag、Last-Modified、Accept-Ranges 和长期缓存头；ETag 优先使用 manifest 中的 BLAKE3。`.hash` 以 `text/plain` 返回，其它未知扩展默认为 `application/octet-stream`。
 
@@ -360,6 +375,7 @@ curl -i -H 'Range: bytes=0-1023' \
 | `daemon.stop` | ✅ | 请求停止（`accepted`） |
 | `daemon.reload` | ✅ | 请求重新发现并强制刷新（`accepted`） |
 | `daemon.refresh` | ✅ | 请求刷新检查（`params.force`，`accepted`） |
+| `daemon.restart` | ✅ | 启动 Rust lifecycle controller，并在响应后停止当前 daemon（`accepted`） |
 | `daemon.doctor` | ✅ | 返回运行时诊断报告（只读，不清理、不重启） |
 | `resource.state` | ✅ | 资源发布根 + 版本状态 + 上次同步结果 |
 | `resource.sync` | ✅ | 触发同步任务（`params.force`），返回 `task_id` |
@@ -374,7 +390,7 @@ curl -i -H 'Range: bytes=0-1023' \
 | `task.list` | ✅ | 列出全部任务（最新在前） |
 | `task.cancel` | ✅ | 请求取消任务（`params.task_id`）；协作式，在同步检查点生效 |
 | `task.logs` | ✅ | 返回任务的进度日志（`params.task_id`，有界） |
-| `daemon.restart` / `daemon.clean-stable` / `patch.*` / `unityfs.*` / `task.create` | ⏳ | 已规划，返回 `BAT-ERR-700003`（not implemented）；restart/clean-stable 仍由 CLI 侧按进程生命周期显式执行，patch/unityfs 待引擎实现，task.create 暂不开放通用任务入口 |
+| `daemon.clean-stable` / 发布级 `patch.*` / 未开放 `unityfs.*` / `task.create` | ⏳ | 已规划，返回 `BAT-ERR-700003`（not implemented）；clean-stable 仍由 CLI 侧按进程生命周期显式执行，task.create 暂不开放通用任务入口 |
 | 未知方法 | — | `BAT-ERR-700001`（unknown method） |
 
 只读查询（`daemon.doctor` / `resource.state` / `resource.manifest` / `resource.list` / `catalog.status` / `catalog.versions` / `catalog.diff`）在尚无已发布版本或对应文件不存在时返回 `ok: true` 且 `data.available: false`（正常状态而非错误，便于调用方直接分支）。