AR-VMS-Seaman/VMS_Sailor_v2_Parte_01.md

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

Visión, modelo de producto, arquitectura general

Instrucciones para Álvaro (no para Code): Este es el primero de seis documentos que conforman el brief completo. Pega este primero en una nueva conversación de Claude Code, espera a que confirme que entendió el alcance, y luego pasa las partes 2 a 6 secuencialmente. Cada parte construye sobre la anterior.

Abre Claude Code en una carpeta padre (D:/Proyectos Software/) y deja que él cree la subcarpeta VMS-Sailor. No abras Code dentro de D:/Proyectos Software/VMS-Sailor/ antes de tiempo.

---

1. Qué es VMS-Sailor

Eres mi co-desarrollador senior en Python, Dart y firmware embebido. Vamos a construir VMS-Sailor, un Vessel Management System completo: un sistema integrado de automatización marina (IAS — Integrated Automation System) para monitoreo y control de toda la planta del buque, dirigido a embarcaciones de 30 a 40 metros (yates motor, pesqueros, patrulleros, ferries pequeños, offshore support pequeño).

VMS-Sailor es un producto vertical completo: hardware propio + firmware embebido + software de configuración + software runtime + app móvil + biblioteca curada de conocimiento naval. Compite con sistemas comerciales como Kongsberg K-Chief, Praxis Mega-Guard, Bachmann M-Series, Wärtsilä NACOS, en el nicho de buques medianos que esos fabricantes desatienden por enfocarse en buques de 80+ metros.

---

2. Contexto comercial — relación con AR-ECDIS

VMS-Sailor NO se vende solo. Forma parte de una oferta comercial mayor donde:

• AR-ECDIS es el producto base de Álvaro: sistema de navegación con cartografía electrónica, que SIEMPRE incluye GPS y sensor giroscópico Bosch BNO085 (9-DOF con fusión sensorial integrada, conectado por I2C/UART al microcontrolador del ECDIS). AR-ECDIS publica los datos de navegación y actitud al backbone NMEA 2000 del buque mediante PGNs estándar (127250 Heading, 127251 Rate of Turn, 127257 Attitude, 129025/129029 Position, 129026 COG/SOG, 128259 Speed Water).

• VMS-Sailor es producto opcional que se vende ENCIMA del AR-ECDIS. Asume que el backbone NMEA 2000 está disponible y los datos de actitud/navegación ya viajan por él. NO instala IMU adicional, NO instala GPS adicional — los lee del backbone.

Importante para Claude Code: AR-ECDIS es un proyecto separado que NO se desarrolla en este repositorio. Solo lo mencionamos para que entiendas de dónde vienen los datos de navegación y actitud que VMS-Sailor consume. Si el cliente compra solo AR-ECDIS, los datos siguen viajando por el backbone (los lee el plotter del puente). Si compra VMS-Sailor además, los aprovecha gratis sin hardware redundante.

---

3. Los cuatro componentes de VMS-Sailor

3.1 VMS-Sailor Studio (herramienta de ingeniería de Álvaro)

Aplicación de escritorio que YO uso en mi oficina cuando un armador me contrata. Incluye:

• Wizard de pre-diseño guiado de 8 pasos
• Biblioteca curada de buques (Sunseeker 76, Ferretti 850, Princess Y85, Azimut Grande 32M, pesqueros y patrulleros 30-40m...)
• Catálogo de equipos comerciales (MTU, CAT, Volvo, Yanmar, Kohler, Northern Lights, Onan, Cummins...)
• Catálogo maestro de sistemas instalables
• Reglas heurísticas en YAML que capturan mi conocimiento de qué sistemas y equipos lleva típicamente cada tipo de buque
• Editor de mímicos (P&IDs interactivos)
• Configurador de tags, alarmas, direcciones Modbus/NMEA 2000, permissives, autoridad
• Editor de topología física: asignación de tarjetas AR-NMEA-IO al buque
• Simulador (test bench) sin hardware real
• Generador de firmware personalizado por tarjeta
• Compilador a .vmspack + instalador MSI
• Generador de deltas (.vmsdelta) para expansiones sin recompilar
• Versionado git interno por proyecto de buque

