# CTI Windows TAPI - Guida Semplice

Questa guida serve a fare il primo passo sulla macchina Windows dove hai installato il driver Panasonic TAPI/TSP.

L'obiettivo non e ancora fare il bridge completo.

L'obiettivo adesso e capire tre cose, con calma:

1. il driver TAPI e davvero visibile a Windows
2. quali linee o indirizzi espone
3. la macchina Windows riesce a parlare con NetGescon con il token corretto

## File da usare

- `scripts/ops/windows/get-netgescon-panasonic-tapi-info.ps1`
- `scripts/ops/windows/test-netgescon-panasonic-api.ps1`

## Passo 1: apri PowerShell come amministratore

Sulla macchina Windows:

1. apri il menu Start
2. cerca `PowerShell`
3. fai click destro
4. scegli `Esegui come amministratore`

## Passo 2: spostati nella cartella dove hai copiato il repo

Esempio:

```powershell
cd C:\netgescon\netgescon-day0
```

## Passo 3: permetti l'esecuzione dello script nella sessione corrente

```powershell
Set-ExecutionPolicy -Scope Process Bypass
```

Questo non cambia in modo permanente la politica della macchina. Vale solo per quella finestra.

## Passo 4: estrai le informazioni dal driver TAPI

Prima prova senza filtro:

```powershell
.\scripts\ops\windows\get-netgescon-panasonic-tapi-info.ps1 -IncludeMembers
```

Se il risultato e troppo lungo, prova filtrando gli interni che ci interessano:

```powershell
.\scripts\ops\windows\get-netgescon-panasonic-tapi-info.ps1 -Filter 205
.\scripts\ops\windows\get-netgescon-panasonic-tapi-info.ps1 -Filter 206
.\scripts\ops\windows\get-netgescon-panasonic-tapi-info.ps1 -Filter 201
```

Lo script crea un file JSON, di default:

```text
netgescon-tapi-info.json
```

### Cosa mi devi mandare dopo questo passo

Mandami una di queste cose:

1. le righe del riepilogo rapido finali
2. il contenuto del file JSON
3. uno screenshot del riepilogo se ti viene piu comodo

## Passo 5: verifica che Windows riesca a parlare con NetGescon

Sostituisci:

- `https://staging.netgescon.it` con il tuo URL reale, se diverso
- `IL_TUO_TOKEN` con il token CTI reale

E lancia:

```powershell
.\scripts\ops\windows\test-netgescon-panasonic-api.ps1 -BaseUrl "https://staging.netgescon.it" -Token "IL_TUO_TOKEN" -Extension "205"
```

### Cosa deve succedere nel watcher

Devi vedere tre blocchi:

1. `Lookup rubrica`
2. `Simulazione incoming`
3. `Simulazione call-ended`

Se dentro i JSON compare `ok: true`, allora:

- il token e giusto
- la macchina Windows raggiunge NetGescon
- gli endpoint sono pronti

## Se qualcosa fallisce

### Caso A: errore creando `TAPI.TAPI`

Significa che il provider COM TAPI non e registrato bene o il driver Panasonic non e installato correttamente.

### Caso B: trovi TAPI ma zero indirizzi

Significa che il driver c'e, ma non sta esponendo ancora linee utilizzabili.

In quel caso di solito bisogna controllare:

1. configurazione del TSP Panasonic
2. `Check Location`
3. IP PBX e porta `33333`
4. licenza CTI lato centralino

### Caso C: gli script API falliscono con `401 Unauthorized`

Significa che il token non coincide con quello configurato in NetGescon.

Importante: il watcher Windows non e bloccato. Continua a ricevere eventi TAPI, ma gli invii `incoming` e `call-ended` verso staging vengono rifiutati, quindi su NetGescon non compare nulla.

### Caso D: gli script API falliscono con timeout o errore TLS

Significa che la macchina Windows non riesce a raggiungere NetGescon su HTTPS.

## Cosa faremo subito dopo

Quando mi mandi l'output del primo script, io ti guidero al passo successivo:

1. capire quali linee TAPI sono quelle giuste
2. decidere se monitorare `201`, `205`, `206`
3. scrivere il probe successivo che ascolta davvero gli eventi chiamata

Il primo obiettivo adesso non e fare tutto.

Il primo obiettivo e vedere nero su bianco che il driver Panasonic espone qualcosa che possiamo usare.

