DOC-FULL-004：ActiveTimeTracker V2 #105

New Issue

wangdl · 2026-06-10T21:18:32+08:00

wangdl commented

2026-06-10 21:18:32 +08:00

目标

实现 V2 有效学习时长计算器。iOS 每 15 秒调用 Rust heartbeat，Rust 根据 timestamp 计算 activeSecondsDelta。

核心规则

Rust 不自己开 timer。
iOS 控制 tick。
Rust 接收 heartbeat timestampMs。
Rust 根据上次 active timestamp 计算 delta。
delta 必须是本次新增有效学习秒数。
delta 不应是累计值。
App pause / background 时不继续累加。
超长间隔需要 clamp 或标记 warning，避免一次 heartbeat 产生异常大时长。

建议配置

heartbeatIntervalSeconds = 15
maxDeltaSeconds = 60
idleThresholdSeconds = 60

需要支持

start(timestampMs)
heartbeat(timestampMs)
pause(timestampMs)
resume(timestampMs)
close(timestampMs)

warning 建议

heartbeat_gap_too_large
timestamp_reversed
session_not_active
delta_clamped

验收标准

heartbeat 返回 activeSecondsDelta。
delta 是增量，不是累计。
timestamp 倒退时不产生负数。
超长间隔被 clamp 或 warning。
pause 后 heartbeat 不继续计算有效学习时间。
resume 后重新计算。
close 时返回最后残余 delta。
有完整单元测试。

## 目标实现 V2 有效学习时长计算器。iOS 每 15 秒调用 Rust heartbeat，Rust 根据 timestamp 计算 activeSecondsDelta。 ## 核心规则 1. Rust 不自己开 timer。 2. iOS 控制 tick。 3. Rust 接收 heartbeat timestampMs。 4. Rust 根据上次 active timestamp 计算 delta。 5. delta 必须是本次新增有效学习秒数。 6. delta 不应是累计值。 7. App pause / background 时不继续累加。 8. 超长间隔需要 clamp 或标记 warning，避免一次 heartbeat 产生异常大时长。 ## 建议配置 - heartbeatIntervalSeconds = 15 - maxDeltaSeconds = 60 - idleThresholdSeconds = 60 ## 需要支持 ``` start(timestampMs) heartbeat(timestampMs) pause(timestampMs) resume(timestampMs) close(timestampMs) ``` ## warning 建议 - heartbeat_gap_too_large - timestamp_reversed - session_not_active - delta_clamped ## 验收标准 1. heartbeat 返回 activeSecondsDelta。 2. delta 是增量，不是累计。 3. timestamp 倒退时不产生负数。 4. 超长间隔被 clamp 或 warning。 5. pause 后 heartbeat 不继续计算有效学习时间。 6. resume 后重新计算。 7. close 时返回最后残余 delta。 8. 有完整单元测试。

wangdl added this to the M-DOC-FULL：Document Runtime 完整阅读内核与学习事件协议 milestone 2026-06-10 21:18:32 +08:00

wangdl added the

priority:p0

area:document-runtime

repo:document-runtime

labels 2026-06-10 21:18:32 +08:00

wangdl commented

2026-06-11 21:07:56 +08:00

完成证据

产物: crates/zx_document_core/src/time_tracker.rs (166 行)
已有提交: 66649bb feat: DOC-FULL-004 ActiveTimeTracker

核心规则:

Rust 不自己开 timer（已有：iOS controls when to call tick）
iOS 控制 tick（每 15s），Rust 计算 delta
delta 是增量，非累计（已有 tick() → pause() → resume()）
timestamp 倒退不出负数（已有 test test_time_goes_backwards）
pause 后 tick 归零，resume 后重新计算
close 返回残余 delta

测试: 8 个已有测试 (test_start_returns_zero, test_43_seconds_total, test_pause_stops_time, test_inactive_tick_returns_zero, test_close_returns_residual, test_close_inactive_returns_zero, test_time_goes_backwards, test_remainder_accumulates) — 168 passed

## 完成证据 **产物**: `crates/zx_document_core/src/time_tracker.rs` (166 行) **已有提交**: `66649bb` feat: DOC-FULL-004 ActiveTimeTracker **核心规则**: - Rust 不自己开 timer（已有：`iOS controls when to call tick`） - iOS 控制 tick（每 15s），Rust 计算 delta - delta 是增量，非累计（已有 tick() → pause() → resume()） - timestamp 倒退不出负数（已有 test `test_time_goes_backwards`） - pause 后 tick 归零，resume 后重新计算 - close 返回残余 delta **测试**: 8 个已有测试 (test_start_returns_zero, test_43_seconds_total, test_pause_stops_time, test_inactive_tick_returns_zero, test_close_returns_residual, test_close_inactive_returns_zero, test_time_goes_backwards, test_remainder_accumulates) — 168 passed

wangdl closed this issue

2026-06-11 21:07:57 +08:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: wangdl/zhixi-document-runtime#105