按发生时间倒序展示客户端埋点

调整事件查询排序及分页游标,保留入库时间快照隔离。
同步后台说明、定向测试和技术文档。
This commit is contained in:
2026-09-22 12:48:49 +00:00
parent fe19a2c4db
commit e07b12daf9
6 changed files with 28 additions and 24 deletions
@@ -1,6 +1,6 @@
# 客户端本地埋点与主站入库契约
Version: 0.27
Version: 0.28
Status: 本地采集及上传、入库、成功清理、后台查询已实现并完成本地隔离环境验收;未部署生产
Date: 2026-09-21
需求来源:[Game Agent 埋点设计原始方案](./【需求来源】GameAgent埋点设计原始方案-2026-09-05.md);原始方案与后续已确认决策有差异时,以本文为准。
@@ -675,8 +675,8 @@ batch_id 是传输关联标识,event_id 是持久幂等依据。一张表不
- UI 首版展示发生时间范围、用户、项目和事件类型;其他关联筛选可通过详情入口携带,均使用精确匹配,不引入全文搜索。
- 时间范围按 event_time,起点包含、终点不包含;时间格式为带时区 RFC3339。默认不设时间过滤,默认每页 50 条,最大 200 条。
- 返回 payload:`entries`、`nextCursor`。条目包括表内字段的 camelCase 映射,`properties` 返回解析后的 JSON 对象;时间转为 UTC 字符串,Option 转 null,不向 UI 暴露 SATS 原始值。
- 列表按首次入库时间 received_at 倒序,同时间按 event_id 稳定排序;明确列标题为“入库时间”和“发生时间”,不混称最新发生的事件。
- cursor 固定查询快照上界、最后一行的 (received_at, event_id) 和筛选摘要;切换筛选重置游标,非法游标返回 400。新增数据点击刷新后出现,分页不依赖会随插入漂移的 offset。
- 列表按发生时间 event_time 倒序,同时间按 event_id 倒序稳定排序;明确列标题为“入库时间”和“发生时间”,补传的历史事件按实际发生时间归位。
- cursor 固定入库时间快照上界、最后一行的 (event_time, event_id) 和筛选摘要;切换筛选重置游标,非法游标返回 400。新增数据点击刷新后出现,分页不依赖会随插入漂移的 offset。旧排序游标失效,刷新列表重新查询;不改变存储表及索引。
- 由数据库查询路径按索引及条件确定排序候选与页边界;若当前 SQL 不支持排序,通过受限 typed procedure 完成。不能任取 LIMIT N 行后排序并宣称为全表最新;实现计划须在现役 2.8.3 上验证此点,不照搬旧页面的截断查询方式。
列表列:入库时间、发生时间、用户、事件中文名、项目、来源、结果、客户端版本。空值显示“—”。详情展示全部既有字段与格式化 properties,包括会话/run/批次 ID;不新增编辑或删除按钮。空结果、加载失败、无权限沿用后台现有反馈,移动端表格支持横向滚动。
@@ -709,7 +709,7 @@ batch_id 是传输关联标识,event_id 是持久幂等依据。一张表不
运行时 smoke 必须包含真实 SpacetimeDB 提交及后台页面;mock 请求成功不算完成入库验收。不需要为本轮重新调用付费模型或扩大 Agent 创作测试。
本版实施口径为:只接收已登录用户、一张事件表、原子整批提交、首轮等待 15 分钟、30 秒请求超时、20 批/2 分钟轮次预算、失败下周期重试、后台按入库时间分页、服务端暂不自动过期。已确认的采集范围、上传周期、静默非阻塞和成功删除原则不变。
本版实施口径为:只接收已登录用户、一张事件表、原子整批提交、首轮等待 15 分钟、30 秒请求超时、20 批/2 分钟轮次预算、失败下周期重试、后台按发生时间倒序分页、服务端暂不自动过期。已确认的采集范围、上传周期、静默非阻塞和成功删除原则不变。
### 13.11 实现与验证记录(2026-09-21)