Estudio queda en mi PC. El cliente NUNCA lo ve. La biblioteca curada y las reglas son mi propiedad intelectual.

3.2 VMS-Sailor Runtime (a bordo del buque)

Aplicación que se instala en el PC industrial del buque. Lo que el armador, capitán, jefe de máquinas y tripulación usan día a día. Incluye:

• Servicio Windows 24/7 con motor de tiempo real, drivers Modbus RTU/TCP y CAN/NMEA 2000, motor de tags, historian (DuckDB), motor de alarmas, motor de permissives, motor de autoridad de control puente↔máquinas, API WebSocket + REST
• Motor de protección de escora con tres niveles (warning, auto-offer, auto-force) usando datos de actitud del backbone NMEA 2000 (PGN 127257)
• Cliente desktop nativo (Python + PySide6) para estaciones puente y máquinas
• Tres perfiles: Operador, Técnico, Admin del buque (= el owner)
• Log Book naval básico (registro automático de eventos del motor, arranques/paradas, alarmas, snapshots periódicos)
• Acceso remoto VPN para soporte técnico de Álvaro, auditado y visible al owner
• Activación HWID + firma criptográfica de paquetes
• Configuración inmutable para el cliente — solo Álvaro firma cambios

3.3 VMS-Sailor Mobile (app nativa)

App nativa iOS y Android en Flutter. Para owner, técnicos y tripulación autorizados, solo dentro de la WiFi local del buque, nunca expuesta a internet.

• TOTP + biométrico del dispositivo (FaceID/TouchID/huella)
• Enrollment de dispositivos vía QR generado en estación principal por el Admin del buque
• Revocación remota de dispositivos perdidos
• Vista de mímicos optimizada para pantalla móvil
• Panel de alarmas con notificaciones push locales
• Control de algunos sistemas con permissives — los críticos solo desde estación fija
• Panel especial "Trim & Maniobra" con sliders visuales (caso de uso destacado)
• WebSocket al Runtime en WiFi local

3.4 Hardware AR-NMEA-IO + firmware ESP32

Tarjeta de I/O distribuida que YO diseño y produzco. Basada en ESP32-DOWD. Una sola SKU física, configurable por software vía descarga de configuración desde el VMS. Distribuida cerca de cada equipo monitoreado o controlado, no centralizada en panel principal.

Capacidades fijas en hardware (21 puntos I/O totales):

• 10 salidas digitales con MOSFET IRLML6344TRPBF aisladas opto PC817, diodo flyback SS14, 30V/5A
• 5 entradas digitales aisladas opto
• 1 entrada de frecuencia (RPM, pickup magnético, tacómetro)
• 4 entradas analógicas con divisores y filtros V3061
• Comunicación: RS485 (transceiver SN65HVD1781) + CAN/NMEA 2000 (transceiver MCP2562T-E_MF) + WiFi del ESP32 + USB para programación inicial
• Alimentación 12 VDC con protección TVS, bucks MP2338 a 5V y 3.3V
• Programación: USB inicial, OTA inalámbrica vía WiFi después

Filosofía clave del firmware: la tarjeta sale de fábrica con firmware universal idéntico para todas. El rol y configuración (esclava N, qué puerto hace qué, filtros locales, permissives locales, alarmas locales) se descargan del VMS al conectarse al bus. Patrón "plug-and-produce" (estándar industrial moderno tipo Beckhoff EtherCAT, Wago I/O System).

---

4. Jerarquía de roles por aplicación

Studio (mi propiedad)

Rol	Quién	Qué hace
Admin Studio	Yo (Álvaro)	Edita biblioteca curada, escribe reglas heurísticas, crea proyectos, compila paquetes, firma deltas
Ingeniero Studio	Colaboradores que contrate	Configura proyectos pero no edita biblioteca curada

Runtime (propiedad del cliente)

