# VTE Watch — Riepilogo completo conversazione

**Data:** 19–20 agosto 2026  
**Progetto:** Mini Program Zepp OS per Amazfit Balance 2 + VTENEXT  
**Server VTE produzione:** `https://vte.mypantarei.net`  
**Cartella progetto (server):** `/var/www/html/vte-watch-zepp/`  
**Zip per Windows:** `/var/www/html/vte-watch-windows.zip`

---

## 1. Obiettivo iniziale

Creare un’app per **Amazfit Balance 2** collegata a **VTE (VTENEXT)** che mostri sul polso:

- Attività calendario (prossimi 7 giorni)
- Ticket HelpDesk (vista **Open Tickets**)
- Notifiche ModNotifications (non lette)

**Scelte confermate:**

| Area | Decisione |
|------|-----------|
| Interattività | **Sola lettura** (liste, badge, dettaglio breve) |
| Utenti | **Tutta l’azienda** (multi-utente) |
| Distribuzione | **Zepp App Store** (obiettivo finale) |
| Auth | OAuth2 PKCE (futuro) + **Touch login / access key** (MVP) |
| MFA | Oggi no, ma **OTP in Settings** quando attivo |
| Telefono | Android + iOS |
| Lingua UI | **IT + EN** |
| Widget quadrante | **Sì** (SecondaryWidget con 3 contatori) |
| Setup URL | Manuale + JSON/QR setup |
| Branding | **VTE Watch** |
| Dev | Linux server; preview/install su **Windows** |

---

## 2. Architettura tecnica

```
Amazfit Balance 2 (Device App + Widget)
        ↕ BLE
Telefono Zepp App (Side Service + Settings App)
        ↕ HTTPS
https://vte.mypantarei.net/restapi/v1/vtews/touch.*
```

**Importante:** l’orologio **non** fa HTTP diretto. Le chiamate VTE passano dal **Side Service** (telefono) o, per il test login, **direttamente dalle Settings** (rete telefono).

### API VTE usate

| Funzione | Endpoint | Note |
|----------|----------|------|
| Login | `touch.login` | Body: `{"request":{"username":"...","password":"..."}}` |
| Auth successive | Header `Authorization: Basic base64(user:accesskey)` | Come Wilson |
| Task calendario | `touch.get_todos` | |
| Eventi | `touch.get_list` | `module: "Events"` |
| Ticket | `touch.get_list` | `module: "HelpDesk"`, `viewname: "Open Tickets"` |
| Notifiche | `touch.get_notifications` | `seen: false` |

**Login info (parametro flat, non wrapped):**

```bash
curl -X POST 'https://vte.mypantarei.net/restapi/v1/vtews/touch.login_info' \
  -H 'Content-Type: application/json' \
  -d '{"username":"admin"}'
```

---

## 3. Struttura progetto

```
vte-watch-zepp/
├── app.json                 # minVersion 4.0, Balance 2
├── app.js
├── app-side/
│   ├── index.js             # Side Service
│   └── vte-api.js           # sync dashboard, cache
├── setting/
│   └── index.js             # login, URL, OTP, test connessione
├── page/
│   ├── home/                # badge + navigazione
│   ├── calendar/
│   ├── tickets/
│   └── notifications/
├── secondary-widget/        # contatori sul quadrante
├── utils/
│   ├── constants.js
│   └── vte-client.js        # login/fetch condiviso
├── assets/gt.r/             # icone 480×480
├── docs/
│   ├── oauth-vte-setup.md
│   ├── privacy-policy.md
│   └── CONVERSAZIONE-COMPLETA.md  ← questo file
├── dist/*.zab               # dopo zeus build
└── README.md
```

**Nessuna modifica al core VTE** (`vte2472`).

---

## 4. Implementazione completata

### Fasi fatte sul server Linux

1. Scaffold progetto Zepp OS (API 4.0, target round 480px)
2. Side Service con `syncDashboard()` (4 chiamate Touch parallele)
3. Settings App IT/EN con test login
4. Device App: home + 3 liste read-only
5. SecondaryWidget badge
6. Documentazione OAuth + privacy (bozza)
7. Fix test login Settings (feedback UI + login diretto via `fetch`)

