# ESP Platform ## Constitución del Proyecto **Documento maestro** Versión: 1.0 --- # Introducción Bienvenido a la Constitución de ESP Platform. Este documento constituye la referencia arquitectónica oficial del proyecto. Su finalidad es proporcionar una visión completa del sistema antes de comenzar cualquier implementación, garantizando que todas las decisiones técnicas respeten una arquitectura común y puedan evolucionar sin perder coherencia. La Constitución está formada por veinte especificaciones (SPEC) que describen la filosofía del proyecto, su arquitectura, los estándares de desarrollo y el Roadmap de evolución. Todas las implementaciones realizadas por desarrolladores humanos o agentes de inteligencia artificial deberán respetar las decisiones recogidas en este documento. Cuando sea necesario modificar la arquitectura, dichas modificaciones deberán aprobarse explícitamente y documentarse mediante un ADR (Architecture Decision Record). --- # Cómo utilizar este documento Las SPEC deben leerse en orden. Cada una desarrolla un aspecto concreto de la plataforma y complementa a las anteriores. No constituyen documentos independientes, sino capítulos de una misma arquitectura. --- # Índice ## Arquitectura - SPEC-001 — Filosofía y Visión - SPEC-002 — Arquitectura Global - SPEC-003 — Aeizoon Edge Platform - SPEC-004 — Edge OS - SPEC-005 — Backend Central ## Infraestructura de dispositivos - SPEC-006 — Flasher Web - SPEC-007 — OTA y Rollback - SPEC-008 — Recovery - SPEC-009 — Provisioning y QR - SPEC-010 — Fleet Management ## Plataforma - SPEC-011 — Seguridad - SPEC-012 — Modelo SaaS - SPEC-013 — Modelo de Datos - SPEC-014 — APIs ## Desarrollo - SPEC-015 — Estándares de Desarrollo - SPEC-016 — Estándares UI/UX - SPEC-017 — Convenciones de Nomenclatura - SPEC-018 — Architecture Decision Records (ADR) - SPEC-019 — Normas para Codex - SPEC-020 — Roadmap --- ## Estado del documento Documento: ESP_PLATFORM_ARCHITECTURE_v1.0.md Versión: 1.0 Estado: Aprobado Número de SPEC: 20 Número de ADR: 0 Fecha de creación: julio de 2026 Responsable de arquitectura: Juan Antonio Arquitectura: ESP Platform Estado del proyecto: Fase de implementación. --- # SPEC-001 — Filosofía y Visión de ESP Platform **Documento:** SPEC-001 **Título:** Filosofía y Visión **Proyecto:** ESP Platform **Versión:** 1.0 **Estado:** Borrador para revisión **Documento maestro final:** ESP_PLATFORM_ARCHITECTURE_v1.0.md --- ## 1. Propósito Esta especificación define la filosofía, visión y principios generales de ESP Platform. Su función es dar contexto a Codex y a cualquier desarrollador que participe en el proyecto, evitando que las primeras implementaciones se conviertan en soluciones aisladas sin coherencia futura. ESP Platform debe desarrollarse como una plataforma reutilizable, no como una colección de firmwares independientes. --- ## 2. Visión ESP Platform nace inicialmente para cubrir necesidades propias de domótica, automatización, monitorización y control. Sin embargo, desde el primer día se diseñará con mentalidad de producto profesional, de forma que pueda evolucionar en el futuro hacia: - uso doméstico avanzado; - instalaciones profesionales; - aplicaciones industriales ligeras; - producto comercial; - backend multiinstalación; - posible modelo SaaS. El objetivo inicial no es construir una empresa ni una plataforma completa desde el primer día. El objetivo inmediato es construir una base técnica correcta que permita validar el concepto y crecer sin rehacerlo todo. --- ## 3. Misión La misión de ESP Platform es permitir crear dispositivos basados inicialmente en ESP32 que compartan: - arquitectura común; - sistema de configuración; - sistema de actualización; - modelo de comunicaciones; - backend; - experiencia de usuario; - herramientas de desarrollo; - gestión centralizada futura. Cada nuevo dispositivo deberá aprovechar el trabajo ya realizado en los anteriores. --- ## 4. Qué NO es ESP Platform ESP Platform no es: - un sketch suelto de Arduino; - un firmware único para un ESP32; - una web aislada para flashear dispositivos; - una colección de pruebas; - un simple servidor MQTT; - un backend sin relación con el firmware; - una solución cerrada solo para AZ-TEMP. La web de flasheo, los firmwares, el backend, el OTA y las aplicaciones son piezas de un sistema mayor. --- ## 5. Componentes principales ESP Platform se organizará en los siguientes bloques. ### 5.1 Edge OS Base común que residirá en los dispositivos. Deberá proporcionar servicios reutilizables como: - red; - configuración persistente; - almacenamiento; - OTA; - rollback; - recovery; - MQTT; - Modbus; - web local; - API local; - logs; - diagnóstico; - seguridad; - provisioning. ### 5.2 Aplicaciones Cada aplicación añadirá lógica específica sobre Edge OS. Aplicaciones previstas: #### AZ-TEMP Dispositivo para adquisición de temperaturas. Funciones previstas: - sondas DS18B20; - nombres configurables; - calibración; - MQTT; - Modbus TCP; - API REST; - alarmas futuras. #### AZ-POWER Pasarela para medidores de energía. Funciones previstas: - RS485; - Modbus RTU Master; - lectura de analizadores eléctricos; - publicación MQTT; - integración con backend, Node-RED y Grafana. #### AZ-NFC Dispositivo para identificación y control mediante NFC. Funciones previstas: - lectura de tarjetas; - identificación de usuarios; - control de accesos; - automatización; - integración con backend. #### AZ-IO Módulo de entradas y salidas. Funciones previstas: - entradas digitales; - salidas digitales; - entradas analógicas; - salidas analógicas; - contadores; - integración con automatización. #### AZ-RELAY Módulo de relés y actuadores. Funciones previstas: - control de relés; - contactores; - escenas; - temporizaciones; - maniobras; - control remoto. ### 5.3 Plataforma central Backend previsto en: ```text iot.aeizoon.com ``` Funciones futuras: - inventario de dispositivos; - catálogo de firmwares; - flasher web; - OTA centralizada; - provisioning; - QR de alta; - usuarios; - logs; - fleet management; - API; - posible SaaS. ### 5.4 Herramientas de desarrollo El desarrollo deberá apoyarse en: - Codex CLI; - PlatformIO; - ESP-IDF; - Git; - VM Debian; - systemd; - PostgreSQL; - Nginx. --- ## 6. Principios básicos ### 6.1 Primero validar, después ampliar La plataforma debe crecer por fases. El primer objetivo práctico será validar: 1. VM funcional. 2. Web de flasheo. 3. Subida de un `.bin`. 4. Flasheo de un ESP32 vacío por USB desde navegador. No se deberá implementar el sistema completo antes de validar este flujo básico. ### 6.2 Arquitectura común Toda pieza nueva deberá diseñarse pensando en su reutilización futura. Si una funcionalidad puede servir para varios dispositivos, deberá considerarse parte de la plataforma común. ### 6.3 Configuración separada del firmware La configuración no debe perderse al actualizar firmware. El firmware será reemplazable. La configuración deberá persistir. ### 6.4 OTA segura Las actualizaciones futuras deberán diseñarse con: - doble partición; - rollback; - comprobación de integridad; - recovery. ### 6.5 Web local en dispositivos Los dispositivos deberán tener una web interna para: - configuración; - diagnóstico; - estado; - OTA local; - mantenimiento. ### 6.6 Backend como centro de gestión El backend no debe ser una simple web auxiliar. Debe evolucionar hacia el centro de gestión de la plataforma. ### 6.7 Experiencia de producto Aunque el proyecto nazca para uso propio, la experiencia debe parecer la de un producto cuidado: - instalación sencilla; - interfaz clara; - nombres consistentes; - mensajes comprensibles; - flujos guiados; - posibilidad de QR; - recuperación ante errores. ### 6.8 No sobredimensionar antes del MVP La visión comercial no debe bloquear la validación técnica. Primero debe funcionar el flujo mínimo. Después se ampliará. --- ## 7. Relación con Codex Codex actuará como implementador técnico. Debe recibir esta documentación para entender: - el objetivo global; - las fases; - las restricciones; - el estilo arquitectónico; - lo que debe evitar. Codex no deberá convertir una fase concreta en una solución cerrada que impida el crecimiento futuro. Tampoco deberá intentar construir toda la plataforma de golpe. Debe implementar exactamente la fase solicitada, dejando la estructura preparada para las siguientes. --- ## 8. Criterio de éxito inicial El primer éxito real del proyecto será: ```text Entrar en iot.aeizoon.com o en la IP interna de la VM, subir un firmware .bin, conectar un ESP32 vacío por USB, seleccionar el firmware, flashear el dispositivo desde el navegador y comprobar que arranca. ``` Hasta conseguir ese resultado, todo lo demás es secundario. --- ## 9. Criterio de éxito futuro ESP Platform será considerada madura cuando sea posible crear nuevos dispositivos reutilizando la misma base: ```text Edge OS + aplicación específica + backend común + OTA + provisioning + fleet management ``` El objetivo final es que desarrollar un nuevo producto no implique volver a resolver desde cero: - configuración; - comunicaciones; - OTA; - recuperación; - flasheo; - backend; - UX. --- ## 10. Regla fundamental La documentación debe servir al proyecto. El proyecto no debe quedar bloqueado por la documentación. Esta Constitución existe para dar dirección a Codex y evitar contradicciones, no para retrasar indefinidamente la implementación. --- ## 11. Estado documental **Estado:** Pendiente de aprobación **Dependencias:** Ninguna **Desarrolla:** Visión general del proyecto **Implementación:** No aplica directamente -------------------------------------------------------------------------------- # SPEC-002 — Arquitectura Global de ESP Platform **Documento:** SPEC-002 **Título:** Arquitectura Global **Proyecto:** ESP Platform **Versión:** 1.0 **Estado:** Borrador para revisión **Documento maestro final:** ESP_PLATFORM_ARCHITECTURE_v1.0.md --- # 1. Propósito Esta especificación define la arquitectura general de ESP Platform. Mientras la SPEC-001 explica la filosofía del proyecto, esta especificación describe cómo se organiza la plataforma y cómo se relacionan sus componentes. No entra en el detalle interno de cada componente; dicho detalle se desarrolla en las especificaciones posteriores. --- # 2. Objetivo de la arquitectura La arquitectura debe permitir desarrollar múltiples dispositivos reutilizando una infraestructura común. Cada nuevo dispositivo deberá implementar únicamente su lógica específica. Todo aquello que pueda compartirse entre varios dispositivos deberá formar parte de la plataforma. El crecimiento del proyecto deberá producirse mediante la incorporación de nuevos módulos y aplicaciones, evitando duplicar funcionalidades ya existentes. --- # 3. Visión global La plataforma se divide en cinco grandes bloques. ```text ESP Platform │ ┌──────────────┬────────────┴────────────┬──────────────┐ │ │ │ │ │ │ │ │ Desarrollo Plataforma Edge Backend Central Usuario │ │ │ │ │ │ │ │ PlatformIO Edge OS iot.aeizoon.com Navegador ESP-IDF Aplicaciones PostgreSQL App móvil (futuro) Codex CLI Web Local OTA API Git MQTT Fleet QR Modbus Firmware ``` Cada bloque tiene responsabilidades claramente definidas. --- # 4. Componentes de la plataforma La plataforma se compone de cuatro niveles principales. ## Nivel 1 — Desarrollo Conjunto de herramientas utilizadas para crear el software. Incluye: - Codex CLI - PlatformIO - ESP-IDF - Git - Máquina Virtual de desarrollo - Sistema de compilación - Publicación de firmware Estas herramientas no forman parte del producto final, pero sí del ecosistema de desarrollo. --- ## Nivel 2 — Plataforma Edge Corresponde al software residente en cada dispositivo. Está formado por: - Edge OS - Aplicación instalada El dispositivo deberá ser completamente autónomo para realizar sus funciones principales. El backend no deberá ser imprescindible para el funcionamiento normal. --- ## Nivel 3 — Backend Corresponde al servidor central. Inicialmente estará instalado en una VM Debian. Funciones previstas: - gestión de firmware - flasher web - OTA - inventario - dispositivos - usuarios - logs - provisioning - Fleet Management - API --- ## Nivel 4 — Usuario Es la capa de interacción. Inicialmente estará formada por una aplicación web. En el futuro podrán existir aplicaciones móviles utilizando las mismas APIs. --- # 5. Separación de responsabilidades Cada bloque tiene responsabilidades exclusivas. ## Desarrollo Responsable de crear el software. Nunca participa en la ejecución normal del sistema. --- ## Edge Responsable de: - adquisición de datos - control - automatización local - comunicaciones - diagnóstico Debe seguir funcionando aunque el backend esté fuera de servicio. --- ## Backend Responsable de: - administración - inventario - actualizaciones - almacenamiento histórico - configuración global - gestión de usuarios No debe asumir funciones críticas de tiempo real que pertenezcan al Edge. --- ## Usuario Responsable únicamente de interactuar con el sistema. No debe contener lógica de negocio. --- # 6. Principios arquitectónicos La arquitectura de ESP Platform se basa en los siguientes principios. ## 6.1 Independencia Cada componente deberá poder evolucionar con el mínimo impacto sobre los demás. --- ## 6.2 Modularidad Cada módulo tendrá una responsabilidad única. Los módulos se comunicarán mediante interfaces claramente definidas. --- ## 6.3 Escalabilidad La plataforma deberá crecer añadiendo componentes, no modificando los existentes. --- ## 6.4 Reutilización Siempre que una funcionalidad pueda reutilizarse por más de una aplicación deberá incorporarse al núcleo común. --- ## 6.5 Baja dependencia La comunicación entre módulos deberá minimizar el acoplamiento. Las dependencias cruzadas deberán evitarse. --- # 7. Flujo general de funcionamiento El funcionamiento habitual será el siguiente. ```text Usuario │ │ Navegador ▼ Backend │ ├───────────── OTA │ ├───────────── API │ ├───────────── Inventario │ ▼ Dispositivo │ ├──────── MQTT ├──────── Modbus ├──────── API Local ├──────── Web Local └──────── Hardware ``` --- # 8. Flujo de desarrollo El desarrollo de una nueva aplicación seguirá el siguiente proceso. ```text Arquitectura │ ▼ Codex │ ▼ PlatformIO │ ▼ Compilación │ ▼ Firmware (.bin) │ ▼ Repositorio Firmware │ ▼ Flasher Web │ ▼ ESP32 ``` En el futuro: ```text Repositorio Firmware ↓ OTA ↓ Dispositivos en producción ``` --- # 9. Arquitectura del dispositivo Cada dispositivo seguirá siempre el mismo esquema. ```text +--------------------------------------+ | Aplicación | | (AZ-TEMP / POWER / NFC / ...) | +--------------------------------------+ | Edge OS | |--------------------------------------| | Configuración | | MQTT | | Modbus | | OTA | | Recovery | | Logging | | Seguridad | | Web | | API | +--------------------------------------+ | ESP-IDF | +--------------------------------------+ | Hardware | +--------------------------------------+ ``` Esto garantiza que todas las aplicaciones compartan la misma infraestructura. --- # 10. Arquitectura del backend El backend estará formado por módulos independientes. Inicialmente: ```text Frontend Web ↓ API ↓ Servicios ↓ PostgreSQL ↓ Repositorio Firmware ``` Cada módulo deberá poder evolucionar de forma independiente. --- # 11. Arquitectura de comunicaciones Inicialmente coexistirán cuatro canales principales. ### HTTP / HTTPS Administración. ### MQTT Eventos. Telemetría. Mensajería. ### Modbus TCP Integración industrial. ### USB Flasheo inicial. En el futuro podrán añadirse nuevos protocolos sin modificar la arquitectura principal. --- # 12. Escalabilidad prevista La arquitectura debe permitir evolucionar desde: ```text 1 ESP32 ``` hasta: ```text Centenares de dispositivos ``` sin modificar la estructura fundamental del sistema. La escalabilidad deberá obtenerse añadiendo nuevos módulos, nunca rediseñando los existentes. --- # 13. Relación con las siguientes SPEC Esta especificación actúa como mapa general. Las siguientes especificaciones desarrollarán cada componente. - SPEC-003 → Aeizoon Edge Platform - SPEC-004 → Edge OS - SPEC-005 → Backend - SPEC-006 → Flasher Web - SPEC-007 → OTA - SPEC-008 → Recovery - SPEC-009 → Provisioning - SPEC-010 → Fleet Management - ... No deberán redefinir esta arquitectura, sino ampliarla. --- # 14. Estado documental **Estado:** Pendiente de aprobación **Dependencias:** - SPEC-001 **Desarrolla:** - Arquitectura general de ESP Platform **Implementación:** - Será utilizada como referencia durante todas las fases del desarrollo. -------------------------------------------------------------------------------- # SPEC-003 — Aeizoon Edge Platform **Documento:** SPEC-003 **Título:** Aeizoon Edge Platform (AEP) **Proyecto:** ESP Platform **Versión:** 1.0 **Estado:** Borrador para revisión **Documento maestro final:** ESP_PLATFORM_ARCHITECTURE_v1.0.md --- # 1. Propósito Esta especificación define Aeizoon Edge Platform (AEP), el núcleo conceptual sobre el que se desarrollarán todos los dispositivos de ESP Platform. Su finalidad es evitar que cada nuevo firmware vuelva a implementar servicios comunes y garantizar una arquitectura uniforme en todos los dispositivos. Todas las aplicaciones deberán ejecutarse sobre AEP. --- # 2. Definición Aeizoon Edge Platform (AEP) es la plataforma software residente en cada dispositivo Edge. No es una aplicación. No es un firmware específico. No depende de AZ-TEMP ni de ninguna otra aplicación. AEP proporciona servicios comunes para que cualquier aplicación pueda centrarse exclusivamente en su lógica funcional. Puede entenderse como la infraestructura común de todos los dispositivos. --- # 3. Objetivos AEP debe conseguir que desarrollar un nuevo dispositivo consista únicamente en implementar la lógica específica del producto. Todo lo demás deberá existir previamente dentro de la plataforma. Los principales objetivos son: - reutilización; - modularidad; - mantenimiento sencillo; - evolución controlada; - comportamiento homogéneo; - reducción del tiempo de desarrollo. --- # 4. Responsabilidades AEP será responsable de todos aquellos servicios que puedan ser utilizados por más de una aplicación. Entre ellos: - gestión de red; - configuración; - almacenamiento persistente; - servidor web; - API local; - autenticación; - MQTT; - Modbus TCP; - OTA; - rollback; - recovery; - logging; - diagnóstico; - identificación del dispositivo; - información de versión; - gestión de usuarios locales (si aplica); - monitorización interna. Las aplicaciones no deberán implementar nuevamente estas capacidades. --- # 5. Qué NO pertenece a AEP Las siguientes funciones pertenecen exclusivamente a las aplicaciones. Ejemplos: AZ-TEMP - lectura de temperatura; - calibración de sondas; - alarmas de temperatura. AZ-POWER - lectura de medidores; - interpretación de registros Modbus; - cálculo energético. AZ-NFC - lectura NFC; - gestión de tarjetas; - identificación de usuarios. AZ-IO - lógica de entradas y salidas. AZ-RELAY - control de relés; - temporizaciones; - escenas. AEP únicamente proporciona la infraestructura necesaria para que estas aplicaciones funcionen. --- # 6. Organización interna Conceptualmente AEP estará organizado mediante servicios. ```text Aplicación │ ┌────────────────────┼────────────────────┐ │ │ │ Configuración Comunicaciones Servicios internos │ │ │ MQTT Web Local OTA Modbus API REST Recovery WiFi Logging Seguridad Ethernet Diagnóstico Storage │ ESP-IDF ``` Cada servicio deberá tener una responsabilidad claramente definida. --- # 7. Independencia de servicios Siempre que resulte razonable, los servicios deberán poder evolucionar de forma independiente. Por ejemplo: Una mejora en OTA no debería requerir modificar el módulo MQTT. Una mejora en Modbus no debería afectar al servidor web. Una modificación del sistema de logs no debería alterar la configuración. La independencia constituye un objetivo arquitectónico. --- # 8. Configuración Toda configuración común deberá gestionarse desde AEP. Ejemplos: - nombre del dispositivo; - hostname; - dirección IP; - DHCP; - WiFi; - Ethernet; - MQTT; - Modbus; - certificados; - usuarios; - parámetros OTA. Las aplicaciones únicamente almacenarán configuración propia. Ejemplo: AZ-TEMP almacenará: - nombres de sondas; - calibraciones; - alarmas. No almacenará configuración de red. --- # 9. Almacenamiento AEP será responsable del almacenamiento persistente. La aplicación solicitará: - guardar; - leer; - eliminar; - actualizar. Nunca deberá conocer el mecanismo físico utilizado. Esto permitirá cambiar la implementación en el futuro sin modificar las aplicaciones. --- # 10. Comunicaciones Todas las comunicaciones comunes estarán gestionadas por AEP. Inicialmente: - HTTP - HTTPS (futuro) - MQTT - Modbus TCP - USB - OTA En el futuro podrán añadirse nuevos protocolos. Las aplicaciones accederán a ellos mediante interfaces proporcionadas por AEP. --- # 11. Seguridad Toda la seguridad común pertenecerá a AEP. Entre otras funciones: - autenticación; - autorización; - validación de firmware; - control de acceso a la web; - control de acceso a la API; - gestión de certificados (futuro). Las aplicaciones no implementarán mecanismos de autenticación propios salvo necesidad justificada. --- # 12. Ciclo de vida Todo dispositivo seguirá el mismo ciclo de funcionamiento. ```text Arranque ↓ Inicialización Edge Platform ↓ Carga de configuración ↓ Inicialización de comunicaciones ↓ Inicialización de aplicación ↓ Funcionamiento normal ↓ OTA (cuando proceda) ↓ Reinicio ``` La aplicación nunca deberá inicializar por sí misma los servicios comunes. --- # 13. Evolución futura AEP deberá diseñarse pensando en el crecimiento. Deberá permitir incorporar nuevos servicios sin modificar la arquitectura existente. Ejemplos futuros: - Bluetooth; - Zigbee; - Matter; - CAN Bus; - Modbus RTU; - VPN; - Edge AI; - sincronización horaria avanzada; - almacenamiento histórico. La incorporación de nuevos servicios no deberá requerir modificar las aplicaciones existentes. --- # 14. Beneficios La existencia de AEP aporta las siguientes ventajas. Para el desarrollo: - menos código duplicado; - menor tiempo de desarrollo; - mayor calidad. Para el mantenimiento: - comportamiento homogéneo; - menor riesgo; - actualizaciones comunes. Para el usuario: - misma experiencia; - misma configuración; - mismo mantenimiento. Para el proyecto: - crecimiento ordenado; - evolución sencilla; - mayor reutilización. --- # 15. Relación con las siguientes SPEC Esta especificación define la plataforma Edge desde un punto de vista conceptual. Las siguientes especificaciones desarrollarán sus componentes. SPEC-004 desarrollará Edge OS. SPEC-007 desarrollará OTA. SPEC-008 desarrollará Recovery. SPEC-011 desarrollará Seguridad. Las aplicaciones utilizarán AEP, pero no modificarán su arquitectura. --- # 16. Estado documental **Estado:** Pendiente de aprobación **Dependencias:** - SPEC-001 - SPEC-002 **Desarrolla:** - Aeizoon Edge Platform **Implementación:** - Constituirá el núcleo común de todos los dispositivos de ESP Platform. -------------------------------------------------------------------------------- # SPEC-004 — Edge OS **Documento:** SPEC-004 **Título:** Edge OS **Proyecto:** ESP Platform **Versión:** 1.0 **Estado:** Borrador para revisión **Documento maestro final:** ESP_PLATFORM_ARCHITECTURE_v1.0.md --- # 1. Propósito Esta especificación define Edge OS, el firmware base sobre el que se ejecutarán todas las aplicaciones de ESP Platform. Mientras que AEP representa el concepto de plataforma Edge, Edge OS constituye su implementación software. Toda aplicación desarrollada para ESP Platform deberá ejecutarse sobre Edge OS. El objetivo es evitar que cada dispositivo implemente nuevamente funcionalidades comunes. --- # 2. Objetivos Edge OS deberá proporcionar una base sólida, estable y reutilizable para todos los dispositivos. Los objetivos principales son: - inicialización uniforme; - servicios comunes; - arquitectura modular; - configuración persistente; - comunicaciones; - actualización segura; - recuperación; - mantenimiento sencillo; - evolución futura. --- # 3. Filosofía Edge OS no debe contener lógica de negocio. Debe proporcionar únicamente infraestructura. Toda funcionalidad específica deberá implementarse en la aplicación correspondiente. Ejemplos: Edge OS sabe: - iniciar WiFi; - publicar MQTT; - responder una API; - actualizar firmware; - guardar configuración. Edge OS no sabe: - qué es una temperatura; - qué es un medidor; - qué es una tarjeta NFC; - qué significa activar un relé. Eso pertenece a las aplicaciones. --- # 4. Organización general Todo firmware seguirá la siguiente estructura conceptual. ```text +------------------------------------------------+ Aplicación -------------------------------------------------- Servicios Edge OS -------------------------------------------------- Configuración Comunicaciones Seguridad Storage OTA Recovery Logging Diagnóstico API Web -------------------------------------------------- ESP-IDF -------------------------------------------------- Hardware +------------------------------------------------+ ``` Esta organización deberá mantenerse en todos los proyectos. --- # 5. Arquitectura modular Edge OS estará dividido en módulos independientes. Inicialmente se prevén los siguientes. ## Core Responsable de: - arranque; - inicialización; - ciclo principal; - coordinación de módulos. --- ## Config Manager Responsable de: - leer configuración; - guardar configuración; - validar parámetros; - migraciones futuras. --- ## Network Manager Responsable de: - WiFi; - Ethernet; - IP; - DHCP; - hostname; - reconexión. --- ## Web Manager Responsable de: - servidor web; - páginas; - autenticación; - recursos estáticos. --- ## API Manager Responsable de: - API REST; - respuestas JSON; - autenticación; - versionado. --- ## MQTT Manager Responsable de: - conexión; - publicación; - suscripciones; - reconexión; - estado. --- ## Modbus Manager Responsable de: - servidor Modbus TCP; - registros; - mapeo; - diagnóstico. --- ## OTA Manager Responsable de: - descarga; - validación; - instalación; - rollback. --- ## Recovery Manager Responsable de: - recuperación; - firmware alternativo; - restauración. --- ## Storage Manager Responsable de: - almacenamiento persistente; - abstracción del soporte físico. --- ## Log Manager Responsable de: - eventos; - errores; - auditoría local. --- ## Diagnostic Manager Responsable de: - estado del dispositivo; - información interna; - estadísticas. --- ## Time Manager Responsable de: - RTC; - NTP; - sincronización. --- # 6. Ciclo de arranque Todos los dispositivos deberán seguir el mismo proceso. ```text Reset ↓ Bootloader ↓ Edge OS ↓ Inicialización Core ↓ Configuración ↓ Red ↓ Servicios ↓ Aplicación ↓ Funcionamiento normal ``` La aplicación nunca deberá alterar este orden. --- # 7. Inicialización de módulos Cada módulo deberá disponer de una función de inicialización propia. Ejemplo conceptual: ```text Config ↓ Storage ↓ Network ↓ Web ↓ API ↓ MQTT ↓ Modbus ↓ OTA ↓ Aplicación ``` Esto facilitará futuras ampliaciones. --- # 8. Comunicación entre módulos Los módulos no deberán acceder directamente a información interna de otros módulos. La comunicación deberá realizarse mediante interfaces públicas. Ejemplo. La aplicación no accederá directamente al WiFi. Solicitará a Network Manager la información necesaria. Del mismo modo: OTA no accederá directamente al almacenamiento. Utilizará Storage Manager. --- # 9. Gestión de errores Todo módulo deberá detectar y comunicar errores. Los errores deberán clasificarse, al menos, en: - información; - advertencia; - error; - error crítico. Siempre que sea posible, el sistema deberá continuar funcionando. Un error en MQTT no deberá impedir el funcionamiento de la aplicación. --- # 10. Configuración Edge OS almacenará toda la configuración común. Ejemplos: - red; - MQTT; - Modbus; - usuarios; - OTA; - hostname; - idioma (futuro); - certificados (futuro). Las aplicaciones únicamente almacenarán parámetros propios. --- # 11. Recursos compartidos Edge OS administrará todos los recursos comunes. Entre ellos: - memoria; - almacenamiento; - red; - reloj; - tareas; - comunicaciones. Las aplicaciones deberán solicitar dichos recursos al núcleo. --- # 12. API interna Todos los servicios ofrecidos por Edge OS deberán exponerse mediante APIs internas claramente definidas. Ejemplos: Storage API MQTT API Network API OTA API Logging API Esto permitirá sustituir implementaciones sin afectar a las aplicaciones. --- # 13. Extensibilidad La incorporación de nuevos módulos no deberá requerir modificar el resto del sistema. Ejemplos futuros: Bluetooth Matter CAN LoRa RS485 VPN Edge AI Cada nuevo módulo deberá seguir la misma filosofía que los existentes. --- # 14. Beneficios Esta arquitectura proporciona: Para el desarrollador: - menos código; - mayor reutilización; - menor tiempo de desarrollo. Para el mantenimiento: - comportamiento uniforme; - menor riesgo; - evolución sencilla. Para el proyecto: - escalabilidad; - independencia entre módulos; - crecimiento ordenado. --- # 15. Relación con las siguientes SPEC Esta especificación define la estructura interna de Edge OS. Las siguientes especificaciones desarrollarán algunos módulos concretos. - SPEC-005 → Backend - SPEC-006 → Flasher Web - SPEC-007 → OTA - SPEC-008 → Recovery - SPEC-011 → Seguridad - SPEC-014 → APIs --- # 16. Consideraciones de implementación Edge OS deberá desarrollarse inicialmente utilizando: - PlatformIO; - ESP-IDF; - arquitectura modular; - Git; - compilación automatizada. La implementación deberá priorizar claridad, modularidad y mantenibilidad sobre la optimización prematura. --- # 17. Estado documental **Estado:** Pendiente de aprobación **Dependencias:** - SPEC-001 - SPEC-002 - SPEC-003 **Desarrolla:** - Arquitectura interna de Edge OS **Implementación:** - Constituirá la base software común de todos los dispositivos desarrollados sobre ESP Platform. -------------------------------------------------------------------------------- # SPEC-005 — Backend Central **Documento:** SPEC-005 **Título:** Backend Central **Proyecto:** ESP Platform **Versión:** 1.0 **Estado:** Borrador para revisión **Documento maestro final:** ESP_PLATFORM_ARCHITECTURE_v1.0.md --- # 1. Propósito Esta especificación define el Backend Central de ESP Platform. El Backend constituye el punto único de administración del ecosistema y será el encargado de proporcionar todos los servicios comunes que no deban ejecutarse dentro de los dispositivos Edge. El Backend no sustituye al funcionamiento autónomo de los dispositivos. Su misión consiste en facilitar su gestión. --- # 2. Objetivos El Backend deberá proporcionar una infraestructura centralizada para administrar todos los dispositivos de la plataforma. Sus objetivos principales son: - gestión de firmware; - flasheo inicial; - OTA; - inventario; - administración; - APIs; - autenticación; - Fleet Management; - auditoría; - crecimiento futuro hacia SaaS. --- # 3. Filosofía Los dispositivos deberán ser capaces de funcionar sin el Backend. El Backend añade funcionalidades de administración y gestión, pero no debe convertirse en un punto único de fallo para el funcionamiento normal de los dispositivos. Si el Backend deja de estar disponible: - los dispositivos seguirán ejecutando su lógica; - seguirán respondiendo por su web local; - seguirán respondiendo mediante Modbus TCP; - seguirán publicando MQTT si el broker continúa disponible. --- # 4. Arquitectura general El Backend se organizará mediante servicios independientes. ```text Navegador │ ▼ Frontend Web │ ▼ API REST │ ┌───────────────┼────────────────┐ │ │ │ Firmware Inventario Usuarios │ │ │ OTA Fleet Manager Auditoría │ │ │ └───────────────┼────────────────┘ │ PostgreSQL │ Repositorio Firmware ``` Cada servicio deberá tener responsabilidades claramente definidas. --- # 5. Responsabilidades El Backend será responsable de: - gestionar usuarios; - gestionar dispositivos; - almacenar firmware; - distribuir firmware; - mantener inventario; - registrar auditoría; - proporcionar APIs; - gestionar Provisioning; - gestionar OTA; - administrar Fleet Management. No será responsable del control en tiempo real de los dispositivos. --- # 6. Frontend Web Inicialmente toda la administración se realizará mediante una aplicación web. La web deberá permitir acceder a todas las funcionalidades del sistema. No deberá existir funcionalidad exclusiva de una futura aplicación móvil. Toda funcionalidad importante deberá poder realizarse desde un navegador. --- # 7. API REST Toda la lógica de negocio deberá residir en la API. La interfaz web actuará únicamente como cliente de dicha API. Esto permitirá desarrollar en el futuro: - aplicaciones móviles; - herramientas CLI; - automatizaciones; - integraciones externas. Sin modificar la lógica del Backend. --- # 8. Base de datos Inicialmente se utilizará PostgreSQL. La base de datos almacenará únicamente información persistente. Ejemplos: - usuarios; - dispositivos; - firmware; - versiones; - auditoría; - inventario; - configuraciones globales. Los datos de telemetría histórica podrán almacenarse posteriormente en sistemas especializados si fuese necesario. --- # 9. Repositorio de firmware El Backend mantendrá un repositorio de firmware. Cada firmware deberá almacenarse acompañado de información como: - nombre; - versión; - fecha; - descripción; - aplicación; - hardware compatible; - checksum; - tamaño. El repositorio será utilizado tanto por el Flasher Web como por OTA. --- # 10. Inventario Todo dispositivo registrado en la plataforma deberá disponer de una ficha propia. Inicialmente se prevén los siguientes datos. - identificador único; - nombre; - aplicación instalada; - versión; - hardware; - dirección IP; - MAC; - estado; - última conexión; - propietario; - ubicación (futuro). El inventario será el punto de partida para Fleet Management. --- # 11. Gestión de usuarios El Backend deberá permitir administrar usuarios. Inicialmente: - autenticación; - cambio de contraseña; - perfiles; - permisos. La arquitectura deberá permitir ampliar posteriormente el sistema de roles. --- # 12. Auditoría Toda operación relevante deberá quedar registrada. Ejemplos: - alta de dispositivo; - actualización OTA; - subida de firmware; - creación de usuario; - modificación de configuración; - operaciones administrativas. La auditoría facilitará el mantenimiento y el diagnóstico. --- # 13. Servicios previstos El Backend crecerá mediante módulos. Inicialmente se prevén: Firmware Service Device Service User Service Provisioning Service OTA Service Fleet Service Audit Service API Service Cada servicio deberá poder evolucionar independientemente. --- # 14. Integración con dispositivos Los dispositivos podrán comunicarse con el Backend mediante: - HTTP/HTTPS; - MQTT; - OTA; - Provisioning. La comunicación deberá minimizar el acoplamiento. Los dispositivos no deberán depender de detalles internos del Backend. --- # 15. Integración con el Flasher El Flasher Web utilizará el Backend para: - consultar firmware; - descargar binarios; - registrar instalaciones (futuro); - validar compatibilidades. El Flasher no almacenará información propia. Será un consumidor de los servicios del Backend. --- # 16. Escalabilidad La arquitectura deberá permitir evolucionar desde: ```text Una instalación doméstica ``` hasta: ```text Múltiples instalaciones ↓ Múltiples clientes ↓ Backend multiusuario ↓ SaaS ``` Sin modificar la arquitectura fundamental. --- # 17. Tecnologías iniciales La primera implementación utilizará: - Debian; - PostgreSQL; - Java (Spring Boot); - Nginx; - systemd. No se utilizarán contenedores. La arquitectura deberá seguir los estándares generales del proyecto. --- # 18. Beneficios El Backend proporciona: Para el usuario: - administración centralizada; - inventario; - firmware; - futuras OTA. Para el desarrollador: - APIs comunes; - reutilización; - separación de responsabilidades. Para la plataforma: - crecimiento ordenado; - punto único de administración; - evolución hacia Fleet Management. --- # 19. Relación con las siguientes SPEC Esta especificación define el Backend de forma general. Las siguientes especificaciones desarrollarán componentes concretos. - SPEC-006 → Flasher Web - SPEC-007 → OTA - SPEC-009 → Provisioning - SPEC-010 → Fleet Management - SPEC-011 → Seguridad - SPEC-014 → APIs --- # 20. Estado documental **Estado:** Pendiente de aprobación **Dependencias:** - SPEC-001 - SPEC-002 - SPEC-003 - SPEC-004 **Desarrolla:** - Arquitectura del Backend Central **Implementación:** - Será el núcleo de administración de ESP Platform y el primer componente desplegado durante la Fase 1. -------------------------------------------------------------------------------- # SPEC-006 — Flasher Web **Documento:** SPEC-006 **Título:** Flasher Web **Proyecto:** ESP Platform **Versión:** 1.0 **Estado:** Borrador para revisión **Documento maestro final:** ESP_PLATFORM_ARCHITECTURE_v1.0.md --- # 1. Propósito Esta especificación define el Flasher Web de ESP Platform. El Flasher Web constituye la puerta de entrada de todos los dispositivos nuevos a la plataforma. Su objetivo es permitir que un usuario conecte un ESP32 vacío mediante USB y pueda instalar un firmware desde un navegador web sin utilizar herramientas de desarrollo. El Flasher será el primer componente funcional del MVP de ESP Platform. --- # 2. Objetivos El Flasher deberá permitir: - seleccionar un firmware; - comprobar la compatibilidad con el hardware; - conectar con un ESP32 mediante USB; - escribir el firmware; - informar del progreso; - informar del resultado; - servir como base del futuro proceso de Provisioning. La experiencia deberá ser sencilla incluso para usuarios sin conocimientos técnicos. --- # 3. Filosofía El Flasher no es únicamente una utilidad de programación. Forma parte de la experiencia de usuario de ESP Platform. Su diseño deberá transmitir la misma sensación que un producto comercial. El usuario no deberá preocuparse por herramientas como: - esptool; - PlatformIO; - puertos serie; - comandos. Todo ello deberá quedar abstraído por la aplicación. --- # 4. Alcance de la primera versión La versión inicial permitirá exclusivamente: - seleccionar un firmware existente; - conectar un ESP32 mediante USB; - escribir el firmware; - comprobar el resultado. No realizará todavía: - Provisioning; - alta automática; - OTA; - inventario; - autenticación avanzada. Estas funcionalidades se incorporarán posteriormente reutilizando la misma arquitectura. --- # 5. Flujo de funcionamiento El proceso previsto será el siguiente. ```text Usuario ↓ Accede al Flasher ↓ Selecciona modelo de ESP32 ↓ Selecciona firmware ↓ Conecta USB ↓ Permitir acceso al dispositivo ↓ Flashear ↓ Verificación ↓ Resultado ``` El proceso deberá minimizar el número de pasos. --- # 6. Integración con el Backend El Flasher obtendrá toda la información desde el Backend. Entre ella: - catálogo de firmware; - versiones; - descripción; - hardware compatible; - tamaño; - checksum. El Flasher no almacenará información propia. --- # 7. Catálogo de firmware El usuario visualizará un catálogo organizado. Cada firmware mostrará, al menos: - nombre; - aplicación; - versión; - fecha; - descripción; - hardware compatible. En el futuro podrán añadirse: - notas de versión; - cambios; - estabilidad; - canal (estable / beta). --- # 8. Compatibilidad Antes de iniciar el proceso deberá comprobarse que el firmware es compatible con el dispositivo seleccionado. Inicialmente la selección será manual. En el futuro podrá detectarse automáticamente el hardware conectado. --- # 9. Comunicación con el ESP32 La comunicación se realizará mediante Web Serial. No será necesario instalar aplicaciones adicionales. El navegador solicitará autorización al usuario para acceder al dispositivo. La aplicación nunca accederá al puerto serie sin autorización explícita. --- # 10. Proceso de flasheo El proceso completo será: ```text Conectar USB ↓ Abrir puerto ↓ Comprobar comunicación ↓ Borrar Flash (si procede) ↓ Escribir firmware ↓ Verificar escritura ↓ Reiniciar ESP32 ↓ Resultado ``` Cada paso deberá informar claramente del estado. --- # 11. Interfaz de usuario La interfaz deberá priorizar claridad y sencillez. Elementos mínimos: - selección de hardware; - selección de firmware; - botón Conectar; - botón Flashear; - barra de progreso; - estado; - resultado. No deberá mostrar información técnica innecesaria al usuario final. --- # 12. Gestión de errores Los errores deberán mostrarse mediante mensajes comprensibles. Ejemplos: - dispositivo no encontrado; - acceso denegado; - puerto ocupado; - firmware incompatible; - error de escritura; - desconexión del dispositivo. Siempre que sea posible se propondrá una acción correctiva. --- # 13. Evolución futura El Flasher deberá crecer sin modificar su filosofía. Funciones previstas: - Provisioning automático; - asignación de nombre; - lectura de QR; - configuración inicial; - alta en Backend; - actualización de bootloader; - copia de seguridad; - recuperación. --- # 14. Beneficios Para el usuario: - instalación sencilla; - sin herramientas externas; - menor riesgo de error. Para el desarrollador: - proceso uniforme; - integración con Backend; - reutilización del repositorio de firmware. Para la plataforma: - punto único de instalación; - integración con OTA; - integración con Provisioning. --- # 15. Tecnologías previstas Primera versión: - Web Serial API; - JavaScript; - HTML; - CSS; - Backend Spring Boot; - PostgreSQL. No se utilizarán aplicaciones de escritorio. Toda la funcionalidad residirá en la aplicación web. --- # 16. Relación con otras SPEC El Flasher utiliza: - SPEC-002 Arquitectura Global; - SPEC-005 Backend. Será utilizado posteriormente por: - SPEC-007 OTA; - SPEC-009 Provisioning; - SPEC-010 Fleet Management. --- # 17. Objetivo del MVP El MVP de ESP Platform se considerará alcanzado cuando sea posible: ```text Abrir la web ↓ Seleccionar firmware ↓ Conectar un ESP32 vacío ↓ Flashearlo completamente ↓ Comprobar que arranca correctamente ``` Todo el desarrollo inicial del proyecto deberá orientarse a conseguir este resultado lo antes posible. --- # 18. Estado documental **Estado:** Pendiente de aprobación **Dependencias:** - SPEC-001 - SPEC-002 - SPEC-005 **Desarrolla:** - Flasher Web **Implementación:** - Constituirá el principal objetivo de la Fase 2 del proyecto y el primer componente funcional visible de ESP Platform. -------------------------------------------------------------------------------- # SPEC-007 — OTA y Rollback **Documento:** SPEC-007 **Título:** OTA y Rollback **Proyecto:** ESP Platform **Versión:** 1.0 **Estado:** Borrador para revisión **Documento maestro final:** ESP_PLATFORM_ARCHITECTURE_v1.0.md --- # 1. Propósito Esta especificación define el sistema de actualización OTA (Over The Air) y el mecanismo de Rollback de ESP Platform. El objetivo es permitir actualizar dispositivos de forma remota con el máximo nivel posible de seguridad y minimizar el riesgo de dejar un dispositivo inutilizable. La actualización OTA constituye una capacidad nativa de Edge OS y deberá estar disponible para todas las aplicaciones de la plataforma. --- # 2. Objetivos El sistema OTA deberá permitir: - actualizar firmware sin conexión física; - minimizar el tiempo de indisponibilidad; - verificar la integridad del firmware; - recuperar automáticamente versiones anteriores cuando sea necesario; - mantener la configuración del dispositivo; - reducir al mínimo el riesgo operativo. --- # 3. Filosofía Actualizar un dispositivo nunca deberá convertirse en una operación de riesgo. Toda actualización deberá poder revertirse automáticamente si el nuevo firmware no supera las comprobaciones definidas. El usuario no deberá intervenir en circunstancias normales. --- # 4. Arquitectura general El sistema OTA estará formado por los siguientes elementos. ```text Repositorio Firmware ↓ Backend ↓ OTA Service ↓ Dispositivo ↓ Verificación ↓ Confirmación ↓ Funcionamiento normal ``` El Backend únicamente distribuirá firmware. La decisión de aceptar o rechazar la actualización corresponderá al dispositivo. --- # 5. Particionado Todos los dispositivos deberán utilizar un esquema de particiones compatible con OTA. Conceptualmente: ```text Bootloader ↓ Firmware A ↓ Firmware B ↓ Configuración ↓ Datos ``` La configuración permanecerá separada del firmware. --- # 6. Proceso OTA El flujo general será: ```text Backend detecta nueva versión ↓ Dispositivo consulta ↓ Descarga firmware ↓ Verifica integridad ↓ Escribe partición alternativa ↓ Reinicio ↓ Arranque nuevo firmware ↓ Autocomprobación ↓ Confirmación ↓ Actualización completada ``` --- # 7. Verificación Antes de aceptar un firmware deberán verificarse, al menos: - integridad del fichero; - compatibilidad con el hardware; - versión; - tamaño; - resultado de la escritura. No deberá instalarse un firmware que no supere las validaciones. --- # 8. Confirmación de arranque Tras el primer arranque del nuevo firmware, Edge OS deberá realizar una comprobación de funcionamiento. Entre otras: - arranque correcto; - inicialización de servicios; - estabilidad mínima; - ausencia de errores críticos. Solo entonces se confirmará definitivamente la nueva versión. --- # 9. Rollback automático Si el nuevo firmware no supera las comprobaciones, el sistema deberá volver automáticamente a la versión anterior. Proceso conceptual: ```text Firmware nuevo ↓ Error ↓ Reinicio ↓ Bootloader ↓ Firmware anterior ↓ Funcionamiento normal ``` El usuario no deberá realizar ninguna intervención. --- # 10. Conservación de configuración Las actualizaciones OTA nunca deberán eliminar: - configuración de red; - parámetros MQTT; - configuración Modbus; - usuarios; - nombres de dispositivos; - configuración específica de la aplicación. La configuración constituye un recurso independiente del firmware. --- # 11. Compatibilidad Antes de iniciar una actualización deberán comprobarse: - modelo de hardware; - aplicación instalada; - versión mínima requerida; - espacio disponible. No deberá instalarse un firmware incompatible. --- # 12. Gestión desde el Backend El Backend permitirá: - publicar versiones; - marcar versión estable; - retirar versiones; - consultar estado de despliegue; - conocer versión instalada; - consultar resultado de la actualización. --- # 13. Estrategias futuras La arquitectura deberá permitir incorporar: - actualización por grupos; - actualización progresiva; - canal estable; - canal beta; - canal desarrollo; - actualización programada; - actualización manual; - actualización automática. Estas capacidades no deberán requerir modificar Edge OS. --- # 14. Gestión de errores El sistema deberá detectar, entre otros: - descarga incompleta; - firmware corrupto; - incompatibilidad; - fallo de escritura; - fallo de arranque; - pérdida de alimentación durante la actualización. Siempre que sea posible deberá recuperarse automáticamente. --- # 15. Beneficios Para el usuario: - actualizaciones sencillas; - mayor seguridad; - menor riesgo. Para el administrador: - despliegue remoto; - control de versiones; - seguimiento de dispositivos. Para la plataforma: - evolución continua; - mantenimiento simplificado; - base para Fleet Management. --- # 16. Evolución futura El sistema OTA podrá ampliarse con: - firmas digitales; - cifrado; - firmware diferencial; - despliegues escalonados; - validaciones avanzadas; - políticas por cliente. La arquitectura actual deberá permitir incorporar estas capacidades sin rediseños importantes. --- # 17. Relación con otras SPEC Esta especificación desarrolla: - SPEC-004 Edge OS; - SPEC-005 Backend. Será utilizada por: - SPEC-008 Recovery; - SPEC-009 Provisioning; - SPEC-010 Fleet Management; - SPEC-011 Seguridad. --- # 18. Estado documental **Estado:** Pendiente de aprobación **Dependencias:** - SPEC-001 - SPEC-002 - SPEC-003 - SPEC-004 - SPEC-005 **Desarrolla:** - Sistema OTA - Rollback automático **Implementación:** - Constituirá el mecanismo oficial de actualización remota de todos los dispositivos de ESP Platform. -------------------------------------------------------------------------------- # SPEC-008 — Recovery **Documento:** SPEC-008 **Título:** Recovery **Proyecto:** ESP Platform **Versión:** 1.0 **Estado:** Borrador para revisión **Documento maestro final:** ESP_PLATFORM_ARCHITECTURE_v1.0.md --- # 1. Propósito Esta especificación define el sistema Recovery de ESP Platform. Su objetivo es garantizar que un dispositivo pueda recuperarse de situaciones excepcionales sin requerir intervención técnica compleja y minimizando la necesidad de conexión física. Recovery constituye el último nivel de protección del dispositivo. --- # 2. Objetivos El sistema Recovery deberá permitir: - recuperar dispositivos que no puedan iniciar la aplicación correctamente; - restaurar un firmware operativo; - mantener la configuración siempre que sea posible; - facilitar el diagnóstico; - minimizar desplazamientos y mantenimiento presencial. --- # 3. Filosofía OTA evita fallos. Rollback corrige actualizaciones fallidas. Recovery permite recuperar situaciones que no pueden resolverse mediante OTA o Rollback. El objetivo es que un dispositivo resulte extremadamente difícil de dejar inutilizable. --- # 4. Relación con OTA El orden de actuación será siempre: ```text OTA ↓ Rollback ↓ Recovery ``` Recovery únicamente actuará cuando los mecanismos anteriores no puedan resolver el problema. --- # 5. Arquitectura general Recovery estará formado por: ```text Bootloader ↓ Recovery Manager ↓ Diagnóstico ↓ Opciones de recuperación ↓ Reinicio ``` El Recovery deberá formar parte de Edge OS. --- # 6. Situaciones de activación Recovery podrá iniciarse cuando ocurra alguna de las siguientes situaciones: - fallo repetido de arranque; - firmware inválido; - corrupción detectada; - interrupción grave durante una actualización; - solicitud manual del usuario; - orden remota autorizada (futuro). --- # 7. Modos de recuperación Inicialmente se contemplan los siguientes modos. ## Recuperación automática El dispositivo intentará restaurar el funcionamiento sin intervención del usuario. Ejemplos: - volver al firmware anterior; - restaurar parámetros seguros; - reiniciar servicios. --- ## Recuperación manual El usuario podrá iniciar Recovery mediante un procedimiento físico. Inicialmente se prevé: - pulsación prolongada de un botón durante el arranque. La combinación exacta dependerá del hardware. --- ## Recuperación desde la web Si el dispositivo conserva conectividad, podrá accederse a una interfaz Recovery simplificada. Permitirá: - consultar estado; - cargar un firmware; - reiniciar; - consultar diagnóstico. --- # 8. Conservación de configuración Recovery nunca deberá eliminar la configuración del usuario salvo que éste lo solicite expresamente. Se conservarán siempre que sea posible: - parámetros de red; - MQTT; - Modbus; - configuración de aplicación; - nombres; - usuarios. El borrado completo constituirá una acción independiente. --- # 9. Diagnóstico Recovery deberá proporcionar información suficiente para identificar la causa del problema. Ejemplos: - motivo de entrada en Recovery; - firmware activo; - firmware alternativo; - último error; - estado de memoria; - versión instalada. --- # 10. Restauración de firmware Recovery permitirá instalar nuevamente un firmware válido. Las fuentes previstas serán: - OTA (si existe conectividad); - Flasher Web mediante USB; - carga desde la interfaz Recovery (futuro). --- # 11. Factory Reset Recovery podrá ofrecer un modo Factory Reset. Este modo deberá: - restaurar configuración por defecto; - conservar el firmware operativo; - advertir previamente al usuario. El Factory Reset no constituye una actualización de firmware. --- # 12. Seguridad Las funciones Recovery deberán protegerse frente a accesos no autorizados. Especialmente: - reinstalación de firmware; - borrado de configuración; - restauración completa. Las acciones críticas requerirán autenticación cuando sea técnicamente posible. --- # 13. Integración con el Backend En futuras versiones Recovery podrá comunicarse con el Backend para: - informar de fallos; - solicitar firmware; - registrar incidencias; - permitir recuperación remota. La ausencia del Backend no deberá impedir el funcionamiento del Recovery. --- # 14. Integración con el Flasher Cuando Recovery no pueda resolver un problema mediante red, el dispositivo podrá recuperarse utilizando el Flasher Web. El procedimiento será idéntico al utilizado para un dispositivo nuevo. Esto garantiza un único proceso de recuperación física. --- # 15. Beneficios Para el usuario: - mayor tranquilidad; - menor riesgo de pérdida del dispositivo; - recuperación sencilla. Para el administrador: - menos intervenciones presenciales; - menor tiempo de mantenimiento. Para la plataforma: - mayor robustez; - mayor fiabilidad; - menor coste operativo. --- # 16. Evolución futura El sistema Recovery podrá incorporar posteriormente: - consola de diagnóstico; - copia de seguridad de configuración; - restauración desde Backup; - recuperación cifrada; - recuperación remota supervisada. La arquitectura deberá permitir añadir estas funciones sin rediseños importantes. --- # 17. Relación con otras SPEC Esta especificación desarrolla: - SPEC-004 Edge OS; - SPEC-006 Flasher Web; - SPEC-007 OTA y Rollback. Será utilizada posteriormente por: - SPEC-009 Provisioning; - SPEC-010 Fleet Management; - SPEC-011 Seguridad. --- # 18. Estado documental **Estado:** Pendiente de aprobación **Dependencias:** - SPEC-001 - SPEC-002 - SPEC-003 - SPEC-004 - SPEC-006 - SPEC-007 **Desarrolla:** - Recovery Manager - Estrategia de recuperación **Implementación:** - Constituirá el mecanismo de recuperación de último nivel para todos los dispositivos de ESP Platform. -------------------------------------------------------------------------------- # SPEC-009 — Provisioning y QR **Documento:** SPEC-009 **Título:** Provisioning y QR **Proyecto:** ESP Platform **Versión:** 1.0 **Estado:** Borrador para revisión **Documento maestro final:** ESP_PLATFORM_ARCHITECTURE_v1.0.md --- # 1. Propósito Esta especificación define el sistema de Provisioning de ESP Platform. Su finalidad es permitir que un dispositivo recién instalado pueda incorporarse a la plataforma de forma sencilla, rápida y segura. El Provisioning constituye el proceso de transición entre un dispositivo recién flasheado y un dispositivo completamente operativo. --- # 2. Objetivos El sistema deberá permitir: - identificar un dispositivo de forma única; - configurar los parámetros mínimos necesarios; - registrar el dispositivo en el Backend; - simplificar al máximo la instalación; - minimizar errores humanos; - servir como base para instalaciones de gran volumen. --- # 3. Filosofía El proceso de alta deberá poder realizarlo un usuario sin conocimientos técnicos. La complejidad deberá recaer sobre la plataforma, nunca sobre el instalador. El objetivo es que poner en marcha un dispositivo resulte tan sencillo como instalar un producto comercial. --- # 4. Flujo general El proceso previsto será: ```text Flasheo ↓ Primer arranque ↓ Modo Provisioning ↓ Configuración inicial ↓ Registro en Backend ↓ Asignación de identidad ↓ Funcionamiento normal ``` Todo dispositivo nuevo deberá seguir este flujo. --- # 5. Identidad del dispositivo Cada dispositivo dispondrá de un identificador único permanente. Este identificador permitirá: - registrar el dispositivo; - identificarlo en el Backend; - asociarlo a un propietario; - localizarlo en Fleet Management. La identidad nunca deberá depender del nombre asignado por el usuario. --- # 6. Código QR Cada dispositivo podrá disponer de un código QR. El QR podrá contener información como: - identificador único; - modelo; - hardware; - versión mínima compatible; - URL de Provisioning. El formato exacto podrá evolucionar sin modificar el proceso general. --- # 7. Primer arranque Tras instalar un firmware por primera vez, el dispositivo iniciará automáticamente el modo Provisioning. Durante este proceso: - generará una configuración temporal; - habilitará la interfaz de configuración; - esperará la configuración inicial. Una vez completado el proceso pasará automáticamente al funcionamiento normal. --- # 8. Configuración inicial Inicialmente podrán configurarse: - nombre del dispositivo; - red; - parámetros MQTT; - parámetros Modbus; - ubicación (opcional); - descripción (opcional). Las aplicaciones podrán añadir parámetros específicos. --- # 9. Registro en el Backend Una vez completada la configuración, el dispositivo podrá registrarse automáticamente. El Backend almacenará: - identificador; - aplicación; - versión; - hardware; - fecha de alta; - propietario; - configuración básica. --- # 10. Repetición del proceso El usuario podrá reiniciar el proceso de Provisioning cuando sea necesario. Ejemplos: - cambio de propietario; - nueva instalación; - sustitución de red; - reconfiguración completa. No será necesario reinstalar el firmware para volver a ejecutar el Provisioning. --- # 11. Integración con el Flasher El Flasher Web podrá iniciar automáticamente el proceso de Provisioning tras finalizar la programación. Esto permitirá reducir el número de pasos necesarios para poner en marcha un dispositivo nuevo. --- # 12. Seguridad El Provisioning deberá impedir altas no autorizadas. La arquitectura deberá permitir incorporar posteriormente: - códigos de activación; - certificados; - tokens temporales; - autenticación mediante usuario. --- # 13. Experiencia de usuario El objetivo será reducir al mínimo la intervención manual. Idealmente: ```text Flashear ↓ Escanear QR ↓ Asignar nombre ↓ Finalizar ``` La experiencia deberá resultar intuitiva y consistente en todos los dispositivos. --- # 14. Beneficios Para el usuario: - instalación rápida; - menos errores; - configuración guiada. Para el administrador: - inventario automático; - dispositivos identificados; - menor tiempo de despliegue. Para la plataforma: - integración con Fleet Management; - integración con OTA; - crecimiento ordenado. --- # 15. Evolución futura El sistema podrá incorporar posteriormente: - configuración masiva; - importación de parámetros; - Provisioning mediante móvil; - Provisioning sin conexión; - plantillas de instalación; - asistentes inteligentes. --- # 16. Relación con otras SPEC Esta especificación desarrolla: - SPEC-005 Backend; - SPEC-006 Flasher Web; - SPEC-008 Recovery. Será utilizada posteriormente por: - SPEC-010 Fleet Management; - SPEC-011 Seguridad; - SPEC-012 Modelo SaaS. --- # 17. Estado documental **Estado:** Pendiente de aprobación **Dependencias:** - SPEC-001 - SPEC-002 - SPEC-005 - SPEC-006 - SPEC-008 **Desarrolla:** - Provisioning - Identidad del dispositivo - QR **Implementación:** - Constituirá el proceso oficial de incorporación de nuevos dispositivos a ESP Platform. -------------------------------------------------------------------------------- # SPEC-010 — Fleet Management **Documento:** SPEC-010 **Título:** Fleet Management **Proyecto:** ESP Platform **Versión:** 1.0 **Estado:** Borrador para revisión **Documento maestro final:** ESP_PLATFORM_ARCHITECTURE_v1.0.md --- # 1. Propósito Esta especificación define el sistema Fleet Management de ESP Platform. Fleet Management constituye el conjunto de herramientas destinadas a administrar, supervisar y operar un gran número de dispositivos desde un único punto. Su objetivo es proporcionar una visión global del estado de toda la plataforma. --- # 2. Objetivos Fleet Management deberá permitir: - visualizar todos los dispositivos; - conocer su estado; - organizar dispositivos; - realizar operaciones masivas; - facilitar el mantenimiento; - reducir el tiempo de administración. --- # 3. Filosofía El número de dispositivos administrados no deberá modificar la experiencia del usuario. La plataforma deberá resultar igual de sencilla administrando: - un único dispositivo; - diez dispositivos; - cien dispositivos; - miles de dispositivos. La arquitectura deberá crecer sin modificar la forma de trabajar. --- # 4. Inventario central Fleet Management utilizará el inventario definido en el Backend. Cada dispositivo dispondrá de una ficha completa. Entre otros datos: - identificador; - nombre; - aplicación; - versión; - hardware; - estado; - propietario; - ubicación; - última conexión. --- # 5. Estado de los dispositivos Cada dispositivo podrá encontrarse, al menos, en uno de los siguientes estados. - En línea. - Desconectado. - Provisioning. - Actualizando. - Recovery. - Error. - Desconocido. El estado deberá actualizarse automáticamente siempre que sea posible. --- # 6. Organización Fleet Management permitirá organizar dispositivos mediante diferentes criterios. Ejemplos: - cliente; - ubicación; - edificio; - planta; - zona; - aplicación; - modelo. La arquitectura deberá permitir añadir nuevos criterios sin modificar el sistema. --- # 7. Búsqueda El usuario deberá localizar rápidamente cualquier dispositivo. Inicialmente podrán utilizarse filtros por: - nombre; - identificador; - aplicación; - versión; - hardware; - estado; - propietario. --- # 8. Operaciones masivas Fleet Management deberá permitir ejecutar operaciones sobre múltiples dispositivos. Ejemplos futuros: - actualizar firmware; - reiniciar; - cambiar configuración; - exportar información; - generar informes. Las operaciones deberán minimizar la intervención manual. --- # 9. Monitorización Fleet Management mostrará información general sobre el estado de la plataforma. Ejemplos: - dispositivos conectados; - dispositivos desconectados; - versiones instaladas; - actualizaciones pendientes; - incidencias. La información deberá presentarse de forma clara. --- # 10. Historial Cada dispositivo dispondrá de un historial. Ejemplos: - altas; - Provisioning; - OTA; - Recovery; - cambios de configuración; - incidencias. El historial facilitará el mantenimiento y el diagnóstico. --- # 11. Integración con OTA Fleet Management utilizará OTA para gestionar actualizaciones remotas. Permitirá: - seleccionar dispositivos; - elegir versión; - iniciar despliegues; - consultar resultados. OTA seguirá siendo el responsable de la actualización. Fleet Management únicamente coordinará el proceso. --- # 12. Integración con Recovery Cuando un dispositivo entre en Recovery, Fleet Management podrá reflejar dicha situación. En futuras versiones permitirá iniciar acciones de recuperación remota cuando la arquitectura lo permita. --- # 13. Panel principal La plataforma dispondrá de un panel principal con información resumida. Ejemplos: - número de dispositivos; - dispositivos en línea; - dispositivos con incidencias; - firmware más utilizado; - actualizaciones pendientes. El objetivo es proporcionar una visión global inmediata. --- # 14. Escalabilidad Fleet Management deberá funcionar correctamente independientemente del número de dispositivos. La arquitectura deberá diseñarse pensando en un crecimiento continuo. No deberán existir limitaciones derivadas del diseño inicial. --- # 15. Beneficios Para el usuario: - administración sencilla; - visión global; - menor tiempo de mantenimiento. Para el administrador: - operaciones centralizadas; - control de versiones; - diagnóstico rápido. Para la plataforma: - escalabilidad; - administración profesional; - evolución hacia SaaS. --- # 16. Evolución futura Fleet Management podrá incorporar posteriormente: - mapas; - planos; - dashboards personalizados; - mantenimiento predictivo; - inteligencia artificial; - reglas automáticas; - informes avanzados. La arquitectura deberá permitir estas ampliaciones sin rediseñar el sistema. --- # 17. Relación con otras SPEC Esta especificación desarrolla: - SPEC-005 Backend; - SPEC-007 OTA; - SPEC-008 Recovery; - SPEC-009 Provisioning. Será utilizada posteriormente por: - SPEC-011 Seguridad; - SPEC-012 Modelo SaaS; - SPEC-014 APIs. --- # 18. Estado documental **Estado:** Pendiente de aprobación **Dependencias:** - SPEC-001 - SPEC-002 - SPEC-005 - SPEC-007 - SPEC-008 - SPEC-009 **Desarrolla:** - Fleet Management - Gestión centralizada de dispositivos **Implementación:** - Constituirá el centro de administración de todos los dispositivos de ESP Platform. -------------------------------------------------------------------------------- # SPEC-011 — Seguridad **Documento:** SPEC-011 **Título:** Seguridad **Proyecto:** ESP Platform **Versión:** 1.0 **Estado:** Borrador para revisión **Documento maestro final:** ESP_PLATFORM_ARCHITECTURE_v1.0.md --- # 1. Propósito Esta especificación define la estrategia de seguridad de ESP Platform. Su objetivo es proteger los dispositivos, el Backend y las comunicaciones, garantizando un funcionamiento seguro sin comprometer la facilidad de uso. La seguridad deberá formar parte del diseño desde el inicio y no añadirse posteriormente. --- # 2. Objetivos La arquitectura deberá proteger: - dispositivos; - firmware; - comunicaciones; - usuarios; - credenciales; - APIs; - actualizaciones; - Backend. La seguridad deberá aplicarse de forma homogénea en toda la plataforma. --- # 3. Filosofía La seguridad deberá basarse en varios niveles de protección. No deberá depender de un único mecanismo. Cada componente protegerá únicamente aquello que le corresponda. La arquitectura evitará confiar ciegamente en cualquier elemento del sistema. --- # 4. Principios generales Se adoptarán los siguientes principios. - mínimo privilegio; - autenticación obligatoria; - autorización explícita; - separación de responsabilidades; - protección por defecto; - registro de acciones relevantes. --- # 5. Seguridad del dispositivo Cada dispositivo deberá proteger: - configuración; - API local; - interfaz web; - actualizaciones; - operaciones críticas. No deberá exponer servicios innecesarios. --- # 6. Seguridad del Backend El Backend deberá proteger: - usuarios; - sesiones; - APIs; - firmware; - auditoría; - base de datos. Todas las operaciones administrativas deberán requerir autenticación. --- # 7. Seguridad de las comunicaciones Inicialmente podrán utilizarse: - HTTP en entornos controlados; - MQTT; - Modbus TCP. La arquitectura deberá permitir evolucionar hacia: - HTTPS; - MQTT TLS; - certificados; - autenticación mutua. Sin modificar el diseño general. --- # 8. Gestión de credenciales Las credenciales nunca deberán almacenarse en texto plano. Siempre que resulte posible se utilizarán mecanismos seguros de almacenamiento. Las contraseñas deberán almacenarse utilizando algoritmos adecuados para este propósito. --- # 9. Seguridad OTA Toda actualización deberá validar: - origen; - integridad; - compatibilidad. La arquitectura permitirá incorporar posteriormente: - firmas digitales; - certificados; - validaciones criptográficas. --- # 10. Seguridad Recovery Las funciones Recovery deberán protegerse especialmente. Entre ellas: - reinstalación; - Factory Reset; - restauración. Estas operaciones requerirán autorización cuando sea técnicamente posible. --- # 11. Seguridad Provisioning El proceso de alta deberá impedir incorporaciones no autorizadas. La arquitectura permitirá incorporar: - tokens; - certificados; - códigos de activación; - validaciones temporales. --- # 12. Auditoría Todas las operaciones relevantes deberán registrarse. Ejemplos: - inicio de sesión; - OTA; - Recovery; - cambios de configuración; - creación de usuarios; - operaciones administrativas. Los registros facilitarán el diagnóstico y la trazabilidad. --- # 13. Gestión de permisos El sistema distinguirá entre autenticación y autorización. Autenticación: - identifica al usuario. Autorización: - determina qué puede hacer. La arquitectura deberá permitir ampliar el sistema de permisos sin rediseños. --- # 14. Evolución futura La plataforma podrá incorporar posteriormente: - autenticación multifactor; - certificados cliente; - HSM; - Secure Boot; - Flash Encryption; - VPN; - Zero Trust. La arquitectura deberá permitir estas mejoras sin modificar el funcionamiento general. --- # 15. Beneficios Para el usuario: - mayor confianza; - protección de datos; - menor riesgo. Para el administrador: - trazabilidad; - control de accesos; - auditoría. Para la plataforma: - arquitectura robusta; - crecimiento seguro; - preparación para entornos profesionales. --- # 16. Relación con otras SPEC Esta especificación complementa todas las SPEC anteriores. Especialmente: - SPEC-004 Edge OS; - SPEC-005 Backend; - SPEC-007 OTA; - SPEC-008 Recovery; - SPEC-009 Provisioning; - SPEC-010 Fleet Management. --- # 17. Estado documental **Estado:** Pendiente de aprobación **Dependencias:** - SPEC-001 a SPEC-010 **Desarrolla:** - Política de seguridad - Protección de la plataforma **Implementación:** - Constituirá la referencia común para todas las decisiones relacionadas con la seguridad de ESP Platform. -------------------------------------------------------------------------------- # SPEC-012 — Modelo SaaS **Documento:** SPEC-012 **Título:** Modelo SaaS **Proyecto:** ESP Platform **Versión:** 1.0 **Estado:** Borrador para revisión **Documento maestro final:** ESP_PLATFORM_ARCHITECTURE_v1.0.md --- # 1. Propósito Esta especificación define la evolución de ESP Platform hacia un modelo SaaS (Software as a Service). El objetivo es que la arquitectura diseñada para una instalación local pueda evolucionar de forma natural hacia un servicio alojado para múltiples clientes sin necesidad de rediseñar la plataforma. El modelo SaaS constituye una evolución de la arquitectura, no una arquitectura diferente. --- # 2. Objetivos El modelo SaaS deberá permitir: - múltiples clientes; - múltiples usuarios; - múltiples organizaciones; - múltiples instalaciones; - aislamiento entre clientes; - administración centralizada; - crecimiento prácticamente ilimitado. --- # 3. Filosofía La plataforma deberá diseñarse desde el primer día pensando en un futuro SaaS, aunque la primera versión funcione únicamente en una instalación local. Las decisiones actuales no deberán impedir esa evolución. --- # 4. Evolución prevista La evolución natural será: ```text Instalación local ↓ Servidor único ↓ Varios usuarios ↓ Varios clientes ↓ Multiempresa ↓ SaaS ``` Cada etapa reutilizará la arquitectura existente. --- # 5. Organización El sistema distinguirá conceptualmente entre: - plataforma; - organización; - usuario; - dispositivo. Cada organización administrará exclusivamente sus propios recursos. --- # 6. Aislamiento Los datos de una organización nunca deberán mezclarse con los de otra. El Backend deberá garantizar el aislamiento lógico entre clientes. La arquitectura permitirá evolucionar posteriormente hacia otros mecanismos de aislamiento si fuese necesario. --- # 7. Gestión de usuarios Cada organización podrá disponer de sus propios usuarios. Inicialmente podrán existir perfiles como: - administrador; - técnico; - operador; - solo lectura. La arquitectura permitirá ampliar estos perfiles. --- # 8. Dispositivos Cada dispositivo pertenecerá a una única organización. El cambio de propietario deberá realizarse mediante los mecanismos definidos en Provisioning. Fleet Management mostrará únicamente los dispositivos autorizados para cada organización. --- # 9. Firmware El repositorio de firmware podrá evolucionar para soportar: - firmware global; - firmware privado; - firmware experimental; - versiones específicas por cliente. La arquitectura deberá permitir estas opciones sin modificar el funcionamiento básico. --- # 10. Administración La plataforma distinguirá entre: Administración del sistema. Administración de la organización. Administración de dispositivos. Cada nivel dispondrá únicamente de las funciones que le correspondan. --- # 11. Escalabilidad El crecimiento del número de clientes no deberá requerir cambios importantes en la arquitectura. La plataforma deberá poder crecer horizontalmente incorporando nuevos servicios cuando sea necesario. --- # 12. Personalización Cada organización podrá personalizar determinados elementos. Ejemplos futuros: - nombre; - logotipo; - idioma; - zonas horarias; - parámetros por defecto; - políticas de actualización. --- # 13. Licenciamiento La arquitectura permitirá incorporar distintos modelos de licencia. Ejemplos: - gratuito; - profesional; - empresarial; - OEM. La gestión de licencias no deberá afectar al funcionamiento interno de los dispositivos. --- # 14. Beneficios Para el usuario: - administración centralizada; - acceso desde cualquier lugar; - crecimiento sencillo. Para el administrador: - mantenimiento simplificado; - reutilización de infraestructura; - despliegue rápido. Para el proyecto: - evolución comercial; - modelo de negocio; - escalabilidad. --- # 15. Evolución futura La arquitectura permitirá incorporar posteriormente: - alta automática de organizaciones; - facturación; - suscripciones; - marketplace; - API pública; - integraciones de terceros. --- # 16. Relación con otras SPEC Esta especificación amplía: - SPEC-005 Backend; - SPEC-010 Fleet Management; - SPEC-011 Seguridad. Servirá de base para: - SPEC-013 Modelo de Datos; - SPEC-014 APIs. --- # 17. Estado documental **Estado:** Pendiente de aprobación **Dependencias:** - SPEC-001 a SPEC-011 **Desarrolla:** - Arquitectura SaaS - Multiempresa - Multiusuario **Implementación:** - Permitirá evolucionar ESP Platform desde una instalación local hasta una plataforma SaaS sin rediseñar su arquitectura. -------------------------------------------------------------------------------- # SPEC-013 — Modelo de Datos **Documento:** SPEC-013 **Título:** Modelo de Datos **Proyecto:** ESP Platform **Versión:** 1.0 **Estado:** Borrador para revisión **Documento maestro final:** ESP_PLATFORM_ARCHITECTURE_v1.0.md --- # 1. Propósito Esta especificación define el modelo conceptual de datos de ESP Platform. Su finalidad es establecer las entidades principales de la plataforma y las relaciones existentes entre ellas. No constituye un diseño físico de base de datos, sino el modelo lógico que servirá como referencia para PostgreSQL y para las APIs del Backend. --- # 2. Objetivos El modelo deberá: - representar toda la plataforma; - evitar duplicidad de información; - facilitar la escalabilidad; - mantener independencia respecto al motor de base de datos; - servir de referencia para toda la implementación. --- # 3. Filosofía Cada entidad deberá representar un único concepto del negocio. Las relaciones deberán ser claras y evitar dependencias innecesarias. El modelo deberá poder evolucionar incorporando nuevas entidades sin alterar las existentes. --- # 4. Entidades principales El modelo inicial estará formado por las siguientes entidades. - Organización - Usuario - Dispositivo - Firmware - Aplicación - Hardware - OTA - Provisioning - Recovery - Auditoría - Grupo - Configuración Estas entidades constituyen el núcleo de la plataforma. --- # 5. Organización Representa una empresa, instalación o cliente. Ejemplos de atributos: - identificador; - nombre; - descripción; - estado; - fecha de creación. Una organización podrá contener múltiples usuarios y múltiples dispositivos. --- # 6. Usuario Representa una persona autorizada para utilizar la plataforma. Ejemplos de atributos: - identificador; - nombre; - correo electrónico; - contraseña; - perfil; - estado. Cada usuario pertenecerá a una organización. --- # 7. Dispositivo Representa un equipo físico. Ejemplos de atributos: - identificador único; - nombre; - hardware; - aplicación; - firmware; - estado; - dirección IP; - MAC; - última conexión. Cada dispositivo pertenecerá a una única organización. --- # 8. Firmware Representa una versión concreta de software. Ejemplos de atributos: - nombre; - versión; - aplicación; - hardware compatible; - fecha; - checksum; - tamaño. Un firmware podrá instalarse en múltiples dispositivos compatibles. --- # 9. Aplicación Representa el tipo funcional del firmware. Ejemplos: - AZ-TEMP; - AZ-POWER; - AZ-NFC; - AZ-IO; - AZ-RELAY. Cada firmware pertenecerá a una aplicación. --- # 10. Hardware Representa la plataforma física. Ejemplos: - ESP32 DevKit; - ESP32-S3; - ESP32-C6; - futuras placas propias. Permitirá comprobar compatibilidades antes de instalar firmware. --- # 11. OTA Representa una operación de actualización. Ejemplos de atributos: - dispositivo; - firmware origen; - firmware destino; - fecha; - estado; - resultado. El historial OTA permanecerá asociado al dispositivo. --- # 12. Provisioning Representa el alta inicial de un dispositivo. Permitirá almacenar: - fecha; - instalador; - organización; - parámetros iniciales. --- # 13. Recovery Representa un proceso de recuperación. Permitirá registrar: - motivo; - fecha; - firmware recuperado; - resultado. --- # 14. Auditoría Representa cualquier operación relevante realizada en la plataforma. Ejemplos: - inicio de sesión; - OTA; - alta; - cambios de configuración; - operaciones administrativas. --- # 15. Grupo Permitirá organizar dispositivos. Ejemplos: - edificio; - planta; - laboratorio; - cliente; - proyecto. Un dispositivo podrá pertenecer a varios grupos si la arquitectura futura así lo requiere. --- # 16. Configuración Representa parámetros persistentes. Existirán dos grandes categorías: Configuración del sistema. Configuración específica de la aplicación. Ambas deberán permanecer separadas conceptualmente. --- # 17. Relaciones principales Conceptualmente: ```text Organización │ ├──── Usuarios │ └──── Dispositivos │ ├──── Firmware │ ├──── Aplicación │ ├──── Hardware │ ├──── OTA │ ├──── Recovery │ └──── Configuración ``` Este modelo constituye la referencia general de toda la plataforma. --- # 18. Evolución futura El modelo permitirá incorporar posteriormente nuevas entidades. Ejemplos: - licencias; - suscripciones; - mapas; - dashboards; - reglas; - IA; - mantenimiento predictivo. Estas ampliaciones no deberán requerir rediseñar el núcleo del modelo. --- # 19. Relación con otras SPEC Esta especificación desarrolla: - SPEC-005 Backend; - SPEC-010 Fleet Management; - SPEC-012 SaaS. Servirá de base para: - SPEC-014 APIs; - implementación PostgreSQL; - implementación JPA. --- # 20. Estado documental **Estado:** Pendiente de aprobación **Dependencias:** - SPEC-001 a SPEC-012 **Desarrolla:** - Modelo lógico de datos **Implementación:** - Constituirá la referencia conceptual para toda la persistencia de ESP Platform. -------------------------------------------------------------------------------- # SPEC-014 — APIs **Documento:** SPEC-014 **Título:** APIs **Proyecto:** ESP Platform **Versión:** 1.0 **Estado:** Borrador para revisión **Documento maestro final:** ESP_PLATFORM_ARCHITECTURE_v1.0.md --- # 1. Propósito Esta especificación define la arquitectura general de las APIs de ESP Platform. Las APIs constituyen el mecanismo oficial de comunicación entre los distintos componentes de la plataforma. Toda comunicación entre aplicaciones deberá realizarse mediante APIs claramente definidas. --- # 2. Objetivos La arquitectura de APIs deberá: - mantener desacoplados los componentes; - facilitar la reutilización; - simplificar futuras integraciones; - garantizar estabilidad; - facilitar el versionado. --- # 3. Filosofía Las APIs representan contratos. Una API nunca deberá depender de la implementación interna de un componente. Mientras el contrato permanezca estable, la implementación podrá evolucionar libremente. --- # 4. Arquitectura Inicialmente existirán tres grandes grupos de APIs. ## Backend API Utilizada por: - Frontend Web; - futuras Apps móviles; - herramientas externas. --- ## Edge API Implementada por Edge OS. Permitirá administrar el dispositivo localmente. --- ## Internal API Utilizada exclusivamente entre servicios internos del Backend. No estará disponible para aplicaciones externas. --- # 5. Principios generales Todas las APIs deberán cumplir: - simplicidad; - coherencia; - estabilidad; - documentación; - versionado; - seguridad. --- # 6. Formato Las APIs utilizarán inicialmente: - HTTP; - JSON; - UTF-8. La arquitectura permitirá incorporar posteriormente otros formatos cuando resulte necesario. --- # 7. Versionado Todas las APIs públicas deberán estar versionadas. Ejemplo: ```text /api/v1/ ``` Las nuevas versiones nunca deberán romper la compatibilidad sin una justificación clara. --- # 8. Convenciones Las rutas deberán ser: - descriptivas; - consistentes; - predecibles. Ejemplos: ```text /api/v1/devices /api/v1/firmware /api/v1/users /api/v1/groups ``` --- # 9. Operaciones Siempre que resulte razonable se utilizarán los métodos HTTP estándar. Ejemplos: GET POST PUT DELETE PATCH Cada operación deberá tener una responsabilidad claramente definida. --- # 10. Respuestas Las respuestas deberán seguir un formato uniforme. Conceptualmente: ```json { "success": true, "data": {}, "message": "" } ``` Los errores deberán seguir la misma filosofía. --- # 11. Códigos de estado Se utilizarán los códigos HTTP apropiados. Ejemplos: 200 201 400 401 403 404 409 500 No deberán utilizarse códigos ambiguos. --- # 12. Autenticación Las APIs protegidas requerirán autenticación. La arquitectura permitirá evolucionar hacia distintos mecanismos sin modificar las rutas. --- # 13. Documentación Toda API pública deberá estar documentada. La documentación deberá generarse automáticamente siempre que sea posible. --- # 14. Integración Las APIs constituirán el único mecanismo oficial de integración. Ejemplos: - Frontend; - aplicaciones móviles; - automatizaciones; - terceros. No deberán realizarse accesos directos a la base de datos. --- # 15. Evolución futura La arquitectura permitirá incorporar posteriormente: - WebSocket; - GraphQL; - gRPC; - Streaming; - APIs públicas. Estas ampliaciones no deberán afectar al diseño actual. --- # 16. Beneficios Para el desarrollador: - menor acoplamiento; - mayor reutilización; - mantenimiento sencillo. Para la plataforma: - crecimiento ordenado; - integración sencilla; - evolución futura. --- # 17. Relación con otras SPEC Esta especificación desarrolla: - SPEC-005 Backend; - SPEC-013 Modelo de Datos. Será utilizada por prácticamente todas las implementaciones de ESP Platform. --- # 18. Estado documental **Estado:** Pendiente de aprobación **Dependencias:** - SPEC-001 a SPEC-013 **Desarrolla:** - Arquitectura de APIs - Contratos de comunicación **Implementación:** - Constituirá la referencia oficial para todas las APIs desarrolladas dentro de ESP Platform. -------------------------------------------------------------------------------- # SPEC-015 — Estándares de Desarrollo **Documento:** SPEC-015 **Título:** Estándares de Desarrollo **Proyecto:** ESP Platform **Versión:** 1.0 **Estado:** Borrador para revisión **Documento maestro final:** ESP_PLATFORM_ARCHITECTURE_v1.0.md --- # 1. Propósito Esta especificación define los estándares generales de desarrollo que deberán seguir todos los componentes de ESP Platform. Su objetivo es garantizar que todo el software desarrollado mantenga un nivel homogéneo de calidad, legibilidad y mantenibilidad. Estas normas serán aplicables tanto al código desarrollado manualmente como al generado mediante inteligencia artificial. --- # 2. Objetivos Los estándares deberán garantizar: - uniformidad; - claridad; - modularidad; - reutilización; - facilidad de mantenimiento; - facilidad de revisión. --- # 3. Filosofía Todo desarrollo deberá priorizar: - simplicidad; - legibilidad; - estabilidad; - mantenibilidad. La complejidad solo se aceptará cuando aporte un beneficio claramente justificado. --- # 4. Modularidad Cada módulo deberá tener una única responsabilidad. Los módulos deberán comunicarse mediante interfaces claramente definidas. Las dependencias entre módulos deberán mantenerse al mínimo. --- # 5. Organización del código Cada proyecto deberá mantener una estructura coherente. La organización deberá facilitar la localización rápida de cualquier componente. No deberán mezclarse responsabilidades diferentes dentro del mismo módulo. --- # 6. Reutilización Antes de desarrollar una nueva funcionalidad deberá comprobarse si ya existe un componente reutilizable. La duplicación de código deberá evitarse siempre que resulte razonable. --- # 7. Documentación Todo componente relevante deberá estar documentado. La documentación deberá explicar: - propósito; - responsabilidades; - funcionamiento general; - limitaciones. La documentación deberá mantenerse sincronizada con el código. --- # 8. Gestión de errores Los errores deberán tratarse explícitamente. No deberán ignorarse excepciones ni situaciones anómalas. Siempre que resulte posible deberán registrarse para facilitar el diagnóstico. --- # 9. Registro de eventos Las operaciones relevantes deberán generar información de diagnóstico. Los mensajes deberán ser claros y útiles. No deberán utilizarse mensajes ambiguos o poco descriptivos. --- # 10. Calidad del código El código deberá ser: - legible; - consistente; - fácilmente revisable; - fácilmente ampliable. La claridad tendrá prioridad sobre la optimización prematura. --- # 11. Compatibilidad Las nuevas funcionalidades no deberán romper el funcionamiento existente salvo decisión explícita. La compatibilidad deberá considerarse durante todo el ciclo de desarrollo. --- # 12. Pruebas Toda funcionalidad importante deberá verificarse antes de considerarse finalizada. Siempre que resulte posible deberán realizarse: - pruebas unitarias; - pruebas de integración; - pruebas funcionales. --- # 13. Control de versiones Todo el desarrollo deberá gestionarse mediante Git. Los cambios deberán mantenerse organizados y ser fácilmente identificables. --- # 14. Dependencias Las dependencias externas deberán mantenerse al mínimo. Solo se incorporarán cuando aporten un beneficio claro para el proyecto. Siempre que resulte posible deberán utilizarse componentes ampliamente mantenidos. --- # 15. Evolución La arquitectura deberá facilitar futuras ampliaciones. Cada nueva funcionalidad deberá integrarse respetando las decisiones arquitectónicas ya establecidas. No deberán introducirse soluciones aisladas que rompan la coherencia del proyecto. --- # 16. Beneficios Para el desarrollador: - mayor productividad; - menor complejidad; - revisiones más sencillas. Para el proyecto: - mantenimiento reducido; - evolución ordenada; - menor deuda técnica. --- # 17. Relación con otras SPEC Esta especificación complementa todas las SPEC anteriores. Será utilizada especialmente junto con: - SPEC-004 Edge OS; - SPEC-005 Backend; - SPEC-019 Normas para Codex. --- # 18. Estado documental **Estado:** Pendiente de aprobación **Dependencias:** - SPEC-001 a SPEC-014 **Desarrolla:** - Estándares generales de desarrollo **Implementación:** - Constituirá la referencia común para cualquier desarrollo realizado dentro de ESP Platform. -------------------------------------------------------------------------------- # SPEC-016 — Estándares UI/UX **Documento:** SPEC-016 **Título:** Estándares UI/UX **Proyecto:** ESP Platform **Versión:** 1.0 **Estado:** Borrador para revisión **Documento maestro final:** ESP_PLATFORM_ARCHITECTURE_v1.0.md --- # 1. Propósito Esta especificación define los estándares de interfaz de usuario (UI) y experiencia de usuario (UX) que deberán seguir todos los componentes de ESP Platform. Su objetivo es proporcionar una experiencia homogénea, intuitiva y profesional en toda la plataforma, independientemente del dispositivo o aplicación utilizada. --- # 2. Objetivos La experiencia de usuario deberá transmitir: - simplicidad; - claridad; - rapidez; - consistencia; - sensación de producto profesional. Todas las aplicaciones deberán compartir la misma filosofía visual. --- # 3. Filosofía La interfaz nunca deberá recordar a una herramienta técnica de desarrollo. ESP Platform deberá percibirse como un producto comercial de alta calidad. La complejidad técnica deberá permanecer oculta siempre que sea posible. --- # 4. Consistencia Todos los componentes deberán compartir: - misma identidad visual; - misma terminología; - misma organización; - mismos criterios de navegación; - mismos mensajes. El usuario no deberá aprender una interfaz diferente para cada módulo. --- # 5. Diseño El diseño deberá priorizar: - espacios amplios; - buena legibilidad; - pocos elementos simultáneos; - navegación sencilla; - jerarquía visual clara. La información importante deberá destacar de forma natural. --- # 6. Navegación Toda la plataforma deberá resultar fácilmente navegable. El usuario deberá saber siempre: - dónde se encuentra; - qué está haciendo; - qué ocurrirá al realizar una acción. --- # 7. Formularios Los formularios deberán minimizar el número de campos. Siempre que sea posible: - valores por defecto; - autocompletado; - validación inmediata; - mensajes claros. --- # 8. Mensajes Todos los mensajes deberán ser: - comprensibles; - breves; - útiles; - consistentes. Nunca deberán mostrarse errores técnicos al usuario cuando puedan sustituirse por explicaciones más claras. --- # 9. Colores Los colores deberán utilizarse con un propósito. Ejemplos: - éxito; - advertencia; - error; - información. El color nunca deberá ser el único mecanismo para transmitir información importante. --- # 10. Iconografía Los iconos deberán ser: - sencillos; - reconocibles; - consistentes. Todo icono importante deberá ir acompañado de texto cuando sea necesario. --- # 11. Adaptabilidad Toda la plataforma deberá funcionar correctamente en: - ordenador; - tablet; - teléfono móvil. El diseño será responsive desde el inicio. --- # 12. Rendimiento La interfaz deberá responder con rapidez. El usuario deberá recibir siempre información sobre el progreso de operaciones largas. Ejemplos: - barras de progreso; - indicadores de carga; - mensajes de estado. --- # 13. Accesibilidad Siempre que resulte posible deberán seguirse criterios básicos de accesibilidad. Ejemplos: - contraste adecuado; - tamaño suficiente; - navegación mediante teclado; - etiquetas descriptivas. --- # 14. Experiencia del instalador Las operaciones habituales deberán requerir el menor número posible de pasos. Ejemplos: - Flasher; - Provisioning; - OTA. El objetivo será reducir tiempos de instalación y errores. --- # 15. Beneficios Para el usuario: - aprendizaje rápido; - menor frustración; - sensación de calidad. Para el administrador: - menor tiempo de formación; - menor número de incidencias. Para la plataforma: - identidad propia; - coherencia; - diferenciación frente a otras soluciones. --- # 16. Evolución futura La identidad visual podrá evolucionar. Sin embargo deberán mantenerse: - coherencia; - simplicidad; - facilidad de uso. Las mejoras visuales nunca deberán perjudicar la usabilidad. --- # 17. Relación con otras SPEC Esta especificación complementa especialmente: - SPEC-006 Flasher Web; - SPEC-009 Provisioning; - SPEC-010 Fleet Management. Será aplicable a toda interfaz desarrollada para ESP Platform. --- # 18. Estado documental **Estado:** Pendiente de aprobación **Dependencias:** - SPEC-001 a SPEC-015 **Desarrolla:** - Estándares UI - Estándares UX - Experiencia de usuario **Implementación:** - Constituirá la referencia común para todas las interfaces de usuario desarrolladas dentro de ESP Platform. -------------------------------------------------------------------------------- # SPEC-017 — Convenciones de Nomenclatura **Documento:** SPEC-017 **Título:** Convenciones de Nomenclatura **Proyecto:** ESP Platform **Versión:** 1.0 **Estado:** Borrador para revisión **Documento maestro final:** ESP_PLATFORM_ARCHITECTURE_v1.0.md --- # 1. Propósito Esta especificación define las convenciones de nomenclatura que deberán utilizarse en todos los componentes de ESP Platform. Su objetivo es mantener una terminología uniforme en el código, la documentación, la infraestructura y los dispositivos. Una nomenclatura coherente reduce errores y facilita el mantenimiento del proyecto. --- # 2. Objetivos Las convenciones deberán garantizar: - claridad; - coherencia; - legibilidad; - escalabilidad; - facilidad de búsqueda. Todos los desarrollos deberán seguir estas normas. --- # 3. Filosofía Cada elemento deberá tener un único nombre oficial. No deberán utilizarse nombres diferentes para representar el mismo concepto. La terminología utilizada en la documentación deberá coincidir con la utilizada en el software. --- # 4. Nombre del proyecto El nombre oficial será: ESP Platform Los componentes internos utilizarán este nombre como referencia. --- # 5. Aplicaciones Las aplicaciones oficiales seguirán el prefijo: AZ- Ejemplos: - AZ-TEMP - AZ-POWER - AZ-NFC - AZ-IO - AZ-RELAY Nuevas aplicaciones deberán respetar este criterio. --- # 6. Edge OS El sistema operativo común recibirá el nombre: Aeizoon Edge OS No deberán utilizarse variantes diferentes. --- # 7. Backend El Backend se identificará como: ESP Platform Backend Los módulos internos podrán disponer de nombres específicos siempre que mantengan coherencia. --- # 8. Firmware Las versiones de firmware deberán identificarse mediante: - aplicación; - versión; - hardware. Ejemplo conceptual: AZ-TEMP v1.2.0 ESP32-S3 --- # 9. Hardware Los modelos deberán identificarse mediante nombres claros y consistentes. Ejemplos: - ESP32 DevKit - ESP32-S3 - ESP32-C6 - Aeizoon Board (futuro) --- # 10. Base de datos Las entidades deberán utilizar nombres descriptivos. Las tablas representarán conceptos del negocio. Se evitarán abreviaturas innecesarias. --- # 11. APIs Las rutas deberán mantener una estructura uniforme. Ejemplo: /api/v1/devices /api/v1/firmware /api/v1/users /api/v1/groups --- # 12. Código Las clases, paquetes y módulos deberán utilizar nombres descriptivos. No deberán utilizarse nombres genéricos como: - Utils - Misc - Temp - Test Salvo justificación clara. --- # 13. Variables Los nombres deberán describir claramente su propósito. Se evitarán abreviaturas ambiguas. La claridad tendrá prioridad sobre la brevedad. --- # 14. Documentación Toda la documentación deberá utilizar la misma terminología definida en esta especificación. No deberán coexistir nombres alternativos para un mismo concepto. --- # 15. Evolución La incorporación de nuevos nombres deberá respetar los criterios definidos en este documento. Cuando aparezca un nuevo concepto, deberá asignársele un nombre único antes de comenzar su implementación. --- # 16. Beneficios Para el desarrollador: - mayor claridad; - menor confusión; - búsqueda más sencilla. Para el proyecto: - documentación consistente; - mantenimiento simplificado; - menor deuda técnica. --- # 17. Relación con otras SPEC Esta especificación complementa especialmente: - SPEC-004 Edge OS; - SPEC-005 Backend; - SPEC-014 APIs; - SPEC-015 Estándares de Desarrollo. Será aplicable a todo el ecosistema ESP Platform. --- # 18. Estado documental **Estado:** Pendiente de aprobación **Dependencias:** - SPEC-001 a SPEC-016 **Desarrolla:** - Convenciones de nomenclatura - Terminología oficial **Implementación:** - Constituirá la referencia oficial para todos los nombres utilizados dentro de ESP Platform. -------------------------------------------------------------------------------- # SPEC-018 — Architecture Decision Records (ADR) **Documento:** SPEC-018 **Título:** Architecture Decision Records (ADR) **Proyecto:** ESP Platform **Versión:** 1.0 **Estado:** Borrador para revisión **Documento maestro final:** ESP_PLATFORM_ARCHITECTURE_v1.0.md --- # 1. Propósito Esta especificación define el uso de Architecture Decision Records (ADR) dentro de ESP Platform. Su objetivo es conservar de forma permanente las decisiones arquitectónicas relevantes adoptadas durante el desarrollo del proyecto. Los ADR permitirán comprender no solo qué se decidió, sino también por qué se tomó cada decisión. --- # 2. Objetivos Los ADR deberán permitir: - documentar decisiones importantes; - justificar alternativas descartadas; - preservar el conocimiento del proyecto; - facilitar futuras revisiones; - reducir la dependencia del conocimiento personal. --- # 3. Filosofía Toda decisión arquitectónica significativa deberá quedar registrada. Las decisiones pequeñas del desarrollo diario no requerirán un ADR. Solo deberán documentarse aquellas decisiones cuyo impacto sea relevante para la evolución del proyecto. --- # 4. Cuándo crear un ADR Se generará un ADR cuando exista una decisión relacionada con: - arquitectura; - tecnologías; - seguridad; - almacenamiento; - comunicaciones; - interfaces; - despliegue; - mantenimiento. --- # 5. Contenido mínimo Cada ADR deberá incluir como mínimo: - identificador; - fecha; - estado; - contexto; - decisión adoptada; - consecuencias. --- # 6. Estados Los ADR podrán encontrarse en alguno de los siguientes estados: - Propuesto. - Aprobado. - Sustituido. - Obsoleto. El historial deberá conservarse. --- # 7. Numeración Cada ADR dispondrá de un identificador único. Ejemplos: ADR-001 ADR-002 ADR-003 La numeración será secuencial. --- # 8. Relación con las SPEC Las SPEC definen la arquitectura general. Los ADR documentan decisiones concretas tomadas durante la implementación. Las SPEC constituyen documentos permanentes. Los ADR reflejan la evolución del proyecto. --- # 9. Modificación Un ADR aprobado no deberá modificarse. Si cambia una decisión, deberá generarse un nuevo ADR indicando cuál sustituye al anterior. Esto permitirá conservar el historial completo. --- # 10. Responsabilidad Los ADR podrán ser redactados por: - desarrolladores; - arquitectos; - Codex. La aprobación corresponderá al responsable del proyecto. --- # 11. Beneficios Los ADR permitirán: - comprender decisiones antiguas; - evitar repetir análisis ya realizados; - facilitar la incorporación de nuevos desarrolladores; - mejorar la continuidad del proyecto. --- # 12. Evolución futura La plataforma podrá incorporar herramientas para consultar automáticamente los ADR. También podrán relacionarse con: - incidencias; - versiones; - Roadmap; - documentación técnica. --- # 13. Relación con otras SPEC Esta especificación complementa especialmente: - SPEC-001 Filosofía; - SPEC-002 Arquitectura; - SPEC-015 Estándares de Desarrollo. Será aplicable a todas las decisiones arquitectónicas futuras. --- # 14. Estado documental **Estado:** Pendiente de aprobación **Dependencias:** - SPEC-001 a SPEC-017 **Desarrolla:** - Gestión de Architecture Decision Records **Implementación:** - Constituirá el procedimiento oficial para registrar las decisiones arquitectónicas relevantes de ESP Platform. -------------------------------------------------------------------------------- # SPEC-019 — Normas para Codex **Documento:** SPEC-019 **Título:** Normas para Codex **Proyecto:** ESP Platform **Versión:** 1.0 **Estado:** Borrador para revisión **Documento maestro final:** ESP_PLATFORM_ARCHITECTURE_v1.0.md --- # 1. Propósito Esta especificación define las normas generales que deberán seguir Codex y cualquier otro agente de inteligencia artificial durante el desarrollo de ESP Platform. Su objetivo es garantizar que toda implementación respete la arquitectura, los estándares y la filosofía del proyecto. --- # 2. Objetivos Codex deberá: - respetar la arquitectura definida; - mantener la coherencia del proyecto; - minimizar la deuda técnica; - documentar su trabajo; - facilitar el mantenimiento futuro. --- # 3. Filosofía Codex actuará como desarrollador del proyecto, no como diseñador de la arquitectura. La arquitectura se encuentra definida en las SPEC. Las modificaciones arquitectónicas deberán proponerse, nunca aplicarse automáticamente. --- # 4. Alcance Codex podrá: - implementar; - refactorizar; - documentar; - corregir errores; - realizar pruebas; - mejorar el código. No deberá modificar decisiones arquitectónicas sin aprobación expresa. --- # 5. Principios generales Toda implementación deberá respetar: - simplicidad; - modularidad; - claridad; - mantenibilidad; - reutilización. --- # 6. Arquitectura Antes de implementar cualquier funcionalidad, Codex deberá comprobar que resulta coherente con las SPEC existentes. En caso de conflicto deberá informar antes de continuar. --- # 7. Reutilización Antes de crear un nuevo componente deberá comprobar si ya existe uno reutilizable. La duplicación de código deberá evitarse siempre que sea posible. --- # 8. Documentación Toda funcionalidad relevante deberá ir acompañada de la documentación correspondiente. La documentación deberá mantenerse sincronizada con el código. --- # 9. Calidad Codex deberá priorizar: - código legible; - estructura clara; - responsabilidades bien definidas; - bajo acoplamiento. La claridad tendrá prioridad sobre soluciones excesivamente complejas. --- # 10. Validación Toda funcionalidad implementada deberá verificarse antes de considerarse terminada. Siempre que resulte posible deberán realizarse pruebas adecuadas. Los resultados deberán documentarse. --- # 11. Cambios Los cambios importantes deberán explicarse. Cuando una implementación implique decisiones relevantes, Codex deberá indicar: - qué cambia; - por qué cambia; - consecuencias. --- # 12. Comunicación Las respuestas deberán ser: - claras; - técnicas; - concisas; - orientadas a la implementación. Cuando exista incertidumbre deberá indicarse explícitamente. --- # 13. Gestión de incidencias Ante un problema, Codex deberá: - identificar la causa; - proponer alternativas; - justificar la solución adoptada. No deberá ocultar limitaciones conocidas. --- # 14. Relación con los ADR Cuando una decisión implique un cambio arquitectónico significativo, Codex deberá proponer la creación de un nuevo ADR. Las SPEC únicamente cambiarán mediante decisión expresa del responsable del proyecto. --- # 15. Relación con el Roadmap Codex deberá respetar el Roadmap definido para ESP Platform. No deberá adelantar fases sin autorización. Cada implementación deberá corresponder con la fase activa del proyecto. --- # 16. Beneficios Estas normas permitirán: - mantener la coherencia; - reducir errores; - facilitar revisiones; - preservar la arquitectura; - acelerar el desarrollo. --- # 17. Relación con otras SPEC Esta especificación complementa especialmente: - SPEC-015 Estándares de Desarrollo; - SPEC-018 ADR. Será aplicable durante todo el ciclo de vida del proyecto. --- # 18. Estado documental **Estado:** Pendiente de aprobación **Dependencias:** - SPEC-001 a SPEC-018 **Desarrolla:** - Normas de trabajo para Codex - Reglas de implementación **Implementación:** - Constituirá el marco de trabajo obligatorio para cualquier agente de inteligencia artificial que participe en el desarrollo de ESP Platform. -------------------------------------------------------------------------------- # SPEC-020 — Roadmap **Documento:** SPEC-020 **Título:** Roadmap **Proyecto:** ESP Platform **Versión:** 1.0 **Estado:** Borrador para revisión **Documento maestro final:** ESP_PLATFORM_ARCHITECTURE_v1.0.md --- # 1. Propósito Esta especificación define el Roadmap oficial de ESP Platform. Su objetivo es establecer el orden de ejecución del proyecto para garantizar un desarrollo progresivo, coherente y alineado con la arquitectura definida en las SPEC anteriores. El Roadmap constituye la planificación de alto nivel del proyecto. --- # 2. Filosofía El desarrollo deberá realizarse mediante fases incrementales. Cada fase deberá generar un resultado funcional antes de comenzar la siguiente. No deberán iniciarse fases posteriores mientras la fase actual no se considere suficientemente estable. --- # 3. MVP El primer objetivo del proyecto será disponer de un MVP completamente funcional. El MVP deberá permitir: - instalar firmware mediante Flasher Web; - arrancar un ESP32; - acceder a la interfaz web del dispositivo; - gestionar firmware desde el Backend. La finalidad del MVP será validar toda la arquitectura definida. --- # 4. Fase 1 Infraestructura. Objetivos: - crear la máquina virtual; - desplegar el Backend; - configurar PostgreSQL; - desplegar el Frontend; - preparar el repositorio de firmware. Resultado esperado: Infraestructura completamente operativa. --- # 5. Fase 2 Flasher Web. Objetivos: - cargar firmware; - seleccionar hardware; - conectar mediante USB; - flashear un ESP32; - verificar el resultado. Resultado esperado: Primer dispositivo funcionando. --- # 6. Fase 3 Edge OS. Objetivos: - estructura común del firmware; - configuración; - interfaz web; - MQTT; - Modbus TCP. Resultado esperado: Primer firmware oficial. --- # 7. Fase 4 Provisioning. Objetivos: - alta automática; - identidad; - QR; - registro en Backend. Resultado esperado: Primer dispositivo integrado completamente en ESP Platform. --- # 8. Fase 5 OTA. Objetivos: - actualización remota; - verificación; - rollback. Resultado esperado: Actualizaciones seguras. --- # 9. Fase 6 Recovery. Objetivos: - recuperación; - Factory Reset; - diagnóstico. Resultado esperado: Arquitectura resiliente. --- # 10. Fase 7 Fleet Management. Objetivos: - inventario; - monitorización; - operaciones remotas. Resultado esperado: Administración centralizada. --- # 11. Fase 8 Aplicaciones. Desarrollo progresivo de: - AZ-TEMP; - AZ-POWER; - AZ-NFC; - AZ-IO; - AZ-RELAY. Cada aplicación reutilizará Edge OS. --- # 12. Fase 9 Industrialización. Objetivos: - hardware propio; - fabricación; - certificaciones; - documentación; - soporte. Resultado esperado: Producto comercial. --- # 13. Fase 10 Modelo SaaS. Objetivos: - multiempresa; - multiusuario; - licencias; - suscripciones; - despliegue cloud. Resultado esperado: ESP Platform como servicio. --- # 14. Prioridades El orden de prioridad será siempre: 1. Arquitectura. 2. Estabilidad. 3. Funcionalidad. 4. Rendimiento. 5. Optimización. Nunca deberá sacrificarse la arquitectura por acelerar una implementación. --- # 15. Gestión del conocimiento Durante todo el desarrollo deberán mantenerse actualizados: - SPEC; - ADR; - documentación técnica; - Roadmap. La documentación formará parte del producto. --- # 16. Evolución El Roadmap podrá ampliarse. Las nuevas fases deberán respetar la arquitectura definida en las SPEC anteriores. Las modificaciones importantes deberán documentarse mediante ADR. --- # 17. Finalización Se considerará completada una fase cuando: - los objetivos se hayan alcanzado; - las pruebas sean satisfactorias; - la documentación esté actualizada. Solo entonces podrá iniciarse la siguiente fase. --- # 18. Relación con otras SPEC Esta especificación resume y coordina todas las SPEC anteriores. Constituye el documento de referencia para planificar el desarrollo de ESP Platform. --- # 19. Estado documental **Estado:** Pendiente de aprobación **Dependencias:** - SPEC-001 a SPEC-019 **Desarrolla:** - Planificación general - Roadmap oficial **Implementación:** - Constituirá la guía oficial para la ejecución del proyecto y la priorización de todas las fases de desarrollo de ESP Platform. --------------------------------------------------------------------------------