54 lines
2.0 KiB
Markdown
54 lines
2.0 KiB
Markdown
# 后台埋点数据页与本地启动验证记录（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>
|
||
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>
|
||
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 未启动，埋点页读真实数据会受影响。
|