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.**