# 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 的索引映射。