Atomic Calendar Revive 事件处理管道 pipeline 源码剖析：排序、过滤与去重是如何实现的

Atomic Calendar Revive 是一款为 Home Assistant Lovelace 打造的进阶日历卡片，支持 Google Calendar 与 CalDAV 日历。它最强大的地方在于"事件处理管道"（pipeline）：从拉取原始事件，到过滤、多日拆分、去重、排序、数量截断，全部在一条清晰的流水线上完成。本文将带你读懂这条管道的设计与实现原理，帮你理解maxDaysToShow、hideDuplicates、sortBy等配置项背后到底发生了什么。

一、管道全景：一次数据流的旅程 🗂️

管道的核心实现在 src/lib/pipeline.ts，对外暴露三个入口函数，分别服务于卡片的三种展示模式：

各视图的调用点分别在 src/lib/views/EventView.ts、src/lib/views/PlannerView.ts 与 src/lib/views/month-grid.ts。

处理主函数processEvents的完整流程只有一屏（src/lib/pipeline.ts#L197-L229），可以概括为五步：

1. 逐事件过滤：不通过则直接丢弃（continue）
2. 多日事件拆分：expandMultiDay把跨天事件切成"每天一份"
3. 二次过滤：hideFinishedEvents隐藏已结束事件
4. 去重：hideDuplicates合并同名同时间的重复事件
5. 排序 + 截断：sortEvents排序后用maxEventCount限制数量

二、第一步：按日历实体并行拉取原始事件

fetchRawEvents（src/lib/pipeline.ts#L259-L297）为每个配置的日历实体构造一个calendars/{entity}?start=...&end=...的 API 请求，并用Promise.all并行执行。两个细节值得注意：

• 每个实体可以有自己的时间窗口：实体级maxDaysToShow会收窄请求的end时间，避免为"只看今天"的日历拉取整周数据
• 失败隔离：某个日历请求失败只会被记入failed数组，不会让整张卡片挂掉，视图层会据此给出降级提示

三、核心：一条"过滤漏斗"决定哪些事件能上卡 🎯

拉到的原始事件会依次穿过 9 道过滤器（src/lib/pipeline.ts#L200-L215），任何一道不过即被丢弃：

几个容易踩坑的设计点：

• 黑白名单匹配的是"原始标题"rawTitle，而不是被titleReplace改写后的展示标题。这样即使你用titleReplace把Dinner = Sushi前缀抹掉了，allowlist: '^Dinner = '依然能命中——这个行为有专门的回归测试保护（src/tests/pipeline.test.ts#L60-L80）
• Calendar 模式跳过窗口过滤：passesAllDayBeforeWindow和passesMaxDaysWindow对月视图直接放行（src/lib/pipeline.ts#L47-L51），因为月网格需要展示当月所有格子
• maxDaysToShow的实体级覆盖：实体级maxDaysToShow优先于全局值，这正是"多卡片滑动布局"能各自看不同天的原理

四、多日事件拆分：showMultiDay 的幕后逻辑

开启showMultiDay后，跨天事件会在过滤器通过后被expandMultiDay展开（src/lib/pipeline.ts#L145-L153）：

• EventClass.split()（src/lib/event.class.ts#L273-L295）按天深拷贝事件，打上addDays、_isFirstDay、_isLastDay标记，让每一天都有一份"部分事件"
• 拆分后还要过一遍可见性窗口：computeVisibilityWindow按模式算出起止范围，只有落在窗口内的部分才会保留（Event/Planner 模式）；Calendar 模式则保留全部
• 实体级showMultiDay可以独立于全局开关生效，方便"每张卡片只看一天"的滑动布局

五、去重原理：hideDuplicates 如何合并重复事件

applyHideDuplicates（src/lib/pipeline.ts#L157-L180）采用经典的哈希键去重两遍扫描：

1. 以标题|开始时间|结束时间拼接为键。相同的事件（比如同一个事件同时同步到了两个日历实体）只会保留第一条，其余来源的日历名被追加进calendars列表
2. 第二遍把收集到的来源名用,拼接后写回事件的originName，卡片上这条事件仍会显示所有来源日历，信息不丢失

这正是官方文档描述的行为："based on summary, start time and end time"（见 docs/configuration/main.rst 第 35 行）。对应测试见 src/tests/pipeline.test.ts#L141-L162。

六、排序规则：按天分桶 + 两种排序策略

排序逻辑独立在 src/common/sort_events.ts 中，分四步：

1. 全局按startDateTime升序，保证"天"的天然顺序
2. 按YYYY-MM-DD分桶，逐天处理：
   • 整天事件按标题字母序排列；allDayBottom: true时反转并放到当天底部（src/common/sort_events.ts#L24-L29）
   • sortBy: start：普通事件按开始时间升序
   • sortBy: milestone（里程碑模式）：正在运行的事件排最前，其余按"距当前时间最近者"排序，已结束事件沉底（src/common/sort_events.ts#L37-L74）
3. 天内合并：整天事件与时刻事件按allDayBottom决定上下位置
4. 跨天合并：各天数组依序拼接，天内的自定义排序不被破坏

这个"先分桶、桶内精排、再按桶序合并"的结构，避免了全局比较器里处理跨天、跨类型事件时的复杂性。

七、数量截断：maxEventCount 与 softLimit 的软硬两级限制

最后的applyEventCountLimit（src/lib/pipeline.ts#L182-L193）实现了"硬限制 + 软缓冲"：

• 只设maxEventCount：超出部分直接截断，截掉的数量记入hidden，卡片上显示 "x hidden"
• 同时设softLimit：事件数不超过maxEventCount + softLimit时不截断——避免"只多出 1 条就截断"造成的观感跳动（说明见 docs/configuration/event.rst 第 13 行）
• 排序发生在截断之前，所以被保留的永远是时间上最靠前的事件

八、三种模式下的行为差异一览 📅

周窗口的对齐算法在getEventModeStart（src/lib/pipeline.ts#L35-L43）：用当前星期几减去firstDayOfWeek得到偏移量，负数时补 7，从而把窗口起点回退到本周第一天。

九、测试如何守护这条管道

管道是纯函数式的数据加工层，因此拥有非常完整的测试套件 src/tests/pipeline.test.ts（540+ 行）：用vi.useFakeTimers固定系统时间，逐一覆盖黑名单/白名单、hideDuplicates合并来源名、softLimit边界、单日窗口不泄漏次日整天事件、showPastDaysOfWeek的周日/周一周界回归等场景，是理解每个过滤器预期行为最快的"活文档"。

十、相关配置项速查

• 主配置：maxDaysToShow、maxEventCount、hideDuplicates、showDeclined、showAllDayEvents、hideFinishedEvents、sortBy、allDayBottom（docs/configuration/main.rst）
• 实体级过滤：blocklist、allowlist、startTimeFilter、endTimeFilter、showMultiDay（docs/configuration/entity.rst）
• 事件模式扩展：softLimit、showHiddenText、hiddenEventText（docs/configuration/event.rst）
• 默认值定义：src/defaults.ts

理解了这条管道，你就能解释卡片上大多数"为什么这条事件没显示 / 为什么排在这个位置"的问题——答案几乎都藏在processEvents那 30 行主干里。