AR-VMS-Seaman/VMS_Sailor_v2_Parte_06_Sprints_y_reglas.md

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

Plan de sprints completo, modelo de datos core, reglas de oro

Esta es la última parte. Asume que ya leíste Partes 1-5.

---

1. Ubicación del proyecto

Todo va en D:/Proyectos Software/VMS-Sailor/.

• Si la carpeta no existe, créala.
• Si existe vacía, úsala.
• Si tiene contenido previo, pregúntame antes de tocar nada.
• Git desde el primer commit. Cada sprint termina con commit etiquetado (sprint-0, sprint-1, etc.).

.gitignore debe incluir:

__pycache__/
*.pyc
.venv/
dist/
build/
*.egg-info/
.idea/
.vscode/
logs/
*.vmspack
*.vmsdelta
licenses/local/
mobile/build/
firmware/.pio/
firmware/.vscode/
*.bin
historian.duckdb
secrets/

---

2. Estructura raíz del repositorio

D:/Proyectos Software/VMS-Sailor/
├── README.md
├── LICENSE.txt
├── CHANGELOG.md
├── pyproject.toml
├── requirements.txt
├── requirements-dev.txt
├── .gitignore
│
├── studio_main.py                    # Entry point del Studio
├── runtime_server_main.py            # Entry point del servicio Windows
├── runtime_client_main.py            # Entry point del cliente desktop
│
├── vmssailor/                        # Código Python compartido
│   ├── __init__.py
│   ├── version.py
│   ├── core/                         # Modelo de datos compartido (CRÍTICO)
│   ├── library/                      # Biblioteca curada (solo Studio)
│   ├── studio/                       # App Studio (Parte 2)
│   ├── runtime/                      # App Runtime (Parte 3)
│   ├── shared/                       # Utilidades compartidas
│   └── tests/                        # Tests Python
│
├── firmware/                         # Firmware ESP32 (Parte 4)
│   └── ar_nmea_io_v1/
│
├── mobile/                           # App Flutter (Parte 5)
│   └── lib/
│
├── docs/                             # Documentación técnica
├── installer/                        # WiX MSI scripts
├── tools/                            # Scripts auxiliares
└── projects/                         # Proyectos de buques específicos (git-ignored excepto seed)

---

3. Modelo de datos core (Sprint 0)

Este es el corazón del sistema. Lo construimos en Sprint 0 antes de cualquier UI.

Coordenadas navales

from dataclasses import dataclass

@dataclass(frozen=True)
class ShipCoord:
    """Coordenadas en el marco del buque.

    x_pp : metros desde Perpendicular de Popa (Pp), positivo hacia proa.
    y_cl : metros desde Línea de Crujía (CL), positivo a estribor, negativo a babor.
    z_bl : metros desde Línea Base (BL), positivo hacia arriba.
    """
    x_pp: float
    y_cl: float
    z_bl: float

Entidades principales

Vessel
 └── Deck[]                  Cubiertas con polígono 2D vista planta + altura

Project (instancia de un buque específico para un cliente)
 ├── vessel_ref              referencia a Vessel de biblioteca o importado
 ├── name                    "M/Y Aurora"
 ├── customer
 ├── systems_enabled         List[SystemId]
 ├── equipment               List[Equipment]
 ├── tags                    List[Tag]
 ├── cards                   List[CardInstance]
 └── topology                Topology

Equipment
 ├── id
 ├── model_ref               referencia a EquipmentModel
 ├── tag_prefix              "ME_PORT", "GEN_1"
 ├── location: ShipCoord
 ├── deck_id
 └── system_id

EquipmentModel (en biblioteca)
 ├── id                      "mtu_12v_2000_m96"
 ├── manufacturer            "MTU"
 ├── model_name              "12V 2000 M96"
 ├── category                ENGINE_MAIN | GENSET | PUMP | ...
 ├── specs                   potencia, RPM nominales, peso, dimensiones
 └── default_sensors         List[Sensor]

