timeTableFix/docs/organize-algorithm.md

间隔合并与链拆分算法

本文档记录 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 天）。交错的多个 序列则由链拆分处理。三者用同一算法兼得。