docs(openspec): add SDD artifact trail for recent alarm and EQ changes

Persist the exploration, proposal, spec, design, tasks, and verify/archive reports produced during the multi-device EQ, alarm-countdown, and notification-visual-polish SDD cycles.
2026-07-04 12:42:11 +02:00
parent e5b6d8acb3
commit bccc5c48b8
64 changed files with 6020 additions and 0 deletions
@@ -0,0 +1,73 @@
+# Proposal: EQ Device Auto-Switch UX
+
+## Intent
+
+Device-specific EQ presets never apply at app startup because `cargarPersistido()` does not query the current audio device, leaving `_dispositivoActualId` null. Users must physically reconnect a device to trigger preset resolution. Additionally, the settings device list lacks connection indicators, rename capability, and inline EQ editing — making multi-device EQ management opaque and tedious.
+
+## Scope
+
+### In Scope
+- Fix startup device query in `cargarPersistido()` to seed `_dispositivoActualId`
+- Add `nombresDispositivos` persistence (`eq_nombres_dispositivos_v1` SharedPreferences key)
+- Expose rename API in `EstadoEcualizador` (set/get custom device name)
+- Connection status indicator (green dot) per device row in settings
+- Device display name fallback chain: customName > platformName > deviceId
+- Bottom sheet modal for device rename + embedded `EcualizadorWidget`
+- Tests for all new/changed behavior
+
+### Out of Scope
+- Export schema v4 extension for device names (deferred)
+- Changing Kotlin/platform-side audio device callback logic
+- Modifying `EcualizadorWidget` internals
+- Offline/background device switching behavior
+
+## Capabilities
+
+### New Capabilities
+- `eq-device-rename`: Persist and manage custom device display names via SharedPreferences
+
+### Modified Capabilities
+- None (no existing specs)
+
+## Approach
+
+**Bug fix**: Call `obtenerDispositivoActual()` inside `cargarPersistido()` after `_configurarSuscripcionDispositivo()` when multi-device is enabled. Seed `_dispositivoActualId`, bootstrap preset if first-seen, re-resolve active preset.
+
+**Rename persistence**: New `Map<String, String>` stored as JSON under `eq_nombres_dispositivos_v1` in `ServicioEcualizador`. `EstadoEcualizador` exposes `renombrarDispositivo(id, nombre)` and `obtenerNombreDispositivo(id)`.
+
+**Settings UI**: Rewrite `_SeccionEcualizadorAvanzado` device rows with connection dot + display name fallback. Tap opens `showModalBottomSheet` (existing pattern: `showDragHandle: true`, `isScrollControlled: true`) containing rename TextField + embedded `EcualizadorWidget`.
+
+## Affected Areas
+
+| Area | Impact | Description |
+|------|--------|-------------|
+| `lib/estado/estado_ecualizador.dart` | Modified | Fix init + rename API + expose nombresDispositivos |
+| `lib/servicios/servicio_ecualizador.dart` | Modified | New SP key for device names |
+| `lib/pantallas/pantalla_ajustes.dart` | Modified | Rewrite device section + new modal widget |
+| `test/` | New | Tests for bug fix, rename logic, display name fallback |
+
+## Risks
+
+| Risk | Likelihood | Mitigation |
+|------|------------|------------|
+| `obtenerDispositivoActual()` fails on edge devices | Low | Existing `builtin_speaker` fallback handles it |
+| Bottom sheet clips EQ widget | Low | Use `isScrollControlled: true` (established pattern) |
+| nombresDispositivos not in export schema | Med | Defer to v4; document omission |
+| Platform `nombre` is null/empty | Med | Fallback chain: customName > platformName > deviceId |
+
+## Rollback Plan
+
+All changes are additive. Revert the commit(s). The new SP key (`eq_nombres_dispositivos_v1`) is ignored if code referencing it is removed. The startup device query is a single method call addition — removing it restores previous (broken) behavior without data loss.
+
+## Dependencies
+
+- None. All required APIs (`obtenerDispositivoActual`, `EcualizadorWidget`, `showModalBottomSheet` pattern) already exist.
+
+## Success Criteria
+
+- [ ] On app startup with multi-device enabled, the correct device preset is applied without user interaction
+- [ ] Device list in settings shows connection status indicator for active device
+- [ ] Users can rename devices; names persist across app restarts
+- [ ] Tapping a device opens bottom sheet with rename + EQ editing
+- [ ] Display name shows customName > platformName > deviceId fallback
+- [ ] All new behavior has passing tests (Strict TDD)