AR-VMS-Seaman/docs/decisions_sprint0.md

Decisiones tomadas autónomamente durante Sprint 0

Bitácora de decisiones que tomé esta noche sin poder consultar a Álvaro. Cada una con su justificación. Revisar al despertar — cualquiera puede revertirse si no convence.

---

D-1 · Pydantic v2 como base del modelo de datos core

Decisión: todas las entidades de vmssailor.core heredan de pydantic.BaseModel (v2.x).

Alternativas consideradas:

• dataclasses puros — más livianos pero sin validación de runtime
• attrs — similar a Pydantic pero menos ecosistema
• Pydantic v1 — viejo, ya no se desarrolla activamente

Justificación:

• Validación automática gratis (rangos, patrones regex, enums)
• Serialización JSON built-in (model_dump(), model_validate()) — crítica para .vmsproj y .vmspack
• Cobertura amplia del ecosistema (FastAPI Sprint 4 lo usa nativamente)
• Validators (@field_validator, @model_validator) son ergonómicos
• ConfigDict(frozen=True, extra="forbid") da inmutabilidad y rechazo de campos extra

Costo: ligera penalización de performance en construcción de objetos (no relevante en Sprint 0).

---

D-2 · SQLite stdlib en vez de SQLAlchemy para .vmsproj

Decisión: el writer y reader de .vmsproj usan sqlite3 stdlib directamente, sin ORM.

Justificación:

• .vmsproj es un archivo plano portable. No hay queries complejas, joins, relaciones evolucionando con el tiempo.
• SQL crudo es más legible y mantenible para serialización 1:1.
• Sin dependencia extra en Sprint 0.
• SQLAlchemy entrará en Sprint 4 cuando aparezca el Runtime servidor con más tablas dinámicas (historian, audit, alarms log).

---

D-3 · hatchling como build backend (no setuptools)

Decisión: [build-system] usa hatchling.

Justificación:

• Moderno (PEP 517/518), recomendado por la comunidad Python actual.
• Integra perfecto con uv.
• Configuración mínima (packages = ["vmssailor"] es suficiente).
• Setuptools es viable pero más verboso.

---

D-4 · Version PEP 440: 0.1.0.dev0 en pyproject, SPRINT_TAG = "sprint0" aparte

Decisión: PEP 440 obliga formato como 0.1.0.dev0. El "sprint0" que figuraba en el brief lo expuse en vmssailor.version.SPRINT_TAG y en el README para que el contexto humano persista.

Justificación: uv rechaza versiones no-PEP440, no había alternativa.

---

D-5 · Roundtrip por rowid de SQLite, sin columna seq explícita

Decisión: los readers (vmsproj_reader.py) hacen ORDER BY rowid en lugar de ORDER BY id. SQLite asigna rowids incrementales en orden de inserción, preservando el orden de la lista original en memoria.

Alternativas consideradas:

• Agregar columna seq INTEGER explícita a cada tabla: más verboso, más cambios.
• Sortear ambos lados por ID al comparar: cambia la semántica del modelo (las listas tendrían orden incidental, no significativo).

Justificación:

• Solución mínima (1 línea por tabla)
• El orden de inserción es exactamente lo que el integrador escribió en el Project — preservarlo es correcto.
• Si en sprints futuros necesitamos re-ordenar (drag & drop en editor), agregamos seq en ese momento (migración schema_version v1→v2).

---

D-6 · IDs de tags deterministas {prefix}.{sensor_id.upper()}

Decisión: make_tag_id("ME_PORT", "oil_press") → "ME_PORT.OIL_PRESS". Patrón regex obliga mayúsculas.

Justificación:

• Determinismo: dado un proyecto, sus tags siempre tienen el mismo ID. Facilita diffs, comparaciones, alarmas configurables por config externa.
• Convención de la industria: tags en mayúsculas con . jerárquicos (estilo OPC UA, JESE/IEC 61131-3).
• IDs jerárquicos permiten queries naturales WHERE id LIKE 'ME_PORT.%'.

