AR-VMS-Seaman/VMS_Sailor_v2_Parte_05_Mobile.md

# VMS-Sailor · Brief para Claude Code · Parte 5 de 6

## VMS-Sailor Mobile (app nativa iOS y Android)

> Esta parte detalla la app móvil. Asume que ya leíste Partes 1-4.

---

## 1. Propósito

App nativa que permite al **Admin del buque** (owner), técnicos y tripulación autorizados ver y operar el VMS desde tablets y smartphones. Diseñada para uso a bordo, no remoto desde tierra.

### Casos de uso principales

- **Owner en cubierta o camarote**: revisar estado general del buque sin ir al puente
- **Owner durante navegación**: ajustar trim desde el flybridge mientras conduce
- **Técnico durante mantenimiento**: ver lecturas en tiempo real estando físicamente en sala de máquinas
- **Tripulación**: recibir notificaciones de alarmas en el teléfono cuando no están en estación fija
- **Owner en muelle**: revisar estado del buque amarrado desde su casa cercana (siempre que esté en WiFi local)

---

## 2. Restricciones críticas de seguridad

### Solo WiFi local del buque

La app **JAMÁS** se expone a internet. El servidor del Runtime escucha solo en la subred WiFi local (192.168.x.x típicamente). La app móvil descubre el servidor por mDNS/Bonjour o IP fija configurada al enrolar.

**Implicaciones:**
- No se requiere certificado SSL público (TLS interno con CA propia)
- Sin cuentas en la nube, sin datos saliendo del buque
- Si la WiFi del buque está apagada, la app no funciona
- Si el dueño quiere acceso remoto desde tierra → debe pasar por VPN del armador (instalación separada, no parte de este proyecto)

### Autenticación TOTP + biométrico

Doble factor obligatorio:
1. **Algo que sabes**: usuario + password
2. **Algo que tienes**: el dispositivo enrolado (TOTP de 30s)
3. **Algo que eres**: biométrico del dispositivo (FaceID, TouchID, huella Android) — antes de revelar el TOTP

### Enrollment controlado

Solo el Admin del buque (owner) puede autorizar nuevos dispositivos. Proceso:
1. Owner en su estación principal del Runtime → "Gestión de dispositivos móviles"
2. Crea nuevo dispositivo: nombre (ej: "iPhone Carlos"), usuario asociado
3. Sistema genera QR con secreto TOTP único
4. Usuario escanea con la app VMS-Sailor Mobile en su dispositivo
5. App pide configurar biométrico local
6. Dispositivo queda enrolado
7. Owner puede revocar en cualquier momento desde la estación

### Permissives respetados igual que estación fija

Los permissives se evalúan en el SERVIDOR, no en el cliente. Móvil y desktop son solo UIs. Si un permissive bloquea una acción, bloquea desde cualquier UI. No hay forma de saltarse permissives desde móvil.

---

## 3. Arquitectura técnica

### Stack tecnológico

| Componente | Tecnología |
|---|---|
| Framework | Flutter 3.x |
| Lenguaje | Dart 3.x |
| State management | Riverpod 2.x |
| Comunicación | WebSocket (web_socket_channel) + HTTP/REST (dio) |
| TOTP | `otp` package |
| Biométrico | `local_auth` |
| Almacenamiento seguro | `flutter_secure_storage` (Keychain iOS, Keystore Android) |
| Gráficas | `fl_chart` |
| SVG (mímicos) | `flutter_svg` |
| Notificaciones locales | `flutter_local_notifications` |
| Cliente HTTPS con CA propia | configurar en `dio` con `IOHttpClientAdapter` |

### Por qué Flutter (no React Native ni nativo puro)

- **Performance gráfico superior**: motor Skia/Impeller propio. Para mímicos con muchas lecturas refrescándose en tiempo real, esto es decisivo. RN sufre con UIs densas y actualizaciones rápidas
- **Un solo código para iOS + Android + posible escritorio**: a futuro se puede tener "VMS-Sailor Mobile Lite" como app de escritorio liviana con el mismo código
- **Coherencia visual**: misma UI en iPhone, iPad y Android. Flutter renderiza por sí mismo, no usa widgets nativos
- **Dart bien diseñado**: tipado fuerte, async/await nativo, null safety. Reduce bugs runtime en sistema crítico
- **Soporte enterprise**: Google + BMW + Toyota lo usan en industria

### Estructura de carpetas Flutter

