开发手册：iCal 解析库 + CalDAV 服务器

• 01 定位与证据链
• 02 进度快照
• 03 架构与数据流
• 04 里程碑阶梯 S0–S9
• 05 每步工作流（Definition of Done）
• 06 MoonBit 工程约定与踩坑清单
• 07 上游接缝登记（活文档）
• 08 明确不做（边界）
• 09 风险与对策
• 10 提交与验收映射

01定位与证据链

一句话定位：纯 MoonBit 的 iCalendar（RFC 5545）解析 / 重复事件展开库，长成 mooncakes.io 生态第一个 CalDAV（RFC 4791）日历服务器——把竞品停在「中段计算层」的流水线，接到「真实日历客户端可直连」的服务端。

立项依据（申报书可直接引用，全部 2026-09-08 核实）：

• 生态空位：mooncakes.io 检索 caldav / webdav / webcal / calendar-import 均返回 No modules found。
• 五家竞品全是离线库：mooncal、mooncalguard、rrule_lab、moon-schedule、moonrrule 输入均为调用方喂好的字符串；mooncal 明言「不做 CalDAV 网络同步」「文件输入不属于 0.1.2 范围」。调研期间已按五道工序逐包核实。
• 评委口径：2026-09-08 评委确认「CalDAV 这个选题没问题」。
• 业界参照：Python 的 Radicale 证明「只实现到各家客户端能理解为止」的最小 CalDAV 服务端路线可行；vdir「一文件一项」是跨工具互认的存储约定。

02进度快照

合计：0.2.0 开发分支严格全目标测试为 wasm 150、wasm-gc 137、JavaScript 150、native 155；S5 21 项与 S6 11 项真实 curl 活体验收全绿。Thunderbird 155.0.1（Windows）已完成发现、读取、创建、原位修改与删除的真实 CalDAV 联调。

03架构与数据流

请求自上而下流经六层，每层一个包、单向依赖；层与层之间只经公开接口（.mbti）通信：

已落地包的公开接口（摘自 pkg.generated.mbti）

ical/text:  unfold(String) -> Array[String]
            parse_content_line(String, Int) -> ContentLine raise
            unescape_value(String) -> String
            suberror ParseError::BadLine(line_no~, line~, message~)

ical/model: parse_components(Array[String]) -> Array[Component] raise
            parse_date_time(ContentLine, ZoneTable, line_no?) -> IcalDateTime raise
            parse_single_date_time(String, ZoneTable, line_no?) -> IcalDateTime raise
            parse_utc_offset(String, line_no~, raw~) -> Int raise
            build_zone_table(Array[Component]) -> ZoneTable
            Component::{property, properties_named, events}
            IcalDateTime::{instant_seconds, is_utc, is_floating, compare}  // derive Eq（S1 起）
            ZoneTable::{empty, builtin_common, with_builtin, insert, lookup}
            parse_events(String) -> Array[Event] raise
            parse_date_time_value(String, ZoneTable, tzid?, value_is_date?, line_no?) raise
            struct Event { uid, summary, location, description : String?
                           dtstart, dtend, recurrence_id : IcalDateTime?
                           rrule : String?  exdates : Array[IcalDateTime] }
            Event::all_day(Self) -> Bool      // impl Show

04里程碑阶梯 S0–S9

哲学：每步一个最小目标 → 代码 + 测试 → 验收 → 一次提交。单步超过半天就拆。任何一步卡住，先砍范围再加班。

05每步工作流（Definition of Done）

每个里程碑严格走同一循环，禁止「先写一大坨再补测试」：