## Risultato atteso corretto

Se nel JSON o nel riepilogo trovi linee simili a queste, significa che il provider Panasonic sta esponendo davvero gli interni giusti:

- `EXT00201`
- `EXT00205`
- `EXT00206`
- `GRP00601`
- `GRP00603`

Se li vedi, il passo successivo e ascoltare gli eventi di chiamata reali.

## Passo 6: watcher TAPI via polling

Lo script VBScript di event sink puo fallire con questo errore:

```text
WScript.CreateObject: Impossibile connettere l'oggetto.
```

Questo non significa che Panasonic TAPI non funziona.

Significa solo che quell'oggetto COM non si lascia agganciare bene da VBScript come sorgente eventi.

Per questo motivo il passo consigliato diventa il polling PowerShell, che e piu robusto.

Usa questi script Windows:

- `scripts/ops/windows/inspect-netgescon-panasonic-address.ps1`
- `scripts/ops/windows/poll-netgescon-panasonic-active-calls.ps1`

### 6.1 Ispezione veloce dell'interno 205

```powershell
.\scripts\ops\windows\inspect-netgescon-panasonic-address.ps1 -Extension 205 -OutFile .\inspect-205.json
```

Se vuoi fare anche 201 e 206:

```powershell
.\scripts\ops\windows\inspect-netgescon-panasonic-address.ps1 -Extension 201 -OutFile .\inspect-201.json
.\scripts\ops\windows\inspect-netgescon-panasonic-address.ps1 -Extension 206 -OutFile .\inspect-206.json
```

### 6.2 Polling chiamate attive

Lancialo cosi da PowerShell:

```powershell
.\scripts\ops\windows\poll-netgescon-panasonic-active-calls.ps1 -Extensions "201,205,206" -LogFile .\netgescon-tapi-poll.log
```

Se vuoi includere anche i gruppi studio:

```powershell
.\scripts\ops\windows\poll-netgescon-panasonic-active-calls.ps1 -Extensions "201,205,206,601,603" -LogFile .\netgescon-tapi-poll.log
```

### Cosa deve succedere nel polling

All'avvio lo script deve stampare righe tipo:

```text
ADDRESS READY name=EXT00205 dial=205 provider=CTSP0000.tsp
```

Poi resta in ascolto e interroga periodicamente il provider.

Adesso fai una chiamata reale verso uno degli interni monitorati.

Se tutto va bene compariranno righe tipo:

```text
CALL address=EXT00205 dial=205 idx=1 state=... caller=... called=... connected=...
```

e lo stesso contenuto verra scritto nel file:

```text
.\netgescon-tapi-poll.log
```

### Cosa mi devi mandare dopo il polling

Mi serve una di queste due cose:

1. l'output console del polling
2. il contenuto del file `netgescon-tapi-poll.log`

## Nota importante sui valori `State=0` e `TerminalCount=0`

Nel dump iniziale non e un problema grave.

Quel dump fotografava solo l'elenco indirizzi esposto dal provider.

Il test decisivo adesso non e il numero di terminali, ma se il polling vede comparire una chiamata attiva durante una chiamata vera.

## Passo 7: ascolto eventi COM reali

Se il polling resta fermo su `IDLE` anche dopo le chiamate, ma `RegisterCallNotifications` e tutto verde, allora il passo corretto e ascoltare gli eventi COM veri del provider.

Usa questo script:

- `scripts/ops/windows/watch-netgescon-panasonic-tapi-com-events.ps1`

Lancialo cosi:

```powershell
.\scripts\ops\windows\watch-netgescon-panasonic-tapi-com-events.ps1 -Extensions "201,205,206" -LogFile .\netgescon-tapi-com-events.log
```

### Cosa deve succedere nell'ispezione interop

All'avvio vedrai le righe di setup e `REGISTER OK`.

Poi, quando fai una chiamata reale verso `201`, `205` o `206`, devono comparire righe tipo:

```text
COM EVENT type=...
```

Se compaiono, abbiamo finalmente il canale giusto da usare per il bridge verso NetGescon.

## Passo 8: ispezione interop .NET di TAPI 3

L'output che hai raccolto conferma che l'interop espone davvero i due canali evento utili:

- `ITTAPIEventNotification`
- `ITTAPIDispatchEventNotification`

