Genarrative/docs/technical/ADMIN_DATABASE_TABLE_QUERY_2026-05-08.md

后台数据库表查询技术方案（2026-05-08）

背景

后台“总览”页已经通过 /admin/api/overview 展示 SpacetimeDB 表统计，但只能看到表名、行数和统计状态。运营和排障时需要从统计行直接进入单表查询页，按基础条件快速查看真实行数据。

目标

• 在后台新增“表查询”页，支持所有 schema 表的只读查询。
• “总览 / 表统计”中的每一行可点击跳转到对应表的查询页。
• 提供基础查询能力：表选择、关键词搜索、JSON 条件过滤、条数限制、刷新、查看行详情。
• 不修改 SpacetimeDB 表结构，不新增 reducer，不引入写操作。

后续增强

• 查询页增加“重置条件”快捷操作，便于运营快速回到默认筛选状态。
• 行详情支持一键复制完整 JSON，减少人工选中复制的操作成本。
• 查询页顶部增加轻量摘要，显示当前选表和可见列数，方便移动端快速确认上下文。

后端接口

GET /admin/api/database/tables

鉴权：沿用 require_admin_auth。

数据来源：SpacetimeDB schema HTTP API。

响应：

{
  "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}；后端返回行后按字段等值过滤。

响应：

{
  "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