AR-VMS-Seaman/VMS_Sailor_v2_Parte_02_Studio.md

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

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

Esta parte detalla el Studio. Asume que ya leíste la Parte 1 (visión general).

---

1. Propósito

El Studio es la herramienta de escritorio que YO (Álvaro) uso para configurar cada proyecto de buque que un armador me contrata. NUNCA llega al cliente. Es mi propiedad intelectual.

Funciones principales:

• Cargar la biblioteca curada (buques, equipos, reglas, sistemas)
• Correr el wizard de pre-diseño de 8 pasos
• Editar mímicos, tags, alarmas, permissives, topología de tarjetas
• Simular el proyecto antes de empaquetar (test bench)
• Generar .vmspack base + instalador MSI Windows
• Generar deltas (.vmsdelta) para expansiones posteriores
• Mantener git interno con historial de versiones por proyecto de buque

---

2. Estructura de carpetas del Studio

vmssailor/studio/
├── __init__.py
├── app.py                          # QApplication principal
├── main_window.py                  # Ventana principal con menú/toolbar
│
├── wizard/                         # Wizard de pre-diseño 8 pasos
│   ├── __init__.py
│   ├── wizard.py                   # QWizard contenedor
│   ├── step_01_vessel_type.py      # Tipo y subcategoría de buque
│   ├── step_02_template.py         # Selección de plantilla de biblioteca
│   ├── step_03_dimensions.py       # Eslora, manga, calado, cubiertas
│   ├── step_04_systems.py          # Checklist de sistemas instalados
│   ├── step_05_equipment.py        # Equipos sugeridos por reglas
│   ├── step_06_refinement.py       # Sustituir genéricos por reales
│   ├── step_07_topology.py         # Asignar tarjetas AR-NMEA-IO + puertos
│   └── step_08_confirm.py          # Resumen + crear proyecto
│
├── editors/
│   ├── __init__.py
│   ├── vessel_editor.py            # Edita silueta y cubiertas
│   ├── system_editor.py            # Edita sistemas instalados
│   ├── equipment_editor.py         # CRUD equipos
│   ├── mimic_editor.py             # Editor visual de mímicos
│   ├── tag_editor.py               # Edita tags, direcciones, escalado
│   ├── alarm_editor.py             # Edita límites y prioridades
│   ├── permissive_editor.py        # Reglas de permissives por acción
│   ├── topology_editor.py          # Asignación tarjetas ↔ buque
│   └── rule_editor.py              # Edita reglas heurísticas YAML
│
├── designer/                       # Motor de pre-diseño
│   ├── __init__.py
│   ├── rule_engine.py              # Aplica reglas YAML al input del wizard
│   ├── layout_generator.py         # Genera disposición inicial
│   ├── similarity_search.py        # Busca buques similares cuando no hay match
│   ├── parametric_silhouette.py    # Genera silueta paramétrica (sprint posterior)
│   └── port_auto_assigner.py       # Asigna sensor a puerto de tarjeta
│
├── simulator/                      # Test bench
│   ├── __init__.py
│   ├── sim_engine.py               # Inyecta valores en tags simulados
│   ├── sim_scenarios.py            # Escenarios pre-armados
│   └── sim_panel.py                # UI de control del simulador
│
├── compiler/                       # Compilador de proyecto
│   ├── __init__.py
│   ├── package_builder.py          # Genera .vmspack
│   ├── delta_builder.py            # Genera .vmsdelta para expansiones
│   ├── msi_builder.py              # Invoca WiX para .msi
│   ├── hwid_binder.py              # Liga paquete a HWID destino
│   ├── firmware_generator.py       # Genera firmware personalizado por tarjeta
│   ├── manifest.py                 # Manifest del paquete con firma
│   └── signer.py                   # Firma criptográfica del paquete
│
├── widgets/                        # Widgets reutilizables
│   ├── __init__.py
│   ├── vessel_canvas.py            # QGraphicsView con silueta y rejilla naval
│   ├── system_sidebar.py           # Barra lateral dinámica de sistemas
│   ├── tag_browser.py
│   ├── alarm_list.py
│   ├── trends_view.py
│   └── card_topology_view.py       # Visualización de buses + tarjetas
│
└── i18n/                           # Traducciones
    ├── es.ts
    └── en.ts