Sensor
 ├── id
 ├── name                    "Oil Pressure"
 ├── type                    TEMPERATURE | PRESSURE | LEVEL | RPM | VOLTAGE | ...
 ├── unit_si                 "bar", "C", "rpm"
 ├── range_normal            (min, max)
 ├── alarm_low               (value, priority)
 ├── alarm_high              (value, priority)
 └── default_signal_type     RTD_PT100 | 4-20MA | 0-10V | PULSE | ...

Tag (punto I/O concreto)
 ├── id                      autogenerado "ME_PORT.OIL_PRESS"
 ├── description
 ├── value                   float | bool | str
 ├── quality                 GOOD | BAD | UNCERTAIN
 ├── timestamp
 ├── unit_si
 ├── range_normal
 ├── alarms                  List[AlarmConfig]
 ├── controllable            bool
 ├── control_mode            MONITOR | MANUAL | AUTO | FUTURE
 ├── authority_required      BRIDGE | ENGINE | EITHER
 ├── protocol                MODBUS_RTU | MODBUS_TCP | NMEA2000 | J1939
 ├── address                 dirección Modbus o ID CAN
 ├── scaling                 raw → engineering
 └── physical_binding        TagBinding

TagBinding (cómo un tag se mapea a un canal físico)
 ├── card_id
 ├── channel_type            AI | DI | DO | RPM
 ├── channel_number          1-10 (o 1-5 para DI, 1-4 para AI)
 ├── signal_type             4-20MA | 0-10V | RTD_PT100 | RELAY_NO | ...
 ├── scaling                 raw_min, raw_max, eng_min, eng_max
 ├── filter                  NONE | MOVING_AVG | MEDIAN | DEADBAND | RATE_LIMIT
 └── update_rate_ms

CardInstance (una tarjeta AR-NMEA-IO en un proyecto concreto)
 ├── id                      "card_001"
 ├── serial_number           "ARC-2026-00153"
 ├── slot_number             1-16 (dipswitch físico)
 ├── physical_location       "Sala máquinas, panel principal"
 ├── ship_coord              ShipCoord aproximada
 ├── bus_role                MODBUS_SLAVE | MODBUS_MASTER | NMEA2000_NODE | DUAL | BRIDGE
 ├── modbus_address          1-247 si esclava
 ├── bus_segment             "bus_main"
 └── firmware_version

Topology (la red completa del proyecto)
 ├── buses                   List[Bus]
 └── cards                   List[CardInstance]

Bus
 ├── id                      "bus_main"
 ├── protocol                MODBUS_RTU | NMEA2000
 ├── physical_port           "COM3" | "USB-CAN0"
 ├── baud_rate
 ├── parity, stop_bits       (Modbus RTU)
 └── termination

Alarm (instancia activa)
 ├── id
 ├── tag_id
 ├── priority                EMERGENCY | HIGH | LOW | INFO
 ├── state                   ACTIVE | ACK | CLEARED
 ├── timestamp_active
 ├── timestamp_ack
 ├── timestamp_cleared
 ├── acknowledged_by
 └── message

PermissiveRule
 ├── action_id               "START_ME_PORT"
 ├── conditions              List[Condition]
 └── on_fail_message

Condition
 ├── tag_ref
 ├── operator                EQ | NEQ | GT | LT | BETWEEN | IS_TRUE | IS_FALSE
 ├── threshold
 ├── severity                FAIL | WARNING
 └── message_on_fail

Persistencia

• Biblioteca curada: archivos JSON/YAML versionados en git
• Proyecto en Studio: archivo único .vmsproj (SQLite portable)
• Paquete distribuible: .vmspack = ZIP firmado con manifest.json + project.db + mímicos + firmware + assets
• Runtime a bordo: descomprime .vmspack en %PROGRAMDATA%/VMS-Sailor/project/
• Capas: cada capa es un .vmsdelta separado en %PROGRAMDATA%/VMS-Sailor/layers/
• Historian: DuckDB en %PROGRAMDATA%/VMS-Sailor/historian.duckdb
• Auditoría: SQLite append-only en %PROGRAMDATA%/VMS-Sailor/audit.db

---

4. Plan completo de sprints