Rol	Quién	Qué hace
Admin del buque	El owner / armador	Máximo nivel en SU buque: gestiona usuarios, ajusta límites menores de alarma, ve auditoría completa, activa modo manual de trim
Técnico	Jefe de máquinas, ingeniero mantenimiento	Opera, ack alarmas, ejecuta controles autorizados, ve trends
Operador	Tripulación general	Solo monitoreo, ack alarmas de baja prioridad
Super-Admin de fábrica	Yo (Álvaro), vía VPN	Acceso de fabricante para diagnóstico y actualizaciones. Cada conexión auditada e inalterable, visible para el Admin del buque en pestaña "Soporte y Auditoría"

El cliente ES el dueño de SU sistema. Yo entro solo cuando el Admin del buque me autoriza y queda registrado en SU auditoría. No soy "big brother" — soy soporte técnico.

---

5. Arquitectura de configuración en capas

Para soportar el modelo de servicio (entrega inicial + comisionado + personalizaciones del owner + expansiones futuras cobradas), la configuración del Runtime se compone de capas apiladas. Las capas superiores tienen prioridad. Cada actualización agrega capa nueva sin tocar las anteriores.

Capa 1 — Paquete base (base.vmspack): Entrega original. Inmutable. Solo se reemplaza en upgrade mayor de versión (v1→v2).

Capa 2 — Comisionado de campo (commissioning.vmsdelta): Ajustes específicos durante puesta en marcha en el buque real: direcciones Modbus reales, offsets de calibración de sensores, permissives ajustados a la planta real, modelo de respuesta de trim aprendido durante prueba de mar.

Capa 3 — Personalizaciones del owner (owner_prefs.vmsdelta): Ajustes vivos durante operación: límites menores de alarma reajustados, renombres de equipos, dispositivos móviles enrolados, preferencias UI.

Capa 4 — Expansiones (expansion_vN.vmsdelta): Cada vez que el cliente paga una expansión (instaló un nuevo equipo, agregó un sistema), Álvaro genera un delta firmado que se apila como nueva capa.

Capa siempre intocable — Datos operativos: Historian completo (todos los registros históricos), log de alarmas, log de auditoría, dispositivos enrolados con sus secretos TOTP. NUNCA se tocan, ni en upgrade mayor.

Mecánica al arrancar el Runtime: Carga capa 1, aplica capa 2 sobreescribiendo, aplica capa 3, aplica capa 4 en orden cronológico. Construye configuración efectiva en memoria. En disco las capas permanecen separadas.

Beneficios:

• Ver qué cambió en cada actualización (diff entre capas)
• Rollback granular accesible al owner (todos los snapshots visibles, puede revertir a cualquier estado)
• Migrar Runtime a hardware nuevo (las capas se mueven y reaplican)
• Compactar capas viejas (operación manual mía con consentimiento del owner)

Aprobación de actualizaciones: Antes de aplicar cualquier delta, debe existir:

1. Orden de Trabajo firmada digitalmente entre Álvaro y owner: qué cambia, costo, riesgos, plan de rollback
2. Disponibilidad operativa: buque en puerto, sin alarmas críticas, sin operaciones críticas en curso. Si no se cumple, el owner debe dar doble confirmación con justificación textual.

---

6. Modelo de negocio

• Studio es mío. Software y biblioteca son propiedad intelectual de Álvaro.
• Runtime + Mobile se venden con licencia atada al HWID del PC industrial del buque.
• Año 1 garantía: mantenimiento correctivo y preventivo remoto incluido sin costo.
• Año 2 en adelante: contrato anual de mantenimiento (10-18% del valor inicial, estándar industria), cubre monitoreo remoto VPN, actualizaciones menores, soporte telefónico.
• Expansiones: cualquier sistema/equipo nuevo se cotiza aparte. Ejemplo: agregar controlador de louvers motorizados = 100 USD configuración software (cliente compra hardware aparte).
• Telemetría de salud del sistema (no de uso): el Runtime reporta proactivamente a Álvaro cuando algo va mal técnicamente (CPU, RAM, errores de drivers, sensores offline). NO reporta contenido operativo. El cliente ve transparentemente qué se envía y puede pausar/desactivar.

