Genarrative/.hermes/skills/genarrative-admin-backoffice/references/spacetimedb-http-sql-sats-display.md

SpacetimeDB HTTP SQL SATS 值后台展示处理

本参考用于 Genarrative 后台通过 SpacetimeDB HTTP SQL 读取表明细并展示/导出时，处理 SQL rows 中的 SATS 原始 JSON 值。

典型现象

读取 private table（例如 tracking_event）后，HTTP SQL 可能返回如下原始形态：

• enum：RuntimeTrackingScopeKind::User 返回 [3, []]
• Option<String>::Some("user_00000001") 返回 [0, "user_00000001"]
• Option<String>::None 返回 [1, []]
• Timestamp 返回 [1778207451731746]

如果直接 value.to_string() 展示，后台会出现 [3,[]]、[0,"..."]、[1,[]]、[1778207451731746]，运营不可读。

推荐处理

1. 后端解析层优先标准化：
   • Option：[0, value] -> value，[1, []] -> None
   • enum：按生成 binding 的 variant 顺序映射，例如 RuntimeTrackingScopeKind 为 site/work/module/user，索引 0/1/2/3 分别对应这些字符串
   • Timestamp：单元素数组 [micros] -> "micros"
2. 前端展示层再格式化时间：
   • 纯数字时间戳按微秒处理：Date(Math.floor(micros / 1000))
   • ISO 字符串用 new Date(value)
   • 展示为 YYYY-MM-DD HH:mm:ss
3. 列表、详情弹窗、Excel 导出必须使用同一套格式化结果，避免导出仍残留 SATS 原始值。
4. 增加单测覆盖 SATS 原始 rows，至少断言：
   • [3, []] -> user
   • [0, "user"] -> Some("user")
   • [1, []] -> None
   • [1778207451731746] -> "1778207451731746"

验收建议

• cargo test -p api-server admin_tracking -- --nocapture
• npm run admin-web:typecheck
• npm run admin-web:build
• npm run check:encoding
• git diff --check

注意

不同 enum 的 variant 顺序必须以生成 binding 或 module 源码为准，不能复用其他 enum 的索引映射。