feat(alarm): add musical alarm foundation

2026-05-21 23:46:52 +02:00
parent 8c2cba093c
commit fb808ebb60
30 changed files with 1437 additions and 43 deletions
@@ -0,0 +1,62 @@
+# Spec: alarm-clock-module
+
+## Requirement: Alarm scheduling
+The app MUST support creating enabled/disabled alarms with a local time, one-shot or recurring schedule, and next occurrence calculation.
+
+### Scenario: one-shot alarm fires once
+Given an enabled one-shot alarm for a future date/time
+When its scheduled occurrence fires
+Then the app MUST start the alarm flow
+And the alarm MUST be disabled or marked completed after that occurrence unless snoozed.
+
+### Scenario: weekday recurring alarm
+Given an enabled recurring alarm with selected weekdays
+When the next matching weekday/time arrives
+Then the app MUST start the alarm flow
+And MUST schedule the following matching occurrence.
+
+## Requirement: Snooze
+The app MUST offer snooze durations of 3, 5, and 10 minutes when an alarm is ringing.
+
+### Scenario: snooze selected
+Given an alarm is ringing
+When the user selects snooze 5 minutes
+Then the app MUST stop current alarm playback
+And MUST schedule a one-off snooze occurrence 5 minutes later.
+
+## Requirement: Pre-alarm notification
+The app MUST schedule a silent notification 30 minutes before each next alarm occurrence when notification permission is available.
+
+### Scenario: skip next occurrence from notification
+Given a pre-alarm notification is visible
+When the user taps skip next occurrence
+Then the app MUST record a skip for that alarm occurrence
+And MUST not fire that specific occurrence
+And MUST preserve future recurring occurrences.
+
+## Requirement: Vacation ranges
+The app MUST support global vacation ranges with start/end dates and per-alarm `soundOnVacation` flag defaulting to true.
+
+### Scenario: alarm disabled for vacation date
+Given today is inside an enabled vacation range
+And an alarm has `soundOnVacation=false`
+When calculating next occurrence
+Then the app MUST skip occurrences inside that vacation range.
+
+## Requirement: Audio fallback
+The app MUST never depend solely on an internet radio stream to ring.
+
+### Scenario: selected station fails
+Given an alarm starts with a selected radio station
+When the stream fails or does not become ready before timeout
+Then the app MUST try a fallback station if configured
+And otherwise MUST play a bundled internal alarm sound.
+
+## Requirement: Android reliability
+The app MUST use native Android scheduling for alarm occurrences and expose permission/diagnostic status.
+
+### Scenario: exact alarm permission missing
+Given Android denies exact alarm scheduling
+When the user views alarm diagnostics
+Then the app MUST show that exact alarm permission is missing
+And MUST provide guidance to enable it.