alro65
36dda85259
Arquitectura asincronica completa para correr 24/7 a bordo del buque.
vmssailor/runtime/server/tag_store.py
- TagStore in-memory con pub/sub asyncio.Queue
- register_tag/register_many con valores iniciales
- TagValue dataclass: value + quality + timestamp + raw_value
- subscribe()/unsubscribe() para fan-out
- stats() con breakdown por Quality
vmssailor/runtime/server/historian.py
- Historian DuckDB embebido (in-memory o archivo)
- Reader loop suscrito al tag_store + buffer + flush periodico (1s)
- query(tag_id, since, until, limit) para series temporales
- Soporta valores numericos y boolean separadamente
vmssailor/runtime/server/alarm_engine.py
- Suscriptor al tag_store que evalua AlarmConfig por update
- Operators: >, >=, <, <=, ==, !=
- Hysteresis correcta: aplica al SALIR de alarma, no a entrar
- Delay configurable (persistencia minima antes de disparar)
- Estados: ACTIVE -> ACK (con user) -> CLEARED
- ack(alarm_id, user) reconoce sin clear
vmssailor/runtime/server/drivers.py
- SimulatorDriver: produce valores sinteticos creibles por UnitSI
- Tick configurable (default 0.5s)
- Respeta range_normal_min/max del tag para mantenerse en rango
- Permite probar UI/API sin hardware ni Modbus real
vmssailor/runtime/server/runtime_app.py
- RuntimeApp dataclass ensambla todos los servicios
- build_runtime(project) construye listo para correr
- start()/stop() async lifecycle ordenado
vmssailor/runtime/server/api.py
- FastAPI app con lifespan que arranca/detiene el runtime
- GET /health, /project
- GET /tags, /tags/{id}, /tags/{id}/history
- GET /alarms, POST /alarms/{id}/ack
- WebSocket /ws/realtime con snapshot inicial + push + heartbeat
runtime_server_main.py
- Entry point con argparse: --vmsproj, --host, --port, --db
- Sin --vmsproj usa proyecto demo Sprint 0 (genera simulator vivo)
- Lanza con uvicorn
Tests (tests/runtime/, 16 nuevos, total 142/142):
- test_tag_store: register, update, subscribe, unsubscribe, stats
- test_historian: roundtrip query, stats
- test_alarm_engine: fire when below, hysteresis clears, ack
- test_api: health, project, tags listing, history, alarms via httpx.ASGITransport
Para correr el servidor en vivo:
uv run python runtime_server_main.py --verbose
Luego en otro shell:
curl http://127.0.0.1:8765/health
curl http://127.0.0.1:8765/tags | jq .
Dependencias agregadas:
- fastapi >=0.110
- uvicorn[standard] >=0.27
- websockets >=12.0
- duckdb >=0.10
- pymodbus >=3.5 (Sprint 5)
- python-can >=4.3 (Sprint 5)
- httpx >=0.27 (testing + cliente HTTP)
142/142 pytest verde, ruff clean.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
VMS-Sailor
Vessel Management System integrado (IAS — Integrated Automation System) para buques de 30 a 40 metros.
Yates motor · Pesqueros · Patrulleros · Ferries pequeños · Offshore support pequeño
Compite en el nicho que Kongsberg K-Chief, Praxis Mega-Guard, Bachmann M-Series y Wärtsilä NACOS desatienden por enfocarse en buques de 80+ m.
Componentes
| Componente | Para quién | Stack |
|---|---|---|
| VMS-Sailor Studio | Ingeniería interna (Álvaro) | Python 3.11 + PySide6 |
| VMS-Sailor Runtime | A bordo del buque | Python 3.11 + FastAPI + SQLite + DuckDB |
| VMS-Sailor Mobile | Owner + tripulación (WiFi local) | Flutter 3.x + Dart 3.x |
| AR-NMEA-IO-v1.0 firmware | Tarjeta I/O distribuida | ESP32 + PlatformIO + C++ |
Estado actual
Sprint 0 — Fundaciones ✓
Lo que existe en este commit:
- Modelo de datos core (
vmssailor/core/) con Pydantic v2 - Persistencia portable a
.vmsproj(SQLite) - Biblioteca curada seed mínima (2 yates motor, 2 motores, 1 genset, reglas)
- Catálogo maestro completo de sistemas (
vmssailor/library/systems_catalog.json) - Validador de biblioteca + generador de proyecto demo
- Tests con cobertura ≥ 80% en
core - Design system + mockups HTML estáticos
- Firmware: solo
pinout.h(Sprint 12 implementa el firmware)
Lo que NO existe aún (sprints siguientes):
- ❌ UI Studio operativa (Sprint 1)
- ❌ Runtime servidor con drivers Modbus/NMEA 2000 (Sprint 4)
- ❌ Cliente desktop (Sprint 6)
- ❌ App móvil Flutter (Sprint 11)
- ❌ Firmware funcional (Sprint 12)
Setup
Requiere Python 3.11 y uv.
# Si no tienes Python 3.11 instalado, uv lo descarga solo:
uv python install 3.11
# Crear entorno virtual + instalar dependencias:
uv sync --extra dev
# Validar la biblioteca curada:
uv run vms-validate-library
# Generar proyecto demo y verificar roundtrip de persistencia:
uv run vms-generate-test-project
# Tests:
uv run pytest
# Lint + type check:
uv run ruff check vmssailor/ tests/ tools/
uv run mypy vmssailor/core/
Estructura del repositorio
.
├── vmssailor/ # Código Python compartido (Studio + Runtime)
│ ├── core/ # ★ Modelo de datos del producto (Sprint 0)
│ ├── library/ # ★ Biblioteca curada seed (Sprint 0)
│ ├── shared/ # Utilidades comunes
│ ├── studio/ # App Studio (Sprint 1+)
│ └── runtime/ # App Runtime (Sprint 4+)
├── firmware/ # Firmware ESP32 (Sprint 12+)
│ └── ar_nmea_io_v1/
│ └── src/config/pinout.h
├── mobile/ # App Flutter (Sprint 11)
├── tests/ # Tests Python (pytest)
├── tools/ # Scripts CLI
│ ├── validate_library.py
│ └── generate_test_project.py
├── docs/ # Documentación
│ ├── architecture.md
│ ├── coords.md
│ ├── design_system.md # ★ Sistema visual completo
│ ├── decisions_sprint0.md
│ ├── seed_data_notes.md
│ ├── mockups/ # ★ HTML mockups del producto
│ └── brand/ # ★ Logo y assets
├── installer/ # WiX MSI scripts (Sprint 7)
├── VMS_Sailor_v2_Parte_*.md # Brief original (intacto)
├── pyproject.toml
└── README.md
Documentos de referencia (intactos)
Los 6 archivos VMS_Sailor_v2_Parte_*.md son el brief original y son la verdad de referencia para todos los sprints. NO se modifican sin acuerdo explícito.
- Parte 1 — Visión, arquitectura general
- Parte 2 — Studio en detalle
- Parte 3 — Runtime en detalle
- Parte 4 — Hardware AR-NMEA-IO + firmware
- Parte 5 — Mobile
- Parte 6 — Sprints + reglas de oro
Reglas de oro (recordatorio)
- Antes de cada sprint, plan + OK explícito antes de codear.
- Tests obligatorios en
coreyruntime/server. - No agregar dependencias sin preguntar.
- Documentar normativa (IEC 60092-504, IACS UR E22, ABYC E-11, NMEA 2000, SAE J1939).
- Sin red de salida en Runtime (salvo activación inicial y VPN administrativa).
- Biblioteca curada es ORO — cambios de formato requieren migración.
- Runtime es inmutable para el cliente — solo deltas firmados.
- Auditoría siempre activa.
- Coordenadas navales
ShipCoord(x_pp, y_cl, z_bl)en todo el código. - Unidades SI internas siempre.
- Idioma: español por defecto.
- AR-ECDIS es producto separado (no se desarrolla aquí).
- Firmware y software van juntos en el mismo
.vmspack.
Detalle completo en VMS_Sailor_v2_Parte_06_Sprints_y_reglas.md sección 5.
Licencia
Software propietario de Álvaro. Ver LICENSE.txt.