In pratica non dobbiamo piu indovinare il nome dell'evento COM. Dobbiamo agganciarci ai wrapper .NET generati dall'interop.

## Passo 9: watcher .NET basato sui wrapper evento interop

Usa questo script:

- `scripts/ops/windows/watch-netgescon-panasonic-tapi-dotnet-events.ps1`

Lancialo cosi:

```powershell
.\scripts\ops\windows\watch-netgescon-panasonic-tapi-dotnet-events.ps1 -Extensions "201-208,601,603,0001,0003" -LogFile .\netgescon-tapi-dotnet-events.log
```

Il watcher ora accetta anche range di interni, quindi `201-208` equivale a `201,202,203,204,205,206,207,208`.

Se vuoi una prova limitata di 90 secondi:

```powershell
.\scripts\ops\windows\watch-netgescon-panasonic-tapi-dotnet-events.ps1 -Extensions "201-208,601,603,0001,0003" -LogFile .\netgescon-tapi-dotnet-events.log -Seconds 90
```

### Prova bridge dry-run

Quando il watcher eventi e stabile, puoi chiedergli di costruire anche i payload candidati per gli endpoint Laravel senza ancora inviarli.

Comando:

```powershell
.\scripts\ops\windows\watch-netgescon-panasonic-tapi-dotnet-events.ps1 -Extensions "201-208,601,603,0001,0003" -LogFile .\netgescon-tapi-dotnet-events.log -Seconds 90 -BridgeMode dry-run
```

In questa modalita vedrai righe aggiuntive tipo:

```text
BRIDGE DRYRUN endpoint=incoming payload=...
BRIDGE MARK answered event_id=...
BRIDGE DRYRUN endpoint=call-ended payload=...
```

Se il provider non espone ancora il numero esterno della chiamata, vedrai invece:

```text
BRIDGE SKIP endpoint=incoming reason=phone-missing ...
```

Questo non e un errore del watcher. Significa solo che per quella chiamata Panasonic non ha ancora reso disponibile il numero nel punto del flusso che stiamo leggendo.

Attenzione: `-BridgeMode dry-run` non invia nulla a NetGescon. Se su staging i Post-it restano fermi, la prima cosa da controllare e che il watcher Windows non sia partito in dry-run ma in `live`.

### Cosa deve succedere nel watcher .NET

All'avvio vedrai prima:

- `REGISTER OK` sugli interni monitorati
- `DOTNET CHECK` per i wrapper provati
- `DOTNET SUBSCRIBE OK` oppure `DOTNET SUBSCRIBE KO`

Se almeno uno dei wrapper va in `DOTNET SUBSCRIBE OK`, fai subito una chiamata reale su `201`, `205` o `206`.

Quando l'aggancio funziona, nel log devono comparire righe tipo:

```text
DOTNET EVENT source=... eventType=... payloadType=... state=... cause=... address=... dial=...
```

### Cosa mi devi mandare dal watcher .NET

Mandami il contenuto completo di:

- console PowerShell
- oppure file `netgescon-tapi-dotnet-events.log`

Con quel log possiamo decidere subito una delle due strade:

1. il watcher PowerShell/.NET basta e lo estendiamo per chiamare gli endpoint NetGescon
2. i wrapper non si agganciano e allora scriviamo il sink COM compilato con la firma esatta appena confermata

Se il dry-run produce payload corretti, il passo successivo e passare a:

```powershell
-BridgeMode live -BaseUrl "https://staging.netgescon.it" -Token "IL_TUO_TOKEN"
```

## Passo 10: tenere il bridge sempre acceso su Windows

Per evitare che tutto dipenda da una finestra PowerShell aperta, usa questi script:

- `scripts/ops/windows/start-netgescon-panasonic-live.ps1`
- `scripts/ops/windows/install-netgescon-panasonic-live-task.ps1`

### 10.1 Avvio live manuale

Prima imposta il token come variabile ambiente persistente Windows.

In PowerShell amministratore:

```powershell
Set-ExecutionPolicy -Scope Process Bypass -Force
[Environment]::SetEnvironmentVariable("NETGESCON_CTI_SHARED_TOKEN", "IL_TUO_TOKEN_REALE", "Machine")
```

Poi avvia il bridge live:

```powershell
cd C:\netgescon\netgescon-day0
.\scripts\ops\windows\start-netgescon-panasonic-live.ps1 -BaseUrl "https://staging.netgescon.it" -Extensions "201-208,601,603,0001,0003" -LogFile "C:\ProgramData\NetGescon\Logs\netgescon-tapi-dotnet-events-live.log"
```

### 10.2 Installazione come task automatico all'avvio macchina con account SYSTEM

In PowerShell amministratore:

```powershell
Set-ExecutionPolicy -Scope Process Bypass -Force
[Environment]::SetEnvironmentVariable("NETGESCON_CTI_SHARED_TOKEN", "IL_TUO_TOKEN_REALE", "Machine")
cd C:\netgescon\netgescon-day0
.\scripts\ops\windows\install-netgescon-panasonic-live-task.ps1 -Mode system-startup -BaseUrl "https://staging.netgescon.it" -Extensions "201-208,601,603,0001,0003" -LogFile "C:\ProgramData\NetGescon\Logs\netgescon-tapi-dotnet-events-live.log"
```

Nota importante: quando il task gira come `SYSTEM`, i drive mappati come `S:` in genere non esistono. Usa quindi percorsi locali tipo `C:\ProgramData\...` oppure percorsi UNC.

### 10.3 Installazione come task al logon utente corrente

Se non hai privilegi amministrativi, usa la modalita legata all'utente corrente.

```powershell
Set-ExecutionPolicy -Scope Process Bypass -Force
[Environment]::SetEnvironmentVariable("NETGESCON_CTI_SHARED_TOKEN", "IL_TUO_TOKEN_REALE", "User")
cd C:\netgescon\netgescon-day0
.\scripts\ops\windows\install-netgescon-panasonic-live-task.ps1 -Mode current-user-logon -BaseUrl "https://staging.netgescon.it" -Extensions "201-208,601,603,0001,0003" -LogFile "$env:LOCALAPPDATA\NetGescon\Logs\netgescon-tapi-dotnet-events-live.log" -InteropOutputDir "$env:LOCALAPPDATA\NetGescon\tapi-interop"
```

### 10.4 Sequenza rapida in 6 comandi per il tuo caso `S:\`