---

7. Catálogo maestro de sistemas

Lista de sistemas que el wizard del Studio ofrece como checklist. Lo que el integrador marca define el menú lateral del Runtime de ese buque (no aparecen sistemas no instalados).

Propulsión y maquinaria:

• Máquina principal (motores principales diesel)
• Transmisiones / reductoras
• Ejes y hélices
• Hélices de proa/popa (thrusters)

Maniobra y trimado:

• Trim de motores / sterndrives
• Trim tabs (Bennett, Lenco)
• Hélices de paso variable (CPP)
• Estabilizadores girostáticos (Seakeeper, Quick MC²) — integración como periférico Modbus/CAN propietario (sprint posterior)
• Estabilizadores de aletas activas
• Joystick docking

Generación eléctrica:

• Gensets diésel
• Shore power con transferencia automática y transformador de aislamiento
• Inversores/cargadores combinados (Victron Quattro, Mastervolt Mass Combi)
• Bancos de baterías litio con BMS inteligente
• Cuadros principales (MSB)
• Cuadros de emergencia (ESB)
• UPS
• Paneles solares + MPPT
• Smart busbars DC (Lynx Smart BMS)
• Tableros inteligentes con monitoreo embebido (V, I, f, kWh por Modbus)

Aislamiento eléctrico:

• Aislamiento por sectores (sectionalizing)
• Aislamiento total de emergencia
• Breakers configurables
• Lockout-tagout digital

Fluidos del buque:

• Combustible (DO/MDO)
• Aceite lubricante
• Aceite hidráulico
• Refrigeración agua dulce
• Refrigeración agua salada
• Aire de arranque / aire comprimido
• Sentinas
• Lastre
• Aguas grises
• Aguas negras
• Agua potable
• Agua salada de servicio
• Watermaker (desalinizadora)

Seguridad:

• Sistema contraincendios — detección
• Sistema contraincendios — extinción (CO₂, HiFog, espuma)
• FiFi externo (monitores de incendio)
• Achique de emergencia
• Detección de gases
• Hombre al agua (MOB)

Ambiente y confort:

• HVAC / aire acondicionado
• Ventilación de máquinas
• Calefacción
• Refrigeración (cámaras, neveras)

Iluminación:

• Luces de navegación
• Luces de cubierta
• Luces interiores por sector
• Luces de emergencia
• Reflectores

Tanques estructurales:

• Tanques de combustible (por tanque)
• Tanques de agua (por tanque)
• Tanques de aguas grises/negras
• Voids
• Cofferdams

Cubierta y maniobra:

• Cabrestantes / molinetes
• Sistema de anclas
• Sistema de amarre
• Davits / pescantes
• Pasarelas / portalones
• Grúas

NO incluidos (parte del AR-ECDIS, NO de VMS-Sailor):

• ECDIS, radar, AIS
• Piloto automático
• Comunicaciones VHF/HF/SatCom
• GPS y sensores de actitud (vienen del AR-ECDIS por NMEA 2000)

Específicos por tipo de buque:

• Maquinaria de pesca (pesqueros)
• Cámaras frigoríficas grandes (pesqueros/comerciales)
• ROV / equipos sumergibles (offshore)
• Sistema de buceo

---

8. Sistema de protección de escora (Roll Safety)

Aprovecha los datos de actitud que publica el AR-ECDIS al backbone NMEA 2000 (PGN 127257). El Runtime suscribe a este PGN y monitorea roll/pitch continuamente.

Tres niveles de respuesta automática:

Nivel 1 — WARNING (escora 8° sostenida por 10s)

• Alerta amarilla en todas las UIs
• Sugiere acción al operador, no actúa solo
• Registra en log book

Nivel 2 — AUTO-OFFER (escora 12° por 5s)

• Alerta naranja crítica
• Ofrece corrección automática con 15s de gracia
• Si nadie responde → corrige hacia neutral automáticamente
• Si responde "manejo manual" → desactiva auto-correction temporal