---

D-7 · Pinout firmware con macros #define (no enum class C++)

Decisión: firmware/ar_nmea_io_v1/src/config/pinout.h usa #define clásicos.

Justificación:

• En Sprint 0 no hay todavía decisión PlatformIO vs ESP-IDF (eso es Sprint 12).
• Macros funcionan tanto con Arduino framework como con ESP-IDF.
• Lo importante es que el header sea la ÚNICA fuente de verdad. Cuando se elija toolchain, se puede refactor a constexpr o enum class si conviene.

TODOs documentados en el header:

• Verificar pines contra esquemático real en Sprint 12.
• Conflictos potenciales (DO3=GPIO16 también es Rx2 UART2; CAN_STBY=GPIO22 también es DO6).

---

D-8 · Mockups HTML estáticos con CSS variables compartidas

Decisión: los 8 mockups en docs/mockups/ son HTML+CSS+SVG vanilla. Comparten _tokens.css con todos los design tokens.

Alternativas consideradas:

• React/Vue: overkill para mockups estáticos
• Figma export: pierde interactividad y tokens son menos legibles
• Storybook: requiere build pipeline para Sprint 0

Justificación:

• Cero build, cero dependencias. Abre en cualquier navegador.
• Los design tokens del CSS coinciden 1:1 con los del design_system.md. Lo que se vea en mockup, así debe verse en PySide6/Flutter.
• Si quiero animaciones, SVG nativo + CSS keyframes suficiente.

---

D-9 · Top-level tools/ con wrappers + vmssailor/tools/ paquete real

Decisión: los CLIs viven en vmssailor/tools/ como módulos Python (expuestos por [project.scripts] para uv run). Hay además tools/*.py en la raíz que son wrappers que llaman al paquete via sys.path insertion.

Justificación:

• uv run vms-validate-library (canónico, profesional)
• python tools/validate_library.py (compatible con la estructura que el brief mencionaba en Parte 6)
• Funcionan ambos. Sin duplicación de lógica.

---

D-10 · Tests con pytest 9.x (en lugar de 7.4 sugerido)

Decisión: uv sync resolvió a pytest 9.0.3 (latest). Lo dejé.

Justificación: API estable entre 7.x y 9.x para nuestros casos. Si en Sprint 4+ hay incompatibilidad, se downgradeará puntualmente.

---

D-11 · Cobertura 95.17% en vmssailor.core (criterio era ≥80%)

No es decisión sino resultado — todas las branches críticas del modelo están cubiertas. Las líneas no cubiertas son mensajes de error legibles o ramas que requerirían escenarios artificiales.

---

D-12 · pulse-emergency y pulse-warn como animaciones CSS

Decisión: las alarmas críticas en mockups usan keyframes CSS para pulsar. En PySide6 (Sprint 6) se replicará con QPropertyAnimation.

Justificación: La animación de pulso es funcional, no decorativa — llama la atención del operador a una condición crítica. Se cumple con prefers-reduced-motion deshabilitando solo en Sprint 6+.

---

Lo que NO decidí (espera tu OK al despertar)

• Stack de UI desktop (Sprint 1+): asumí PySide6 porque está en el brief, pero confirmar antes de Sprint 1.
• Toolchain firmware: deferred a Sprint 12 — no toqué.
• Servidor de licencias: deferred a Sprint 7 — sólo dejé activación HWID en el modelo.
• Estilo definitivo del logo: hice una propuesta funcional (compass + casco + glow cyan). Si no te gusta, lo rediseñamos.
• Datasheets reales: ninguno cargado. Todo seed_estimate. Ver seed_data_notes.md.

---

Cualquiera de estas decisiones puede revertirse en una sesión normal de diálogo. La idea era no bloquear el progreso mientras dormías.