task_pilot/docs/decisions/0001-cron-engine.md

ADR-0001：Cron 解析与任务调度

• 状态：已接受
• 日期：2026-10-18

背景

TaskPilot 需要校验 5 位和 6 位 Cron 表达式、计算未来执行时间，并支持在任务创建、编辑、启停后动态调整调度。

决策

使用 croner 负责 Cron 表达式解析和下次执行时间计算，使用 Tokio 定时循环负责任务注册、等待和触发。

第一阶段验证结果：

• 支持 5 位分钟级和 6 位秒级表达式。
• 支持 @hourly 等别名。
• 支持月份和星期名称，星期 7 与 0 均表示星期日。
• 默认按 POSIX 语义处理日和星期的组合。
• 非法的 */0 会被拒绝，不会形成无限循环。
• 可从指定时间计算下一次及连续多次执行时间。

原因

• croner 专注解析和日期计算，不绑定调度运行时。
• 自建 Tokio 循环可以按 SQLite 中的任务状态动态注册和取消任务。
• 避免将持久化任务 ID 和外部调度器 ID 做双重状态映射。
• 后续可以替换触发层而无需更换 Cron 表达式语义。

影响

• 调度器需要自行维护任务句柄、取消信号和执行并发策略。
• 必须用可控时间测试覆盖等待逻辑、任务更新和进程关闭。
• 时区支持继续使用 Chrono 的时区能力，Phase 2 引入 chrono-tz 存储 IANA 时区。