```
mobile/
├── pubspec.yaml
├── README.md
├── android/
├── ios/
│
└── lib/
    ├── main.dart
    ├── app.dart                       # Material/Cupertino app
    │
    ├── core/
    │   ├── models/
    │   │   ├── tag.dart
    │   │   ├── alarm.dart
    │   │   ├── system.dart
    │   │   ├── permissive.dart
    │   │   └── user.dart
    │   ├── api/
    │   │   ├── ws_client.dart         # Cliente WebSocket
    │   │   ├── rest_client.dart       # Cliente REST
    │   │   └── auth_client.dart       # Auth + TOTP
    │   ├── auth/
    │   │   ├── totp_manager.dart
    │   │   ├── biometric_gate.dart    # local_auth wrapper
    │   │   └── secure_storage.dart    # secretos en Keychain/Keystore
    │   ├── discovery/
    │   │   └── mdns_finder.dart       # Encuentra servidor en WiFi
    │   └── theme/
    │       ├── light_theme.dart
    │       └── dark_theme.dart
    │
    ├── features/
    │   ├── enrollment/
    │   │   ├── qr_scanner.dart        # Escanea QR del Runtime
    │   │   └── enrollment_flow.dart
    │   ├── login/
    │   │   ├── login_screen.dart
    │   │   └── biometric_unlock.dart
    │   ├── overview/
    │   │   └── overview_screen.dart   # Dashboard inicial
    │   ├── systems/
    │   │   ├── system_list.dart       # Lista de sistemas activos
    │   │   ├── mimic_view.dart        # Mímico de un sistema
    │   │   └── tag_detail.dart
    │   ├── alarms/
    │   │   ├── alarm_list.dart
    │   │   ├── alarm_detail.dart
    │   │   └── alarm_notifications.dart
    │   ├── trends/
    │   │   └── trends_screen.dart     # Gráficas con fl_chart
    │   ├── trim/
    │   │   ├── trim_control_screen.dart  # Panel destacado de trim
    │   │   ├── trim_slider_widget.dart
    │   │   ├── stability_indicator.dart  # Roll/pitch en vivo
    │   │   └── emergency_reset_button.dart
    │   ├── logbook/
    │   │   ├── logbook_view.dart
    │   │   └── manual_entry.dart
    │   └── settings/
    │       └── settings_screen.dart
    │
    └── widgets/                       # Widgets reutilizables
        ├── tag_card.dart
        ├── alarm_badge.dart
        ├── gauge_widget.dart
        ├── lamp_indicator.dart
        ├── bar_graph.dart
        └── permissive_status.dart
```

---

## 4. Pantallas principales

### Login

- Detecta si hay servidor VMS-Sailor en la WiFi local (mDNS)
- Si no, pide IP manual
- Login con usuario + password
- Pide biométrico para revelar TOTP
- Verifica TOTP contra servidor
- Si OK, guarda token de sesión

### Overview (dashboard inicial)

Lo primero que ve el usuario después de loguear:
- Nombre del buque + estado general (verde/amarillo/rojo)
- Resumen: motores estado, gensets estado, tanques niveles, alarmas activas
- Roll/pitch actual (gauge visual)
- Acceso rápido a sistemas más usados

### Lista de sistemas (menú lateral o pestaña)

Generado dinámicamente desde el `.vmspack` activo. Solo muestra los sistemas que el integrador marcó en el wizard.

### Vista de mímico por sistema

Carga el SVG del mímico empaquetado en el `.vmspack`. Se renderiza con `flutter_svg`. Los elementos del mímico se actualizan con WebSocket en tiempo real:
- Cambios de color por estado
- Valores numéricos sobre los símbolos
- Tap en un elemento → muestra detalle del tag

### Panel de Trim y Maniobra (destacado)

Esta es la pantalla estrella para el owner. UI optimizada para uso con una mano mientras conduce:
- Sliders verticales grandes para cada actuador de trim (touch-friendly)
- Indicador horizontal de roll en vivo (animado)
- Indicador de pitch
- Botón grande rojo de "RESET EMERGENCIA"
- Toggle de "Modo Manual del Owner" (requiere biométrico para activar)
- Indicación clara del envelope activo (línea visual donde el sistema empieza a bloquear)

### Panel de alarmas

- Lista cronológica con color por prioridad
- Notificaciones push locales cuando entra alarma crítica (incluso con la app en background)
- Botón ACK por alarma (respeta permisos del rol)
- Filtros y búsqueda

### Trends

- Gráficas con fl_chart
- Múltiples tags simultáneos
- Zoom y pan
- Selector de rango temporal (1h, 24h, 7d)

### Log Book

- Lista de entradas cronológica
- Filtros por categoría (eventos motor, alarmas, manuales)
- Botón "Agregar entrada manual" (Técnico/Admin)

### Settings

- Cambiar password
- Cerrar sesión / desautorizar dispositivo
- Configuración de notificaciones
- Idioma
- Modo oscuro

---

## 5. Permisos por rol en la app

Mismos roles que en estación desktop, pero con restricciones adicionales por ser móvil:

