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