v2.2.0

小时/分钟重复

• 重复单位新增 RepeatUnit.HOUR / RepeatUnit.MINUTE（常量追加，既有值不变，持久化的 repeatUnit Int 兼容）
• 语义为真实时长格点（ISO 8601 time-based 惯例）：出现 = 锚点 + 步数×间隔，跨日连续、每 8 小时就是 8 个真实小时；跨夏令时间隔不变、本地钟面漂移 1 小时（与天及以上单位的钟面格点语义分界，文档已写明）
• nextTarget（含 until 封顶与锚点豁免）/ previousTarget（含等于）/ anchor 全部支持，均为 O(1) epoch 秒算术；lunar 与小时/分钟无关
• 小时/分钟推算不经「日期 + 时刻 + 时区」组合，不受 0001..9999 日期界守护约束（Instant 值域内任意推进，不抛越界异常），KDoc 已写明

修复

• 天/周快路径的步数估计曾用 Duration 纳秒差：锚点距 now 超约 292 年即 Long 饱和，「0001 年锚点 + 每日重复」会误抛 IllegalStateException；改用 epoch 秒差后远古锚点正常落位（nextTarget 与 previousTarget 两处）

测试

• 138 → 150 用例（× JVM / Android / wasm 三平台，iOS 由 macOS CI 执行）：小时/分钟推进与含等于、跨日连续、锚点豁免与封顶、跨春令时本地钟面漂移（实测 +18 真实小时 = 04:00，钟面 +18h 为 03:00）、previousTarget 三态、两千年分钟格点无溢出、0001 年天/1500 年周远古锚点回归、常量校验与 lunar 无关性、正反对偶不变量
• 探针记录：上海远古年份 LMT 偏移 +08:05:43（秒级分量），长跨度格点对齐断言以 anchor(zone) 为参照；天/周钟面格点跨 1901 年 LMT→CST 换偏移后 epoch 对齐不保持（按本地日期断言）

Full Changelog: v2.1.0...v2.2.0

v2.1.0

反向推算与锚点

• 新增 Schedule.previousTarget(before, zone)：不晚于 before 的最近一次出现（含恰等于）；与 nextTarget 遍历同一条出现序列、复用同一套快路径，消费方无需再以「区间二分 nextTarget」硬凑完结事件锚点；before 早于锚点返回 null（可回退 anchor(zone)）；推算至 9999 上界返回界内最后一次出现（不抛异常，与正向越界语义不同）
• 新增 Schedule.anchor(zone)：出现序列的第一次出现；夏令时缺口日按缺口顺延（02:30 → 03:30），恒等于 nextTarget(锚点前一瞬)

正向推算带上限

• nextTarget(now, zone, until)：重复出现晚于 until 时返回 null（序列单调，后续必然超限）；锚点与非重复日程不受约束——重复结束不能追溯取消锚点，takeIf { it <= end } 式封顶会误杀锚点，语义由库钉死

倒计时

• countdown(target, now, rounding) 新增进一模式 Rounding.CEIL_FUTURE：未到方向向上取整（差一秒满整单位也进位：86399 秒 + 1 纳秒 = 1 天；24 时 → 1 天、60 分 → 1 时边界进位），已过方向恒截断；默认 TRUNCATE 保持历史行为
• 新增 calendarCountdown(target, now, zone) → CalendarCountdown：年/月/日/时/分/秒钟面分量，闰年与月长由日历处理，月末钳制与 java.time Period 一致——跨平台替代 JVM 专属 API；跨夏令时一天计 1 天 0 小时（与 countdown() 真实时长语义对照）

测试与文档

• 测试 101 → 138（× JVM / Android / wasm 三平台，iOS 由 macOS CI 执行）：封顶三态与误杀反例、反向边界（含等于/锚点前一瞬/DST 重叠日/收缩回弹/越界收尾/闰六月格点年）、六日程正反对偶不变量、进一三层取整、日历分量对拍；农历年表与 periodUntil 语义先探针实测再落断言
• README 重构：按新手使用路径重排、精简章节，版本历史收敛为版本索引
• 全部为增量 API，无破坏性变更（nextTarget/countdown 仅追加默认参数）