### Build

```bash
cd /var/www/html/vte-watch-zepp
npm install
zeus build
# Output: dist/109872001-VTE_Watch-1.0.0-*.zab
```

### Zip per Windows (senza node_modules)

```bash
cd /var/www/html/vte-watch-zepp
zip -r /var/www/html/vte-watch-windows.zip . -x "node_modules/*" -x "dist/*"
```

---

## 5. Setup ambiente Windows (Gabriele)

### Prerequisiti

- Node.js LTS + `npm install -g @zeppos/zeus-cli`
- Zepp App con **Developer Mode** (7 tap su logo in About)
- Amazfit Balance 2 associato

### PowerShell vs cmd

I comandi `cd /d` e `copy /Y` sono per **cmd**. In PowerShell:

```powershell
Set-Location "C:\Users\Gabriele\vte-watch-zepp"
Copy-Item -Force "origine.zab" "destinazione\"
```

Se PowerShell blocca npm:

```powershell
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
```

### Zeus login (account developer Zepp)

```cmd
zeus login
```

- Si apre il browser → login Zepp
- Callback su `http://localhost:PORT/login/callback?apptoken=...`
- **Terminale deve restare aperto** fino a `Login success`
- Browser e `zeus login` devono essere **sullo stesso PC**

**Errore frequente:** `ERR_CONNECTION_REFUSED` su localhost → Zeus non in ascolto (terminale chiuso, o login lanciato su Linux ma browser su Windows).

**Riparo manuale token:** file `C:\Users\Gabriele\.zepp\.zeus`:

```env
____user_zepp_com__token=apptoken_da_url
____user_zepp_com__userid=userid_da_url
____user_zepp_com__cname=cname_da_url
```

### Installazione su orologio

```cmd
cd /d C:\Users\Gabriele\vte-watch-zepp
npm install
zeus preview
```

- Scegli **Amazfit Balance 2**
- Scan QR con Zepp App → Developer Mode → Scan

**Nota:** `zeus preview` **ricompila** il progetto: servono `app.js`, `package.json`, cartelle sorgente — **non basta solo il `.zab`**.

### Struttura cartella Windows richiesta

```
C:\Users\Gabriele\vte-watch-zepp\
  app.json
  app.js
  package.json
  app-side\
  setting\
  page\
  utils\
  assets\
  ...
```

Verifica:

```cmd
dir app.js
dir package.json
```

---

## 6. Configurazione VTE (dopo installazione)

1. Zepp App → **VTE Watch → Settings**
2. URL: `https://vte.mypantarei.net`
3. Username + password VTE
4. **Test connessione / Login**
5. Sull’orologio: apri app → **Sync**

### Payload QR setup (opzionale)

```json
{
  "vte_url": "https://vte.mypantarei.net",
  "client_id": "OPZIONALE_OAUTH_CLIENT_ID"
}
```

Incollare in «JSON setup / QR» nelle Settings.

---

## 7. Problemi incontrati e soluzioni

### 7.1 `zeus dev` — connect simulator failed (7650)

**Causa:** simulatore Zepp OS è app **desktop Windows/Mac**, non gira su server Linux headless.

**Soluzione:** `zeus dev` solo su PC con simulatore installato; oppure `zeus preview` su orologio reale.

---

### 7.2 `zeus` non riconosciuto / npm ENOENT

**Causa:** Zeus non installato; PowerShell execution policy; cartella senza `package.json`.

**Soluzione:** `npm install -g @zeppos/zeus-cli`; usare cmd o `RemoteSigned`; copiare progetto completo.

---

### 7.3 `You must execute in project's root directory`

**Causa:** manca `app.json` nella cartella corrente.

**Soluzione:** estrarre zip correttamente (file alla radice, non sottocartella annidata).

---

### 7.4 `The app.js file must be included in the project`

**Causa:** solo `.zab` copiato, senza sorgenti.

**Soluzione:** copiare intero progetto da server o `vte-watch-windows.zip`.

---

### 7.5 Login Zepp — localhost callback refused (45701, 38397)

**Causa:** server callback Zeus non attivo; URL vecchio; login su macchina diversa dal browser.

**Soluzione:** `zeus login` su Windows, terminale aperto, completare login in una sessione.

