255 lines
3.5 KiB
Plaintext
255 lines
3.5 KiB
Plaintext
1. Contesto del progetto (READ FIRST)
|
|
|
|
Stiamo costruendo un sistema di controllo remoto composto da:
|
|
|
|
Windows Client (Electron)
|
|
⇅ WebSocket (control-plane)
|
|
VPS Signaling Server (Node.js / TS)
|
|
⇅ WebSocket
|
|
Android Tablet Agent (Kotlin)
|
|
|
|
|
|
⚠️ IMPORTANTE
|
|
|
|
Il VPS NON trasporta video/audio/input.
|
|
|
|
Il VPS serve SOLO per:
|
|
|
|
autenticazione
|
|
|
|
signaling
|
|
|
|
presence (online/offline)
|
|
|
|
autorizzazione connessioni
|
|
|
|
In fasi successive, il traffico media passerà via WebRTC P2P/TURN (NON in Fase 1).
|
|
|
|
2. Stack tecnologico (decisioni definitive)
|
|
Linguaggi
|
|
|
|
TypeScript ovunque possibile
|
|
|
|
server: Node.js + TypeScript
|
|
|
|
windows: Electron + TypeScript
|
|
|
|
shared: TypeScript
|
|
|
|
Android: Kotlin (fuori scope TS)
|
|
|
|
Scelte chiave (NON cambiare senza chiedere)
|
|
|
|
Client Windows: Electron
|
|
|
|
Protocollo: WebSocket + JSON tipizzato
|
|
|
|
Condivisione tipi: pacchetto shared/protocol
|
|
|
|
Stato: in-memory per Fase 1 (DB arriverà dopo)
|
|
|
|
Auth Fase 1: seed user + pairingKey (MVP)
|
|
|
|
3. Modalità operativa tablet (definitiva)
|
|
|
|
Tablet Android:
|
|
|
|
sempre in ascolto
|
|
|
|
ForegroundService sempre attivo
|
|
|
|
MediaProjection verrà avviata in Fase 2
|
|
|
|
Connessioni in ingresso:
|
|
|
|
SEMPRE con accettazione manuale
|
|
|
|
notifica Android con “Accetta / Rifiuta”
|
|
|
|
⚠️ Non implementare:
|
|
|
|
auto-accept
|
|
|
|
connessioni silenziose
|
|
|
|
bypass dei permessi Android
|
|
|
|
4. Fase attuale del progetto
|
|
✅ Fase 1 — Control-plane ONLY
|
|
|
|
In questa fase:
|
|
|
|
❌ NIENTE WebRTC
|
|
|
|
❌ NIENTE MediaProjection
|
|
|
|
❌ NIENTE streaming
|
|
|
|
❌ NIENTE input remoto
|
|
|
|
✔️ SOLO:
|
|
|
|
WebSocket server
|
|
|
|
login client
|
|
|
|
register agent
|
|
|
|
device list
|
|
|
|
connect_request
|
|
|
|
accept / deny / expired
|
|
|
|
Se una PR introduce WebRTC o video → È SBAGLIATA
|
|
|
|
5. Protocollo di comunicazione
|
|
|
|
Tutti i messaggi:
|
|
|
|
{
|
|
"v": 1,
|
|
"type": "...",
|
|
"requestId": "...",
|
|
"...": "..."
|
|
}
|
|
|
|
|
|
I tipi sono definiti in:
|
|
|
|
/shared/protocol
|
|
|
|
|
|
⚠️ Regole:
|
|
|
|
Non inventare campi fuori dai tipi condivisi
|
|
|
|
Non usare stringhe “magiche”
|
|
|
|
Se serve un nuovo messaggio → aggiornare shared/protocol
|
|
|
|
6. Regole di sviluppo per Codex
|
|
Come lavorare
|
|
|
|
Ogni task = UNA PR
|
|
|
|
PR piccole, focalizzate
|
|
|
|
Niente “mega commit”
|
|
|
|
Ogni PR DEVE includere:
|
|
|
|
Codice funzionante
|
|
|
|
Logging minimo (no spam)
|
|
|
|
Error handling (no crash)
|
|
|
|
Checklist “come testare manualmente”
|
|
|
|
NON fare:
|
|
|
|
refactor non richiesti
|
|
|
|
miglioramenti “creativi”
|
|
|
|
cambiare stack
|
|
|
|
anticipare fasi future
|
|
|
|
7. Stato & persistenza (Fase 1)
|
|
|
|
Tutto in memoria
|
|
|
|
Restart server = stato perso (OK per MVP)
|
|
|
|
Nessun database obbligatorio ora
|
|
|
|
Strutture tipiche:
|
|
|
|
devicesById
|
|
|
|
sessionsById
|
|
|
|
clientSessionsByWs
|
|
|
|
8. Sicurezza (livello attuale)
|
|
|
|
Fase 1 = MVP controllato
|
|
|
|
Seed user + password in env
|
|
|
|
PairingKey in env
|
|
|
|
TLS solo in VPS (non locale)
|
|
|
|
⚠️ Non implementare:
|
|
|
|
hashing avanzato
|
|
|
|
JWT
|
|
|
|
refresh token
|
|
|
|
OAuth
|
|
|
|
Arriveranno in Fase 3.
|
|
|
|
9. Error handling (obbligatorio)
|
|
|
|
Su errore:
|
|
|
|
{
|
|
"v": 1,
|
|
"type": "error",
|
|
"requestId": "...",
|
|
"code": "UNAUTHORIZED | BAD_REQUEST | NOT_FOUND | CONFLICT | DEVICE_OFFLINE",
|
|
"message": "human readable"
|
|
}
|
|
|
|
|
|
Mai crashare il server
|
|
|
|
Mai lasciare una promise non gestita
|
|
|
|
10. Naming e stile
|
|
|
|
camelCase per JSON
|
|
|
|
kebab-case per file
|
|
|
|
TypeScript strict
|
|
|
|
No any salvo motivazione
|
|
|
|
11. Test mindset
|
|
|
|
Ogni feature deve essere:
|
|
|
|
testabile via CLI o WS
|
|
|
|
osservabile via log
|
|
|
|
verificabile senza UI (se possibile)
|
|
|
|
Se non è testabile → probabilmente è sbagliata.
|
|
|
|
12. Frase guida del progetto
|
|
|
|
“Il VPS coordina, non guarda.
|
|
Il tablet decide, non subisce.
|
|
Il client controlla, non buca.”
|
|
|
|
13. In caso di dubbio
|
|
|
|
Se una decisione:
|
|
|
|
tocca sicurezza
|
|
|
|
cambia protocollo
|
|
|
|
anticipa WebRTC
|
|
|
|
rompe compatibilità
|
|
|
|
👉 FERMATI e chiedi prima. |