Nivel 3 — AUTO-RESET FORZADO (escora 18° o pitch peligroso)

• Alerta roja máxima
• Reset emergencia inmediato de todos los trims
• Anula override manual del owner
• Alarma sonora si hay buzzer en estación
• Registro inmediato en log book como evento crítico de seguridad

Modo Manual del Owner con safety envelope:

El owner puede activar "Control Manual 100%" desde su tablet/móvil con doble confirmación (PIN o biométrico, decisión final de Álvaro pendiente). Esto:

• Deshabilita Niveles 1 y 2 (no más warnings ni offers)
• Permite mover trim libremente
• PERO mantiene activo el Nivel 3 (seguridad crítica siempre prevalece)
• Y mantiene safety envelope: el sistema predice el efecto del comando antes de ejecutarlo. Si la predicción supera el límite configurado (default 10°), bloquea el comando con explicación: "Este ajuste llevaría a ~13° de escora, límite es 10°".

Botón de Reset de Emergencia:

Disponible siempre, físico en consola del puente Y virtual en UI. Un toque (no doble confirmación, es emergencia). Lleva todos los trims a posición neutra. Anula cualquier comando en curso. Registra evento con causa.

Modelo de respuesta del trim (calibración):

Cuánto cambia la escora resultante por grado de trim depende del buque. Se calibra automáticamente durante prueba de mar (el sistema observa cómo responde el barco a ajustes controlados) + ajuste fino manual del integrador en el Studio. Almacenado en capa 2 (comisionado) de la configuración.

---

9. Permissive Engine (lógica de pre-condiciones)

Cada acción de control crítica (arrancar motor, abrir válvula de mar, energizar thruster, mover trim) NO ejecuta directo. Antes se evalúa una lista de pre-condiciones que deben cumplirse TODAS.

Estados de cada permissive:

• OK: condición cumplida, verde
• FAIL: condición no cumplida, rojo, bloquea acción
• WARNING: el sensor que debería verificarlo no existe o está mal, amarillo, requiere override consciente del Admin del buque
• N/A: la pre-condición no aplica a este buque

Ejecución: En el servidor del Runtime, NO en la UI. Las mismas reglas aplican a todas las UIs (puente, máquinas, móvil) — única fuente de verdad.

Ejemplo arranque thruster de proa:

ACCIÓN: Arrancar bow thruster
PERMISSIVES:
  ✓ Control en posición NEUTRAL                     [OK]
  ✓ Nivel aceite hidráulico > 40%                   [OK: 65%]
  ✗ Temperatura aceite > 5°C                        [FAIL: 3°C]
  ✓ Válvula de mar refrigeración abierta            [OK]
  ⚠ Sensor presión hidráulica                       [WARNING: inactivo]
  ✓ No alarmas críticas activas                     [OK]

RESULTADO: BLOQUEADO
RAZÓN: Temperatura aceite hidráulico 3°C (mín 5°C)

---

10. Filosofía técnica clave

Monitor-now / control-later: Cada tag del sistema se define con capacidad de control desde el día 1, aunque inicialmente solo se monitoree. Cuando el cliente instale el actuador físico en el futuro, basta cambiar un flag control_mode: future → manual sin tocar arquitectura.

Sistemas dinámicos: El menú lateral del Runtime se genera según los sistemas que el integrador marcó en el wizard. Si el buque no tiene watermaker, el botón "Watermaker" ni aparece. Si después se instala, se agrega como delta.

Coordenadas navales SIEMPRE: X desde Perpendicular de Popa (Pp) hacia proa positivo. Y desde Línea de Crujía (CL), estribor positivo, babor negativo. Z desde Línea Base (BL) hacia arriba positivo. Todo en metros. Clase ShipCoord(x_pp, y_cl, z_bl) en core. Cualquier transformada a pantalla pasa por método explícito.

Unidades SI internas siempre: metros, kilogramos, Pascales, °C, segundos. Conversión a imperial (pies, AWG, psi, °F, nudos) solo en UI cuando el usuario lo pida.