---

3. Flujo del wizard de pre-diseño

Paso 1 — Tipo de buque

• Selector de categoría: yate motor, yate vela, pesquero, patrullero, ferry, offshore support
• Subcategoría según categoría:
  • Yate motor: planeo, semi-planeo, desplazamiento
  • Pesquero: cerquero, arrastrero, palangrero
  • Patrullero: costero, oceánico
  • Ferry: pasajeros, ro-ro
  • Offshore support: AHTS, PSV
• Filtra plantillas disponibles en biblioteca

Paso 2 — Plantilla

• Lista de plantillas compatibles con filtros del Paso 1
• Si el modelo exacto existe (ej: "Sunseeker 76") → uso directo
• Si no:
  • Buscar similares por similitud (eslora ±5%, tipo de casco) y proponer la más parecida como base editable
  • Importar silueta nueva (DXF, SVG, imagen rasterizada con escala)
  • Generar silueta paramétrica genérica con dimensiones (sprint posterior, no Sprint 0)

Paso 3 — Dimensiones

• Eslora total, manga máxima, calado, número de cubiertas
• Ubicaciones aproximadas de mamparos principales (proa/popa sala de máquinas)
• Auto-rellenado por plantilla, todo editable

Paso 4 — Sistemas instalados (genera el menú del Runtime)

• Checklist con TODOS los sistemas del catálogo maestro (ver Parte 1, sección 7)
• La plantilla pre-marca los típicos de su categoría
• El usuario afina (marca/desmarca según el buque real)
• Esta selección define qué aparece en el menú lateral del Runtime y qué genera tags

Paso 5 — Equipos sugeridos