Full Changelog: v2.0.1...v2.1.0

v2.0.1

文档修正

• JitPack 坐标按平台拆分（2.0.0 转 KMP 库后坐标变化，非仅版本号）：JitPack 把六模块改发到组 com.github.kamiiroawase.nexttime，且不托管根模块的 .module、把根 POM 改写为连带声明全部平台变体（含 native klib），Android 工程直接依赖根坐标 com.github.kamiiroawase:nexttime 解析报 No matching variant
• README「引入」改为五平台变体坐标表（Android / JVM / iOS 真机 / iOS 模拟器 / wasmJs，均经 JitPack 产物探针实测）；KMP 工程按目标源集各引变体，commonMain 共享消费给出 Release 附件自建镜像与接口抽象两条路径；「已知限制」同步补记

修复

• 消除废弃 API 警告：LocalDate.dayOfMonth → day（kotlinx-datetime 0.8.0 更名，行为不变）

测试

• 测试类补充 IDE 检查抑制（@Suppress），用例数不变：101 × JVM / Android / wasm(Node)，iOS 模拟器由 macOS CI 执行

Full Changelog: v2.0.0...v2.0.1

v2.0.0

平台与依赖

• 迁移到 Kotlin Multiplatform：Android（minSdk 24）/ JVM（11+）/ iOS（arm64 真机与模拟器）/ wasmJs 五目标，commonMain 单一代码；Android 不再要求 minSdk 26 与 desugaring
• 农历历法由 lunar-java 换为同作者 KMP 库 tyme4kt（com.tyme.* API，MIT；全部农历断言实测与 lunar-java 一致，含农历 0 年下界与 2025 闰六月场景）；java.time 换为 kotlinx-datetime 0.8.0 + kotlin.time.Instant/Duration/Clock
• wasmJs 内嵌 @js-joda/timezone：IANA 时区库随 klib 传递给消费方，零配置

API（破坏性）

• nextTarget(now: Instant = Clock.System.now(), zone: TimeZone = TimeZone.currentSystemDefault()): Instant?、countdown(target: Instant, now: Instant)；1.x 的 ZonedDateTime 调用方以 instant.toLocalDateTime(zone) 迁移
• 推算结果统一以 0001-01-01..9999-12-31 为界：公历月/年重复越过 9999 现与农历一致抛 IllegalStateException（1.2.x 曾可组合出 10359 年的结果）

测试与 CI

• 101 个用例迁移到 commonTest（kotlin.test），在 JVM / Android / wasm(Node) 三平台运行，iOS 模拟器由 macOS CI 执行
• AGP 9 的 KMP 库插件（com.android.kotlin.multiplatform.library）+ Gradle 9.7 + spotless 8；CI 新增 macOS iOS 模拟器测试 job，以及 tag 触发的 Release 附件自动发布（本页产物即由其上传）

Maven 坐标：com.github.kamiiroawase:nexttime:2.0.0（JitPack）

Full Changelog: v1.2.2...v2.0.0

v1.2.2

测试

• 77 → 101：倒计时补齐精确量级边界（恰满一天/一小时/一分、亚秒进位翻量级、已过多日）与分处不同时区的同瞬间零秒
• 公历补测：天/周重复跨秋令时回拨与春令时缺口直算、Apia 与 Kwajalein 跳日整天缺口、南半球夏令时缺口与重叠、半时区（如 +05:30）与午夜跳变时区组合、时分秒上界组合
• 农历补测：年重复三十锚点在无三十小年收缩、闰月三十锚点闰月年收缩、月重复多间隔跨年、闰月日日程闰月参与沿月序推进、闰月日年重复间隔二格点年退化、锚点恰在上界（月/年重复）立即抛 IllegalStateException、非重复农历日程返回公历锚点日

纯测试增补，无 API 变更。Maven 坐标：com.github.kamiiroawase:nexttime:1.2.2（JitPack）

Full Changelog: v1.2.1...v1.2.2

v1.2.1

测试

