# 后台数据库表查询技术方案（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`