Idioma: Español por defecto, inglés como segunda opción. Strings en vmssailor/i18n/.

Sin red de salida: Salvo activación inicial de licencia (Studio → servidor licencias de Álvaro) y VPN administrativa (cliente WireGuard externo). Sin telemetría implícita NUNCA — solo telemetría de salud técnica visible al cliente.

Auditoría siempre activa en Runtime: Quién hizo ack de qué alarma, quién pidió control, quién hizo override, cada conexión VPN mía con timestamps y endpoints accedidos.

---

11. Pila tecnológica (vista general)

Capa	Tecnología
Studio + Runtime cliente	Python 3.11 + PySide6 (Qt 6)
Canvas 2D (siluetas, mímicos)	QGraphicsScene / QGraphicsView
Runtime servidor	FastAPI + WebSockets + asyncio
Base de datos	SQLite + SQLAlchemy
Historian	DuckDB embebido
Drivers Modbus	pymodbus 3.x
Drivers CAN/NMEA 2000	python-can + canopen + librería NMEA 2000
Empaquetado	PyInstaller + WiX Toolset MSI
Servicio Windows	pywin32 + servicemanager
VPN	WireGuard externo
Mobile	Flutter 3.x + Dart 3.x
Firmware tarjeta	ESP-IDF (C/C++) o Arduino framework
Activación / HWID	UUID + MAC + Disk Serial firmados
Tests	pytest + pytest-qt + pytest-asyncio

Detalle completo en las Partes 2-5.

---

12. Sprints (vista general)

Plan de desarrollo aproximado. Detalle completo en Parte 6.

• Sprint 0 — Fundaciones: estructura, modelo de datos core, biblioteca seed inicial, tests
• Sprint 1-3 — Studio: shell, wizard, editores (mímicos, equipos, tags, alarmas)
• Sprint 4-5 — Runtime servidor: drivers, tag db, historian, alarm engine
• Sprint 6 — Runtime cliente desktop: estaciones puente y máquinas
• Sprint 7 — Empaquetador MSI, activación HWID
• Sprint 8 — Permissive Engine completo + Authority transfer + Protección de escora
• Sprint 9-10 — Layer Config Engine + deltas + rollback
• Sprint 11 — VMS-Sailor Mobile (Flutter)
• Sprint 12 — Firmware ESP32 + plug-and-produce + OTA
• Sprint 13+ — Log Book regulatorio completo, integraciones Seakeeper, cotizador de expansiones, refinamientos

---

13. Reglas de oro

1. Antes de cada sprint, me presentas plan y esperas mi OK. No improvises features.
2. Cada cambio importante se discute primero. 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.
4. No agregues dependencias sin preguntarme.
5. Documenta normativa cuando implementes algo regulado: IEC 60092-504 (automation), IACS UR E22 (computer-based systems), ABYC E-11 (electrical), NMEA 2000 (protocolos), IMO MARPOL/SOLAS (log book).
6. Sin red de salida en Runtime salvo activación y VPN. Sin telemetría implícita NUNCA.
7. La biblioteca curada es ORO. Cualquier cambio de formato requiere migración para proyectos existentes.
8. El Runtime es inmutable para el cliente. Solo deltas firmados por mí cambian configuración.
9. Auditoría siempre activa en Runtime.
10. Coordenadas navales consistentes en TODO el código.

---

14. Cómo proceder ahora

Paso 1. Confirma que entendiste el alcance general. 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. Espera a que te envíe la Parte 2 (VMS-Sailor Studio en detalle) antes de empezar a planificar Sprint 0. La Parte 1 es contexto general; las partes 2-6 traen los detalles técnicos por componente.

Paso 4. Cuando tengas las 6 partes, presenta tu plan detallado del Sprint 0: lista de archivos a crear, librerías, tests. Espera mi OK antes de codear.

---

Fin de Parte 1 de 6. Próxima: Parte 2 — VMS-Sailor Studio en detalle.