• 56 → 77，补齐此前无测试钉住的承诺行为与组合缺口：countdown 同一瞬间输出 0 秒、配了间隔但单位未选视为不重复、重复日程锚点在未来原样返回、targetDay 只取日期部分（非零点毫秒）与范围上界日末毫秒、README 快速上手示例端到端
• 组合缺口：夏令时重叠 × 重复、农历候选日 × 缺口与重叠、周重复跨秋令时回拨与 Apia 跳日整天缺口的直算对齐、倒计时跨夏令时与跨时区按真实时刻差细分、月/年重复多间隔收缩回弹、闰月计入步数与闰月年恢复取闰月、农历年重复越界守护；不变量矩阵扩至纽约时区与新日程形态

文档修正

• 快速上手示例倒计时注释 39 → 38（实隔 38 天 22 小时，取天向下取整）
• nextTarget 行为表「targetDay <= 0 返回 null」为 1.2.0 前残留，改为「targetDay == -1」
• 补记倒计时跨夏令时按真实时刻差细分、公历推算无 9999 结果上限

纯测试与文档修订，无 API 变更。Maven 坐标：com.github.kamiiroawase:nexttime:1.2.1（JitPack）

Full Changelog: v1.2.0...v1.2.1

v1.2.0

新特性

• targetDay 支持 1970 年前日期：范围放宽为 0001-01-01 至 9999-12-31（UTC 日期），0 与负毫秒（1970-01-01 当天及更早）合法，-1 仍为「未选」哨兵；1970 年前出生的生日可直接录入，MaterialDatePicker 的负毫秒返回值直接可用

变更

• 日期范围校验前移到构造期并对全部日程生效（此前仅农历月/年重复在 nextTarget 抛锚点异常）
• 农历年表下界经实测标定（往返一致、月表结构、史实锚点三重验证），推算守护双侧化（农历 0..9999 年）
• 文档注明 1645 年前历史日期按现代天文规则回推；修正快速上手示例的时变输出注释与措辞歧义

测试

• 52 → 56（纪元日零毫秒锚点、负毫秒公历/农历生日、公元 1 年范围下界、越界构造拒绝）

Full Changelog: v1.1.0...v1.2.0

v1.1.0

修复

• 修复农历月重复跨无闰月农历年腊月边界的死循环：月表末尾的次年正月须连年份一并采用，MAX_LUNAR_YEAR 守护恢复有效
• 农历推算加固：锚点年超出 9999 在历法换算前即抛 IllegalArgumentException；逐月推进越过 9999 立即抛 IllegalStateException，不消费 lunar-java 越界年表的错误数据
• repeatInterval 增加上界 100000（Schedule.MAX_REPEAT_INTERVAL），任意单位组合日期均不超出 java.time 范围，不再裸抛 JDK DateTimeException

性能

• 公历天/周重复按周期秒直算远期出现（1970→2026 每日重复单次调用 1.63ms → 0.01ms）
• 农历长跨度跳过远期年份的历法换算、年表按年缓存（农历月重复 95.77ms → 16.10ms）

其他

• 异常文案统一英文；README 新增「已知限制与常见坑」章节
• CI 改完整克隆并断言发布版本非 0.0.0-SNAPSHOT，tag 推导失效立即红
• 测试 42 → 52

Full Changelog: v1.0.0...v1.1.0

v1.0.0

首个发布。

• 公历 / 农历（闰月语义）目标时刻推算，天/周/月/年重复；月/年重复的月末收缩以锚点日为基准、后续回弹，公历与农历一致
• countdown() 倒计时状态细分：秒级向上取整、进位不闪跳，目标与当前恰为同一瞬间时输出 0 秒
• 夏令时缺口时刻自动顺延（只影响当日）；重叠时刻取较早一次
• Schedule 构造期全字段校验，非法取值抛 IllegalArgumentException
• 农历推算以公历 9999 年为上限，极端规则无法命中时抛 IllegalStateException
• 公共 API 显式声明（explicitApi），KDoc 补全
• 42 个 JUnit 5 用例，覆盖公历/农历推算、闰月、月末收缩、DST、入参校验、结果不变量与倒计时状态细分