# MoonCalGuard 项目申报书

## 基本信息

- 项目名称：MoonCalGuard：MoonBit 原生 iCalendar/ICS 解析、校验、重复规则、提醒与报告工具库
- 参赛者：吴越腾
- 联系方式：以黑客松报名问卷填写信息为准
- GitHub 仓库链接：https://github.com/WYT-ai-nb/mooncalguard
- 项目方向：MoonBit 原生开源库 / 文件格式解析 / 规则校验 / 数据导出工具
- 是否为移植项目：否，原创 MoonBit 开源项目
- 开源许可证：MIT

## 项目简介

MoonCalGuard 是一个纯 MoonBit 实现的 iCalendar / ICS 解析、校验、导出、重复规则分析、提醒校验、议程查询与事件差异检测库。项目将 `.ics` 文本解析为结构化日历模型，检查常见 RFC5545 规则问题，识别 `RRULE` 重复规则和 `VALARM` 提醒配置，并能按事件 `UID` 比较两个日历版本的新增、删除和修改。它补足 MoonBit 生态中日历文件处理能力，可用于课程表、会议日程、活动报名系统、日历订阅源和 CI 数据检查。

## 项目方向与适用场景

本项目面向 MoonBit 库作者、工具开发者、教学项目和需要导出日历数据的应用。典型场景包括：发布前校验日历订阅源；检查 `UID`、`DTSTAMP`、`DTSTART/DTEND` 等关键字段；规范化导出 ICS；比较活动日程版本变更；在 CI 中把日历 fixture 作为可测试资产管理。

## 拟实现的核心功能

- iCalendar content line、参数、折行和嵌套组件解析；
- VCALENDAR、VEVENT、VTODO、VJOURNAL、VTIMEZONE、STANDARD/DAYLIGHT、VALARM 基础建模；
- 严格/宽松校验策略，覆盖版本、PRODID、UID、DTSTAMP、时间格式、DTEND/DURATION 冲突等规则；
- `RRULE` 解析、规范化与校验，覆盖 FREQ、INTERVAL、COUNT、UNTIL、WKST、BYDAY、BYMONTH、BYMONTHDAY、BYSETPOS；
- `DURATION` 与 `VALARM` 校验，覆盖 ACTION、TRIGGER、DESCRIPTION、SUMMARY、ATTENDEE、REPEAT、DURATION；
- 内置属性目录，检查 property 所属组件、重复字段、未知字段和扩展字段；
- 日历统计、Markdown/JSON 风格报告、议程渲染、日期/状态/提醒/重复事件查询；
- 规范化 ICS 导出与文本转义；
- 基于事件 `UID` 的日历 diff；
- 提供自制 fixture、单元测试、可运行 demo、README、CI 和 Mooncakes 发布配置。

## 项目现有基础与本次计划

当前已经完成 MoonBit 工程骨架、核心数据模型、嵌套组件解析器、RRULE 解析器、DURATION 解析器、VALARM 分析器、属性目录、校验器、报告生成器、议程查询、导出器、事件 diff、自制 fixture、测试、demo 入口、README、设计说明、调研记录、MIT 许可证与 GitHub Actions CI。当前本地有效 MoonBit 代码约 5245 行，已经达到 4k 规模参考。本地已通过 `moon fmt --check`、`moon check --deny-warn`、`moon build`、`moon test --deny-warn`、`moon info` 和 demo smoke test。后续发布前需要推送公开仓库并发布到 Mooncakes。

## 创新点

- 面向 MoonBit 生态的原生 ICS 质量门禁：不是简单字符串工具，而是把日历文件解析为可校验、可统计、可 diff 的结构化模型；
- 把重复规则、提醒配置、属性目录和 CI 报告组合在一起，适合课程表、会议日程、活动报名系统等实际数据发布流程；
- 支持 Markdown/JSON 风格报告与议程查询，可作为命令行、CI、网站后端或教学样例的基础库；
- 实现不依赖外部运行时和第三方源码，便于 Mooncakes 发布、审计和二次开发。

## 原创或参考说明

本项目为原创 MoonBit 实现，不移植第三方源码，不包含来源不明素材或私有代码。项目依据公开 iCalendar / RFC5545 格式规则设计解析和校验流程，测试 fixture 由项目内文本自制。