# 架构设计

RRuleLab 采用“解析—校验—展开—组合—审计—接口”分层。各层只依赖更底层的稳定数据结构，命令行只是库 API 的薄封装。

```text
RRULE / iCalendar text
        │
        ▼
 parser + typed model ──► validation + explanation
        │
        ▼
 bounded expansion engine
        │
        ▼
 recurrence set (RRULE/RDATE/EXDATE)
        │
        ├──► behavioral diff
        ├──► schedule audit
        ├──► collision/free-time analysis
        └──► CLI / MoonBit package
```

## 模块

| 模块 | 职责 |
|---|---|
| `datetime.mbt` | 公历、星期、epoch 换算和确定性日期运算 |
| `duration.mbt` | ISO 8601 持续时间解析和日历加法 |
| `rrule_model.mbt` | 类型化 RRULE、规范化与语义诊断 |
| `rrule_parser.mbt` | 文本解析、中英文解释 |
| `recurrence_engine.mbt` | 候选生成、BY 过滤、BYSETPOS 与安全上限 |
| `recurrence_set.mbt` / `ical.mbt` | 规则集合、RDATE/EXDATE、iCalendar 子集 |
| `schedule_audit.mbt` | 指标、质量发现、冲突和变更影响 |
| `business_calendar.mbt` | 工作周、节假日和业务日顺延规则 |
| `time_range.mbt` | 半开区间、合并、交集和空闲窗口 |
| `cli.mbt` | 无进程副作用的可测试命令分派 |

## 关键决策

1. 日期时间内核使用本地浮动时间，不隐式读取系统时区。时区数据库属于独立适配层，保证 Wasm、JS 与不同机器结果一致。
2. 所有展开必须提供半开时间窗口 `[start, end)`，同时设置输出上限和迭代上限，避免无界规则耗尽资源。
3. RRULE 先解析为类型化模型，再做语义校验。规范化不会掩盖错误，调用方可以稳定处理诊断码。
4. 规则差异按实际实例集合计算，不用字符串差异代替行为差异。
5. 事件和忙碌时间使用半开区间，端点相接不算冲突，可避免连续预约被重复计时。

## 功能边界与维护

0.1.x 保持核心日期与规则类型兼容，优先补充 RFC 边界用例、诊断和性能。完整时区、CalDAV 与完整 iCalendar 组件不会塞入核心包；未来应作为显式扩展包维护。