Route HTTP principali

Questa pagina costituisce il contratto operativo tra playroll-ui e playroll-cpp per l'API core su localhost.

Il renderer non deve chiamare queste route direttamente. playroll-ui chiama il core dal processo main di Electron attraverso handler IPC tipizzati, e le richieste verso il core devono includere gli header di session-auth UI/core, a meno che non sia esplicitamente abilitato un bypass per i test locali.

Stato dell'inventario delle route

L'handoff della Paper UI non introduce attualmente una nuova route HTTP su localhost. playroll-ui continua a comunicare con playroll-cpp attraverso la stessa superficie IPC del main process e gli stessi percorsi dell'API core.

Il lavoro di integrazione è quindi lavoro contrattuale: forma del payload, codici di motivo stabili, semantica del ciclo di vita, autenticazione delle route, garanzie di ordinamento e comportamento del read-model della UI.

Lavoro contrattuale che conta

Quando l'inventario delle route non cambia, il lavoro rischioso non consiste nell'aggiungere un URL. Consiste nell'assicurarsi che entrambe le parti concordino sul significato di ciascuna route.

Area	Requisito contrattuale
Identità della sessione di registrazione	Una singola sessione di registrazione possiede gli artefatti MP4, CSV degli input e JSON dei metadati. La cronologia UI raggruppa per recording_session / recording_session_id, ricorrendo al legacy session_id solo quando necessario.
Motivi terminali	Le righe di cronologia fallite o non conteggiate devono riportare un motivo stabile (reason, error_message, o un campo normalizzato equivalente).
Ciclo di vita del gioco selezionato	Il gioco selezionato è l'unico gioco il cui processo/finestra dovrebbe essere monitorato per la registrazione. Cambiare gioco rilascia il lavoro di monitoraggio precedente.
Stato del recorder	/api/recorder/status deve descrivere il ciclo di vita del gioco selezionato in modo sufficientemente chiaro da consentire all'island di transitare tra gli stati idle, ready, recording, paused e blocked.
Avvisi sull'ambiente	Gli avvisi di /api/environment/check necessitano di codici stabili affinché la UI possa sopprimere o raggruppare casi specifici in modo deterministico.
Hardening di localhost	Tutte le chiamate UI-to-core non di test devono essere rifiutate in assenza degli header di session-auth attesi.
Cronologia degli upload	La cronologia è un vero read model proveniente da core/SQLite in modalità normale; i dati mock sono solo per il dev-preset.

Route consumate dalla UI

Queste sono le route attualmente chiamate dall'IPC del main process di playroll-ui.

Method	Route	Scopo UI	Note contrattuali
GET	/api/status	Fallback/read model generale dello stato core.	Deve includere uno stato nested del recorder sufficiente per il fallback legacy da /api/recorder/status.
GET	/api/recorder/status	Stato corrente di recorder/island/sessione.	Deve esporre il gioco selezionato, lo stato di detection, la fase recording/paused, i timing e l'eventuale errore UI terminale.
POST	/api/record/start	Avvia la registrazione per il gioco selezionato.	Deve applicare auth, vincoli di gioco selezionato, gate di avvio e restituire motivi di blocco stabili.
POST	/api/record/stop	Ferma la registrazione corrente.	Deve restituire successo o un rifiuto stabile come "not recording".
POST	/api/record/pause	Mette in pausa la registrazione corrente.	Deve restituire motivi di rifiuto stabili quando la pausa non è consentita.
POST	/api/record/resume	Riprende una registrazione in pausa.	Deve restituire motivi di rifiuto stabili quando la ripresa non è consentita.
POST	/api/overlay/toggle	Attiva/disattiva l'overlay del recorder.	Deve restituire lo stato di visibilità più un'eventuale direttiva di errore UI.
GET	/api/uploader/status	Stato dell'uploader e file in attesa.	Deve includere lo stato paused/uploading, il file corrente, l'avanzamento, il conteggio dei pendenti e l'ultimo errore quando disponibile.
GET	/api/uploader/history	Righe di attività/cronologia.	Deve preservare separatamente l'id di riga e l'identità della sessione. recording_session raggruppa le righe MP4 + CSV + JSON; session_id è legacy/compatibile internamente. Le righe fallite necessitano di reason/error.
POST	/api/uploader/action	Comando dell'uploader come scan/pause/resume.	Deve restituire l'azione accettata e un motivo di fallimento stabile.
GET	/api/environment/check	Controlli ambientali bloccanti/di avviso.	I codici di warning/blocker devono essere stabili; la UI può sopprimere codici noti come multi-GPU.
GET	/api/environment/adapter	Snapshot dell'adapter hardware (vendor, nome GPU, driver NVENC).	Usata dallo step system-check dell'onboarding per mostrare un messaggio preciso sulla versione del driver.
GET	/api/hw/snapshot	Snapshot HW canonico — system (CPU/RAM/OS) e gpus[] (vendor/device/driver/VRAM).	Stesso payload che il core scrive in ogni _meta.json::hardware di ogni registrazione. Consumato dal flusso di bug report in-app; uno schema unico tra metadata delle registrazioni, bug report e inventario device_hw_snapshots.
GET	/api/settings	Lettura delle impostazioni core.	La risposta deve tollerare campi mancanti ma essere stabile per le impostazioni salvate.
PUT	/api/settings	Aggiorna le impostazioni core.	Deve fare il merge senza eliminare impostazioni non correlate.
GET	/api/sound-cues	Lettura dei binding dei sound cue.	Lo snapshot deve essere deterministico e includere lo stato enabled per ciascun cue.
PUT	/api/sound-cues	Salva i binding dei sound cue.	Deve validare gli id dei cue e i percorsi dei file.
POST	/api/sound-cues/preview	Anteprima di un sound cue.	Non deve persistere stato.
GET	/api/encoders	Lettura degli encoder disponibili.	Deve includere l'encoder selezionato e i motivi di indisponibilità.
POST	/api/encoders/select	Seleziona l'encoder.	Deve rifiutare gli encoder non disponibili con un motivo stabile.
GET	/api/monitor/targets	Lettura dei target di monitoraggio gioco/processo.	Deve riflettere i giochi installati noti al core e i vincoli del gioco selezionato.
PUT	/api/monitor/targets	Sostituisci/sincronizza i target di monitoraggio.	Deve essere indipendente dalla macchina ed evitare percorsi locali hardcoded.
POST	/api/monitor/rescan	Forza il rescan dei target di monitoraggio.	Deve essere idempotente e sicuro mentre la UI è aperta.
PUT	/api/monitor/selection	Imposta il gioco selezionato.	Cambiare la selezione deve rilasciare i monitor per il gioco precedentemente selezionato.
POST	/api/settings-enforcement/apply	Applica l'enforcement delle impostazioni per gioco.	Deve essere confinato all'id gioco/store selezionato.
POST	/api/settings-enforcement/restore	Ripristina le impostazioni dopo una sessione.	Deve essere sicuro da chiamare anche se nulla è stato applicato.
GET	/api/settings-enforcement/status	Lettura dello stato di enforcement, opzionalmente per gioco.	Supporta query tramite game_store_id.
PUT	/api/settings-enforcement/sync-targets	Sincronizza i target del settings-enforcement.	Deve restare allineato con i target del monitor e con il gioco selezionato.
POST	/api/debug/toast	Ciclo di notifiche per dev/debug.	Route di debug; deve restare un comportamento non rivolto al giocatore.
POST	/api/debug/overlay/cycle	Ciclo dell'overlay per dev/debug.	Route di debug; deve restare un comportamento non rivolto al giocatore.