Se il repo e davvero montato in `S:\` e non hai privilegi amministrativi, usa questi 6 comandi esatti nell'ordine indicato.

```powershell
Set-ExecutionPolicy -Scope Process Bypass -Force
cd S:\
[Environment]::SetEnvironmentVariable("NETGESCON_CTI_SHARED_TOKEN", "IL_TUO_TOKEN_REALE", "User")
.\scripts\ops\windows\install-netgescon-panasonic-live-task.ps1 -Mode current-user-logon -BaseUrl "https://staging.netgescon.it" -Extensions "201-208,601,603,0001,0003" -LogFile "$env:LOCALAPPDATA\NetGescon\Logs\netgescon-tapi-dotnet-events-live.log" -InteropOutputDir "$env:LOCALAPPDATA\NetGescon\tapi-interop"
Start-ScheduledTask -TaskName "NetGescon Panasonic Live Bridge"
Get-ScheduledTaskInfo -TaskName "NetGescon Panasonic Live Bridge"
```

Se il quarto comando fallisce, non lanciare il quinto: significa che il task non e stato creato.

Il file di log non esiste finche il task non parte davvero almeno una volta. Dopo che il sesto comando mostra che il task esiste, puoi seguire il log con:

```powershell
Get-Content "$env:LOCALAPPDATA\NetGescon\Logs\netgescon-tapi-dotnet-events-live.log" -Tail 100 -Wait
```

## Passo 11: messa in esercizio su staging

Quando il watcher e avviato e i log mostrano `DOTNET SUBSCRIBE OK`, la checklist minima per entrare davvero in live e questa.

### 11.1 Verifica token prima di fare chiamate reali

Sul PC Windows che gira il bridge:

```powershell
[Environment]::GetEnvironmentVariable("NETGESCON_CTI_SHARED_TOKEN", "User")
```

Se leggi il placeholder o una stringa vecchia, riscrivilo con quello reale e poi reinstalla/rilancia il task.

### 11.2 Smoke test HTTP verso staging

```powershell
.\scripts\ops\windows\test-netgescon-panasonic-api.ps1 -BaseUrl "https://staging.netgescon.it" -Token "IL_TUO_TOKEN_REALE" -Extension "205"
```

Se questo test non restituisce `ok: true`, non fare ancora chiamate reali: il problema e a livello token o connettivita HTTP.

### 11.3 Come leggere il log del bridge live

Nel log live, questi casi significano cose diverse:

- `BRIDGE LIVE OK endpoint=incoming`: la chiamata e stata accettata da staging
- `BRIDGE LIVE OK endpoint=call-ended`: la chiusura chiamata e stata accettata da staging
- `BRIDGE LIVE KO endpoint=incoming error=(401) Non autorizzato`: token errato sul bridge Windows oppure token diverso su staging
- `BRIDGE IGNORE endpoint=... category=EXT mode=group-first`: evento visto ma non scelto come sorgente autorevole per il bridge

### 11.4 Dove vedere le nuove chiamate su staging

Quando l'invio live va a buon fine, le nuove chiamate Panasonic compaiono in due punti applicativi:

1. `Strumenti -> Post-it Gestione`
	- legge i record `chiamate_post_it`
	- e il punto principale per vedere le chiamate create dal bridge
2. flussi tecnici basati su `communication_messages`
	- canale `panasonic_csta`
	- utili per verifica tecnica e correlazione con routing/intercettazione operatore

In aggiunta, il banner operatore mobile usa anche `panasonic_csta`, quindi una chiamata instradata a un interno monitorato puo comparire anche lato operatore senza passare solo da SMDR.

### 11.5 Procedura rapida di ripartenza se staging smette di ricevere chiamate

Sul PC Windows:

```powershell
cd S:\
Stop-ScheduledTask -TaskName "NetGescon Panasonic Live Bridge" -ErrorAction SilentlyContinue
.\scripts\ops\windows\install-netgescon-panasonic-live-task.ps1 -Mode current-user-logon -BaseUrl "https://staging.netgescon.it" -Extensions "201-208,601,603,0001,0003" -LogFile "$env:LOCALAPPDATA\NetGescon\Logs\netgescon-tapi-dotnet-events-live.log" -InteropOutputDir "$env:LOCALAPPDATA\NetGescon\tapi-interop"
Start-ScheduledTask -TaskName "NetGescon Panasonic Live Bridge"
Get-Content "$env:LOCALAPPDATA\NetGescon\Logs\netgescon-tapi-dotnet-events-live.log" -Tail 100 -Wait
```

Se dopo una chiamata reale appare `401`, fermati subito: il bridge sta funzionando ma staging sta rifiutando il token.

Avvio immediato del task:

```powershell
Start-ScheduledTask -TaskName "NetGescon Panasonic Live Bridge"
```

Stato task:

```powershell
Get-ScheduledTask -TaskName "NetGescon Panasonic Live Bridge"
Get-ScheduledTaskInfo -TaskName "NetGescon Panasonic Live Bridge"
```

Stop task:

```powershell
Stop-ScheduledTask -TaskName "NetGescon Panasonic Live Bridge"
```

Rimozione task:

```powershell
Unregister-ScheduledTask -TaskName "NetGescon Panasonic Live Bridge" -Confirm:$false
```

ma solo dopo aver validato bene il contenuto dei payload dry-run.

Se il provider Panasonic accetta `RegisterCallNotifications`, ma:

- il polling resta sempre `IDLE`
- `CallHubs` resta `none`
- `Register-ObjectEvent` dice che non esiste l'evento `Event`

allora PowerShell in late binding non basta piu.

In quel caso il passo corretto e generare l'interop .NET della type library `tapi3.dll` e vedere i nomi reali di tipi, delegate ed eventi da usare in un watcher compilato.

Usa questo script:

- `scripts/ops/windows/inspect-netgescon-tapi-interop.ps1`

Lancialo cosi:

```powershell
.\scripts\ops\windows\inspect-netgescon-tapi-interop.ps1
```

### Cosa deve succedere

Lo script:

1. usa le classi .NET gia presenti in Windows
2. genera un assembly .NET da `C:\Windows\System32\tapi3.dll`
3. elenca i tipi che contengono `Event`
4. elenca i tipi legati a `ITTAPI`

### Cosa mi devi mandare

Mandami l'output completo dello script.

Con quello preparo il watcher compilato con i nomi esatti esposti dall'interop reale della tua macchina Windows.