# 后台管理服务设计

日期：`2026-04-23`

## 1. 目标

为当前 Rust `api-server` 增加一套同源后台管理服务，满足以下首版目标：

1. 支持管理员用户名密码登录。
2. 支持独立的管理员鉴权，不允许普通玩家 JWT 越权访问。
3. 支持在后台查看当前服务与数据库概览信息。
4. 支持在后台测试当前 `api-server` 已挂载接口。
5. 保持首版工程足够轻量，不新建额外独立服务进程，不引入第二套前端工程。

## 2. 背景与约束

当前仓库已具备：

1. Rust `api-server` 主链。
2. 基于 JWT + refresh session 的普通用户登录体系。
3. `SpacetimeDB + spacetime-client` 的主数据面。

本次后台管理服务必须继续遵守：

1. 后端统一落在 `server-rs`，不回退到 `server-node`。
2. 不额外新起独立管理服务进程。
3. 首版以“一个受保护管理域 + 一个同源后台页面”为落地形态。
4. 数据库信息必须尽量读取真实数据库侧信息，不能只展示硬编码假数据。

## 3. 首版范围

### 3.1 包含

1. `GET /admin`：后台管理页面入口。
2. `POST /admin/api/login`：管理员用户名密码登录。
3. `GET /admin/api/me`：当前管理员会话信息。
4. `GET /admin/api/overview`：服务与数据库概览。
5. `POST /admin/api/debug/http`：受控 HTTP 接口调试。
6. 基于 Bearer JWT 的管理员鉴权中间件。

### 3.2 不包含

1. 多角色管理员体系。
2. 管理员 refresh cookie / 多端会话管理。
3. 后台直接写库、删库、执行 reducer。
4. 任意 SQL 执行器。
5. 新建独立 React/Vite 管理端工程。

## 4. 总体方案

### 4.1 部署形态

后台管理服务直接挂载在现有 `server-rs/crates/api-server` 内，作为同一个 Axum 进程的一部分。

原因：

1. 当前 `api-server` 已具备配置、JWT、错误包裹、日志与同源路由能力。
2. 后台本质上是服务运维与调试面，不值得单独再起一个网关或 BFF。
3. 同源可以避免开发期额外 CORS 和 cookie 域问题。

### 4.2 页面形态

后台管理页面采用 `api-server` 直接返回一份内嵌 HTML/CSS/JS 的管理页。

原因：

1. 首版目标是“可用的后台能力”，不是新建一套复杂前端基建。
2. 管理页面交互相对简单，直接内嵌更易随服务端一起部署。
3. 可以避免新增构建链和静态资源发布路径。

### 4.3 数据库信息来源

数据库概览不走本地 CLI shell，也不依赖前端直接访问数据库。

首版采用两类信息源：

1. 服务端配置与连接信息：来自 `api-server` 当前 `AppConfig`。
2. SpacetimeDB 真正的数据库元信息与表行数：由 `api-server` 通过 SpacetimeDB 官方 HTTP API 读取。

读取口径：

1. `/v1/database/{database}`：读取数据库基础信息。
2. `/v1/database/{database}/schema`：读取 schema 信息。
3. `/v1/database/{database}/sql`：对受控表执行 `SELECT COUNT(*)` 统计。

说明：

1. 首版只做只读概览，不暴露任意 SQL 输入。
2. 表清单由后端显式维护，避免用户在后台拼接任意查询。

## 5. 管理员鉴权设计

### 5.1 管理员账号来源

首版不复用普通玩家账号仓储，不把管理员账号混进 `module-auth` 用户表。

管理员账号来自环境变量：

1. `GENARRATIVE_ADMIN_USERNAME`
2. `GENARRATIVE_ADMIN_PASSWORD`

原因：

1. 管理员是平台运维身份，不等于玩家账号。
2. 首版目标是尽快落地可靠后台，不引入额外管理员表迁移。
3. 环境变量方案最适合当前阶段的单后台入口。

### 5.2 管理员 JWT

后台登录成功后签发独立管理员 Bearer JWT。

claims 设计：

1. 继续复用 `platform-auth::AccessTokenClaims`。
2. `roles` 固定包含 `admin`。
3. `sub` 使用稳定管理员主体，例如 `admin:<username>`。
4. `sid` 使用后台会话 ID。
5. 不写 refresh cookie。

### 5.3 权限校验

新增 `require_admin_auth` 中间件，校验规则如下：

