Genarrative/.hermes/skills/genarrative-admin-backoffice/references/admin-database-table-query-2026-05-08.md

本次后台表查询接入的可复用经验

需求落点

• 后台“总览”页的表统计仍保留，只把每张表的表名改成可点击跳转到 #tables?table=<name>。
• 新增独立 #tables 页承载表选择、关键词搜索、JSON filters、limit、行详情弹窗。

后端实现要点

• 新增只读接口：
  • GET /admin/api/database/tables
  • GET /admin/api/database/tables/{table_name}/rows
• 表名必须来自 schema 白名单；再加一层 identifier 校验，避免任意 SQL 表名注入。
• limit 必须 clamp；本次实现使用默认 100、最大 500。
• search / filters 不进入 SQL 字符串：
  • SQL 只负责 SELECT * FROM {table_name} LIMIT {limit}
  • 返回后在 api-server 内存中过滤
  • filters 仅接受 JSON object，按列名匹配；非 object 直接 400
• SpacetimeDB HTTP SQL 返回可能是 statement array + rows，解析时要兼容这一层结构。

前端实现要点

• adminRoutes 必须新增 tables，AdminShell.routeIcons 也要同步覆盖。
• AdminApp 需要显式渲染 AdminDatabaseTablesPage。
• worktree 下可能没有本地 node_modules/typescript/bin/tsc，而根目录有依赖；在验证前可以临时把根目录 node_modules 软链到 worktree 再执行 npm run admin-web:typecheck，验证后删除软链，避免污染 git 状态。

验证结果

• cargo test -p api-server admin_database -- --nocapture 通过。
• cargo fmt --manifest-path Cargo.toml -p api-server -p shared-contracts --check 通过。
• npm run admin-web:typecheck 通过。
• npm run admin-web:build 通过。
• npm run check:encoding 通过。