docs: add shared admin backoffice skill

This commit is contained in:
2026-05-08 16:58:28 +08:00
parent b995809f75
commit 747ef790ac
7 changed files with 545 additions and 0 deletions

View File

@@ -0,0 +1,43 @@
# 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 的索引映射。