1. 写测试先行或同步：每块新行为至少一个 assert_eq / assert_true(pattern is …) 级别的断言测试；边界（空输入、畸形输入、行号）必须覆盖。
2. 实现：块式组织，///| 分隔，每块带一句话文档注释说明「为什么」。
3. 验证链：moon fmt && moon check && moon test && moon info，然后检查 .mbti diff——接口变化必须是预期内的，意外的 diff 说明改坏了边界。
4. 提交：一次提交一个里程碑，消息格式 S<n>: <一句话>，正文列改动点 + 验收证据（测试数、对拍结果）。命令必须是 git -c core.hooksPath=.githooks commit …——项目钩子会跑 moon check 并拒绝「改源码但不更新 PROGRESS.md」的提交。
5. 更新跟进文档：docs/PROGRESS.md（跨会话状态源：本地文件，不入库——§1 快照、§2 里程碑、§3 会话日志）与本手册 §02/§04/§07。钩子会校验它在上次提交后被更新过。

06MoonBit 工程约定与踩坑清单

新格式（rr_moon_mod + rr_moon_pkg）下的硬规则，违反即编译失败或静默 bug：

• 导入只写 moon.pkg：import { "moonbitlang/async/http" @http } 写在所在目录的 moon.pkg；.mbt 文件里写 import "..." 是硬错误（3001/3002）。测试专用导入用 import { … } for "test"。
• 可抛错误类型：pub(all) suberror Name { Ctor(field~ : Type) }；Error 是内建 opaque 类型不是 trait，impl Error for X 必失败。展示用 pub impl Show for Name with fn output(...)。
• 带标签字段两头都要带：构造 Ctor(a=1, b=2)，匹配 Ctor(a=x, b=y)；位置式会报 requires 0 positional arguments。
• 区间：a..<b（右开）/ a..=b（闭）；for 头写坏会在下游报假错误（unbound identifier / 类型不匹配）——先修 for 头。
• 不要 String::trim() 接 StringView::data()：data() 返回整个原串不是切片，trim 会静默消失。用 String::from_array(s.to_array()[i:j]) 或手写字符数组裁剪（ical/text/content_line.mbt 里的 trim_ascii 就是这么写的）。
• API 拿不准先查：moon ide doc "Type::method"（搜 core + 已注册依赖），不要凭记忆写 stdlib 名字。
• async 入口：async fn main 需要根包 moonbitlang/async 一并导入；可执行包声明 pkgtype(kind: "executable")。

07上游接缝登记（活文档）

原则：业务代码永不 import 兜底实现，只 import trait；每个临时实现标注 UPSTREAM-GAP；探针转绿 = 上游已补齐 = 立即执行切换配方。完整表格在 docs/upstream-seams.md，此处摘要：

S5/S6 用到的上游 API（已核实）

// 响应侧（直接用，无障碍）：
conn.send_response(200, "OK", extra_headers={ "Content-Type": "text/calendar" })
conn <+ body            // 字符串插值写入
conn.end_response()

// 请求侧（绕开 read_request 的方法枚举）：
ServerConnection 实现了 @io.Reader（server.mbt:65）
//   → 自己读字节流，解析请求行 "PROPFIND /cal/ HTTP/1.1"、头、Content-Length 体

// XML：Milky2018/xml 0.4.1（拉式解析）或 moonbit-community/XMLParser 0.2.5
// JSON：moonbitlang/core/json（REPORT/调试输出用）

08明确不做（边界）

• CalDAV 客户端——只做服务端；客户端行为由 Thunderbird/DAVx5 承担。
• 云平台同步适配——不接 Google Calendar OAuth、iCloud/Yahoo 账户或 Outlook/Microsoft Graph；均列为赛后方向。
• iTIP/iMIP 会议邀请、参会人状态、协作流程。
• ACL 权限体系——首版无认证（localhost 演示），TLS 留赛后。
• 完整 IANA tzdb——固定偏移 + VTIMEZONE，边界进 README（接缝 S2）。
• chunked 请求体——回 411 Length Required（客户端 PUT 几乎不用 chunked）。
• 超 大 .ics 流式解析、sync-token 全量同步（getctag 基础版即可）。
• RRULE 第三档（BYWEEKNO/BYYEARDAY/BYHOUR 系/SECONDLY/MINUTELY）——显式报错拒绝，不静默吞。

09风险与对策

10提交与验收映射

八月场验收硬标准 → 里程碑映射（九月场以官方章程为准）：