Inventario completo delle route del core

Queste sono le route esposte da playroll-cpp sul branch di integrazione.

Runtime e documentazione

Method	Route	Note
GET	/health	Probe di health.
GET	/ping	Probe di liveness leggero.
POST	/heartbeat	Heartbeat UI/core.
POST	/shutdown	Comando di shutdown del core.
GET	/api/docs	Pagina di documentazione dell'API core integrata.

Auth

Method	Route	Note
POST	/auth/token	Fornisce il token di auth al core.
POST	/api/auth	Route API correlata all'auth esposta dal core.

Recorder e overlay

Method	Route	Note
GET	/api/status	Envelope di stato generale.
GET	/api/recorder/status	Stato specifico del recorder.
POST	/api/record/start	Avvia la registrazione.
POST	/api/record/stop	Ferma la registrazione.
POST	/api/record/pause	Mette in pausa la registrazione.
POST	/api/record/resume	Riprende la registrazione.
POST	/api/overlay/toggle	Attiva/disattiva la visibilità dell'overlay.

Libreria giochi, target di monitoraggio e selezione

Method	Route	Note
GET	/api/games	Elenco dei giochi del core.
POST	/api/games/refresh	Aggiorna i giochi noti.
POST	/api/games/rescan	Rescansione dei giochi.
GET	/api/monitor/targets	Lettura dei target di monitoraggio.
PUT	/api/monitor/targets	Sostituisce i target di monitoraggio.
POST	/api/monitor/rescan	Rescansione dei target di monitoraggio.
PUT	/api/monitor/selection	Imposta il gioco selezionato per il monitoraggio processo/finestra.

Impostazioni ed enforcement

Method	Route	Note
GET	/api/settings	Lettura delle impostazioni.
PUT	/api/settings	Aggiornamento delle impostazioni.
GET	/api/settings-enforcement/status	Lettura dello stato di enforcement.
POST	/api/settings-enforcement/apply	Applica le impostazioni enforced.
POST	/api/settings-enforcement/restore	Ripristina le impostazioni enforced.
PUT	/api/settings-enforcement/sync-targets	Sincronizza i target di enforcement.
GET	/api/settings/audio-cues	Route legacy delle impostazioni degli audio cue.
PUT	/api/settings/audio-cues	Route legacy di aggiornamento delle impostazioni degli audio cue.
GET	/api/sound-cues	Lettura dello snapshot dei sound cue.
PUT	/api/sound-cues	Aggiornamento dello snapshot dei sound cue.
POST	/api/sound-cues/preview	Anteprima di un sound cue.
GET	/api/hotkeys	Lettura delle impostazioni degli hotkey.
PUT	/api/hotkeys	Aggiornamento delle impostazioni degli hotkey.
GET	/api/preprocessor/config	Lettura della configurazione del preprocessor.
PUT	/api/preprocessor/config	Aggiornamento della configurazione del preprocessor.

Read model di uploader e validazione

Method	Route	Note
GET	/api/uploader/status	Lettura dello stato dell'uploader.
GET	/api/uploader/history	Lettura delle righe recenti di cronologia caricate/fallite.
POST	/api/uploader/action	Controllo dell'uploader.
GET	/api/uploader/config	Lettura della configurazione dell'uploader.
PUT	/api/uploader/config	Aggiornamento della configurazione dell'uploader.
GET	/api/environment/check	Lettura dei blocker e degli avvisi ambientali.
GET	/api/environment/adapter	Lettura dello snapshot dell'adapter HW primario (vendor + versioni driver).
GET	/api/hw/snapshot	Lettura dello snapshot HW canonico (stessa forma di _meta.json::hardware).