feat: Implement startup retry mechanism for custom stations and equalizer persistence
- Added state management for startup retry and custom station handling in `EstadoRadio`. - Created tasks for implementing strict TDD with RED tests for HTTP failure retries and EQ persistence. - Developed verification report to ensure compliance with TDD practices. - Introduced fake services for testing, including `FakeServicioAudio`, `FakeServicioFavoritos`, and `FakeServicioRadio`. - Implemented widget tests for `PantallaInicio` and `PantallaFavoritos` to validate UI behavior with custom stations. - Enhanced `ServicioRadio` to support host rotation and retry logic for API calls. - Established a new configuration file to enforce project constraints and testing rules.
This commit is contained in:
Javier Bautista Fernández
@@ -0,0 +1,49 @@
|
||||
# Apply Progress - startup-retry-custom-stations-eq-persistence
|
||||
|
||||
## Status
|
||||
|
||||
- Phase: `apply-partial`
|
||||
- Date: 2026-04-27
|
||||
- Strict TDD mode: active
|
||||
- Runtime verification: blocked (`flutter` CLI is not available in PATH)
|
||||
|
||||
## Fixes implemented for verify findings
|
||||
|
||||
1. **CRITICAL: `mediaItem.add(null)` shadowing bug**
|
||||
- Fixed in `lib/servicios/servicio_audio.dart` inside `playMediaItem(...)`.
|
||||
- Replaced ambiguous `mediaItem.add(null)` with `this.mediaItem.add(null)` in the exception path.
|
||||
|
||||
2. **WARNING: async EQ graph updates fired in loop**
|
||||
- Fixed in `lib/pantallas/pantalla_ajustes.dart`.
|
||||
- `EcualizadorWidget.onCambio` now calls one atomic state update (`estado.cambiarPresetEcualizador(p)`) instead of launching async updates per band in a loop.
|
||||
|
||||
3. **CRITICAL: missing scenario tests**
|
||||
- Expanded `test/estado/estado_radio_test.dart`:
|
||||
- EQ state persists when native EQ is unavailable.
|
||||
- Startup failure leaves visible error and manual reload recovers.
|
||||
- Favorite without own EQ falls back to main EQ from first playback.
|
||||
- Expanded `test/pantallas/pantalla_inicio_test.dart`:
|
||||
- Custom station tap starts playback through `EstadoRadio.reproducir`.
|
||||
- Manual retry button after startup failure triggers a new station load cycle.
|
||||
- Favorites screen shows a custom station after favoriting + reload.
|
||||
- Expanded `test/helpers/fakes.dart` with call counters and per-call failure/data sequencing for deterministic startup/retry tests.
|
||||
|
||||
## TDD Cycle Evidence
|
||||
|
||||
| Cycle | RED-first test intent | GREEN code change | Verification command | RED evidence | GREEN evidence | Result |
|
||||
|---|---|---|---|---|---|---|
|
||||
| 1 | Add missing tests for EQ unavailable, manual retry, custom playback tap, and favorites reload flows | Fix `servicio_audio.dart`, `pantalla_ajustes.dart`, and test fakes | `Get-Command flutter -ErrorAction SilentlyContinue` | `flutter` not found in PATH | Blocked (cannot execute tests) | BLOCKED |
|
||||
| 2 | Keep new/updated tests in place and execute strict runner only | No further production changes after test additions | `flutter test` | Command attempted | `flutter` command not recognized | BLOCKED |
|
||||
|
||||
## Validation commands run
|
||||
|
||||
| Command | Result |
|
||||
|---|---|
|
||||
| `Get-Command flutter -ErrorAction SilentlyContinue` | `FLUTTER_NOT_FOUND` |
|
||||
| `flutter test` | `CommandNotFoundException` (Flutter missing from PATH) |
|
||||
| `flutter build` | Not run (prohibited) |
|
||||
|
||||
## Remaining before verify can pass
|
||||
|
||||
1. Install/expose Flutter in PATH for this environment.
|
||||
2. Run `flutter test` and capture passing evidence for every scenario in `spec.md` (tasks 5.3 and 5.4).
|
||||
@@ -0,0 +1,86 @@
|
||||
# Design: Startup retry, custom stations, and equalizer persistence
|
||||
|
||||
## Technical Approach
|
||||
|
||||
Keep the existing Provider/ChangeNotifier architecture. Add test seams first, then implement: radio retry in `ServicioRadio`, main-list composition in `EstadoRadio`, and EQ persistence in a dedicated `ServicioEcualizador` using SharedPreferences. Persisted Provider EQ state must not depend on Android equalizer availability.
|
||||
|
||||
## Architecture Decisions
|
||||
|
||||
| Decision | Choice | Alternatives | Rationale |
|
||||
|---|---|---|---|
|
||||
| API retry owner | `ServicioRadio._get()` owns bounded retry and host rotation | Retry only in `EstadoRadio` | Centralizes network resilience for startup and search; avoids duplicated policy. |
|
||||
| Custom stations home UX | Add `EstadoRadio.emisorasInicio`/similar combining custom + popular when no genre filter | Separate home section | Minimal UI change and reuses `TarjetaEmisora` favorite behavior; separate section can come later. |
|
||||
| EQ storage | New `ServicioEcualizador` with SharedPreferences JSON | SQLite migration in favorites DB | Main EQ is app-level, not favorite-row data; SharedPreferences is already available and simpler. |
|
||||
| Station EQ fallback | `Map<uuid, PresetEcualizador>`; absent key means "use main" | Store explicit mode enum per station | Absence is compact and maps naturally to disabling own EQ. |
|
||||
| Current station source | Fix `ServicioAudio`/handler to assign/clear `emisoraActual` | Track only in `EstadoRadio` | Existing mini player and player screen already read `audio.emisoraActual`; fix the actual source. |
|
||||
|
||||
## Data Flow
|
||||
|
||||
Startup:
|
||||
|
||||
PluriWaveApp -> EstadoRadio._init()
|
||||
-> ServicioEcualizador.cargar() -> preset principal + mapa por emisora
|
||||
-> ServicioRadio.obtenerPopulares/Tendencias() -> retry/rotate host
|
||||
-> ServicioFavoritos + emisoras_custom.json
|
||||
|
||||
Playback:
|
||||
|
||||
UI -> EstadoRadio.reproducir(emisora)
|
||||
-> ServicioAudio.reproducir(emisora) sets current station
|
||||
-> EstadoRadio selects EQ: presetsPorEmisora[uuid] ?? presetPrincipal
|
||||
-> ServicioAudio.aplicarPreset(selected)
|
||||
|
||||
EQ update:
|
||||
|
||||
Settings/player EQ controls -> EstadoRadio
|
||||
-> update main EQ OR station EQ
|
||||
-> ServicioEcualizador.guardar(...)
|
||||
-> ServicioAudio applies if available
|
||||
|
||||
## File Changes
|
||||
|
||||
| File | Action | Description |
|
||||
|---|---|---|
|
||||
| `lib/servicios/servicio_ecualizador.dart` | Create | Load/save main EQ and station EQ map from SharedPreferences. |
|
||||
| `lib/servicios/servicio_radio.dart` | Modify | Add injectable client/config, retry count, backoff, and host rotation. |
|
||||
| `lib/estado/estado_radio.dart` | Modify | Inject services, load EQ during init, expose combined main listing, apply fallback EQ policy. |
|
||||
| `lib/servicios/servicio_audio.dart` | Modify | Assign/clear `emisoraActual`; keep default behavior backward-compatible. |
|
||||
| `lib/pantallas/pantalla_inicio.dart` | Modify | Use combined main listing when no genre filter. |
|
||||
| `lib/pantallas/pantalla_ajustes.dart` | Modify | Distinguish main EQ from favorite-station own EQ controls. |
|
||||
| `lib/modelos/preset_ecualizador.dart` | Modify | Add equality/copy helpers if tests need deterministic comparisons. |
|
||||
| `test/servicios/servicio_radio_test.dart` | Create | Retry/host rotation tests. |
|
||||
| `test/estado/estado_radio_test.dart` | Create | EQ persistence, custom listing, and station EQ policy tests. |
|
||||
| `test/pantallas/pantalla_inicio_test.dart` | Create | Widget coverage for custom station rendering/favorite action. |
|
||||
|
||||
## Interfaces / Contracts
|
||||
|
||||
Suggested public surface:
|
||||
|
||||
```dart
|
||||
class ServicioEcualizador {
|
||||
Future<ConfiguracionEcualizador> cargar();
|
||||
Future<void> guardarPrincipal(PresetEcualizador preset);
|
||||
Future<void> guardarPorEmisora(String uuid, PresetEcualizador preset);
|
||||
Future<void> eliminarPorEmisora(String uuid);
|
||||
}
|
||||
```
|
||||
|
||||
`ConfiguracionEcualizador` contains `PresetEcualizador principal` and `Map<String, PresetEcualizador> porEmisora`.
|
||||
|
||||
## Testing Strategy
|
||||
|
||||
| Layer | What to Test | Approach |
|
||||
|---|---|---|
|
||||
| Unit | `ServicioRadio` retries and rotates hosts | Fake `http.Client`, zero delay. |
|
||||
| Unit | EQ load/save and fallback selection | SharedPreferences mock values + fake audio service. |
|
||||
| Unit | Custom station added appears in combined listing | Inject fake custom storage or initial state. |
|
||||
| Widget | Home renders custom station and favorite tap persists | Pump `PantallaInicio` with test `EstadoRadio`. |
|
||||
| Regression | Current station updates for mini player/station EQ | Fake audio handler/service assertions. |
|
||||
|
||||
## Migration / Rollout
|
||||
|
||||
No destructive migration. On first run without EQ keys, use `PresetEcualizador.flat` as main EQ and empty per-station map. Existing export/import keys can be read opportunistically but app-local persistence should use the new service.
|
||||
|
||||
## Open Questions
|
||||
|
||||
- None blocking. The first implementation can place station EQ controls in Settings for the currently playing favorite; a richer per-favorite management screen can be deferred.
|
||||
@@ -0,0 +1,69 @@
|
||||
# Exploration: Startup retry, custom stations, and equalizer persistence
|
||||
|
||||
## Current State
|
||||
|
||||
- `lib/main.dart` only initializes `AudioService` and launches `PluriWaveApp`; app data initialization starts later when `EstadoRadio` is created by `ChangeNotifierProvider` in `lib/app.dart`.
|
||||
- `EstadoRadio` constructor calls `_init()` without awaiting it. `_init()` runs `Future.wait([cargarPopulares(), cargarFavoritos(), _cargarEmisoresCustom()])`.
|
||||
- `cargarPopulares()` fetches `radio.obtenerPopulares()` and `radio.obtenerTendencias()` once. On any failure it sets `_errorCarga = 'Sin conexion a la API de radio'`; the UI exposes a manual "Reintentar" button but there is no automatic startup retry.
|
||||
- `ServicioRadio._get()` picks one fallback Radio Browser host, applies a 10s timeout, and clears `_servidorActual` on error so a later call can rotate. It does not retry within the same request.
|
||||
- Custom stations are stored as JSON from inside `EstadoRadio` (`emisoras_custom.json`) and are only rendered in `_SeccionEmisoras` in `pantalla_ajustes.dart`. `PantallaInicio` lists API stations only, so custom stations never enter the main grid. `TarjetaEmisora` already supports favorites for any `Emisora`.
|
||||
- Equalizer state is in memory only: `_presetActual` plus `_presetsEmisoraMap` in `EstadoRadio`. Export/import includes station preset maps, but startup never loads EQ state from app storage.
|
||||
- Per-station EQ is currently unreliable because `EstadoRadio.cambiarPresetEcualizador()` stores by `emisoraActual`, while `PluriWaveAudioHandler.emisoraActual` is declared but never assigned when playback starts.
|
||||
- Existing tests are only `test/widget_test.dart`, a placeholder asserting `true`. Strict TDD is active, so the implementation needs test seams before behavior changes.
|
||||
|
||||
## Affected Areas
|
||||
|
||||
- `lib/servicios/servicio_radio.dart` - startup/API fetch resilience and host retry behavior.
|
||||
- `lib/estado/estado_radio.dart` - startup orchestration, custom station listing, EQ load/save, station EQ selection.
|
||||
- `lib/servicios/servicio_audio.dart` - current station tracking needed for mini player and per-station EQ.
|
||||
- `lib/pantallas/pantalla_inicio.dart` - main listing must include custom stations.
|
||||
- `lib/pantallas/pantalla_ajustes.dart` / `lib/widgets/ecualizador_widget.dart` - EQ scope controls and persisted graph display.
|
||||
- `lib/modelos/preset_ecualizador.dart` - equality/copy helpers may be needed for persistence tests.
|
||||
- `test/` - new unit/widget tests for startup retry, custom station listing/favorites, and EQ persistence.
|
||||
|
||||
## Approaches
|
||||
|
||||
1. **Retry in `EstadoRadio.cargarPopulares()`**
|
||||
- Pros: small change; directly targets startup; easy to preserve `ServicioRadio`.
|
||||
- Cons: search calls still lack retry; duplicated retry policy if other API calls need it.
|
||||
- Effort: Low.
|
||||
|
||||
2. **Retry inside `ServicioRadio._get()` with host rotation**
|
||||
- Pros: centralizes network resilience; startup and search benefit; keeps `EstadoRadio` simpler.
|
||||
- Cons: needs injectable HTTP client/delay for tests; must avoid long blocking startup.
|
||||
- Effort: Medium.
|
||||
|
||||
3. **Merge custom stations into main grid via `EstadoRadio` getter**
|
||||
- Pros: minimal UI disruption; `TarjetaEmisora` already handles favorite toggles.
|
||||
- Cons: custom and API stations share one grid; no separate "My stations" visual grouping.
|
||||
- Effort: Low.
|
||||
|
||||
4. **Separate "Mis emisoras" section on `PantallaInicio`**
|
||||
- Pros: clearer UX; no confusion with API popularity ranking.
|
||||
- Cons: more UI work and widget tests; still must define empty/genre-filter behavior.
|
||||
- Effort: Medium.
|
||||
|
||||
5. **Persist EQ in SharedPreferences through a dedicated service**
|
||||
- Pros: dependency already exists; JSON values fit `PresetEcualizador`; avoids SQLite migration.
|
||||
- Cons: less relational than SQLite; needs careful key/version handling.
|
||||
- Effort: Medium.
|
||||
|
||||
6. **Persist EQ in SQLite favorites table**
|
||||
- Pros: station-specific EQ close to favorite rows.
|
||||
- Cons: requires DB migration and does not naturally store global/main EQ.
|
||||
- Effort: High.
|
||||
|
||||
## Recommendation
|
||||
|
||||
Use service-level radio retry with host rotation, expose a combined main-station getter for custom stations, and introduce a small `ServicioEcualizador` backed by SharedPreferences. Represent station EQ as "entry exists = own EQ; no entry = use main EQ". Also fix current-station tracking in the audio layer before wiring station EQ; otherwise the UI and per-station persistence sit on arena sand, not concrete.
|
||||
|
||||
## Risks
|
||||
|
||||
- Retrying both popular and trending in parallel can lengthen startup; cap attempts and use short backoff.
|
||||
- SharedPreferences persistence must be loaded before the first playback applies EQ.
|
||||
- Android equalizer availability is runtime-dependent; persisted EQ must still load even when native EQ is not available yet.
|
||||
- Adding test seams can touch constructors; keep backward-compatible defaults.
|
||||
|
||||
## Ready for Proposal
|
||||
|
||||
Yes. The code paths are clear enough to plan without production changes.
|
||||
@@ -0,0 +1,72 @@
|
||||
# Proposal: Startup retry, custom stations, and equalizer persistence
|
||||
|
||||
## Intent
|
||||
|
||||
Make startup resilient to transient Radio Browser/API failures, make user-added stations first-class in the main listing/favorites flow, and persist equalizer choices so the app restores the configured graph and respects station-specific EQ.
|
||||
|
||||
## Scope
|
||||
|
||||
### In Scope
|
||||
- Add bounded retry with host rotation for initial radio API fetches.
|
||||
- Show custom stations from Settings in the main station listing.
|
||||
- Keep custom stations favorite-capable through existing favorite persistence.
|
||||
- Persist main EQ and per-favorite station EQ.
|
||||
- Apply station EQ when present; otherwise apply main EQ.
|
||||
- Add strict-TDD tests before implementation.
|
||||
|
||||
### Out of Scope
|
||||
- `flutter build` or release packaging.
|
||||
- Replacing Provider/ChangeNotifier.
|
||||
- Full redesign of radio browsing/search UX.
|
||||
- Cloud sync of EQ or station data.
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
- `startup-radio-loading`: resilient startup station loading with bounded retry.
|
||||
- `custom-stations-listing`: custom stations appear in the main listing and can be favorites.
|
||||
- `equalizer-persistence`: main EQ persists and loads on startup.
|
||||
- `station-equalizer`: favorite stations may own EQ or use main EQ.
|
||||
|
||||
### Modified Capabilities
|
||||
- None; no existing OpenSpec source specs exist yet.
|
||||
|
||||
## Approach
|
||||
|
||||
Centralize API retry in `ServicioRadio`, add test-friendly dependency injection, expose a combined main listing in `EstadoRadio`, and introduce `ServicioEcualizador` using SharedPreferences JSON. Use null/no entry for station EQ fallback to main EQ.
|
||||
|
||||
## Affected Areas
|
||||
|
||||
| Area | Impact | Description |
|
||||
|---|---|---|
|
||||
| `lib/servicios/servicio_radio.dart` | Modified | Retry/host rotation and injectable HTTP client/delay. |
|
||||
| `lib/estado/estado_radio.dart` | Modified | Init flow, main listing getter, EQ load/save/apply policy. |
|
||||
| `lib/servicios/servicio_audio.dart` | Modified | Track current station correctly for UI and EQ. |
|
||||
| `lib/servicios/servicio_ecualizador.dart` | New | Persist main and station EQ settings. |
|
||||
| `lib/pantallas/pantalla_inicio.dart` | Modified | Render custom stations in the main list. |
|
||||
| `lib/pantallas/pantalla_ajustes.dart` | Modified | EQ scope controls/load state. |
|
||||
| `test/` | Modified | Unit/widget tests for all spec scenarios. |
|
||||
|
||||
## Risks
|
||||
|
||||
| Risk | Likelihood | Mitigation |
|
||||
|---|---:|---|
|
||||
| Startup delay from retries | Med | Cap attempts, short backoff, preserve manual retry. |
|
||||
| Native EQ unavailable before playback | Med | Persist Provider state independently from Android EQ. |
|
||||
| Constructor changes break widgets | Low | Keep default constructors backward compatible. |
|
||||
|
||||
## Rollback Plan
|
||||
|
||||
Revert the change folder and implementation commits. Since persistence uses new SharedPreferences keys, rollback can ignore them safely.
|
||||
|
||||
## Dependencies
|
||||
|
||||
- Existing `shared_preferences`, `http`, `provider`, `flutter_test`.
|
||||
|
||||
## Success Criteria
|
||||
|
||||
- [ ] Transient startup API failure retries and succeeds without showing final error.
|
||||
- [ ] Exhausted startup attempts leave the app usable with manual retry.
|
||||
- [ ] Custom stations appear in `PantallaInicio` and can be favorited.
|
||||
- [ ] Main EQ restores after app restart.
|
||||
- [ ] Favorite station own EQ overrides main EQ only when enabled.
|
||||
@@ -0,0 +1,83 @@
|
||||
# Spec: Startup retry, custom stations, and equalizer persistence
|
||||
|
||||
## Requirement: Startup radio loading resilience
|
||||
|
||||
The system MUST retry initial Radio Browser station loading with bounded attempts and host rotation before exposing a startup connection error.
|
||||
|
||||
### Scenario: transient startup failure recovers
|
||||
- GIVEN the first radio API request fails due to a transient connection error
|
||||
- WHEN the app initializes `EstadoRadio`
|
||||
- THEN the system MUST retry using an eligible host
|
||||
- AND popular/tending stations SHALL be populated when a later attempt succeeds
|
||||
- AND no final startup error SHALL remain visible
|
||||
|
||||
### Scenario: startup failures are exhausted
|
||||
- GIVEN all configured retry attempts fail
|
||||
- WHEN initial station loading completes
|
||||
- THEN the system MUST stop retrying automatically
|
||||
- AND it MUST expose a user-visible connection error
|
||||
- AND the manual retry action MUST still call station loading again
|
||||
|
||||
## Requirement: Custom stations in the main listing
|
||||
|
||||
The system MUST include stations added in Settings in the main station listing and MUST allow them to be marked/unmarked as favorites through the same favorite flow as API stations.
|
||||
|
||||
### Scenario: added custom station appears on home
|
||||
- GIVEN a user saves a valid custom station in Settings
|
||||
- WHEN the main listing is rendered without a genre filter
|
||||
- THEN the custom station MUST be visible in the listing
|
||||
- AND selecting it MUST start playback through the normal `EstadoRadio.reproducir` path
|
||||
|
||||
### Scenario: custom station can be favorited
|
||||
- GIVEN a custom station is visible in the main listing
|
||||
- WHEN the user taps its favorite action
|
||||
- THEN the station MUST be persisted in favorites
|
||||
- AND the Favorites screen SHALL show it after favorite state reloads
|
||||
|
||||
## Requirement: Main equalizer persistence
|
||||
|
||||
The system MUST persist the main equalizer preset/graph and MUST load it during state initialization before the first playback-specific EQ decision.
|
||||
|
||||
### Scenario: main EQ restores after restart
|
||||
- GIVEN the user configures the main EQ to a non-flat graph
|
||||
- WHEN the app state is recreated
|
||||
- THEN `EstadoRadio.presetEcualizador` MUST expose the saved graph
|
||||
- AND the native audio equalizer SHALL receive it when the EQ becomes available
|
||||
|
||||
### Scenario: EQ state persists even when native EQ is unavailable
|
||||
- GIVEN the platform has no available native equalizer at startup
|
||||
- WHEN persisted EQ settings are loaded
|
||||
- THEN Provider state MUST still expose the saved EQ graph
|
||||
- AND no persistence data SHALL be discarded
|
||||
|
||||
## Requirement: Favorite station equalizer mode
|
||||
|
||||
The system MUST let each favorite station either use the main equalizer or use its own saved equalizer. If own EQ exists for a station, playback MUST respect it.
|
||||
|
||||
### Scenario: favorite station own EQ is applied
|
||||
- GIVEN a favorite station has its own saved EQ graph
|
||||
- WHEN the user plays that station
|
||||
- THEN the system MUST apply the station EQ graph
|
||||
- AND it MUST expose that graph as the current EQ in state
|
||||
|
||||
### Scenario: favorite station falls back to main EQ
|
||||
- GIVEN a favorite station has no own EQ enabled
|
||||
- AND the main EQ is configured
|
||||
- WHEN the user plays that station
|
||||
- THEN the system MUST apply the main EQ graph
|
||||
|
||||
### Scenario: disabling own EQ restores main behavior
|
||||
- GIVEN a favorite station has own EQ enabled
|
||||
- WHEN the user switches that station to use main EQ
|
||||
- THEN the station-specific EQ entry MUST be removed or ignored
|
||||
- AND future playback of that station MUST use the current main EQ
|
||||
|
||||
## Requirement: Test-first implementation
|
||||
|
||||
The implementation MUST add failing tests for each scenario before production behavior is changed.
|
||||
|
||||
### Scenario: strict TDD guardrail
|
||||
- GIVEN this change is implemented
|
||||
- WHEN an implementation task begins
|
||||
- THEN the corresponding test MUST be written first
|
||||
- AND verification MUST use `flutter test`, never `flutter build`
|
||||
@@ -0,0 +1,48 @@
|
||||
schema: spec-driven
|
||||
change: startup-retry-custom-stations-eq-persistence
|
||||
project: pluriwave
|
||||
artifact_store: hybrid
|
||||
execution_mode: auto
|
||||
strict_tdd: true
|
||||
test_command: flutter test
|
||||
build_command: null
|
||||
current_phase: apply-partial
|
||||
next_recommended: sdd-verify
|
||||
phases:
|
||||
explore:
|
||||
status: completed
|
||||
file: openspec/changes/startup-retry-custom-stations-eq-persistence/explore.md
|
||||
engram_topic_key: sdd/startup-retry-custom-stations-eq-persistence/explore
|
||||
proposal:
|
||||
status: completed
|
||||
file: openspec/changes/startup-retry-custom-stations-eq-persistence/proposal.md
|
||||
engram_topic_key: sdd/startup-retry-custom-stations-eq-persistence/proposal
|
||||
spec:
|
||||
status: completed
|
||||
file: openspec/changes/startup-retry-custom-stations-eq-persistence/spec.md
|
||||
engram_topic_key: sdd/startup-retry-custom-stations-eq-persistence/spec
|
||||
design:
|
||||
status: completed
|
||||
file: openspec/changes/startup-retry-custom-stations-eq-persistence/design.md
|
||||
engram_topic_key: sdd/startup-retry-custom-stations-eq-persistence/design
|
||||
tasks:
|
||||
status: completed
|
||||
file: openspec/changes/startup-retry-custom-stations-eq-persistence/tasks.md
|
||||
engram_topic_key: sdd/startup-retry-custom-stations-eq-persistence/tasks
|
||||
apply:
|
||||
status: partial
|
||||
file: openspec/changes/startup-retry-custom-stations-eq-persistence/apply-progress.md
|
||||
engram_topic_key: sdd/startup-retry-custom-stations-eq-persistence/apply-progress
|
||||
verify:
|
||||
status: pending
|
||||
archive:
|
||||
status: pending
|
||||
constraints:
|
||||
- Do not implement production code during planning.
|
||||
- Do not run flutter build.
|
||||
- Apply strict TDD: write failing tests before production changes.
|
||||
- Preserve Spanish folder/naming style and Provider/ChangeNotifier patterns.
|
||||
risks:
|
||||
- Retry policy must not block startup for too long.
|
||||
- Native equalizer availability is platform/runtime dependent.
|
||||
- Current station tracking must be fixed for station-specific EQ to be reliable.
|
||||
@@ -0,0 +1,39 @@
|
||||
# Tasks: Startup retry, custom stations, and equalizer persistence
|
||||
|
||||
## Phase 1: Test seams and RED tests
|
||||
|
||||
- [x] 1.1 RED: Add `test/servicios/servicio_radio_test.dart` proving a transient HTTP failure retries with another host and succeeds.
|
||||
- [x] 1.2 RED: Add `test/servicios/servicio_radio_test.dart` proving exhausted retries surface an error after the configured attempt cap.
|
||||
- [x] 1.3 RED: Add `test/estado/estado_radio_test.dart` proving a saved custom station is included in the main listing getter.
|
||||
- [x] 1.4 RED: Add `test/estado/estado_radio_test.dart` proving main EQ loads from persistence before playback EQ selection.
|
||||
- [x] 1.5 RED: Add station EQ tests proving own EQ overrides main and disabled own EQ falls back to main.
|
||||
- [x] 1.6 RED: Add/update a widget test proving `PantallaInicio` renders custom stations and favorite tap calls the favorite flow.
|
||||
|
||||
## Phase 2: Foundation / services
|
||||
|
||||
- [x] 2.1 GREEN: Modify `ServicioRadio` to accept injectable `http.Client`, host list, max attempts, and retry delay while preserving default constructor behavior.
|
||||
- [x] 2.2 GREEN: Implement bounded retry/host rotation in `ServicioRadio._get()` without adding unbounded startup waits.
|
||||
- [x] 2.3 GREEN: Create `lib/servicios/servicio_ecualizador.dart` with SharedPreferences JSON load/save for main EQ and per-station EQ map.
|
||||
- [x] 2.4 GREEN: Add equality/copy helpers to `PresetEcualizador` only if required by tests.
|
||||
|
||||
## Phase 3: State integration
|
||||
|
||||
- [x] 3.1 GREEN: Update `EstadoRadio` constructor for optional service injection and load EQ config during `_init()`.
|
||||
- [x] 3.2 GREEN: Add a combined main listing getter (`emisorasInicio` or equivalent) that includes custom stations plus API stations without duplicates.
|
||||
- [x] 3.3 GREEN: Persist main EQ changes when no station-own EQ scope is active.
|
||||
- [x] 3.4 GREEN: Add methods to enable/update/disable EQ per favorite station and persist the map.
|
||||
- [x] 3.5 GREEN: Change playback EQ selection to apply station EQ when present, otherwise main EQ.
|
||||
|
||||
## Phase 4: UI wiring
|
||||
|
||||
- [x] 4.1 GREEN: Update `PantallaInicio` to render the combined main listing when no genre filter is selected.
|
||||
- [x] 4.2 GREEN: Reuse `TarjetaEmisora` favorite controls for custom stations; do not introduce a parallel favorite path.
|
||||
- [x] 4.3 GREEN: Update `PantallaAjustes` EQ controls to show/edit main EQ and, when the current station is a favorite, allow own-EQ vs main-EQ mode.
|
||||
- [x] 4.4 GREEN: Fix `ServicioAudio`/handler so `emisoraActual` is set on successful playback and cleared on stop/error as tests require.
|
||||
|
||||
## Phase 5: REFACTOR and verification
|
||||
|
||||
- [x] 5.1 REFACTOR: Remove duplicated JSON/persistence logic from `EstadoRadio` where the new service owns it.
|
||||
- [x] 5.2 REFACTOR: Keep Spanish naming and Provider/ChangeNotifier style consistent with existing folders.
|
||||
- [ ] 5.3 VERIFY: Run `flutter test` only; never run `flutter build`.
|
||||
- [ ] 5.4 VERIFY: Compare passing tests against every Given/When/Then scenario in `spec.md`.
|
||||
@@ -0,0 +1,222 @@
|
||||
# Verification Report: startup-retry-custom-stations-eq-persistence
|
||||
|
||||
**Status**: blocked
|
||||
**Mode**: Strict TDD
|
||||
**Date**: 2026-04-27
|
||||
**Verifier**: sdd-verify worker 2
|
||||
**Round**: re-verify after targeted apply-fix
|
||||
|
||||
Runtime verification remains blocked because `flutter` is not available in PATH in this shell. Static review confirms the targeted fixes from the prior verification round are present. This change is still **not archiveable** because Strict TDD requires passing `flutter test` evidence before scenarios can be marked compliant and before tasks 5.3/5.4 can be completed.
|
||||
|
||||
---
|
||||
|
||||
## Completeness
|
||||
|
||||
| Metric | Value |
|
||||
|---|---:|
|
||||
| Tasks total | 23 |
|
||||
| Tasks complete | 21 |
|
||||
| Tasks incomplete | 2 |
|
||||
|
||||
Incomplete by design until runtime evidence exists:
|
||||
|
||||
- `[ ] 5.3 VERIFY: Run flutter test only; never run flutter build.`
|
||||
- `[ ] 5.4 VERIFY: Compare passing tests against every Given/When/Then scenario in spec.md.`
|
||||
|
||||
Tasks 5.3 and 5.4 **must remain incomplete**. `flutter test` was attempted and could not run because Flutter is missing from PATH.
|
||||
|
||||
---
|
||||
|
||||
## Validation Commands Attempted
|
||||
|
||||
| Command | Exit | Result |
|
||||
|---|---:|---|
|
||||
| `git status --short` | 0 | Confirmed active uncommitted work exists; verification did not revert or edit production code. |
|
||||
| `Get-Command flutter -ErrorAction SilentlyContinue` | 127 | `FLUTTER_NOT_FOUND: Get-Command flutter returned no executable on PATH.` |
|
||||
| `flutter test` | 1 | `CommandNotFoundException`: `flutter` is not recognized as a cmdlet/program in this PowerShell session. |
|
||||
| `flutter build` | N/A | Not run; prohibited by project and mission constraints. |
|
||||
|
||||
Coverage, linter, and type-check commands were not run because the configured tools are Flutter-backed (`flutter test --coverage`, `flutter analyze`) and Flutter is unavailable.
|
||||
|
||||
---
|
||||
|
||||
## TDD Compliance
|
||||
|
||||
| Check | Result | Details |
|
||||
|---|---|---|
|
||||
| TDD Evidence reported | PASSED STATIC | `apply-progress.md` now contains `## TDD Cycle Evidence`. |
|
||||
| Test files exist | PASSED STATIC | Verified `test/servicios/servicio_radio_test.dart`, `test/estado/estado_radio_test.dart`, and `test/pantallas/pantalla_inicio_test.dart`. |
|
||||
| RED confirmed | PARTIAL / BLOCKED | Test intent is documented and test files exist, but RED-first ordering cannot be independently proven without historical run output. |
|
||||
| GREEN confirmed | BLOCKED | `flutter test` cannot execute in this environment. |
|
||||
| Triangulation adequate | PARTIAL / BLOCKED | Targeted missing scenarios now have tests; runtime proof is blocked. |
|
||||
| Safety net for modified files | BLOCKED | Apply-progress records the same Flutter availability blocker. |
|
||||
|
||||
**TDD compliance verdict**: blocked. The prior missing-evidence-table finding is fixed, but Strict TDD cannot pass until `flutter test` runs successfully.
|
||||
|
||||
---
|
||||
|
||||
## Test Layer Distribution
|
||||
|
||||
| Layer | Tests | Files | Tool |
|
||||
|---|---:|---:|---|
|
||||
| Unit/service | 2 | 1 | `flutter_test` + `http/testing` |
|
||||
| Unit/state | 6 | 1 | `flutter_test` |
|
||||
| Widget/component | 3 | 1 | `flutter_test` |
|
||||
| E2E | 0 | 0 | Not configured |
|
||||
| **Total** | **11** | **3** | |
|
||||
|
||||
Related helper file:
|
||||
|
||||
- `test/helpers/fakes.dart`
|
||||
|
||||
---
|
||||
|
||||
## Scenario Coverage Matrix
|
||||
|
||||
Runtime result is `BLOCKED` for every scenario because no test execution was possible. Under Strict TDD, no scenario can be marked compliant until a covering test has passed.
|
||||
|
||||
| Requirement | Scenario | Static implementation evidence | Test evidence found | Result |
|
||||
|---|---|---|---|---|
|
||||
| Startup radio loading resilience | transient startup failure recovers | `ServicioRadio._get()` retries with host rotation; `EstadoRadio._init()` calls station loading after EQ load. | `test/servicios/servicio_radio_test.dart` covers retry/host rotation success. No direct `EstadoRadio` startup integration test for final visible error clearing, but design assigns retry ownership to `ServicioRadio`. | PARTIAL STATIC / BLOCKED |
|
||||
| Startup radio loading resilience | startup failures are exhausted | `ServicioRadio._get()` caps attempts; `EstadoRadio.cargarPopulares()` exposes `Sin conexión a la API de radio`; `PantallaInicio` has `Reintentar`. | Service cap/error test exists. State and widget tests now cover startup failure plus manual retry recovery. | COVERED STATICALLY / BLOCKED |
|
||||
| Custom stations in main listing | added custom station appears on home | `EstadoRadio.emisorasInicio` combines custom + popular; `PantallaInicio` uses it without genre filter; tap calls `EstadoRadio.reproducir`. | State getter test exists. Widget test now renders `Custom Uno` and taps it, asserting fake audio playback and click registration. | COVERED STATICALLY / BLOCKED |
|
||||
| Custom stations in main listing | custom station can be favorited | `TarjetaEmisora` uses the same `EstadoRadio.toggleFavorito` flow for all station cards; `toggleFavorito` reloads favorites. | Widget test taps favorite on the custom station. Widget test now opens `PantallaFavoritos` and verifies the custom station appears after reload. | COVERED STATICALLY / BLOCKED |
|
||||
| Main equalizer persistence | main EQ restores after restart | `ServicioEcualizador.cargar()` loads persisted main EQ; `EstadoRadio._cargarEcualizadorPersistido()` sets provider state before station loading; playback applies selected EQ. | State test covers persisted main EQ before playback EQ selection. | COVERED STATICALLY / BLOCKED |
|
||||
| Main equalizer persistence | EQ state persists even when native EQ is unavailable | `EstadoRadio` loads persisted EQ independent of `audio.ecualizadorDisponible`; production `ServicioAudio.aplicarPreset()` stores `_presetActual` before returning when native EQ is unavailable. | State test now uses `FakeServicioAudio(ecualizadorActivo: false)` and verifies main + per-station persisted EQ remain exposed. | COVERED STATICALLY / BLOCKED |
|
||||
| Favorite station equalizer mode | favorite station own EQ is applied | `_presetParaEmisora()` prefers `_presetsEmisoraMap[uuid]`; `reproducir()` applies selected preset and updates state. | State test covers own EQ overriding main. | COVERED STATICALLY / BLOCKED |
|
||||
| Favorite station equalizer mode | favorite station falls back to main EQ | Map absence falls back to `_presetPrincipal`. | State test now covers a favorite without own EQ using main EQ from first play. | COVERED STATICALLY / BLOCKED |
|
||||
| Favorite station equalizer mode | disabling own EQ restores main behavior | `deshabilitarPresetEcualizadorPorEmisora()` removes persisted entry and applies main when current station matches. | State test covers disabling own EQ and replaying with main fallback. | COVERED STATICALLY / BLOCKED |
|
||||
| Test-first implementation | strict TDD guardrail | `openspec/config.yaml` and `state.yaml` have Strict TDD active; `apply-progress.md` now records TDD cycle evidence and blocked Flutter commands. | TDD table exists, but `flutter test` cannot run, so GREEN evidence is unavailable. | PARTIAL STATIC / BLOCKED |
|
||||
|
||||
**Runtime compliance summary**: 0/10 scenarios compliant because no covering test has passed in this environment.
|
||||
**Static coverage summary**: 8/10 scenarios covered statically, 2/10 partial statically.
|
||||
|
||||
---
|
||||
|
||||
## Prior Findings Re-check
|
||||
|
||||
| Prior finding | Status | Evidence |
|
||||
|---|---|---|
|
||||
| `mediaItem.add(null)` shadowing in `playMediaItem(MediaItem mediaItem)` | FIXED | `lib/servicios/servicio_audio.dart:239` now uses `this.mediaItem.add(null)`. Other `mediaItem.add(null)` calls are outside the shadowing scope. |
|
||||
| `apply-progress.md` missing Strict TDD Cycle Evidence | FIXED | `openspec/changes/startup-retry-custom-stations-eq-persistence/apply-progress.md` now contains `## TDD Cycle Evidence`. |
|
||||
| Missing native-EQ-unavailable test | FIXED STATICALLY | `test/estado/estado_radio_test.dart` includes `mantiene EQ persistido aunque el ecualizador nativo no esté disponible`. |
|
||||
| Missing manual retry test | FIXED STATICALLY | `test/pantallas/pantalla_inicio_test.dart` includes `PantallaInicio permite reintentar manualmente tras fallo inicial agotado`; state test also checks manual `cargarPopulares()` recovery. |
|
||||
| Missing custom station playback tap test | FIXED STATICALLY | `test/pantallas/pantalla_inicio_test.dart` taps `Custom Uno` and asserts playback via fake audio. |
|
||||
| Missing favorites screen reload test | FIXED STATICALLY | `test/pantallas/pantalla_inicio_test.dart` opens `PantallaFavoritos` after favoriting and expects `Custom Uno`. |
|
||||
| Missing favorite main-EQ fallback test | FIXED STATICALLY | `test/estado/estado_radio_test.dart` includes `favorita sin EQ propio usa EQ principal desde el primer play`. |
|
||||
| `PantallaAjustes` async per-band loop | FIXED | `lib/pantallas/pantalla_ajustes.dart:94-98` calls `estado.cambiarPresetEcualizador(p)` once from `EcualizadorWidget.onCambio`; no per-band async loop remains in the widget. |
|
||||
|
||||
---
|
||||
|
||||
## Correctness: Static Structural Evidence
|
||||
|
||||
| Requirement | Status | Notes |
|
||||
|---|---|---|
|
||||
| Startup radio loading resilience | PARTIAL STATIC | Retry/host rotation and exhausted retry behavior exist. Manual retry coverage was added. Automatic transient startup recovery is proven primarily at the service layer, not with a direct `EstadoRadio` startup integration test. |
|
||||
| Custom stations in the main listing | IMPLEMENTED STATICALLY | Combined listing, normal playback path, same favorite flow, and favorites screen reload are represented in code/tests. |
|
||||
| Main equalizer persistence | IMPLEMENTED STATICALLY | EQ persistence service, provider load, native-unavailable state retention, and playback application are represented in code/tests. |
|
||||
| Favorite station equalizer mode | IMPLEMENTED STATICALLY | Own EQ, main fallback, and disabling own EQ are represented in state code/tests. |
|
||||
| Test-first implementation | BLOCKED | Strict TDD metadata and TDD evidence table exist; runtime GREEN evidence is blocked by missing Flutter. |
|
||||
|
||||
---
|
||||
|
||||
## Coherence: Design Decisions
|
||||
|
||||
| Decision | Followed? | Notes |
|
||||
|---|---|---|
|
||||
| API retry owner in `ServicioRadio._get()` | Yes | Bounded retry/host rotation remains centralized in `ServicioRadio._get()`. |
|
||||
| Custom stations home UX via combined listing | Yes | `EstadoRadio.emisorasInicio` combines custom + popular; `PantallaInicio` uses it when no genre filter is selected. |
|
||||
| EQ storage in `ServicioEcualizador` with SharedPreferences JSON | Yes | `ServicioEcualizador` stores main and per-station EQ JSON. |
|
||||
| Station EQ fallback by `Map<uuid, PresetEcualizador>` absence | Yes | `_presetParaEmisora()` returns station preset or main preset. |
|
||||
| Current station source in `ServicioAudio`/handler | Yes static | `ServicioAudio` sets/clears `emisoraActual`; the previously shadowed `playMediaItem` exception path now uses `this.mediaItem.add(null)`. |
|
||||
|
||||
---
|
||||
|
||||
## Assertion Quality Audit
|
||||
|
||||
Reviewed related tests:
|
||||
|
||||
- `test/servicios/servicio_radio_test.dart`
|
||||
- `test/estado/estado_radio_test.dart`
|
||||
- `test/pantallas/pantalla_inicio_test.dart`
|
||||
|
||||
**Assertion quality**: PASSED STATIC REVIEW. No tautological assertions, ghost loops, or smoke-only widget tests were found in the reviewed change tests. Assertions check concrete behavior: host sequence, call counts, visible text, persisted favorite state, selected EQ preset, and playback calls.
|
||||
|
||||
---
|
||||
|
||||
## Issues Found
|
||||
|
||||
### CRITICAL
|
||||
|
||||
None found in static re-review after the targeted fixes.
|
||||
|
||||
### WARNING
|
||||
|
||||
1. Runtime verification is blocked because Flutter is unavailable. This is not a production-code defect, but it blocks Strict TDD completion and archive.
|
||||
2. The transient startup recovery scenario is still proven most directly at `ServicioRadio` level rather than by a direct `EstadoRadio.inicializar()` integration test that starts with a transient service failure and ends with no visible startup error. Given the design decision that retry ownership lives in `ServicioRadio`, this is a coverage nuance, not a new blocker beyond runtime execution.
|
||||
|
||||
### SUGGESTION
|
||||
|
||||
1. When Flutter is available, run `flutter test` first; only after it passes should tasks 5.3/5.4 be marked complete.
|
||||
2. Consider adding one direct `EstadoRadio.inicializar()` transient-recovery test later if the team wants tighter end-to-end coverage for the first startup scenario.
|
||||
|
||||
---
|
||||
|
||||
## Changed File Coverage
|
||||
|
||||
Coverage analysis skipped: Flutter is unavailable, so `flutter test --coverage` cannot run.
|
||||
|
||||
---
|
||||
|
||||
## Quality Metrics
|
||||
|
||||
**Linter**: Not run (`flutter analyze` requires Flutter in PATH).
|
||||
**Type checker**: Not run (`flutter analyze` requires Flutter in PATH).
|
||||
**Build**: Not run; build commands are prohibited by project and mission constraints.
|
||||
|
||||
---
|
||||
|
||||
## Tasks 5.3 / 5.4 Status
|
||||
|
||||
| Task | Status | Reason |
|
||||
|---|---|---|
|
||||
| 5.3 VERIFY: Run `flutter test` only; never run `flutter build`. | INCOMPLETE | `flutter test` was attempted but failed before execution because the `flutter` command is unavailable. |
|
||||
| 5.4 VERIFY: Compare passing tests against every Given/When/Then scenario. | INCOMPLETE | No test passed at runtime in this environment, so scenario compliance cannot be accepted under Strict TDD. |
|
||||
|
||||
Do not mark either task complete until `flutter test` actually passes.
|
||||
|
||||
---
|
||||
|
||||
## Verdict
|
||||
|
||||
**BLOCKED, not archiveable.**
|
||||
|
||||
Static targeted fixes are present and no new static blockers were found, but Strict TDD runtime verification cannot pass without a successful `flutter test` run.
|
||||
|
||||
---
|
||||
|
||||
## Next Recommended
|
||||
|
||||
1. Install/expose Flutter on PATH for the verification environment.
|
||||
2. Run `flutter test` only; do **not** run `flutter build`.
|
||||
3. If tests pass, update tasks 5.3/5.4 and rerun verify to produce a passing scenario compliance matrix.
|
||||
|
||||
---
|
||||
|
||||
## Risks
|
||||
|
||||
- Until `flutter test` runs, compile errors or failing tests may still exist undetected.
|
||||
- Archive would be premature because Strict TDD requires passing behavioral evidence, not just static review.
|
||||
|
||||
---
|
||||
|
||||
## Artifacts Updated
|
||||
|
||||
- `openspec/changes/startup-retry-custom-stations-eq-persistence/verify-report.md`
|
||||
- Engram topic `sdd/startup-retry-custom-stations-eq-persistence/verify-report`
|
||||
|
||||
---
|
||||
|
||||
## Skill Resolution
|
||||
|
||||
injected
|
||||
64
openspec/config.yaml
Normal file
64
openspec/config.yaml
Normal file
@@ -0,0 +1,64 @@
|
||||
schema: spec-driven
|
||||
|
||||
context: |
|
||||
Tech stack: Flutter/Dart app for Android+iOS.
|
||||
Architecture: Provider/ChangeNotifier with Spanish domain folders: estado, modelos, pantallas, servicios, widgets.
|
||||
Testing: flutter_test via `flutter test`; Strict TDD enabled.
|
||||
Style: flutter_lints via analysis_options.yaml; use flutter analyze and dart format.
|
||||
Constraint: never run flutter build after changes.
|
||||
|
||||
strict_tdd: true
|
||||
|
||||
testing:
|
||||
strict_tdd: true
|
||||
detected: 2026-04-27
|
||||
test_runner:
|
||||
framework: flutter_test
|
||||
command: flutter test
|
||||
layers:
|
||||
unit:
|
||||
available: true
|
||||
tool: flutter_test
|
||||
integration:
|
||||
available: false
|
||||
tool: null
|
||||
e2e:
|
||||
available: false
|
||||
tool: null
|
||||
coverage:
|
||||
available: true
|
||||
command: flutter test --coverage
|
||||
quality_tools:
|
||||
linter:
|
||||
available: true
|
||||
command: flutter analyze
|
||||
type_checker:
|
||||
available: true
|
||||
command: flutter analyze
|
||||
formatter:
|
||||
available: true
|
||||
command: dart format .
|
||||
|
||||
rules:
|
||||
proposal:
|
||||
- Include rollback plan for risky changes
|
||||
- Identify affected modules/packages
|
||||
specs:
|
||||
- Use Given/When/Then format for scenarios
|
||||
- Use RFC 2119 keywords
|
||||
design:
|
||||
- Include architecture decisions with rationale
|
||||
tasks:
|
||||
- Group tasks by phase
|
||||
- Use hierarchical numbering
|
||||
- Keep tasks small enough to complete in one session
|
||||
apply:
|
||||
- Follow existing code patterns and conventions
|
||||
- Strict TDD Mode is active
|
||||
- Never run flutter build
|
||||
verify:
|
||||
- Run tests if possible
|
||||
- Compare implementation against every spec scenario
|
||||
- Never run flutter build
|
||||
archive:
|
||||
- Persist final state to Engram and openspec
|
||||
Reference in New Issue
Block a user