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

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

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.3.0 开发分支严格全目标测试为 wasm 189、wasm-gc 174、JavaScript 189、native 197；S5 23 项与 S6 36 项真实 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–S10

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

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（闭）。旧写法 a..=b 语义等价，但新版 formatter 会归一成 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")。
• Int 与 Int32 是同一个类型：新版 formatter 把源码里的 Int 归一成 Int32；moonc v0.10.15 及以前 .mbti 会归一回 Int，v0.10.17 起直接渲染 Int32（全仓 6 个接口文件 24 行纯渲染 diff，已随 S10.5 入库）——语义完全不变。S10 后仓库源码统一为 Int32，新代码跟随现状即可。
• 源码里的可选参数是带标签参数：新版 formatter 把 name? : T = d 改写成 name~ : T = d。差别在调用方式——~ 形式只能按名字传（f(x, name=1)），不能再按位置传（实测 parse_date_time(line, zones, 7) 报「requires 2 positional arguments, but is given 3」）。仓库内所有调用点都用 name=value，故本次迁移零调用点改动。
• .mbti 分不清 ? 与 ~：两者在接口文件里都渲染成 name? : T。于是「.mbti 无 diff ⇒ 对外接口无变化」这条判据在新工具链下有盲区——S10 迁移 .mbti 零 diff，但按位置传可选参数的调用方会编译失败。判断接口兼容性时不能只看 .mbti。
• 默认关闭的新 lint：新版引入了一批默认 off 的检查（0073 unnecessary_annotation、0074 missing_doc、0038/0039 证明类等），--deny-warn 不会开启它们。用 moon check --warn-list "+74" 之类的开关按需排查（编号见 moon explain --diagnostic）。

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 基础版即可）。
• PROPFIND/REPORT 的 DAV:prop 选择——S10 让 calendar-query 求值了 filter，但请求的属性集合仍被忽略，响应固定返回 resourcetype / getcontenttype / getetag / calendar-data；按 prop 裁剪与「未知属性回 404 propstat」留后续。
• MKCALENDAR 请求体属性——S10 让 MKCALENDAR 真正建集合，但 body 里的 displayname / calendar-color 等属性不落盘；集合名即 displayname。
• /cal/ 兼作家目录与默认集合——S10 刻意的兼容取舍：首版已从 /cal/ 直接服务事件且既有客户端按该路径配置，故新建集合并排放在其下（/cal/<cal>/），而不是把事件搬进 /cal/default/。
• VALARM 的 time-range——回 403 supported-filter，不解析相对 trigger。
• RRULE 第三档（BYWEEKNO/BYYEARDAY/BYHOUR 系/SECONDLY/MINUTELY）——显式报错拒绝，不静默吞。

09风险与对策

10提交与验收映射

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

11验收有效性：为什么缺陷能过验收（S10 复盘）

背景：0.2.0 发布、进入验收后被指出两条缺陷——「calendar-query 忽略 filter，关键语义缺失」与「MKCALENDAR 不建集合」。两条都属实，却在此前所有闸门全绿的情况下漏过：全目标测试、S5/S6 活体验收、Thunderbird 真实联调、96% 覆盖率，没有一项报警。本节记录根因，并把它固化成规则，避免再犯。

根因

硬性规则（并入 §05 的 Definition of Done）

能力 → 证据矩阵（活文档，随能力声明同步）

规则 R4 的载体：凡在 Features / §02 出现的对外能力，都必须能在此表定位到判别性证据；定位不到的一律移入 §08「明确不做」。

当前已知的未验证 / 未支持面（诚实清单）

• <D:prop> 属性选择：已知被忽略（见 §08），无任何证据；PROPFIND / REPORT 都返回固定属性集。
• sync-collection / CTag：未支持，返回 400——有单测钉住「不支持」这一事实本身，但没有实现。
• MKCALENDAR 请求体属性（displayname、calendar-color）：不落盘（见 §08）。
• VALARM 的 time-range：显式 403 supported-filter（有单测）。
• 并发写入 / 冲突解决：无证据。
• TLS / 认证 / ACL：不做（见 §08）。
• DAVx5 / Apple 日历：未跑（README 互操作矩阵已标 Not run）。