# 后台埋点数据页与本地启动验证记录（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 转科学计数法。

## 验证命令

```bash
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
```

## 本地启动观察

启动命令：

```bash
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 未启动，埋点页读真实数据会受影响。