netgescon-day0/docs/ai/restart/CTI-PANASONIC-NS1000-SETUP.md

# CTI Panasonic NS1000 - Setup operativo

Obiettivo: intercettare chiamate dal centralino Panasonic NS1000 (CSTA porta 33333) e creare/chiudere automaticamente Post-it in NetGescon con filtro rubrica.

Nota architetturale:

- non serve un hardware dedicato aggiuntivo se il PBX espone gia CSTA in rete;
- il bridge/adapter puo essere eseguito internamente su Linux come servizio applicativo;
- il flusso consigliato resta `Panasonic NS1000 -> adapter CSTA Linux -> API HTTPS NetGescon`.

## Prerequisiti verificati

- Connessione TCP PBX CSTA: `192.168.0.101:33333` raggiungibile.
- Modello centralino: Panasonic NS1000.

## 1) Configurazione applicazione NetGescon

Aggiungi in `.env` del nodo applicativo:

```env
NETGESCON_CTI_SHARED_TOKEN=<TOKEN_LUNGO_RANDOM>
NETGESCON_CTI_PBX_HOST=192.168.0.101
NETGESCON_CTI_PBX_PORT=33333
NETGESCON_CTI_BRIDGE_TIMEOUT=10
NETGESCON_CTI_BRIDGE_READ_BYTES=2048
NETGESCON_CTI_BRIDGE_RECONNECT_DELAY=5
NETGESCON_CTI_BRIDGE_MAX_IDLE_TIMEOUTS=30
NETGESCON_CTI_BRIDGE_LOG_FILE=storage/logs/cti-panasonic-raw.ndjson
```

Poi:

```bash
cd /home/michele/netgescon/netgescon-day0
php artisan optimize:clear
php artisan config:clear
php artisan route:clear
```

Staging reale (confermato):

- path applicazione: `/var/www/netgescon`
- web server: `nginx`
- porta pubblica: `80`
- URL staging tipico: `http://<IP_SERVER_200>/`

## 2) Endpoint disponibili

- `POST /api/v1/cti/panasonic/incoming`
  - crea Post-it chiamata in `chiamate_post_it`
  - fa match automatico numero -> `rubrica_universale`
  - scrive anche `communication_messages` con `channel=panasonic_csta`, `target_extension`, `assigned_user_id`
- `POST /api/v1/cti/panasonic/call-ended`
  - chiude automaticamente il Post-it aperto (match su `event_id`, fallback su numero)
  - salva `esito`, `durata_secondi`, `chiusa_il`
  - chiude anche il record `communication_messages` CSTA corrispondente
- `GET /api/v1/cti/panasonic/lookup?phone=...`
  - solo lookup rubrica (match yes/no)
- `GET /api/v1/cti/panasonic/click-to-call/pending?extension=101`
  - coda outbound per adapter/middleware CSTA
- `POST /api/v1/cti/panasonic/click-to-call/{id}/claim`
  - lock logico della richiesta da parte dell'adapter
- `POST /api/v1/cti/panasonic/click-to-call/{id}/status`
  - esito esecuzione (`accepted`, `completed`, `failed`, `cancelled`)

Autenticazione: header `X-CTI-Token: <TOKEN>`.

## 3) Comando server web prova (porta 8000, solo sviluppo)

```bash
cd /home/michele/netgescon/netgescon-day0
php artisan serve --host=0.0.0.0 --port=8000
```

Nota: in staging non usare `artisan serve`; usare nginx su porta `80` con root applicativa `/var/www/netgescon`.

## 4) Comando minimo per vedere solo dati HTTP in arrivo

Se vuoi solo vedere cosa arriva, senza script:

```bash
ncat -kl 8099
```

Se `ncat` non e disponibile:

```bash
while true; do nc -l -p 8099; echo; echo "-----"; done
```

Poi configura il centralino (o il tool di test) verso `http://<IP_SERVER_200>:8099`.

## 5) Comando minimo per sniffing CSTA grezzo (porta 33333)

Per vedere traffico protocollo CSTA a livello rete direttamente sul server `.200`:

```bash
sudo tcpdump -i any -nn -s0 -A host 192.168.0.101 and port 33333
```

Per dump esadecimale (piu utile se payload non testuale):

```bash
sudo tcpdump -i any -nn -s0 -X host 192.168.0.101 and port 33333
```