Sprint 0 — Fundaciones (2-3 semanas)

Objetivo: estructura completa del proyecto + modelo de datos + biblioteca seed mínima.

Entregables:

• Repositorio Git inicializado con la estructura completa (stubs creados)
• pyproject.toml, requirements.txt, .gitignore
• Módulo vmssailor.core completo con tests (cobertura ≥80%)
• Persistencia: serialización/deserialización a .vmsproj
• Biblioteca seed mínima:
  • 2 yates motor (Sunseeker 76, Ferretti 850)
  • 2 motores principales (MTU 12V 2000 M96, Volvo D13 900hp)
  • 1 genset (Northern Lights M65C13)
  • 1 archivo de reglas (yacht_motor_planeo.yaml)
  • systems_catalog.json completo (todos los sistemas de la Parte 1)
• Validador de biblioteca: tools/validate_library.py
• Tests unitarios para core (cobertura ≥80%)
• README con setup
• Pinout inicial del firmware en firmware/ar_nmea_io_v1/src/config/pinout.h (sin firmware funcional aún)

Criterio de aceptación: pytest pasa todo, validate_library.py pasa todo, se puede crear/guardar/leer un Project programáticamente desde script.

Sprint 1 — Studio shell + wizard básico (3-4 semanas)

• QApplication del Studio con ventana principal y menú
• Wizard pasos 1-4 funcional (tipo, plantilla, dimensiones, sistemas)
• Visualización de silueta en QGraphicsView con sistema de coordenadas naval (rejilla en metros desde Pp)
• Sin paso 5-8 aún (mocked)
• Se puede crear proyecto desde wizard y guardarlo como .vmsproj

Sprint 2 — Wizard completo + editor de equipos (3-4 semanas)

• Pasos 5-8 del wizard: motor de reglas YAML, propuesta de equipos, refinamiento manual con drag-and-drop, paso 7 de topología
• Editor de equipos: CRUD, vista planta, vista lista
• Más buques en biblioteca: 5-7 yates motor + 2 pesqueros + 1 patrullero
• Más equipos en biblioteca: 10+ motores, 6+ gensets, bombas básicas

Sprint 3 — Editor de mímicos + tags + alarmas (3-4 semanas)

• Editor visual de mímicos por sistema (QGraphicsView con símbolos arrastrables)
• Editor de tags: tabla con filtros, edición de direcciones, escalado, control_mode
• Editor de alarmas: límites, prioridades, histéresis, mensajes
• Símbolos básicos: motor, bomba, válvula, tanque, sensor, indicador, línea

Sprint 4 — Runtime servidor base (4-5 semanas)

• Servicio Windows operativo (pywin32) arrancando al boot
• Driver Modbus TCP funcional (pymodbus)
• Driver Modbus RTU funcional
• tag_store en memoria con pub/sub
• Historian básico DuckDB con retención configurable
• Alarm engine con evaluación de límites, prioridades, ack
• API REST/WebSocket básica
• Simulador del Studio que inyecta valores en servidor de pruebas

Sprint 5 — NMEA 2000 + Log Book básico (3-4 semanas)

• Driver NMEA 2000 (CAN) suscribiendo a PGNs configurados
• Log Book básico:
  • Auto-detección arranque/parada motores
  • Snapshots periódicos cada 15 min
  • Registro de alarmas con ack
  • Entradas manuales
  • Firma digital inmutable
• Cliente desktop básico (login + overview + lista de sistemas)

Sprint 6 — Cliente desktop completo (3-4 semanas)

• Renderizado completo de mímicos desde .vmspack
• Panel de alarmas viviente con ack
• Trends básicos (gráficas tiempo real con fl_chart Python equivalente: pyqtgraph)
• Login con tres perfiles
• Permisos por rol
• Vista de logbook
• Vista de soporte y auditoría (Admin solo)

Sprint 7 — Empaquetador + activación + MSI (3 semanas)

• package_builder genera .vmspack desde proyecto del Studio
• delta_builder genera .vmsdelta
• hwid_binder liga paquete a HWID destino
• Activación online inicial del Runtime
• WiX scripts para generar instalador MSI Windows con servicio
• Activación del Studio (protegerlo a mi PC)

