Genarrative/docs/technical/ADMIN_TRACKING_EVENT_DETAIL_EXPORT_2026-05-07.md

后台埋点数据明细与 Excel 导出方案

For Hermes: Use subagent-driven-development skill to implement this plan task-by-task.

Goal: 在百梦后台新增“埋点数据”页，展示每条埋点原始事件的详细字段，并支持导出为 Excel 可直接打开的表格文件。

Architecture: 后端继续由 api-server 作为后台 BFF，经 SpacetimeDB HTTP SQL 只读查询 tracking_event，不改变表结构和 reducer。前端在 apps/admin-web 中新增独立路由与页面，页面渲染后端返回的原始明细，并在浏览器侧导出 Excel 兼容的 .xls HTML 表格，避免新增依赖。

Tech Stack: Rust Axum、SpacetimeDB HTTP SQL、shared-contracts、React 19、TypeScript、Vite。

---

范围

本次只做后台只读能力：

• 展示 tracking_event 原始事件明细。
• 每条埋点展示：事件 ID、Event Key、事件名称、Scope、Scope ID、Day Key、用户 ID、作品拥有者、Profile ID、模块、metadata、发生时间。
• 支持按 Event Key、用户 ID、Scope Kind、Scope ID 筛选。
• 支持导出当前筛选结果为 Excel 可打开文件。

不做：

• 不新增或修改 SpacetimeDB 表结构。
• 不在后台写入或删除埋点。
• 不把埋点聚合口径下沉到前端计算。

后端契约

新增接口：

GET /admin/api/tracking/events?eventKey=&userId=&scopeKind=&scopeId=&limit=

鉴权：复用后台 require_admin_auth。

返回：

{
  "entries": [
    {
      "eventId": "daily-login:user:xxx:123",
      "eventKey": "daily_login",
      "eventTitle": "每日登录",
      "scopeKind": "user",
      "scopeId": "xxx",
      "dayKey": 20580,
      "userId": "xxx",
      "ownerUserId": null,
      "profileId": null,
      "moduleKey": "profile",
      "metadataJson": "{}",
      "occurredAt": "2026-05-07T00:00:00Z"
    }
  ]
}

后端实现要点：

1. DTO 放在 shared-contracts/src/admin.rs，避免 Rust 与前端口径分叉。
2. Handler 放在 api-server/src/admin.rs，使用当前已有 SpacetimeDB HTTP SQL helper 思路。
3. SQL 只读 tracking_event，固定白名单列；由于 SpacetimeDB 2.2 HTTP SQL 不支持 ORDER BY，后端取回默认 200 / 最大 1000 条后在 API 层按 occurred_at 倒序排序。
4. 查询条件只通过字符串转义函数拼接，禁止直接拼接未转义用户输入。
5. eventTitle 由后端根据已知事件 key 映射，未知事件返回 eventKey。

前端页面

新增路由：#tracking，导航标题为“埋点数据”。

页面能力：

1. 顶部筛选区：Event Key、用户 ID、Scope Kind、Scope ID、刷新、导出 Excel。
2. 列表区：移动端可横向滚动，桌面端表格展示。
3. 详情区：每行有“详情”按钮，弹出独立面板展示完整字段与格式化后的 metadata JSON。
4. 导出：导出当前页面已加载结果，文件名形如 tracking-events-2026-05-07.xls。

导出实现：

• 使用 HTML table + Excel MIME：application/vnd.ms-excel;charset=utf-8。
• 文件扩展名使用 .xls，Excel/WPS 可直接打开。
• 所有单元格做 HTML 转义。
• metadata 保留原始 JSON 文本，便于运营继续筛选。

验收命令

npm run check:encoding
npm run admin-web:typecheck
cargo test -p shared-contracts -p api-server admin_tracking -- --nocapture

如后端接口改动较大，再补充：

npm run api-server
curl http://127.0.0.1:<port>/healthz

实施任务

Task 1: 补充 shared-contracts 后台埋点 DTO

Files:

• Modify: server-rs/crates/shared-contracts/src/admin.rs

Steps:

1. 新增 AdminTrackingEventListQuery。
2. 新增 AdminTrackingEventEntryPayload。
3. 新增 AdminTrackingEventListResponse。
4. 为 DTO 添加中文注释。

Task 2: 增加后端后台埋点查询接口

Files:

• Modify: server-rs/crates/api-server/src/admin.rs
• Modify: server-rs/crates/api-server/src/app.rs

Steps:

1. 在 admin.rs 新增 query 解析与 SQL 构造。
2. 复用 SpacetimeDB HTTP SQL 调用风格读取 rows。
3. 新增 admin_list_tracking_events handler。
4. 在 app.rs 挂载 /admin/api/tracking/events。
5. 添加单元测试覆盖 SQL 字符串转义、limit clamp、SQL 响应解析。

Task 3: 增加前端 API 类型与客户端方法

Files:

• Modify: apps/admin-web/src/api/adminApiTypes.ts
• Modify: apps/admin-web/src/api/adminApiClient.ts

Steps:

1. 新增埋点 entry/list/query 类型。
2. 新增 listAdminTrackingEvents(token, query)。
3. 使用 URLSearchParams 拼接非空查询字段。

Task 4: 新增后台埋点数据页面

Files:

• Create: apps/admin-web/src/pages/AdminTrackingEventsPage.tsx
• Modify: apps/admin-web/src/styles/admin.css

Steps:

1. 实现筛选、刷新、错误状态。
2. 实现明细表格。
3. 实现独立详情面板。
4. 实现 Excel .xls 导出。
5. 保持 UI 简洁，不添加说明类大段文案。

Task 5: 接入后台路由与导航

Files:

• Modify: apps/admin-web/src/app/adminRoutes.ts
• Modify: apps/admin-web/src/app/AdminShell.tsx
• Modify: apps/admin-web/src/app/AdminApp.tsx

Steps:

1. 增加 tracking 路由。
2. 导航增加图标。
3. AdminApp 渲染新页面。

Task 6: 验证并提交

Steps:

1. 运行 npm run check:encoding。
2. 运行 npm run admin-web:typecheck。
3. 运行后端相关 cargo test。
4. 修复问题后提交并推送当前分支。