• Para cada sistema marcado en Paso 4, el rule_engine.py consulta library/rules/*.yaml y propone equipos típicos con ubicaciones y cantidades
• Tabla editable con: sistema, equipo genérico, cantidad, ubicación sugerida (coordenadas Pp/CL/BL)
• Ejemplo para yate motor planeo 20-30m, sistema "máquina principal":
  • 2× motor HSDI 800-1400 kW
  • Sugerencias en orden: MTU 10V 2000 M96, MTU 12V 2000 M96, Volvo D13 900hp, CAT C32

Paso 6 — Refinamiento manual

• Para cada equipo propuesto, sustituir genérico por modelo real (MTU 12V 2000 M96 específico)
• Reposicionar equipos en vista de planta de la silueta (drag-and-drop con coordenadas reales)
• Agregar o quitar equipos
• Validar que los equipos caben físicamente

Paso 7 — Topología de tarjetas AR-NMEA-IO y asignación de puertos

Este paso es CRÍTICO porque define el hardware del proyecto. Hardware único (AR-NMEA-IO-v1.0, ver Parte 4), pero asignación de puertos y rol de cada tarjeta varía por proyecto.

Procedimiento:

1. Inventario de I/O necesarios: el sistema cuenta automáticamente cuántos DO, DI, RPM, AI necesita el proyecto basado en los equipos del Paso 6 y sus sensores.

2. Cantidad de tarjetas: propone N tarjetas (cada una tiene 10 DO + 5 DI + 1 RPM + 4 AI = 20 + 1 frecuencia). Ejemplo para buque 30m con 2 motores + 2 gensets + tanques + auxiliares: 6-7 tarjetas típicamente.

3. Ubicación física de cada tarjeta: drag-and-drop sobre la silueta del buque. Cerca de cada equipo principal (motor PORT, motor STBD, genset 1, genset 2, sala bombas, etc.).

4. Rol de cada tarjeta en el bus:

   • Maestra del bus Modbus RTU (típicamente 1 por proyecto, en PC industrial central)
   • Esclava Modbus RTU con dirección 1-247
   • Nodo NMEA 2000 (cualquiera con NMEA 2000 activado publica al backbone)
   • Modo dual (Modbus + NMEA 2000 simultáneo) — típico en motores y gensets
   • Modo bridge (lee NMEA 2000 y expone por Modbus)

5. Asignación de puerto físico ↔ sensor/actuador: por cada equipo del Paso 6, el sistema busca una tarjeta cercana con canal libre del tipo correcto. Te propone, tú validas o cambias. Ejemplo:

Equipo: ME_PORT (Motor principal babor)
Sensores:
  - Temp aceite        → Card_02.AI1 (RTD PT100, escalado -50 a 200°C)
  - Presión aceite     → Card_02.AI2 (4-20mA, escalado 0-10 bar)
  - Temp refrigerante  → Card_02.AI3 (RTD PT100, escalado -50 a 200°C)
  - Voltaje batería    → Card_02.AI4 (divisor, escalado 0-32V)
  - RPM                → Card_02.RPM1 (pickup magnético)
  - Estado arranque    → Card_02.DI1 (contacto)
  - Estado parada      → Card_02.DI2 (contacto)
  - Pre-calentamiento  → Card_02.DI3 (contacto)
  - Comando arranque   → Card_02.DO1 (relé)
  - Comando parada     → Card_02.DO2 (relé)
  - Trim UP            → Card_02.DO3 (relé)
  - Trim DOWN          → Card_02.DO4 (relé)
  - Posición trim      → Card_02.AI? — NO HAY MÁS AI libres, conflicto

6. Validación de capacidades:

   • No exceder 4 AI por tarjeta
   • No exceder 5 DI por tarjeta
   • No exceder 10 DO por tarjeta
   • No mezclar tipos de señal incompatibles en mismo canal
   • Si hay conflictos, sugiere agregar otra tarjeta

7. Identificación física para reemplazo futuro: Sistema combinado A+C (decisión Álvaro):

   • Cada tarjeta tiene dipswitches físicos para que el técnico setee el número de slot (1-16 por bus) al instalarla
   • El VMS confirma en pantalla del Runtime cuando se instala una nueva: "esta tarjeta reemplaza a la del motor PORT"
   • Si los dos no coinciden, alarma "Tarjeta no esperada en slot N"

Paso 8 — Confirmación

• Resumen: N sistemas, M equipos, K tags, P tarjetas, alarmas configuradas
• Validación final: todos los equipos tienen sus sensores asignados, no hay conflictos
• Crear proyecto → abre el editor principal del Studio con todo cargado

---

4. Editores principales (post-wizard)

Después del wizard, el integrador puede refinar todo en editores específicos:

Editor de equipos

Tabla y vista de planta. CRUD de equipos. Cambiar ubicación, modelo, sistema asignado.

Editor de mímicos (uno por sistema)

Canvas QGraphicsView donde se dibuja el P&ID del sistema. Símbolos arrastrables (motor, bomba, válvula, tanque, sensor, indicador). Cada símbolo se vincula a un tag o varios.

Símbolos disponibles desde el primer sprint:

• Motor (ISO 14617)
• Bomba (centrífuga, engranajes, pistón)
• Válvula (manual, motorizada, retención, alivio)
• Tanque (rectangular, cilíndrico)
• Intercambiador de calor
• Filtro / separador
• Compresor
• Sensor (T, P, L, F)
• Indicador (display digital, gauge, bar graph, lamp)
• Línea (líquido, gas, eléctrica, datos)

Editor de tags

Tabla con filtros por sistema/equipo. Columnas: ID, descripción, tipo, unidad, rango normal, alarmas, controllable, control_mode, authority_required, protocol, card+port, escalado.

Editor de alarmas

Por cada tag con alarmas: límite alto/bajo, prioridad (Emergency/High/Low/Info), histéresis, retraso, mensaje, escalación.

Editor de permissives

Por cada acción crítica del sistema, define lista de pre-condiciones (ver Parte 1, sección 9). Editor visual estilo if-then con drag-and-drop de tags como condiciones.

Editor de topología

Vista del buque con tarjetas ubicadas, buses dibujados como líneas, cada tarjeta clickable muestra sus puertos asignados.

Editor de reglas heurísticas

YAML editor con syntax highlighting para library/rules/*.yaml. Permite a Álvaro agregar nuevas reglas o refinar las existentes basado en experiencia con clientes.

---

5. Simulador (test bench)

Antes de empaquetar y entregar al cliente, el integrador prueba TODO el proyecto sin necesidad de hardware real.

• Crea instancias virtuales de cada tarjeta del proyecto
• Inyecta valores en los tags (manuales o por escenarios)
• El motor de alarmas, permissives, autoridad funcionan exactamente como funcionarán en producción
• Escenarios pre-armados: arranque normal, falla de sensor, alarma crítica, blackout, transferencia puente↔máquinas, escora peligrosa
• Si funciona en simulador → se puede empaquetar con confianza

---

6. Compilador de proyecto

Genera artefactos distribuibles:

.vmspack (paquete base)

Archivo ZIP firmado criptográficamente que contiene:

• manifest.json — versión, HWID destino, fecha compilación, firma SHA-256 con clave privada de Álvaro
• project.db — SQLite con toda la configuración congelada del buque
• mimics/ — SVG/JSON de mímicos por sistema
• assets/ — silueta del buque, iconos personalizados
• runtime_config.json — parámetros del servidor (puertos serie, drivers, baud rates...)
• firmware/ — binarios de firmware para cada tarjeta del proyecto

.vmsdelta (expansión sobre base existente)

Solo contiene lo agregado/cambiado respecto al estado conocido del Runtime cliente. Firmado igual.

Instalador MSI

WiX scripts en installer/wix/. Genera instalador Windows estándar que:

• Instala el Runtime como servicio Windows que arranca al boot
• Configura permisos
• Crea accesos directos del cliente desktop
• Lee el .vmspack durante instalación inicial

Generador de firmware

Para cada tarjeta del proyecto, genera un .bin que ya viene preconfigurado con:

• Su card_id y posición lógica en el bus
• Dirección Modbus o ID CAN
• Tipo de señal de cada uno de los 10 puertos
• Filtros locales activos
• Permissives locales
• Alarmas locales con sus umbrales

Esto significa que al cliente le llegan tarjetas "ready to plug" — no necesita programarlas con USB.

---

7. Versionado por proyecto de buque

Cada cliente tiene su carpeta de proyecto dentro del Studio con su propio git interno:

projects/
└── m_y_aurora_sunseeker_76/
    ├── .git/                    # Historial completo del proyecto
    ├── project.db
    ├── mimics/
    ├── assets/
    ├── deltas/                  # Históricos de deltas generados
    │   ├── v1.0_base.vmspack
    │   ├── v1.1_louvers.vmsdelta
    │   └── v2.0_watermaker_solar.vmsdelta
    └── README.md                # Notas del cliente, contacto, contratos

Cada delta generado se commit con mensaje descriptivo: "v1.1 - Agregado controlador louvers MAS-LC4 - OT-2027-042".

---

8. Activación / licencia del Studio

El Studio mismo requiere activación (es MI propiedad, no puede correr en cualquier PC):

• Archivo de licencia studio_license.lic con HWID de mi PC, firmado por mí mismo
• Al arrancar, valida HWID contra licencia
• Sin licencia válida → no arranca
• Esto protege contra robo del Studio (si alguien copia los archivos a su PC, no funciona)

---

9. Sprints relacionados con Studio

• Sprint 0: estructura, modelo de datos core compartido con Runtime
• Sprint 1: shell del Studio + ventana principal + wizard pasos 1-4
• Sprint 2: wizard pasos 5-8 + editor de equipos + biblioteca seed ampliada
• Sprint 3: editor de mímicos + editor de tags + editor de alarmas
• Sprint 7: compilador completo + activación HWID + MSI
• Sprint 8 (parte): editor de permissives

Detalle completo en Parte 6.

---

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