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,32 @@
+# Proposal: alarm-clock-module
+
+## Intent
+Build an Android-first musical alarm system for PluriWave that can wake the user with radio/music while keeping reliable fallbacks and clear Android permission diagnostics.
+
+## Scope
+- Add a new alarm domain separate from the existing sleep timer.
+- Support one-shot and recurrent alarms by weekday.
+- Support snooze options: 3, 5, and 10 minutes.
+- Support a silent pre-alarm notification 30 minutes before the next occurrence, with an action to skip only that next execution.
+- Support vacation ranges and per-alarm `soundOnVacation` behavior. Default: true.
+- Support audio fallback chain: selected station, optional fallback station, bundled internal alarm sounds.
+- Add Android native scheduling using AlarmManager/setAlarmClock via MethodChannel.
+- Add Flutter UI for listing, editing, enabling/disabling, vacation ranges, and reliability diagnostics.
+
+## Out of Scope for MVP
+- Cloud sync.
+- iOS reliable alarm parity.
+- Complex alarm-dismiss challenges.
+- Multiple fallback station chains beyond one optional fallback station.
+- Full background radio streaming implementation independent from existing audio_service if not needed for MVP.
+
+## Rollback Plan
+- Alarm functionality is isolated behind new services/models/screens and Android receivers.
+- Existing radio playback, timer, favorites, EQ, and recording flows should remain untouched except for navigation entry points.
+- If native scheduling causes issues, remove Android manifest receiver/service entries and hide the alarms entry point.
+
+## Risks
+- Android exact alarms require special permissions on Android 12+ and can be denied by default on Android 14+.
+- OEM battery managers may still interfere; app must expose diagnostics and guidance.
+- DND bypass requires Notification Policy Access and cannot be silently forced.
+- Playing a radio stream at alarm time depends on network; bundled sounds must always be present.