---

### 7.6 Test login Settings «non fa niente»

**Causa:** nessun feedback UI; Side Service non attivo; login delegato solo al Side Service.

**Fix applicato (v1.0.1+):**
- Messaggio immediato «Connessione in corso…»
- Login **diretto** dalle Settings via `fetch` (rete telefono)
- Fallback Side Service con polling
- Messaggio «Apri VTE Watch sull’orologio» se Side Service in attesa

**Dopo fix:** rifare `zeus preview` e scan QR.

---

## 8. OAuth VTE (fase store)

Guida dettagliata: [docs/oauth-vte-setup.md](oauth-vte-setup.md)

1. VTE Admin → Settings → **External Applications**
2. Nome: `VTE Watch`, Authorization Code + PKCE
3. Scope: `rest.all`, `touch.all`
4. Endpoint:
   - `https://vte.mypantarei.net/oauth2/v2.0/auth.php`
   - `https://vte.mypantarei.net/oauth2/v2.0/token.php`

---

## 9. Limitazioni MVP

- **Sola lettura** — nessuna modifica record da orologio
- **Niente push real-time** — sync manuale o all’apertura (Wilson fa push sul telefono)
- Widget mostra **ultimo sync** (cache), non dati live
- OAuth PKCE struttura predisposta; login attivo via Touch/Basic
- Privacy policy e account developer Zepp **da completare** per store

---

## 10. Comandi cheat sheet

### Server Linux

```bash
cd /var/www/html/vte-watch-zepp
npm install
zeus build
zeus status

# Smoke test VTE
curl -sS -X POST 'https://vte.mypantarei.net/restapi/v1/vtews/touch.login_info' \
  -H 'Content-Type: application/json' -d '{"username":"TUO_USER"}'
```

### Windows (cmd)

```cmd
npm install -g @zeppos/zeus-cli
zeus login
cd /d C:\Users\Gabriele\vte-watch-zepp
npm install
zeus preview
zeus status
```

---

## 11. Criteri di successo MVP

- [x] Progetto isolato in `vte-watch-zepp/`
- [x] Build `.zab` OK
- [x] Scan QR installazione su Balance 2
- [ ] Test login Settings → «Connessione riuscita»
- [ ] Sync orologio con dati reali
- [ ] Widget quadrante con contatori
- [ ] Account developer Zepp + privacy policy per store

---

## 12. Prossimi passi suggeriti

1. Aggiornare app su orologio dopo fix login (`zeus preview` + scan)
2. Verificare credenziali VTE da browser mobile
3. Test Sync su home / ticket / notifiche
4. Registrare External Application OAuth in VTE
5. Account developer Zepp + privacy policy per submission store
6. (Opzionale) Modulo SDK `VTEWatch` con endpoint `watch.get_dashboard` aggregato

---

## 13. Link utili

- [Zepp OS Simulator](https://docs.zepp.com/docs/guides/quick-start/simulator-dev/)
- [Zepp Developer](https://developer.zepp.com/os/home)
- [Zeus CLI](https://docs.zepp.com/docs/guides/tools/cli/)
- [VTE External Applications](https://usermanual.vtenext.com/books/user-manual-vtenext-2502/page/1510-external-applications)
- Manuale skill workspace: `.cursor/skills/vte-developers/reference-integrazioni-rest-oauth.md`

---

## 14. Cronologia chat (sintesi turni)

1. **Richiesta iniziale:** app Amazfit Balance 2 + VTE (calendario, ticket, notifiche)
2. **Domande contesto:** read-only; moduli calendar/ticket/notifications; store aziendale; OAuth+MFA; widget; URL `vte.mypantarei.net`
3. **Piano approvato** → implementazione in `/var/www/html/vte-watch-zepp/`
4. **Problemi Windows:** PowerShell vs cmd; zip con sottocartella; solo zab senza sorgenti
5. **QR preview OK** → test login non rispondeva
6. **Fix login Settings** + documentazione troubleshooting
7. **Richiesta MD completo** → questo file

---

*Generato per portare in locale la documentazione del progetto VTE Watch. Per dettagli tecnici aggiornati vedere anche [README.md](../README.md).*