docs(sdd): add delta specs for the functional redesign

2026-07-28 18:06:46 +02:00
parent f58cf8739f
commit 433373ad7f
9 changed files with 729 additions and 0 deletions
@@ -0,0 +1,104 @@
+# EQ Custom Presets Specification
+
+## Purpose
+
+User-defined preset save/name/list on top of the existing 6 fixed presets,
+a per-station EQ entry point from the player's tool tray, and a
+"stations with their own EQ" drill-down. **Band count stays 5** — resolved
+by spike (Engram id 2498), not a pending decision. Traceable to WU13
+(Settings screen) and WU14 (player tool tray, shares WU13's editor
+component).
+
+## Requirements
+
+### Requirement: Five-Band Equalizer (Regression Guard, First-Class)
+
+The equalizer screen MUST render exactly **5** vertical sliders.
+`assert(bandas.length == 5)` in `preset_ecualizador.dart` MUST remain
+unchanged. Band count is device-reported via `just_audio`'s
+`AndroidEqualizer` (`params.bands`), not app-chosen; any requirement or
+implementation asserting 7 bands is rejected on sight.
+
+#### Scenario: Ecualizador screen renders 5 sliders
+
+- GIVEN the user opens the Ecualizador settings screen
+- WHEN it renders
+- THEN exactly 5 vertical sliders are shown, one per band
+
+#### Scenario: Band-count regression is rejected (edge case)
+
+- GIVEN a future change proposes 7 sliders or a modified `bandas.length` assert
+- WHEN that change is reviewed against this requirement
+- THEN it fails: 5 is the resolved, binding band count for this change
+
+### Requirement: Custom Preset Save
+
+The user MUST be able to save the current 5-band configuration as a new,
+named custom preset, which then appears alongside the 6 fixed presets in
+the preset chip row.
+
+#### Scenario: Saving a custom preset
+
+- GIVEN the user has adjusted the 5 sliders from a fixed preset
+- WHEN they choose "Guardar como preset" and enter the name "Mi preset"
+- THEN a new preset named "Mi preset" is persisted
+- AND it appears in the preset chip row on next render
+
+### Requirement: Custom Preset Naming Validates Non-Empty Input
+
+The system MUST reject an empty or whitespace-only preset name without
+crashing, and MUST NOT persist a preset in that case.
+
+#### Scenario: Empty name is rejected
+
+- GIVEN the "Guardar como preset" flow is open
+- WHEN the user submits an empty name
+- THEN a validation message is shown and no preset is saved
+
+### Requirement: Per-Station EQ Entry Point From the Player
+
+The player's tool tray MUST expose an "EQ propio" tile that opens a
+per-station EQ bottom sheet. That sheet MUST reuse the same 5-band editor
+component used by the Settings Ecualizador screen (not a separate
+implementation).
+
+#### Scenario: Opening per-station EQ from the player
+
+- GIVEN a station is currently playing
+- WHEN the user taps "EQ propio" in the tool tray
+- THEN a bottom sheet opens with 5 sliders bound to that station's resolved preset
+- AND changes made there apply through the existing per-station EQ persistence path
+
+### Requirement: Stations-With-Own-EQ Drill-Down
+
+The Settings Ecualizador screen MUST expose a row that navigates to a list
+of stations that currently have a station-specific preset override,
+sourced from the existing `presetsPorEmisora` map.
+
+#### Scenario: Drill-down lists exactly the overridden stations
+
+- GIVEN 2 stations have entries in `presetsPorEmisora` and N others do not
+- WHEN the user opens the drill-down
+- THEN exactly those 2 stations are listed
+
+### Requirement: Base-vs-Per-Station Explainer Preserved
+
+An info banner distinguishing the base (global/device) EQ from per-station
+overrides MUST remain visible on the Ecualizador screen.
+
+#### Scenario: Banner is visible on screen open
+
+- GIVEN the user opens the Ecualizador screen
+- WHEN it renders
+- THEN the base-vs-per-station explainer banner is visible
+
+### Requirement: Active Output Surfaced on the Main Screen
+
+The "Salida activa" (active output device) row MUST be visible on the main
+Ecualizador screen, not only in the Advanced sub-section.
+
+#### Scenario: Output row updates on device change
+
+- GIVEN the Ecualizador screen is open
+- WHEN the active audio output device changes (e.g. Bluetooth connects)
+- THEN the "Salida activa" row updates to reflect the new device