99 lines
3.7 KiB
Markdown
99 lines
3.7 KiB
Markdown
# 后台数据库表查询技术方案（2026-05-08）
|
||
|
||
## 背景
|
||
|
||
后台“总览”页已经通过 `/admin/api/overview` 展示 SpacetimeDB 表统计，但只能看到表名、行数和统计状态。运营和排障时需要从统计行直接进入单表查询页，按基础条件快速查看真实行数据。
|
||
|
||
## 目标
|
||
|
||
- 在后台新增“表查询”页，支持所有 schema 表的只读查询。
|
||
- “总览 / 表统计”中的每一行可点击跳转到对应表的查询页。
|
||
- 提供基础查询能力：表选择、关键词搜索、JSON 条件过滤、条数限制、刷新、查看行详情。
|
||
- 不修改 SpacetimeDB 表结构，不新增 reducer，不引入写操作。
|
||
|
||
## 后续增强
|
||
|
||
- 查询页增加“重置条件”快捷操作，便于运营快速回到默认筛选状态。
|
||
- 行详情支持一键复制完整 JSON，减少人工选中复制的操作成本。
|
||
- 查询页顶部增加轻量摘要，显示当前选表和可见列数，方便移动端快速确认上下文。
|
||
|
||
## 后端接口
|
||
|
||
### `GET /admin/api/database/tables`
|
||
|
||
鉴权：沿用 `require_admin_auth`。
|
||
|
||
数据来源：SpacetimeDB schema HTTP API。
|
||
|
||
响应：
|
||
|
||
```json
|
||
{
|
||
"tables": ["tracking_event", "user_account"],
|
||
"fetchErrors": []
|
||
}
|
||
```
|
||
|
||
### `GET /admin/api/database/tables/{tableName}/rows`
|
||
|
||
鉴权：沿用 `require_admin_auth`。
|
||
|
||
Query：
|
||
|
||
- `limit`：默认 100，范围 1-500。
|
||
- `search`：可选，前端关键词；后端返回行后在 JSON 文本中大小写不敏感过滤。
|
||
- `filters`：可选 JSON object 字符串，例如 `{"user_id":"u1","enabled":true}`；后端返回行后按字段等值过滤。
|
||
|
||
响应：
|
||
|
||
```json
|
||
{
|
||
"tableName": "tracking_event",
|
||
"columns": ["event_id", "event_key"],
|
||
"rows": [
|
||
{
|
||
"cells": {
|
||
"event_id": "event-1",
|
||
"event_key": "daily_login"
|
||
},
|
||
"raw": ["event-1", "daily_login"]
|
||
}
|
||
],
|
||
"totalReturned": 1,
|
||
"limit": 100
|
||
}
|
||
```
|
||
|
||
实现约束：
|
||
|
||
- 表名必须来自 schema 且通过标识符安全校验，避免任意 SQL 注入。
|
||
- SQL 固定为 `SELECT * FROM {tableName} LIMIT {limit}`；SpacetimeDB 2.2 HTTP SQL 不拼 `ORDER BY`。
|
||
- 用户输入不直接拼入 SQL；关键词和条件在 API Server 内存中过滤。
|
||
- private 表或 token 不可见时返回后台可读错误信息。
|
||
- SpacetimeDB SQL 行和 SATS 值统一转成人可读 JSON：Option None 为 null，Some 展开为内部值，Timestamp 单元素数组展开为内部值，enum 可保留 tag/name 或原始数组文本。
|
||
|
||
## 前端页面
|
||
|
||
路由：`#tables`，导航名“表查询”。
|
||
|
||
页面能力：
|
||
|
||
- 表选择下拉展示中文表名并保留原始表名，支持 URL hash `#tables?table=xxx` 直达指定表。
|
||
- 查询表单：表名、关键词、JSON 条件、条数。
|
||
- 查询结果表格横向滚动，移动端不撑坏布局。
|
||
- 查询结果标题和已选表摘要展示中文表名，鼠标悬浮显示原始表名和表说明，方便运营识别真实数据域。
|
||
- 表头支持点击排序，排序只作用于当前已拉取的行数据，不改变后端 SQL。
|
||
- 表头展示中文字段名，鼠标悬浮显示原始字段名、字段说明和排序提示，方便运营阅读且保留排障所需的真实列名。
|
||
- 单元格内容过长时在表格内单行省略，完整内容可通过悬浮标题或行详情弹层查看。
|
||
- 每行提供“详情”按钮，以独立弹层展示完整 JSON。
|
||
- 总览表统计行点击后跳转到 `#tables?table={tableName}`。
|
||
|
||
## 验收
|
||
|
||
- `cd server-rs && cargo fmt -p api-server -p shared-contracts --check`
|
||
- `cd server-rs && cargo test -p api-server admin_database -- --nocapture`
|
||
- `npm run admin-web:typecheck`
|
||
- `npm run admin-web:build`
|
||
- `npm run check:encoding`
|
||
- `git diff --check`
|