Sprint 8 — Permissive + Authority + Stability (3-4 semanas)

• Permissive engine completo con todas las pre-condiciones
• Editor de permissives en Studio
• Authority manager: transferencia bilateral puente↔máquinas
• Override de emergencia (E-stop)
• Stability monitor con los 3 niveles + envelope + modo manual owner
• UI de autoridad y stability en clientes desktop

Sprint 9 — Layer Config Engine (3 semanas)

• Carga de capas en orden al boot
• Aplicación de deltas firmados con verificación criptográfica
• Snapshots automáticos antes de aplicar
• Rollback granular accesible al owner
• Schema validation entre versiones
• UI de gestión de actualizaciones en cliente desktop (orden de trabajo + disponibilidad)

Sprint 10 — Telemetría + VPN + auditoría (2-3 semanas)

• Telemetría de salud transparente (visible al owner, pausable)
• Soporte WireGuard externo (cliente VPN en Runtime)
• Endpoints administrativos solo desde IP del túnel
• Auditoría completa de sesiones VPN
• Vista de "Soporte y Auditoría" en cliente

Sprint 11 — VMS-Sailor Mobile (Flutter) (4-5 semanas)

• Setup proyecto Flutter
• Enrollment flow con QR
• Login + TOTP + biométrico
• Cliente WebSocket + REST
• Pantallas: Overview, Lista sistemas, Mímico, Alarmas con notificaciones
• Panel Trim y Maniobra destacado
• Build iOS + Android

Sprint 12 — Firmware ESP32 base (4 semanas)

• Setup PlatformIO o ESP-IDF
• Modbus RTU esclava funcional
• Discovery broadcast + config push desde VMS
• Lectura de 5 DI + 4 AI con oversampling
• Comando de 10 DO
• Lectura de RPM
• Filtros locales (moving average, median, deadband)
• Tests con simulador y banco de pruebas

Sprint 13 — Firmware NMEA 2000 + J1939 (3 semanas)

• Stack NMEA 2000 funcional
• Publicación de PGNs estándar (127488, 127489, 127505, 127508)
• Listener J1939 para motores que hablan ese protocolo
• Modo dual (Modbus + NMEA 2000 simultáneo)

Sprint 14 — OTA + permissives locales + alarmas locales (3 semanas)

• Cliente OTA seguro con verificación de firma
• Rollback automático si firmware nuevo falla
• Permissives locales críticos (E-stop) ejecutándose en la tarjeta
• Alarmas locales con umbrales
• Health reporter cada 60s

Sprint 15 — Pruebas integradas + hardening (3 semanas)

• Pruebas de integración VMS + tarjetas reales
• Pruebas de stress (alta carga de tags, alarmas masivas)
• Pruebas de fallo (cable cortado, tarjeta sin energía, bus colgado)
• Watchdog y recovery automático
• Documentación de operador y mantenimiento

Sprint 16+ — Refinamientos y extensiones

• Log Book regulatorio completo (MARPOL, IMO)
• Integración Seakeeper, Quick MC², CMC stabilizers
• Cotizador de expansiones
• Generador paramétrico de silueta
• Plantillas adicionales (offshore support, ferries más grandes)
• Edge cases y polishing
• Manuales de usuario completos

---

5. Reglas de oro (recordatorio)

1. Antes de cada sprint, me presentas plan detallado de lo que vas a hacer y esperas mi OK. No improvises features.

2. Cada cambio importante se discute primero en chat. Yo decido alcance.

3. Tests obligatorios para todo lo que toca core y runtime/server. UI más relajada pero pytest-qt en flujos críticos. Firmware: Unity + PlatformIO test runner. Mobile: tests de widget Flutter.

4. No agregues dependencias sin preguntarme primero.

5. Mantén consistencia con mis otras apps (AR ShipDesign, AR-ElecArrangement, AR-StabCol): misma filosofía UX, mismo idioma por defecto (español), mismo manejo de coordenadas navales.

