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,37 @@
+# Design: alarm-clock-module
+
+## Architecture
+- Flutter owns alarm domain data, UX, recurrence calculation, and persistence.
+- Android owns exact wakeup delivery through AlarmManager/setAlarmClock and notification actions.
+- Communication uses a MethodChannel, tentatively `pluriwave/alarm_scheduler`.
+- Existing `ServicioTimer` remains unchanged; a new `ServicioAlarmas` manages alarms.
+
+## Data model
+- `AlarmaMusical`: id, name, enabled, hour, minute, scheduleType, weekdays, stationUuid/url snapshot, fallbackStation snapshot, bundledSoundId, volume, snoozeMinutes, soundOnVacation, nextOccurrenceAt.
+- `RangoVacaciones`: id, name, startDate, endDate, enabled.
+- `ExcepcionAlarma`: alarmId, occurrenceAt, type (`skipNext`, `snooze`, `vacation`).
+- `EjecucionAlarma`: scheduledAt, firedAt, status, fallbackUsed, failureReason.
+
+## Persistence
+Use JSON files or SharedPreferences for MVP to avoid risky DB migrations. If alarm history grows, migrate to sqflite later.
+
+## Android native components
+- `PluriWaveAlarmReceiver`: receives exact alarm and pre-alarm actions.
+- `PluriWaveAlarmScheduler`: schedules/cancels next alarm and pre-notification.
+- `PluriWaveAlarmActivity` or full-screen notification target for the ringing UI.
+- Notification channels:
+  - `alarm_pre_notice`: silent, low/default importance, no sound.
+  - `alarm_ringing`: high importance for active alarms.
+
+## Audio strategy
+MVP: when the alarm fires, bring the Flutter app/alarm screen forward and use existing audio_service to play station/fallback. If Flutter/audio startup fails, Android should be able to play a bundled raw sound as last fallback.
+
+## Reliability diagnostics
+Expose statuses for:
+- exact alarm permission (`canScheduleExactAlarms`).
+- notification permission.
+- battery optimization warning.
+- DND policy access for optional override.
+
+## Key decision
+Use `setAlarmClock` for actual alarm occurrences because Android treats these as critical and visible user alarms. Use a separate exact/inexact notification alarm for the 30-minute silent pre-notice depending on permission and platform behavior.