📝 docs(timing): 补充提醒触发器模块设计 - #223
Open
jing-gou wants to merge 1 commit into
Open
Conversation
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
![fennoai[bot]](https://avatars.githubusercontent.com/in/1924301?s=60&v=4){kind=small}
| - `snooze` 和 `dismiss` 只作用于该条 `trigger`，不修改日程及后续 occurrence。 | ||
|
|
||
| - **`notification_outbox` 通知发件箱** | ||
| - `trigger` 释放时与其原子写入的可靠投递记录，每个输出目标一条。 |
| ### 4.2 到期推进与直接输出 | ||
|
|
||
| 1. 定时器唤醒、设备启动、日程注册完成或 Outbox 重试到期时，Runtime 调用 `RunDueTriggers(now)`。 | ||
| 2. Runner 取得 `trigger_at <= now` 的活动触发；对每条触发原子地标记为 `released`，并为 `voice_reminder`、`im_notification` 等目标写入稳定 `delivery_id` 的 Outbox 记录。 |
There was a problem hiding this comment.
P1 — 在释放流程中物化下一次 occurrence
第 47 行要求周期日程在当前触发释放后注册下一条，但这里的事务只做 released + Outbox，第 199 行也只保证这两者原子。按这段主流程实现，首次 occurrence 释放后将不再有活动 trigger。请把查询并注册下一 occurrence 纳入明确流程，并说明它与释放事务的原子性或失败补偿。
|
|
||
| ### 4.5 注释 - 硬件定时与唤醒 | ||
|
|
||
| 1. Runtime 从持久化 `trigger.trigger_at` 与 Outbox 的下次重试时间中选出最近时间，使用 `esp_timer` 设置一次性唤醒。 |
There was a problem hiding this comment.
P1 — 不要用 esp_timer 表示深睡唤醒
第 10 行引用的 ESP-IDF 6.0.2 文档明确说明 esp_timer 在 Deep-sleep 中会停用；它只能配合运行态/Light-sleep 调度，深睡定时唤醒需要配置 sleep timer wake source，并在重启入口调用 Runner。当前描述会让按文档实现的设备在深睡后无法按提醒时间唤醒。请区分两种电源模式及对应 Adapter。
| - `released` 仅表示已写入 Outbox；各输出的完成情况只由 Outbox 状态表达。 | ||
|
|
||
| - `notification_outbox.status` | ||
| - 非终态：`pending`、`processing`、`retry_pending`。 |
There was a problem hiding this comment.
P1 — 给 processing 状态定义可恢复的租约
Runner 若先持久化 processing，随后在调用 Port 前重启，该记录既不是 pending / retry_pending，模型中也没有 claimed_at、lease_until 或 owner 可用于回收，会永久停止投递。请定义领取与超时回收规则并补齐字段，或不要持久化这个中间状态。
V3 文档存在自洽性漏洞与精简遗留：周期日程释放后未注册下一次 occurrence，正常完成的 trigger 无终态，upsert 幂等规则缺失， 多提醒建模与 IM 动作通道未对齐。 修订内容：RunDueTriggers 在释放事务内注册下一次触发； trigger.status 补 completed 终态；upsert 改为 reminders 数组 全量同步，按 (schedule_id, offset_minutes) 定位旧触发； 新增 reminder_config 表持久化提醒配置；snooze 取消旧 pending/retry_pending Outbox；动作入口对接 ImActionChannel。 纯文档修订，未触发构建；reminder_config 为新增表，IM 契约 （taskId/instanceId）变更待跨团队对齐。 Refs 1024XEngineer#216
jing-gou
force-pushed
the
dev/216-reminder-trigger-module
branch
from
August 11, 2026 08:42
b9f9e15 to
f0f3d54
Compare
Collaborator
Author
FennoAI 结果发现 3 个实现前需要明确的设计问题：
验证
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
结论：新增提醒触发器模块设计文档，明确日程、提醒触发、Outbox、语音与 IM Port 的边界。
背景：需要将提醒从旧的 timer_task、timer_instance、reminder_rule 和动作执行模型中简化出来，并适配 ESP32 定时唤醒。
改动范围：新增 local/reminder-module.md，定义 RegisterTrigger、RunDueTriggers、trigger、notification_outbox、输出 Port、重试和 esp_timer 触发流程。
明确没有改动：没有修改代码、日程模块实现、IM 实现、local/action-module.md 或其他文档。
接口与依赖影响：仅新增设计约束；实现阶段将由 Runner 依赖日程查询 Port、ReminderOutputPort 和 ImNotificationPort，不直接依赖平台 SDK。
测试与构建证据：git diff --cached --check 通过；本 PR 仅包含 Markdown 文档，未运行固件或主机测试。
已知风险：文档中的持久化结构、Outbox 恢复策略和硬件深度睡眠适配仍需实现阶段验证。
兼容窗口与回退：当前无运行时兼容影响；如设计不采纳，可回退提交 ec15d51。
Refs #216