diff --git a/docs/audit-core-audio.md b/docs/audit-core-audio.md index a5b3606..30fa289 100644 --- a/docs/audit-core-audio.md +++ b/docs/audit-core-audio.md @@ -1,7 +1,8 @@ # Auditoría `core/audio/` -Rama: `audit/core-audio` -Estado global: neteja aplicada. 17 ítems `DONE` (+1 parcial), 4 `WONTFIX`, 4 `DEFERRED`. Els `DEFERRED` apunten al refactor pendent d'encapsular `Ja::*` en classe (COUP-01), que arrossegarà COUP-02, PATCH-03, PATCH-05, CONV-02, CONV-03 i la meitat restant d'INCONS-05. +Rama inicial: `audit/core-audio` (ítems DONE/WONTFIX/DEFERRED inicials). +Rama posterior: `refactor/audio-engine-class` — tanca els `DEFERRED` principals (COUP-01/02, PATCH-03, CONV-02/03, INCONS-05 complet). +Estado global: auditoria + refactor aplicats. 22 ítems `DONE`, 4 `WONTFIX`, 1 `DEFERRED` (PATCH-05 — política voice-stealing, és feature no deute). Estados posibles: - `PENDING` — identificado, sin tocar @@ -18,7 +19,7 @@ Los IDs se mantienen estables una vez asignados. Cada entrada apunta al(los) fic | ID | Título | Estado | |----|--------|--------| -| COUP-01 | Encapsular globals `Ja::` en clase (engine sin estado global) | DEFERRED | +| COUP-01 | Encapsular globals `Ja::` en clase (engine sin estado global) | DONE | | HC-02 | Formato/canales/freq hardcodeado en 3+ sitios | DONE | | INCONS-02 | Doble `MusicState` + `getRealMusicState` como cache paralelo | DONE | | HC-01 | Parámetros de audio no configurables (viola convención del proyecto) | DONE | @@ -52,7 +53,7 @@ Los IDs se mantienen estables una vez asignados. Cada entrada apunta al(los) fic |----|---------------|----------|-----------|--------|-------| | PATCH-01 | `audio.hpp:98,105,111` | `toggleEnabled/toggleSound/toggleMusic` sólo flipan el flag; no reaplican volúmenes | Importante | DONE | `toggle*()` i variants sense bool passen per `enable[Sound|Music](bool)`. Aquestes funcions ara reapliquen el volum cap a `Ja::` perquè els canals actius responguin al toggle | | PATCH-02 | `audio.cpp:98` | `music_.name.clear()` en overload por puntero → `getCurrentMusicName()` miente | Importante | DONE | `music_.name = music->filename`. Si `Ja::Music` va ser carregat amb filename, `getCurrentMusicName()` ara retorna el nom correcte; si no, queda buit (contracte explícit) | -| PATCH-03 | `audio.cpp:14-21` | `#undef L,C,R,PLAYBACK_*` workaround para macros filtradas por stb_vorbis | Importante | WONTFIX | Documentado; aislar stb_vorbis en TU propio sería más invasivo — se hará con COUP-01 | +| PATCH-03 | `audio.cpp:14-21` | `#undef L,C,R,PLAYBACK_*` workaround para macros filtradas por stb_vorbis | Importante | DONE | `stb_vorbis.c` + `#undef` migrats a `jail_audio.cpp` (TU únic). `audio.cpp` neta d'aquest workaround | | PATCH-04 | `jail_audio.hpp:501-507` | `setMusicPosition`/`getMusicPosition` stubs no-op | Importante | DONE | Eliminats (veure DEAD-01) | | PATCH-05 | `jail_audio.hpp:532-535` | "No hay canal libre → canal 0" robo de voz arbitrario | Importante | DEFERRED | Política de voice-stealing es una feature; se documenta | @@ -60,8 +61,8 @@ Los IDs se mantienen estables una vez asignados. Cada entrada apunta al(los) fic | ID | Fichero:línea | Hallazgo | Severidad | Estado | Notas | |----|---------------|----------|-----------|--------|-------| -| COUP-01 | `jail_audio.hpp:107-118` | `inline` globals en namespace: estado del engine sin encapsulación | Crítico | DEFERRED | Refactor grande; se hará en fase posterior | -| COUP-02 | `jail_audio.hpp` entero | Engine header-only: 678 líneas compilándose en cada TU | Importante | DEFERRED | Depende de COUP-01 | +| COUP-01 | `jail_audio.hpp:107-118` | `inline` globals en namespace: estado del engine sin encapsulación | Crítico | DONE | `Ja::Engine` classe amb RAII; `Audio` en posseeix `std::unique_ptr`. `Engine::active()` static accessor per als deleters de `Resource::Cache`. Branca `refactor/audio-engine-class` | +| COUP-02 | `jail_audio.hpp` entero | Engine header-only: 678 líneas compilándose en cada TU | Importante | DONE | `jail_audio.cpp` nou conté totes les definicions + `stb_vorbis.c`. El `.hpp` baixa a ~130 línies de declaracions | | COUP-03 | `audio.cpp:3`, `jail_audio.hpp:8` | `#include ` sólo para `std::cout` de errores | Importante | DONE | `` → `` als dos fitxers. `jail_audio.hpp` ja no arrossega iostream a cada TU que l'inclou. Missatges prefixats `Ja::` / `Audio:` (convenció `Module: message` del projecte) | | COUP-04 | `audio.cpp:43-45`, `208` | `Ja::init` en `initSDLAudio` vs `Ja::quit` en destructor (asimetría) | Menor | WONTFIX | Convive con singleton; se revisará con COUP-01 | | COUP-05 | `audio.hpp:71,79` | API pública expone `Ja::Music*`/`Ja::Sound*` | Menor | WONTFIX | Forward-declare ya mitiga; evita doble lookup por nombre | @@ -74,7 +75,7 @@ Los IDs se mantienen estables una vez asignados. Cada entrada apunta al(los) fic | INCONS-02 | `audio.hpp:44-48` + `jail_audio.hpp:44-50` | Dos `MusicState` paralelos + `getRealMusicState` como puente | Importante | DONE | Eliminat `music_.state` (cache) i `getRealMusicState`. `getMusicState()` consulta Ja::* directament i projecta INVALID/DISABLED → STOPPED. La font de veritat passa a ser Ja. `update()` ja no necessita sincronització | | INCONS-03 | `audio.cpp` varios | Comentarios mezclan catalán y español | Menor | DONE | Tots els comentaris en castellà passats a català (incloent-hi els dels enums, constants, `--- Secció ---`, includes `Per a ...`, variables membre). Resta els comentaris en català que ja hi eren | | INCONS-04 | `audio.hpp:70,78` | `playMusic` `loop=-1` vs `playSound` `loop=0` | Menor | WONTFIX | Convención razonable (música loop / sonido one-shot); documentar | -| INCONS-05 | `audio.hpp:102-105` | 4 formas de enable/disable sound (API redundante) + divergencia con `Ja::enableSound` | Importante | DONE (parcial) | 4 variants no-arg eliminades. La divergència amb `Ja::enableSound/enableMusic` es manté: Audio silencia per gain, Ja pararia els canals; la decisió es posposa a COUP-01 | +| INCONS-05 | `audio.hpp:102-105` | 4 formas de enable/disable sound (API redundante) + divergencia con `Ja::enableSound` | Importante | DONE | 4 variants no-arg eliminades. Divergència resolta: `Ja::Engine::enableMusic/enableSound` i els flags `music_enabled_`/`sound_enabled_` del motor eliminats (decisió de l'usuari: silenciar per gain des d'Audio via effectiveVolume). Tanca amb el commit 4 del refactor | ## 6. Código muerto @@ -91,5 +92,5 @@ Los IDs se mantienen estables una vez asignados. Cada entrada apunta al(los) fic | ID | Fichero:línea | Hallazgo | Severidad | Estado | Notas | |----|---------------|----------|-----------|--------|-------| | CONV-01 | varios | Parámetros de audio fuera de `Defaults`/`config.yaml` | Importante | DONE (parcial) | Els que encaixen (`VOLUME_STEP`, `FREQUENCY`, `CROSSFADE_MS`, `FORMAT`, `CHANNELS`) ja són a `Defaults::Audio` (HC-01, HC-02). La resta són tuning intern del motor i resten a `jail_audio.hpp` per preservar-ne la independència | -| CONV-02 | `jail_audio.hpp` | Engine no es clase (namespace + globals), viola OOP | Importante | DEFERRED | Cubierto por COUP-01 | -| CONV-03 | `jail_audio.hpp` | No hay callback "music ended"; polling desde `update()` | Menor | DEFERRED | Requiere COUP-01 | +| CONV-02 | `jail_audio.hpp` | Engine no es clase (namespace + globals), viola OOP | Importante | DONE | Resolt amb COUP-01: `Ja::Engine` és classe amb ctor/dtor RAII, membres privats i API explícita | +| CONV-03 | `jail_audio.hpp` | No hay callback "music ended"; polling desde `update()` | Menor | DONE | `Ja::Engine::setOnMusicEnded(std::function)` disparat des de `updateCurrentMusic` després de `stopMusic()`. Exposat via `Audio::setOnMusicEnded`. Commit 5 del refactor |