# 间隔合并与链拆分算法

本文档记录 `src/lib/organize.js` 的算法设计、关键决策与踩过的坑。
测试用例见 `test/organize.test.js`（含黄金用例 `golden-org.ics`）。

## 目标

把导出为 N 个扁平单次事件的重复日程，合并为带 `RRULE` + `EXDATE` 的
重复事件。需要覆盖：每周、每两周、每 N 天，以及「稀疏但有规律」（如
约每 3 周一次的 workshop）和「交错的多班次」（同名同时但分属周一/周二）。

## 算法分层

### 1. 分组（`seriesKey`）

键 = `[summary, location, dtstartTime, durationMin].join('|')`。

**关键决策：键不含星期。** 早期版本键含 `weekday = getDay()`，导致周期
为非 7 倍数（如每 3 天）的 DAILY 序列落在不同星期，被拆成单事件组，
永远到不了 `fitSeries`——这是「间隔 3 天无法合并」的根因。移除后，
WEEKLY 序列（间隔 7 倍数，weekday 本就相同）仍归一组；DAILY 序列也
能归一组，交给 `fitSeries` 判断。星期改由 `fitSeries` 内的 `byday`
从首日期推导（仅 WEEKLY 有意义，DAILY 设 `null`）。

时长（分钟）保留在键中，不同时长不算同系列。

### 2. 单一网格拟合（`fitSeries`）

对组内事件：

1. 求所有相邻 gap（天数）的 GCD，作为「最小公约间隔」`d`——使每个 gap
   均为其整数倍的最小正整数。例如 gap `[7,7,14,7] -> d=7`（中间跳过
   一周，14=2×7）；`[3,3,3] -> d=3`；`[21,28] -> d=7`。
2. 从首日期到末日期按 `d` 步进构建期望网格。
3. `missing` = 网格上但 absent 的日期；`offGrid` = present 但不在网格
   上的日期。
4. `offGrid` 非空 -> 该组不是单一周期序列，返回 `null`（交由链拆分）。
5. 否则合并：`d` 是 7 的倍数 -> `WEEKLY`（`byday` 从首日期推导），
   否则 -> `DAILY`（`byday=null`）；`exdates = missing`。

**阈值放宽**：合并条件仅为 `evs.length >= 2` 且 `offGrid` 为空。不再
因「太稀疏」（`missing >= present`）而拒绝——稀疏但有规律的序列（如
BUS LAW Workshop，3 个事件跨 49 天，gap 21/28，d=7）同样合并为
`WEEKLY` + 5 个 EXDATE。

### 3. 链拆分（`splitIntoChains`）

仅在 `fitSeries` 返回 `null` 时调用，即该组无法落在单一 GCD 网格上。
典型场景：同名同时但分属周一/周二的两个班，排序后 gap 交替为
`1,6,1,6,1,6`，GCD=1。

**触发条件：组级 GCD=1**（相邻 gap 含互质值，即交错）。`fitSeries` 在
`interval === 1` 时直接返回 `null`，交由拆分处理。为何 GCD=1 要拆：
`d=1` 的网格逐日命中所有日期，恒产生单链，把所有不在同子序列的日期
当 EXDATE，是伪合并（如把周一+周二两班误合成一个 `DAILY;INTERVAL=1`）。

**候选间隔 d**：相邻 gap 的**两两之和**（去重，降序）。仅用两两之和而
非单个 gap，因为交错子序列的「偏移」（如 1 或 2）比真实周期短，拿单个
gap 当周期会得到过密的伪网格。此函数仅在 GCD=1（交错）时调用，故两两
之和总是能给出真实周期：
- gap `1,6` -> 和 `7`（每周）
- gap `2,5` -> 和 `7`（每周）

**网格抽取**：对每个候选 `d`，从最早未分配日期起按 `d` 步进到最末日期，
收集命中的 present 日期（**允许跳过周期**——缺席的网格点日后记为
EXDATE），形成一条链；剩余未分配日期重复抽取，得若干链。