Se non vedi nessun pacchetto durante una chiamata:

1. Verifica che il PBX stia davvero parlando con questo server (e non con altro host).
2. Verifica che l'evento chiamata sia abilitato lato centralino (CSTA monitor/notify).
3. Prova senza filtro host per escludere IP errato:

```bash
sudo tcpdump -i any -nn -s0 -A port 33333
```

1. Verifica quale sorgente arriva davvero sulla porta:

```bash
sudo tcpdump -i any -nn "tcp port 33333"
```

1. Verifica che non sia traffico su altra porta (es. CTI middleware):

```bash
sudo tcpdump -i any -nn -s0 -A host 192.168.0.101 and \(port 33333 or port 33334 or port 33335\)
```

1. Verifica che sul server non ci sia un servizio locale che assorbe la sessione senza inoltro HTTP:

```bash
sudo ss -lntp | grep -E ':33333|:8099|:80'
```

## 5-bis) Daemon Linux minimale di cattura CSTA

Avvio manuale:

```bash
cd /home/michele/netgescon/netgescon-day0
bash scripts/ops/netgescon-panasonic-csta-bridge.sh
```

Il daemon:

- apre la socket TCP verso il PBX
- resta in ascolto con riconnessione automatica
- salva i frame grezzi in `storage/logs/cti-panasonic-raw.ndjson`
- stampa dump hex e una resa testuale best-effort

Per installarlo come servizio usare il template:

```text
scripts/systemd/netgescon-panasonic-csta-bridge.service.template
```

## 6) Listener terminale con script (log su file)

Metti questo listener in ascolto e punta il PBX a `http://<IP_SERVER_200>:8099` per vedere esattamente i dati in arrivo.

```bash
cd /home/michele/netgescon/netgescon-day0
bash scripts/ops/netgescon-cti-listener.sh --port 8099
```

## 7) Test rapido terminale (incoming + call-ended)

```bash
cd /home/michele/netgescon/netgescon-day0
bash scripts/ops/netgescon-panasonic-csta-test.sh \
  --pbx-ip 192.168.0.101 \
  --pbx-port 33333 \
  --app-url http://127.0.0.1:8000 \
  --token "<TOKEN_LUNGO_RANDOM>" \
  --phone "+393331112233" \
  --ext "101" \
  --duration 90 \
  --outcome "risposta"
```

## 8) Comandi singoli per simulare chiamate da terminale

Evento incoming (una riga):

```bash
curl -sS -X POST "http://127.0.0.1:8000/api/v1/cti/panasonic/incoming" -H "Content-Type: application/json" -H "X-CTI-Token: <TOKEN_LUNGO_RANDOM>" -d '{"phone":"+393331112233","direction":"inbound","event_type":"Delivered","called_extension":"101","event_id":"evt-001","note":"test incoming"}'
```

Evento call-ended (una riga):

```bash
curl -sS -X POST "http://127.0.0.1:8000/api/v1/cti/panasonic/call-ended" -H "Content-Type: application/json" -H "X-CTI-Token: <TOKEN_LUNGO_RANDOM>" -d '{"phone":"+393331112233","direction":"inbound","event_type":"ConnectionCleared","event_id":"evt-001","outcome":"risposta","duration_seconds":83,"ended_at":"2026-03-11T10:20:00+01:00","note":"test call-ended"}'
```

Lookup rubrica (una riga):

```bash
curl -sS "http://127.0.0.1:8000/api/v1/cti/panasonic/lookup?phone=+393331112233" -H "X-CTI-Token: <TOKEN_LUNGO_RANDOM>"
```

## 9) Esempio comandi da usare lato interfaccia centralino

Se il centralino puo inviare HTTP su evento incoming call, usa:

```bash
curl -sS -X POST "http://<IP_NETGESCON>:8000/api/v1/cti/panasonic/incoming" \
  -H "Content-Type: application/json" \
  -H "X-CTI-Token: <TOKEN_LUNGO_RANDOM>" \
  -d '{
    "phone": "<CALLING_NUMBER>",
    "name": "<CALLER_NAME_OPTIONAL>",
    "direction": "in_arrivo",
    "called_extension": "<EXT>",
    "event_id": "<PBX_EVENT_ID>",
    "note": "evento CSTA NS1000"
  }'
```

