sprint-0: fundaciones VMS-Sailor

Sprint 0 completo del producto VMS-Sailor (Vessel Management System integrado para buques 30-40m). Brief de referencia en VMS_Sailor_v2_Parte_*.md (intacto). Core (vmssailor.core, 95.17% coverage, 99 tests verde): - ShipCoord: sistema naval x_pp/y_cl/z_bl frozen - Vessel, Deck, Bulkhead - Equipment, EquipmentModel, Sensor, EquipmentSpec - Tag, AlarmConfig, TagBinding, Scaling - CardInstance, Bus, Topology con validacion 21 puntos I/O AR-NMEA-IO-v1.0 - Alarm, PermissiveRule, Condition - Project agregado raiz con validacion cross-entity - Persistencia portable .vmsproj (SQLite) con roundtrip verificable Biblioteca curada seed (vmssailor.library): - systems_catalog.json completo (catalogo maestro Parte 1 sec 7) - 2 vessels: Sunseeker 76, Ferretti 850 - 2 motores: MTU 12V 2000 M96, Volvo D13-900 - 1 genset: Northern Lights M65C13 - yacht_motor_planeo.yaml (reglas heuristicas) - TODO marcado data_source=seed_estimate - requiere validacion datasheets Tools: - vms-validate-library: CLI valida biblioteca completa - vms-generate-test-project: CLI demo + verificacion roundtrip persistencia Design System + 8 mockups HTML estaticos: - docs/design_system.md (paleta Deep Ocean, gradientes, typography, motion) - docs/brand/ (logo + variantes SVG) - docs/mockups/splash, studio_main, runtime_overview, runtime_mimic_fuel (P&ID animado), runtime_alarms, runtime_trim (panel estrella con horizonte artificial), mobile_overview, mobile_trim - docs/mockups/index.html (galeria) Firmware (Sprint 12+ implementacion): - firmware/ar_nmea_io_v1/src/config/pinout.h con macros GPIO Decisiones autonomas documentadas en docs/decisions_sprint0.md. Stack: Python 3.11 + uv + Pydantic v2 + SQLite stdlib + hatchling + pytest 9 + ruff + mypy. Sin PySide6, FastAPI, Flutter ni firmware funcional (entran en sprints siguientes). Criterio de aceptacion Sprint 0: cumplido. - uv sync: OK - pytest: 99/99 verde - cov vmssailor.core: 95.17% (objetivo >=80%) - ruff: clean - vms-validate-library: OK - vms-generate-test-project: INTEGRIDAD OK Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-17 07:26:06 -04:00
commit deb04c9315
96 changed files with 15335 additions and 0 deletions
@@ -0,0 +1,341 @@
+# 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.