Genarrative/.hermes/skills/genarrative-admin-backoffice/references/admin-tracking-events-export-2026-05-07.md

后台埋点数据页与本地启动验证记录（2026-05-07）

背景

本次在 Genarrative/百梦后台新增“埋点数据”页：

• 后端新增 GET /admin/api/tracking/events。
• shared-contracts 新增 admin tracking query/list/entry DTO。
• 前端新增 #tracking 路由、导航、表格、详情面板与 .xls 导出。
• 导出使用浏览器端 HTML table + Excel MIME，不引入 xlsx 依赖。

关键实现点

• 后台只读接口仍必须套 require_admin_auth。
• SpacetimeDB 明细读取使用 HTTP SQL，不新增 reducer、不改 schema。
• SQL 固定白名单列，不用 SELECT *。
• Query 只允许 eventKey/userId/scopeKind/scopeId/limit。
• scopeKind 只允许 site/work/module/user。
• limit 默认 200，最大 1000。
• SpacetimeDB HTTP SQL 响应要兼容 statement array + rows，Option 可能表现为 { "some": value }。
• 前端导出 .xls 时给单元格加 mso-number-format:'\\@';，防止 Excel 把 ID 转科学计数法。

验证命令

cd <repo-root>/.worktrees/hermes-996d586b
npm install                         # 若 node_modules 缺失
npm run admin-web:typecheck
npm run admin-web:build
npm run check:encoding

cd server-rs
cargo fmt -p api-server -p shared-contracts --check
cargo test -p api-server admin_tracking -- --nocapture

本地启动观察

启动命令：

cd <repo-root>/.worktrees/hermes-996d586b
npm run api-server
npm run admin-web:dev -- --host 127.0.0.1

实际验证：

• api-server 监听 127.0.0.1:3100，健康检查为 http://127.0.0.1:3100/healthz。
• admin-web 监听 127.0.0.1:5173，后台地址为 http://127.0.0.1:5173/admin/。
• 请求 http://127.0.0.1:5173/ 会 302 到 /admin/。
• 不能默认用 3200 检查 api-server；本地脚本通过 GENARRATIVE_API_PORT=3100 启动。
• 如果启动日志出现 SpacetimeDB 127.0.0.1:3101 connection refused，api-server 仍可能已正常监听；这是依赖的本地 SpacetimeDB 未启动，埋点页读真实数据会受影响。