# MoonCalGuard 设计说明

## 目标

MoonCalGuard 的目标是为 MoonBit 生态补充一个可复用的 iCalendar / ICS 基础库。项目不是页面演示，也不绑定外部工具，而是围绕文本协议解析、结构化模型、规则校验、规范化导出和事件 diff 形成完整能力。

## 模块结构

- `types.mbt`：错误类型、日历模型、校验结果和 diff 类型；
- `text.mbt`：ASCII token、折行展开、切分、转义工具；
- `parser.mbt`：VCALENDAR、嵌套组件、属性和参数解析；
- `recurrence.mbt`：RRULE 解析、规范化、规则形态分析；
- `duration.mbt`：DURATION / TRIGGER 持续时间解析；
- `alarm.mbt`：VALARM 提取、完整性判断和摘要；
- `catalog.mbt`：iCalendar 属性目录、组件归属和字段基线；
- `validate.mbt`：发布前规则校验、属性目录校验、重复规则和提醒校验；
- `report.mbt`：统计、Markdown 报告和 JSON 风格报告；
- `query.mbt`：按 UID、日期、状态、提醒和重复规则查询事件；
- `export.mbt`：规范化 ICS 与报告输出；
- `diff.mbt`：基于 UID 的事件变化检测；
- `fixtures.mbt`：自制 ICS fixture；
- `cmd/demo`：可运行示例。

## 核心流程

1. `split_physical_lines` 兼容 CRLF 和 LF。
2. `unfold_lines` 展开 RFC5545 折行。
3. `parse_content_line` 将 `NAME;PARAM=VALUE:content` 转为结构化属性。
4. `parse_calendar` 使用组件栈识别 `VCALENDAR`、`VEVENT`、`VTODO`、`VTIMEZONE`、`VALARM` 等嵌套结构。
5. `parse_recurrence_rule` 与 `parse_duration` 对 RRULE、DURATION、TRIGGER 做结构化解析。
6. `validate_calendar` 根据严格或宽松策略输出 `Finding`，覆盖属性归属、时间、重复规则、提醒和组件放置。
7. `render_calendar` 输出保留嵌套组件的规范化 ICS。
8. `collect_calendar_stats` 与 `render_calendar_report` 输出可读验收报告。
9. `diff_calendars` 按事件 `UID` 比较新增、删除和修改。

## 创新点

- 避开已有 Wasm 基础库方向，聚焦 MoonBit 生态中少见的日历文件格式处理；
- 将 ICS 解析、校验、导出和 diff 放在同一个 MoonBit 原生库中；
- 支持 CI 作为“日历订阅源发布门禁”使用；
- 测试 fixture 全部项目内自制，验收不依赖来源不明数据；
- 输出面向自动化和人工审查的可读报告。
- 内置属性目录，把“未知字段”和“字段放错组件”变成可测试的诊断能力；
- 支持 RRULE、VALARM、DURATION 和议程查询，覆盖真实日历订阅源常见需求。

## 已知边界

- 不连接网络或读取系统日历；
- 不完整展开无限或复杂 RRULE 实例序列；
- 不内置完整时区数据库；
- 不发送真实提醒、邮件或桌面通知；
- 不执行跨月精确时间运算。