**择优**：选产生**链数最少**的 `d`（最大化分组）；所有链长度须 ≥2，
否则该 `d` 不合格（单点链说明 `d` 不适配）。链数相同取较小 `d`。

**兜底**：无候选 `d` 能给出全 ≥2 链时，退化为每日期一链（全部保留为
独立事件）。例如仅 2 个相邻同名事件（gap 1，无两两之和候选）。

### 4. `organize` 总流程

1. 按 `seriesKey` 分组。
2. 每组调 `organizeGroup`：先 `fitSeries`；成功则输出 1 个合并事件；
   失败则 `splitIntoChains` 后对每条链独立 `fitSeries`，链长 <2 或无
   规律的保留为独立事件。
3. 合并后事件保留 base 的原始 UID（不重新分配），避免重新导入冲突、
   保证幂等。

## 行为对照表

| 序列 | 相邻 gap | 结果 |
|------|----------|------|
| ACC INFO SYS（golden） | 7×7,14,7×3 | WEEKLY;1 + 1 exdate（跳过 9-21） |
| 每 3 天 | 3,3,3,3 | DAILY;3 |
| 每两周 | 14,14,14 | WEEKLY;2 |
| BUS LAW Workshop（golden） | 21,28 | WEEKLY;1 + 5 exdates |
| 周一+周二两班（同名同时） | 1,6,1,6,1,6 | 拆成 2 个 WEEKLY;1（MO / TU） |
| 两班各暂停一周（gap 2,5,2,5,2,12,2,5,2,5） | 交错 | 拆成 2 个 WEEKLY;1，各带 1 exdate |
| 2 个相邻同名事件 | 1 | 保留 2 个独立事件（无候选） |

## 踩过的坑

### 坑 1：weekday 分组拆碎 DAILY 序列
最初 `seriesKey` 含 `weekday`，每 3 天的事件落在 5 个不同星期，被拆成
5 个单事件组，`fitSeries` 永远收不到 ≥2 事件。直接调 `fitSeries` 能
合并，但 `organize` 的分组步骤先把它拆碎了。**根因在分组键，不在
`fitSeries`。** 修复：键移除 weekday。

### 坑 2：GCD=1 的平凡网格伪合并
移除 weekday 后，周一+周二两班（gap 1,6,1,6）GCD=1，`d=1` 网格逐日
命中所有日期，offGrid 恒为空，被误合并成一个 `DAILY;INTERVAL=1` +
大量 EXDATE。**这是「present>0 即合并」与「拆分交错序列」的直接冲突。**
修复：`fitSeries` 在 `interval===1` 时拒绝（交由链拆分）。

### 坑 3：候选 d 选错导致伪链
链拆分最初用「所有日期两两之差」作候选，并按链数最少择优。结果对
gap `2,5,2,5,...` 的用例，`d=2` 与 `d=7` 都产生 2 条链，平局取较小 `d`
选了 `d=2`，得到错误的 `DAILY;INTERVAL=2` + 大量 EXDATE 分组。`d=2`
是交错偏移而非周期。**修复：候选改为相邻 gap 两两之和**（偏移相加得
真实周期），排除单个 gap。

### 坑 4：BUS LAW Workshop 从「3 flat」变「1 recurring」
原阈值 `missing >= present` 拒绝了 BUS LAW Workshop（5 missing ≥
3 present），保留为 3 个独立事件。放宽阈值后合并为 1 个 WEEKLY + 5
exdates。这是预期行为变化，golden 测试相应更新（61 事件 -> 6 系列，
原为 8 = 5 系列 + 3 flat）。

## 决策记录：为何选「最小公约间隔 + EXDATE」而非「严格相等 gap」

严格相等 gap（所有相邻 gap 必须完全一致才合并）会拒绝 ACC INFO SYS
（gap 含一个 14，其余 7），破坏现有 golden 合并。最小公约间隔 + EXDATE
允许「跳过周期」（gap 是 `d` 的倍数），既保留 ACC INFO SYS 的合并，又
支持稀疏序列（BUS LAW Workshop）与 DAILY 序列（每 3 天）。交错的多个
序列则由链拆分处理。三者用同一算法兼得。