docs: 同步引擎设计定稿,API 时刻改为 Unix 秒

独立 apps/engine、setTimeout 轮次、engine_status 快照、不为 CFW 预留;
公共约定 §4 响应时刻统一 Unix 秒;契约 engine 增 sync_interval_ms。
This commit is contained in:
2026-10-07 12:53:37 +08:00
parent de48e5d39c
commit 3e12db1706
5 changed files with 213 additions and 6 deletions
+4 -3
View File
@@ -56,9 +56,10 @@
## 4. 时间口径
- **传输格式:ISO 8601 UTC 字符串**(如 `2026-10-02T14:22:05Z`)——自描述;存储层维持 UTC Unix 秒(表设计约定),DTO 层转换;北京时间展示由前端完成(共性 §3.3)
- **时间范围参数**:`from` / `to`,秒级 ISO 8601 UTC,**左闭右开 `[from, to)`**——快捷项边界无歧义、无跨桶重复计数
- 快捷项(最近 7 / 30 天、本订阅期间、自定义起止)是前端预置逻辑:前端算出 `from/to` 再请求,后端无快捷参数;「本订阅期间」的期间数据来源归后两篇各自定义
- **响应时刻字段:Unix 秒整数**(UTC 时刻,如 `1780000000`)——无时区歧义;本地/北京时间由展示层转换
- **请求时间参数**(`from` / `to` 等):ISO 8601 UTC 字符串(便于试调);范围 **左闭右开 `[from, to)`**
- 存储层维持 timestamptz / 上游 Unix 秒;DTO 输出统一 `toUnixSec`
- 快捷项(最近 7 / 30 天、本订阅期间、自定义起止)是前端预置逻辑:前端算出 `from/to` 再请求,后端无快捷参数
## 5. 数值口径(对齐共性 §3.2)