6. Documenta normativa cuando implementes algo regulado:

   • IEC 60092-504 (electrical installations in ships - automation)
   • IACS UR E22 (computer-based systems)
   • ABYC E-11 (electrical)
   • NMEA 2000 (protocolo, PGNs)
   • SAE J1939 (CAN motores)
   • IMO MARPOL/SOLAS (log book — sprint 16+)

7. Sin red de salida en Runtime salvo:

   • Activación inicial de licencia (Studio → mi servidor)
   • Túnel VPN administrativa (cliente WireGuard externo)
   • Telemetría técnica solo si el owner la habilita

   Sin telemetría implícita NUNCA.

8. La biblioteca curada es ORO. Cualquier cambio en formato de archivos de biblioteca requiere migración para los proyectos existentes.

9. El Runtime debe ser inmutable para el cliente. El cliente no puede editar tags, alarmas, mímicos, topología. Solo opera lo que el Studio le entregó vía paquetes y deltas firmados.

10. Auditoría siempre activa en Runtime:

    • Cada ack de alarma
    • Cada solicitud de autoridad
    • Cada override de permissive
    • Cada conexión VPN mía con timestamps y endpoints accedidos
    • Cada aplicación de delta
    • Cada rollback
    • Cada enrolamiento/revocación de dispositivo móvil

11. Coordenadas navales consistentes en TODO el código: ShipCoord siempre, conversión a pantalla solo en renderers.

12. Unidades SI internas siempre: m, kg, Pa, °C, s. Conversión a imperial solo en UI cuando el usuario lo pida.

13. Idioma: español por defecto, inglés como segundo. Strings en vmssailor/i18n/.

14. AR-ECDIS es producto separado, no se desarrolla en este repositorio. Solo se asume que publica al backbone NMEA 2000 datos de navegación y actitud (PGN 127257) que el VMS-Sailor consume.

15. Firmware y software van juntos. El mismo .vmspack que configura el Runtime incluye los binarios de firmware para las tarjetas del proyecto. Versionados consistentemente.

---

6. Cómo proceder ahora

Paso 1. Confirma que entendiste el alcance global de las 6 partes. Pregunta cualquier duda ANTES de tocar código.

Paso 2. Verifica si existe D:/Proyectos Software/VMS-Sailor/. Si está vacía, OK. Si tiene contenido, pregúntame.

Paso 3. Presenta tu plan detallado del Sprint 0: lista de archivos que vas a crear, librerías que vas a usar, tests que vas a escribir. Espera mi OK.

Paso 4. Cuando dé OK, ejecutas el Sprint 0 completo. Al final me presentas:

• Repositorio completo con commit sprint-0
• Resultado de pytest (todo en verde)
• Resultado de validate_library.py (todo en verde)
• Script de demo tools/generate_test_project.py que crea proyecto de prueba, lo guarda como .vmsproj y lo lee de vuelta para verificar integridad

Paso 5. Yo reviso, doy feedback, y cuando apruebo, taggeas sprint-0-approved y pasamos al Sprint 1.

---

7. Información adicional

• Mi código LiveCode original de VMS-Sailor: NO TENGO. Construimos desde cero.
• Capturas de pantalla de mímicos comerciales (Kongsberg K-Chief, Praxis Mega-Guard, Wärtsilä NACOS) como referencia visual: te los pasaré en mensajes posteriores si hace falta.
• El servidor de licencias para activación es proyecto APARTE que no se construye aquí; solo el cliente de activación dentro del Runtime y dentro del Studio.
• WireGuard se gestiona externamente; solo helpers en Runtime, no embebido.
• Cualquier feature que se te ocurra que NO esté en estas 6 partes, lo discutes conmigo antes.
• El hardware AR-NMEA-IO-v1.0 ya está diseñado (PCB esquemático en archivos del proyecto), no se modifica en este desarrollo. El firmware sí lo escribimos desde cero.

---

Fin del brief completo (Partes 1-6).

Comienza confirmando que entendiste el alcance global, y luego preséntame tu plan del Sprint 0.