Per filtro rubrica (prima del popup interno):

```bash
curl -sS "http://<IP_NETGESCON>:8000/api/v1/cti/panasonic/lookup?phone=<CALLING_NUMBER>" \
  -H "X-CTI-Token: <TOKEN_LUNGO_RANDOM>"
```

Per evento fine chiamata (chiusura automatica Post-it):

```bash
curl -sS -X POST "http://<IP_NETGESCON>:8000/api/v1/cti/panasonic/call-ended" \
  -H "Content-Type: application/json" \
  -H "X-CTI-Token: <TOKEN_LUNGO_RANDOM>" \
  -d '{
    "phone": "<CALLING_NUMBER>",
    "direction": "inbound",
    "event_type": "ConnectionCleared",
    "event_id": "<PBX_EVENT_ID>",
    "outcome": "risposta",
    "duration_seconds": 83,
    "ended_at": "2026-03-11T10:20:00+01:00",
    "note": "evento call-ended NS1000"
  }'
```

## 13) Bridge/adapter CSTA Phase III: prova pratica

Contratto minimo consigliato per un adapter esterno:

1. Sottoscrive gli eventi PBX/CSTA su uno o piu interni.
2. Converte i nomi evento PBX in payload HTTP NetGescon:
   - `Delivered` -> `incoming`
   - `ConnectionCleared` -> `call-ended`
3. Per l'outbound interroga periodicamente `click-to-call/pending`.
4. Esegue claim della richiesta.
5. Invia `MakeCall` o equivalente al PBX verso `source_extension` -> `target_number`.
6. Aggiorna lo stato con `accepted/completed/failed`.

Payload di stato outbound consigliato:

```json
{
  "status": "completed",
  "event_id": "csta-out-001",
  "provider_call_id": "ns1000-call-7788",
  "called_extension": "101",
  "duration_seconds": 64,
  "outcome": "answered"
}
```

## 10) Cosa fa il match numeri

- normalizza il numero (es. `+39`, `0039`, spazi, trattini)
- confronta le ultime 7 cifre con:
  - `telefono_cellulare`
  - `telefono_ufficio`
  - `telefono_casa`
  - `telefono_cellulare_nazionale`

## 11) Dev + staging sulla stessa macchina (.200)

- Sviluppo consigliato: `http://127.0.0.1:8000` (`artisan serve`)
- Staging reale: `http://<IP_SERVER_200>/` su `nginx:80`, app in `/var/www/netgescon`

Comandi esempio:

```bash
# sviluppo
cd /home/michele/netgescon/netgescon-day0
php artisan serve --host=0.0.0.0 --port=8000

# staging (deploy path reale)
cd /var/www/netgescon
php artisan optimize:clear
php artisan migrate --force
sudo systemctl reload nginx
```

Nel PBX configura URL diversi per ambiente, mantenendo stesso payload/token o token distinti.

## 12) Step successivo consigliato

1. Agganciare evento reale CSTA incoming.
2. Agganciare evento call-ended per aggiornare `esito` e durata.
3. Mostrare popup operatore in Filament con scheda rubrica trovata.

## 12-bis) Mappatura studio corrente

- `201`: centralino con segreteria
- `205`: operatore studio
- `206`: amministratore
- `601`: gruppo/modalita giorno
- `603`: gruppo/modalita notte

Questi interni devono essere censiti nella scheda amministratore per consentire al routing applicativo di riconoscere gli alias condivisi del PBX oltre agli interni utente personali.

## 12-ter) Impostazioni PBX da recuperare o configurare

- conferma che la porta CTI/CSTA sia realmente `33333`
- eventuale utente/password o token richiesti per la sessione CSTA
- eventuale payload iniziale di handshake/login richiesto dal PBX
- conferma della licenza o modulo necessario per `MonitorStart` e `MakeCall`
- elenco device/interni da monitorare:
  - `201`
  - `205`
  - `206`
  - `601`
  - `603`
- eventi da ricevere, se configurabili:
  - `Delivered`
  - `Established`
  - `ConnectionCleared`
  - `Failed` o equivalente
- abilitazione del controllo outbound per chiamate originate da `205`

Se il PBX espone solo un feed CTI generico e non una configurazione eventi dettagliata, va comunque bene: il daemon serve proprio a catturare il traffico reale e ricostruire il protocollo effettivo.