1. Bearer token 必须可被当前 JWT 配置正确验签。
2. `roles` 中必须包含 `admin`。
3. `sub` 必须匹配当前管理员配置主体。

普通用户 token 即使同样由本服务签发，只要不带 `admin` 角色，也一律拒绝访问后台接口。

## 6. 后台页面设计

首版页面包含三个主区域：

1. 登录卡片。
2. 数据库概览面板。
3. API 调试面板。

交互原则：

1. 页面简洁，不默认塞说明性长文案。
2. 移动端优先，窄屏下卡片改纵向堆叠。
3. API 调试结果在独立结果面板展示，不在按钮下方临时插一段文本。

## 7. 数据库概览设计

`GET /admin/api/overview` 返回以下信息：

1. 当前服务监听信息。
2. 当前 `SpacetimeDB server/database` 配置。
3. `SpacetimeDB` 数据库基础信息。
4. 当前 schema 表清单。
5. 首批关键表的行数统计。

首批关键表固定覆盖：

1. `runtime_setting`
2. `runtime_snapshot`
3. `user_browse_history`
4. `profile_dashboard_state`
5. `profile_wallet_ledger`
6. `profile_played_world`
7. `profile_save_archive`
8. `story_session`
9. `story_event`
10. `battle_state`
11. `inventory_slot`
12. `quest_record`
13. `quest_log`
14. `treasure_record`
15. `npc_state`
16. `custom_world_profile`
17. `custom_world_gallery_entry`
18. `custom_world_agent_session`
19. `custom_world_agent_message`
20. `custom_world_agent_operation`
21. `custom_world_draft_card`
22. `big_fish_creation_session`
23. `big_fish_agent_message`
24. `big_fish_asset_slot`
25. `big_fish_runtime_run`
26. `puzzle_work_profile`
27. `puzzle_agent_session`
28. `puzzle_agent_message`
29. `puzzle_runtime_run`
30. `ai_task`
31. `ai_task_stage`
32. `ai_text_chunk`
33. `ai_result_reference`
34. `asset_object`
35. `asset_entity_binding`

返回中的计数失败项必须带错误信息，不能静默吞掉。

## 8. API 调试设计

`POST /admin/api/debug/http` 提供一个受控 HTTP 调试代理。

请求参数：

1. `method`
2. `path`
3. `headers`
4. `body`

限制：

1. 只允许访问当前服务同源相对路径。
2. 调试回环地址由服务端按当前 `bind_host` 解析；若服务监听在 `0.0.0.0` 或 `::`，后台自动改走 loopback，避免把通配监听地址直接当成调试目标。
2. 禁止调 `/admin/api/login` 本身，避免自套娃。
3. 禁止覆盖 `host`、`content-length` 等危险头。
4. 请求超时固定收口。
5. 返回调试结果时回显状态码、响应头、响应文本预览。

该能力用于验证当前服务端接口，不等价于通用代理工具。

## 9. 配置项

新增以下环境变量：

1. `GENARRATIVE_ADMIN_USERNAME`
2. `GENARRATIVE_ADMIN_PASSWORD`
3. `GENARRATIVE_ADMIN_TOKEN_TTL_SECONDS`

默认策略：

1. 若未配置用户名或密码，则后台登录接口返回 `503`，后台页面显示“后台未启用”。
2. 默认管理员 token TTL 为 `4` 小时。

## 10. 测试要求

至少覆盖：

1. 管理员登录成功。
2. 管理员密码错误返回 `401`。
3. 普通用户 token 访问后台接口返回 `403`。
4. 未登录访问后台接口返回 `401`。
5. 后台概览接口在未启用管理员配置时返回 `503`。
6. API 调试接口能成功访问 `/healthz`。
7. API 调试接口拒绝绝对 URL 和后台自身登录接口。

## 11. 路由清单

首版新增路由：

1. `GET /admin`
2. `POST /admin/api/login`
3. `GET /admin/api/me`
4. `GET /admin/api/overview`
5. `POST /admin/api/debug/http`

## 12. 完成定义

满足以下条件时，本任务视为完成：

1. `api-server` 内存在受保护后台管理域。
2. 管理员用户名密码可登录。
3. 普通用户 token 无法访问后台接口。
4. 后台能看到服务和数据库真实概览。
5. 后台能调试当前服务 HTTP 接口。
6. 路由索引与技术文档已同步更新。