| Acción | Operador | Técnico | Admin (owner) |
|---|---|---|---|
| Ver mímicos | ✓ | ✓ | ✓ |
| Ver alarmas | ✓ | ✓ | ✓ |
| ACK alarmas Info/Low | ✓ | ✓ | ✓ |
| ACK alarmas High/Emergency | ✗ | ✓ | ✓ |
| Ver trends | ✓ | ✓ | ✓ |
| Ver logbook | ✓ | ✓ | ✓ |
| Agregar entrada manual logbook | ✗ | ✓ | ✓ |
| Control de luces, A/A (no críticos) | ✗ | ✓ | ✓ |
| Control trim | ✗ | ✓ | ✓ |
| Activar modo manual del owner | ✗ | ✗ | ✓ |
| Reset emergencia | ✓ | ✓ | ✓ |
| Arrancar motores / thrusters | ✗ | ✗ | ✗ (solo estación fija) |
| Override de permissives WARNING | ✗ | ✗ | ✓ |
| Gestión de usuarios y dispositivos | ✗ | ✗ | ✓ |

**Regla de oro**: acciones de propulsión y maquinaria principal (arranque/parada motores, thrusters, parada de emergencia general) **solo desde estación fija puente o máquinas**, nunca desde móvil. Por seguridad.

---

## 6. Notificaciones push locales

Sin servicios externos (no Firebase, no APNs externos). La app mantiene WebSocket persistente con el Runtime. Cuando recibe evento crítico:
- Si la app está en foreground → notificación dentro de la app
- Si la app está en background → notificación local del sistema operativo (`flutter_local_notifications`)
- Sonido distintivo por prioridad
- Tocar la notificación → abre la app en el evento específico

Limitación: si el usuario fuerza-cierra la app, no llegan notificaciones. Documentar al owner.

---

## 7. Modo offline degradado

Si la conexión WebSocket cae:
- Banner persistente "Sin conexión al VMS"
- Sigue mostrando los últimos valores conocidos (con badge "desactualizado X minutos")
- Permite ver histórico cached
- No permite enviar comandos
- Intenta reconectar automáticamente cada 10s

---

## 8. Empaquetado y distribución

### iOS

- Build con Xcode
- Distribución vía TestFlight para clientes específicos (no App Store público inicialmente)
- Requiere cuenta Apple Developer ($99/año) — gasto del integrador (Álvaro)
- Cada armador recibe invitación TestFlight con el binario

### Android

- Build APK firmado
- Distribución directa por enlace (no Google Play inicialmente)
- O via Play Store con cuenta de desarrollador ($25 una vez) si se decide más adelante

**Por qué no stores públicas inicialmente:**
- Las stores requieren accesibilidad pública (cualquiera puede instalar)
- Eso introduce riesgo de seguridad (cualquiera podría intentar usar la app contra cualquier IP)
- Distribución privada (TestFlight + APK firmado) garantiza que solo clientes autorizados tienen acceso

---

## 9. Sprints relacionados con Mobile

- **Sprint 11**: VMS-Sailor Mobile completo
  - Setup Flutter project
  - Enrollment flow + QR scan
  - Login + TOTP + biométrico
  - WebSocket client + REST client
  - Pantallas: Overview, Lista sistemas, Mímico simple
  - Panel alarmas con notificaciones locales
  - Panel Trim (caso destacado)
  - Permisos por rol
  - Build iOS + Android

- **Sprint posterior**: refinamientos, trends avanzados, modo offline robusto, logbook completo

---

## 10. Consideraciones de UI/UX móvil

### Touch targets

Mínimo 44×44 pt en iOS, 48×48 dp en Android. Los sliders de trim deben ser grandes para uso con guantes o manos mojadas.

### Lecturabilidad bajo sol

- Modo de pantalla "outdoor" con contraste aumentado
- Texto grande por defecto (configurable)
- Evitar colores pastel para datos críticos

### Orientación

- Tablets: soportar landscape y portrait
- Smartphones: portrait principalmente; landscape para mímicos complejos y trends

### Accesibilidad

- Soporte de screen readers (VoiceOver iOS, TalkBack Android)
- Tamaño de fuente respetando configuración del sistema
- Contraste WCAG AA mínimo

---

## 11. Privacidad y datos

La app NO recolecta:
- Datos de telemetría de uso
- Analítica
- Crash reports a servidores externos

La app guarda LOCALMENTE en almacenamiento seguro del dispositivo:
- Secreto TOTP (cifrado en Keychain/Keystore)
- Token de sesión
- Últimos valores cached (para modo offline)
- Configuración del usuario

Si el dispositivo se restablece o se borra la app → todo se pierde. El owner debe enrolar nuevamente.

---

**Fin de Parte 5 de 6.** Próxima: Parte 6 — Plan de Sprints completo.