# HomeCore ## Especificación técnica inicial para desarrollo **Versión:** 0.1 **Estado:** Documento de arranque / MVP **Objetivo:** Servir como especificación base para iniciar el desarrollo de HomeCore en Codex. **Enfoque:** Hogares, residentes y propietarios particulares. --- ## 1. Resumen ejecutivo HomeCore es una plataforma de hogar inteligente orientada al público general. Su objetivo es permitir que una persona controle, monitoree y automatice elementos de su casa desde una interfaz sencilla, sin tener que entender conceptos técnicos como ESP32, GPIO, WebSocket, MQTT o redes IoT. La plataforma conecta dispositivos físicos instalados en el hogar —microcontroladores, sensores, relés, switches, cerraduras compatibles y otros equipos— con un servidor central accesible por Internet. Desde una aplicación web responsive o PWA, el residente puede consultar el estado de su casa, recibir alertas, revisar históricos y ejecutar acciones remotas autorizadas. A diferencia de PropertyCore, que está diseñado para empresas administradoras de múltiples propiedades, HomeCore debe priorizar: - Facilidad de uso. - Instalación y configuración sencilla. - Experiencia móvil. - Privacidad del residente. - Automatizaciones domésticas simples. - Control por habitaciones y zonas. - Alertas útiles y fáciles de entender. - Funcionamiento seguro ante pérdida de Internet. El MVP utilizará un servidor Bitnami como infraestructura principal. Apache gestionará HTTPS/WSS y actuará como reverse proxy; PHP expondrá la API y lógica de usuarios; MySQL almacenará configuración, telemetría, escenas, automatizaciones y auditoría; y un servicio Node.js mantendrá conexiones WebSocket persistentes con los dispositivos HomeCore. --- ## 2. Posicionamiento comercial **Nombre:** HomeCore **Categoría:** Smart Home Platform **Descripción:** Plataforma para monitorear, controlar y automatizar tu hogar desde un solo lugar. **Público objetivo:** Personas, familias, propietarios y residentes que buscan una solución sencilla de hogar inteligente. HomeCore no debe venderse como un proyecto de electrónica ni como “una ESP32 conectada a Internet”. El usuario final debe percibirlo como una plataforma completa de hogar inteligente. ### Propuesta de valor > Tu hogar conectado, seguro y bajo control desde un solo lugar. ### Mensajes comerciales posibles - Controla tu hogar estés donde estés. - Automatiza lo cotidiano. - Recibe alertas antes de que un problema crezca. - Monitorea agua, clima, accesos, energía y más. - Convierte tu casa en un hogar realmente inteligente. ### Familia de productos - **HomeCore Cloud:** backend, API, WebSocket, autenticación y datos. - **HomeCore App:** interfaz web/PWA para residentes. - **HomeCore Hub:** controlador o gateway principal instalado en el hogar. - **HomeCore Sensors:** sensores de temperatura, humedad, agua, movimiento, puertas, etc. - **HomeCore Control:** relés, switches y controladores de equipos. - **HomeCore Alerts:** alertas y notificaciones. - **HomeCore Access:** integración con accesos y cerraduras compatibles. - **HomeCore Scenes:** escenas y automatizaciones domésticas. --- ## 3. Problema que resuelve En un hogar moderno existen múltiples equipos, sensores y dispositivos que suelen funcionar de forma aislada o requieren aplicaciones distintas. HomeCore busca centralizar en una sola plataforma información y control como: - Temperatura y humedad. - Estado de puertas y ventanas. - Detección de fugas de agua. - Nivel de cisterna o tinaco. - Estado de bombas. - Iluminación. - Ventiladores. - Equipos eléctricos autorizados. - Alberca o jacuzzi. - Consumo eléctrico. - Movimiento o presencia. - Estado de dispositivos conectados. - Alertas técnicas del hogar. También debe permitir acciones remotas seguras, por ejemplo: - Encender o apagar una luz. - Activar un ventilador. - Encender o apagar una bomba. - Cambiar un setpoint permitido. - Ejecutar una escena. - Activar un modo “Fuera de casa”. - Activar un modo “Noche”. --- ## 4. Principios de experiencia de usuario HomeCore está orientado a usuarios no técnicos. El usuario debe pensar en: - Mi casa. - Sala. - Cocina. - Recámara. - Alberca. - Puerta principal. - Luces. - Temperatura. - Agua. No debe pensar en: - GPIO 23. - ESP32-001. - Payload JSON. - WebSocket. - Dirección IP. - Topic. - Relay Channel 4. La interfaz debe traducir la complejidad técnica a conceptos familiares. Ejemplo: ```text MALA EXPERIENCIA ESP32-0001 GPIO 23: HIGH DHT22: 26.4 RELAY_1: ON BUENA EXPERIENCIA Sala Temperatura: 26.4 °C Luz principal: Encendida [ Apagar luz ] ``` --- ## 5. Alcance del MVP El primer MVP debe demostrar el flujo completo entre el hogar, HomeCore Cloud y el residente. ### Incluido 1. Registro e inicio de sesión de usuario. 2. Creación de un hogar. 3. Soporte para uno o varios hogares por cuenta. 4. Registro de habitaciones o zonas. 5. Registro y aprovisionamiento de dispositivos ESP32. 6. Autenticación de dispositivos mediante identificador y secreto/token. 7. Conexión WSS persistente entre ESP32 y HomeCore Cloud. 8. Estado Online/Offline y `last_seen`. 9. Recepción de telemetría de sensores. 10. Almacenamiento de lecturas en MySQL. 11. Dashboard principal del hogar. 12. Vista por habitación. 13. Envío de comandos desde la app hacia un dispositivo. 14. Confirmación de comandos por el dispositivo. 15. Registro de actividad. 16. Alertas básicas. 17. Usuarios del hogar con permisos simples. 18. Escenas básicas. 19. Automatizaciones sencillas basadas en reglas. 20. Diseño responsive/mobile-first. ### Fuera del MVP inicial - Aplicación móvil nativa iOS/Android. - Integración con Alexa, Google Home, Siri o Matter. - Suscripciones y facturación. - Machine learning. - Reconocimiento de voz propio. - Editor visual complejo de automatizaciones. - Geofencing avanzado. - Integración masiva con dispositivos de terceros. - OTA firmware completo. Estas funciones deben quedar contempladas arquitectónicamente, pero no son necesarias para la primera versión funcional. --- ## 6. Arquitectura general ```text HOMECORE INTERNET │ ┌────────────────┴────────────────┐ │ │ │ │ RESIDENTE HOGAR │ │ ▼ ▼ HomeCore App ESP32 / HomeCore Hub │ │ │ HTTPS │ WSS │ │ └──────────────┐ ┌──────────────┘ ▼ ▼ HOMECORE CLOUD Apache / TLS │ ┌──────────┼──────────┐ │ │ │ ▼ ▼ ▼ API WebSocket PHP │ Server │ └──────────┬──────────┘ │ ▼ MySQL │ ┌───────────────────┼────────────────────┐ ▼ ▼ ▼ Hogares Dispositivos Usuarios Habitaciones Sensores Alertas Escenas Comandos Actividad Automatizaciones Históricos Permisos ``` ### Principio fundamental Los dispositivos HomeCore deben iniciar la conexión hacia HomeCore Cloud. El sistema no debe requerir: - Abrir puertos en el router del hogar. - Tener IP pública fija. - Exponer la ESP32 directamente a Internet. --- ## 7. Capas del sistema ### 7.1 Capa física del hogar Incluye los elementos instalados en la vivienda: - ESP32 u otros microcontroladores compatibles. - Sensores digitales y analógicos. - Relés. - Módulos MOSFET cuando aplique. - Contactores para cargas que lo requieran. - Switches físicos. - Sensores de puerta/ventana. - Sensores de fuga. - Sensores de temperatura/humedad. - Medidores eléctricos compatibles. - Equipos domésticos controlables. HomeCore no debe asumir que una carga de potencia puede conectarse directamente a un GPIO. La parte eléctrica debe usar interfaces apropiadas y mantener separado el circuito lógico del circuito de potencia. ### 7.2 Capa de firmware El firmware de una ESP32 debe: 1. Conectarse a Wi-Fi. 2. Resolver el dominio de HomeCore. 3. Abrir conexión WSS. 4. Autenticarse como dispositivo. 5. Mantener heartbeat/keepalive. 6. Leer sensores. 7. Publicar telemetría. 8. Recibir comandos. 9. Validar comandos permitidos. 10. Ejecutarlos localmente. 11. Responder con ACK o error. 12. Reconectarse automáticamente. 13. Mantener estados seguros si pierde conexión. 14. Permitir controles físicos locales cuando existan. ### 7.3 Capa de comunicación Protocolos iniciales: - HTTPS para API REST y HomeCore App. - WSS para comunicación persistente en tiempo real. - JSON para mensajes del MVP. Apache debe recibir tráfico TLS en el puerto 443 y actuar como reverse proxy hacia Node.js en localhost. ### 7.4 HomeCore Cloud Infraestructura inicial: - Linux / Bitnami. - Apache. - Certificado TLS válido. - PHP. - MySQL. - Node.js. - Servicio WebSocket. Responsabilidades: - Autenticación de usuarios. - Autenticación de dispositivos. - Gestión de hogares. - Gestión de habitaciones. - Gestión de dispositivos. - Enrutamiento de comandos. - Recepción de telemetría. - Persistencia. - Alertas. - Escenas. - Automatizaciones. - Registro de actividad. - Estado de conectividad. ### 7.5 HomeCore App Debe ser mobile-first. El residente debe poder abrir la aplicación desde el teléfono y entender el estado general de su hogar en segundos. Ejemplo: ```text HOMECORE Mi Casa Todo está bien ✓ Temperatura 24 °C Puertas abiertas 0 Alertas 0 Dispositivos 12 online Favoritos Luz sala ON [ Apagar ] Bomba cisterna OFF [ Encender ] A/C recámara 23 °C Habitaciones Sala Cocina Recámara principal Terraza Alberca ``` --- ## 8. Modelo de cuenta y hogar HomeCore no necesita una arquitectura multiempresa como PropertyCore. La jerarquía principal será: ```text CUENTA / USUARIO │ └── HOGAR ├── HABITACIONES │ ├── DISPOSITIVOS │ ├── SENSORES │ └── ACTUADORES │ ├── ESCENAS ├── AUTOMATIZACIONES ├── ALERTAS └── MIEMBROS ``` Una cuenta puede tener varios hogares: ```text Oscar ├── Casa principal ├── Departamento └── Casa de vacaciones ``` Un hogar también puede compartirse con otros usuarios. --- ## 9. Usuarios y permisos Roles iniciales sugeridos: ### Owner Propietario principal del hogar. Puede: - Configurar el hogar. - Invitar usuarios. - Registrar dispositivos. - Crear automatizaciones. - Ejecutar controles. - Consultar históricos. ### Resident Miembro del hogar. Puede: - Consultar dispositivos. - Ejecutar controles autorizados. - Usar escenas. - Recibir alertas. ### Guest Acceso limitado. Ejemplo: - Encender luces. - Controlar clima. - Sin acceso a configuración. - Sin acceso a históricos sensibles. ### Installer / Support Rol temporal o técnico para instalación y soporte. Debe poder limitarse por tiempo y por dispositivo. La autorización siempre debe validarse en backend. --- ## 10. Habitaciones y zonas El hogar debe organizarse visualmente por espacios. Ejemplos: - Sala. - Cocina. - Comedor. - Recámara principal. - Recámara 2. - Oficina. - Jardín. - Terraza. - Alberca. - Cochera. - Cuarto de máquinas. Cada dispositivo puede pertenecer a una habitación o zona. Ejemplo: ```text Sala ├── Luz principal ├── Luz ambiental ├── Temperatura ├── Humedad └── Ventilador ``` --- ## 11. Modelo de datos inicial Los nombres son preliminares y pueden refinarse durante implementación. ### users - id - name - email - password_hash - status - created_at - updated_at ### homes - id - owner_user_id - name - code - timezone - status - created_at - updated_at ### home_members - id - home_id - user_id - role - status - invited_at nullable - accepted_at nullable ### rooms - id - home_id - name - room_type - sort_order - status ### devices - id - home_id - room_id nullable - device_uid - name - device_type - firmware_version - auth_secret_hash - status - connection_status - last_seen_at - last_ip - created_at - updated_at ### sensor_channels - id - device_id - channel_key - name - sensor_type - data_type - unit - min_value nullable - max_value nullable - enabled ### actuator_channels - id - device_id - channel_key - name - actuator_type - safe_state - enabled ### sensor_readings - id - device_id - sensor_channel_id - value_numeric nullable - value_text nullable - recorded_at - received_at ### commands - id - home_id - device_id - actuator_channel_id nullable - command_uid - command_type - payload_json - requested_by_user_id nullable - source - status - requested_at - sent_at nullable - acknowledged_at nullable - completed_at nullable - error_message nullable Estados sugeridos: - queued - sent - acknowledged - completed - failed - expired - cancelled ### alerts - id - home_id - device_id nullable - sensor_channel_id nullable - severity - alert_type - title - message - status - triggered_at - acknowledged_at nullable - acknowledged_by nullable - resolved_at nullable ### scenes - id - home_id - name - icon nullable - status - created_by_user_id - created_at - updated_at ### scene_actions - id - scene_id - device_id - actuator_channel_id - action_type - value_json - sort_order ### automations - id - home_id - name - enabled - trigger_type - trigger_config_json - conditions_json nullable - created_by_user_id - created_at - updated_at ### automation_actions - id - automation_id - action_type - target_type - target_id nullable - action_config_json - sort_order ### activity_logs - id - home_id - user_id nullable - device_id nullable - event_type - entity_type - entity_id nullable - description - metadata_json - ip_address nullable - created_at --- ## 12. Protocolo WebSocket inicial El protocolo debe incluir `type` y versión de protocolo. ### Autenticación del dispositivo Dispositivo -> servidor: ```json { "type": "device.auth", "protocol": 1, "device_uid": "HC-ESP32-0001", "token": "DEVICE_SECRET" } ``` Servidor -> dispositivo: ```json { "type": "device.auth.result", "success": true, "server_time": "2026-09-10T00:00:00-07:00" } ``` ### Heartbeat ```json { "type": "device.heartbeat", "device_uid": "HC-ESP32-0001", "uptime": 8412, "rssi": -58 } ``` ### Telemetría ```json { "type": "telemetry.publish", "device_uid": "HC-ESP32-0001", "timestamp": "2026-09-10T00:02:10-07:00", "readings": { "temperature": 24.6, "humidity": 55.2, "light_state": true, "leak_detected": false } } ``` ### Comando servidor -> dispositivo ```json { "type": "command.execute", "command_uid": "CMD-01JXYZ123", "channel": "living_room_light", "action": "set", "value": false, "expires_at": "2026-09-10T00:03:00-07:00" } ``` ### ACK dispositivo -> servidor ```json { "type": "command.ack", "command_uid": "CMD-01JXYZ123", "accepted": true } ``` ### Resultado final ```json { "type": "command.result", "command_uid": "CMD-01JXYZ123", "success": true, "state": { "living_room_light": false } } ``` Cada comando debe tener un identificador único para evitar doble ejecución. --- ## 13. API REST inicial Ruta base sugerida: ```text /api/v1/ ``` ### Autenticación - POST `/api/v1/auth/register` - POST `/api/v1/auth/login` - POST `/api/v1/auth/logout` - GET `/api/v1/auth/me` ### Hogares - GET `/api/v1/homes` - POST `/api/v1/homes` - GET `/api/v1/homes/{id}` - PATCH `/api/v1/homes/{id}` ### Miembros - GET `/api/v1/homes/{homeId}/members` - POST `/api/v1/homes/{homeId}/members/invite` - PATCH `/api/v1/homes/{homeId}/members/{memberId}` - DELETE `/api/v1/homes/{homeId}/members/{memberId}` ### Habitaciones - GET `/api/v1/homes/{homeId}/rooms` - POST `/api/v1/homes/{homeId}/rooms` - PATCH `/api/v1/rooms/{id}` ### Dispositivos - GET `/api/v1/homes/{homeId}/devices` - POST `/api/v1/homes/{homeId}/devices` - GET `/api/v1/devices/{id}` - PATCH `/api/v1/devices/{id}` - POST `/api/v1/devices/{id}/rotate-secret` ### Telemetría - GET `/api/v1/devices/{id}/telemetry/latest` - GET `/api/v1/devices/{id}/telemetry/history` ### Comandos - POST `/api/v1/devices/{id}/commands` - GET `/api/v1/commands/{commandUid}` ### Alertas - GET `/api/v1/alerts` - POST `/api/v1/alerts/{id}/acknowledge` - POST `/api/v1/alerts/{id}/resolve` ### Escenas - GET `/api/v1/homes/{homeId}/scenes` - POST `/api/v1/homes/{homeId}/scenes` - PATCH `/api/v1/scenes/{id}` - POST `/api/v1/scenes/{id}/execute` ### Automatizaciones - GET `/api/v1/homes/{homeId}/automations` - POST `/api/v1/homes/{homeId}/automations` - PATCH `/api/v1/automations/{id}` - DELETE `/api/v1/automations/{id}` ### Dashboard - GET `/api/v1/homes/{homeId}/summary` - GET `/api/v1/homes/{homeId}/favorites` - GET `/api/v1/homes/{homeId}/activity` --- ## 14. HomeCore App / Dashboard ### Pantalla de inicio Debe mostrar información resumida y accionable. ```text HOMECORE Buenos días Mi Casa ✓ Todo está bien Clima interior 24 °C Puertas abiertas 0 Alertas 0 Dispositivos online 12 FAVORITOS Sala · Luz principal ON Recámara · A/C 23 °C Cisterna 78 % Puerta principal Cerrada ``` ### Vista por habitación ```text SALA Temperatura 24.6 °C Humedad 55 % Luz principal ON [ Apagar ] Luz ambiental OFF [ Encender ] Ventilador OFF [ Encender ] ``` ### Vista del hogar Secciones sugeridas: - Inicio. - Habitaciones. - Favoritos. - Escenas. - Automatizaciones. - Alertas. - Energía. - Actividad. - Configuración. ### Configuración - Nombre del hogar. - Zona horaria. - Miembros. - Habitaciones. - Dispositivos. - Notificaciones. - Privacidad. --- ## 15. Favoritos El usuario debe poder marcar controles o sensores como favoritos. Ejemplos: - Luz principal. - Puerta principal. - Bomba de agua. - Temperatura de recámara. - Alberca. Esto permite construir una pantalla principal personalizada sin exponer toda la estructura técnica. --- ## 16. Escenas Una escena ejecuta varias acciones a la vez. Ejemplos: ### Buenas noches ```text Apagar luces de sala Apagar luces de cocina Apagar terraza Ajustar A/C recámara a 23 °C Verificar puerta principal ``` ### Salir de casa ```text Apagar iluminación seleccionada Apagar ventiladores Activar modo ahorro Activar alertas de movimiento ``` ### Llegar a casa ```text Encender luz exterior Encender sala Ajustar clima ``` El MVP debe permitir escenas simples basadas en acciones ordenadas. --- ## 17. Automatizaciones HomeCore debe permitir reglas simples del tipo: ```text SI pasa X Y se cumple Y ENTONCES hacer Z ``` Ejemplos: ### Temperatura ```text SI temperatura > 28 °C ENTONCES encender ventilador ``` ### Fuga ```text SI leak_detected == true ENTONCES crear alerta crítica ``` ### Horario ```text SI son las 19:00 ENTONCES encender luz exterior ``` ### Nivel de agua ```text SI cisterna < 20 % ENTONCES enviar alerta ``` El MVP no requiere un editor visual complejo; puede usar formularios simples. --- ## 18. Sistema de alertas Las alertas deben estar escritas para residentes, no para técnicos. Mala alerta: ```text HC-ESP32-0004 CHANNEL_2 BOOLEAN TRUE ``` Buena alerta: ```text ⚠ Posible fuga de agua Se detectó agua en el sensor de la cocina. Revisa el área lo antes posible. ``` Severidades iniciales: - Info. - Warning. - Critical. Ejemplos: - Fuga detectada -> Critical. - Dispositivo importante offline -> Warning. - Cisterna baja -> Warning. - Temperatura anormal -> Warning. --- ## 19. Requisitos de seguridad y privacidad HomeCore estará dentro del hogar de una persona, por lo que privacidad y seguridad deben ser parte central del diseño. ### Servidor - Todo tráfico público mediante HTTPS/WSS. - Node.js escuchando preferentemente en `127.0.0.1`. - Apache como reverse proxy. - Secretos fuera del repositorio. - Variables sensibles en `.env`. - MySQL no expuesto públicamente. - Contraseñas con hash seguro. - Tokens de dispositivo no almacenados en texto plano. - Rate limiting. - Validación estricta de payloads. - Logs sin secretos. ### Privacidad El backend debe tratar como información privada: - Estado de presencia. - Horarios de actividad. - Apertura de puertas. - Históricos de dispositivos. - Consumo del hogar. - Información de miembros. Los usuarios solo deben acceder a hogares de los que sean miembros autorizados. ### Comandos físicos Los comandos deben: - Ser autorizados. - Tener `command_uid`. - Poder expirar. - Tener ACK y resultado. - Registrar actividad cuando sea apropiado. - Ser idempotentes cuando sea posible. - Definir un estado seguro ante pérdida de conexión. Para equipos de riesgo deben existir protecciones físicas independientes del software. --- ## 20. Funcionamiento local y tolerancia a fallas HomeCore no debe volver inutilizable un hogar si falla Internet. Principios: 1. Los interruptores físicos deben seguir funcionando cuando sea posible. 2. Automatizaciones críticas pueden ejecutarse localmente en el HomeCore Hub/ESP32. 3. Las cargas deben volver a un estado seguro después de reinicio. 4. La pérdida de WSS no debe activar acciones inesperadas. 5. Un comando expirado no debe ejecutarse al reconectar. Firmware: - Reconexión Wi-Fi. - Reconexión WSS con backoff. - Heartbeat. - Watchdog. - Manejo de mensajes inválidos. - Prevención de comandos duplicados. - Estado seguro después de reboot. Servidor: - Registro de conexiones activas. - Timeout de heartbeat. - Limpieza de conexiones muertas. - Expiración de comandos. - Distinción entre `sent`, `acknowledged` y `completed`. --- ## 21. Servicio WebSocket El servicio Node.js será responsable de la comunicación en tiempo real. Responsabilidades: - Aceptar conexiones proxied por Apache. - Autenticar dispositivos. - Mantener mapa `device_uid -> socket`. - Registrar Online/Offline. - Recibir telemetría. - Enviar telemetría a persistencia/backend. - Recibir comandos del backend. - Enviar comandos al dispositivo. - Procesar ACK y resultados. - Manejar desconexiones. No debe concentrar toda la lógica del negocio. --- ## 22. Reverse proxy Bitnami / Apache Arquitectura conceptual: ```text Internet │ │ 443 HTTPS / WSS ▼ Apache Bitnami │ ├── / -> HomeCore App / PHP ├── /api/ -> PHP API └── /ws/ -> ws://127.0.0.1:8080 ``` El puerto 8080 no debe exponerse públicamente. La configuración exacta se documentará durante deployment y dependerá de la instalación real de Bitnami. --- ## 23. Stack técnico inicial sugerido ### Backend/API - PHP 8.x compatible con el Bitnami instalado. - MySQL/MariaDB. - API REST JSON. ### Tiempo real - Node.js LTS. - Biblioteca WebSocket estable. - Servicio gestionado por systemd, PM2 o equivalente. ### Frontend MVP: - HTML5. - CSS. - JavaScript. - Bootstrap o framework UI ligero. - Diseño responsive/mobile-first. - PWA opcional desde la primera etapa si no agrega complejidad excesiva. ### Firmware - ESP32. - Arduino framework o ESP-IDF. - Wi-Fi. - WSS/TLS. - JSON. --- ## 24. Estructura inicial del repositorio Se recomienda monorepo. ```text homecore/ │ ├── README.md ├── docs/ │ ├── architecture.md │ ├── websocket-protocol.md │ ├── api.md │ ├── database.md │ ├── deployment-bitnami.md │ ├── security.md │ └── ux-principles.md │ ├── backend/ │ ├── public/ │ ├── src/ │ ├── config/ │ ├── migrations/ │ ├── tests/ │ └── .env.example │ ├── websocket-server/ │ ├── src/ │ ├── tests/ │ ├── package.json │ └── .env.example │ ├── app/ │ ├── assets/ │ ├── js/ │ ├── css/ │ └── views/ │ ├── firmware/ │ ├── esp32-reference/ │ ├── include/ │ ├── src/ │ └── README.md │ ├── database/ │ ├── schema.sql │ └── seed.sql │ └── deployment/ ├── apache/ ├── systemd/ └── scripts/ ``` --- ## 25. Convenciones iniciales ### IDs - IDs internos: enteros o UUID según decisión de implementación. - Dispositivos con UID estable, por ejemplo `HC-ESP32-0001`. - Comandos con UID único. ### Fechas - Guardar timestamps en UTC cuando sea práctico. - Presentar fechas según timezone del hogar. - Cada hogar debe tener `timezone`. ### API - JSON. - Versionado `/api/v1`. - Códigos HTTP correctos. - Errores estructurados. Ejemplo: ```json { "error": { "code": "DEVICE_OFFLINE", "message": "El dispositivo no está disponible en este momento." } } ``` --- ## 26. Observabilidad Registrar: - Inicio/parada del WebSocket Server. - Conexión/desconexión de dispositivos. - Fallos de autenticación. - Firmware. - Errores de payload. - Comandos. - ACK/resultados. - Excepciones. Evitar registrar: - Contraseñas. - Tokens completos. - Secretos de dispositivos. --- ## 27. Primer caso de uso del MVP ### Habitación inteligente de demostración Hardware de referencia: - 1 ESP32. - Sensor de temperatura/humedad. - Sensor de fuga opcional. - Relé con LED o lámpara de baja potencia durante pruebas. - Switch físico opcional. HomeCore App: ```text Mi Casa Sala Temperatura: 24.6 °C Humedad: 55 % Fuga: No Luz principal: ENCENDIDA Dispositivo: ONLINE [ APAGAR LUZ ] ``` Flujo de telemetría: ```text Sensor -> ESP32 -> WSS -> Node -> Backend/DB -> HomeCore App ``` Flujo de comando: ```text HomeCore App -> API -> WebSocket Server -> WSS -> ESP32 -> Relé │ └-> ACK / Resultado ``` Este prototipo valida: - Login. - Hogar. - Habitación. - Dispositivo. - Sensor. - Actuador. - Telemetría. - WSS. - Comandos. - ACK. - Estado Online/Offline. - Interfaz mobile-first. --- ## 28. Fases de desarrollo ### Fase 0 - Base del repositorio - Crear estructura. - README. - `.gitignore`. - `.env.example`. - Convenciones. - Documentación inicial. ### Fase 1 - Usuarios y hogares - Registro. - Login. - Homes. - Miembros. - Roles. - Habitaciones. ### Fase 2 - Dispositivos - Registro. - Aprovisionamiento. - Sensores. - Actuadores. ### Fase 3 - WebSocket Server - Node.js. - Auth de dispositivo. - Online/Offline. - Heartbeat. ### Fase 4 - Firmware ESP32 - Wi-Fi. - WSS. - Auth. - Heartbeat. - Reconexión. - Telemetría simulada. ### Fase 5 - Telemetría real - Sensor real. - Persistencia. - Última lectura. - Historial. ### Fase 6 - Comandos - Endpoint API. - Enrutamiento. - ACK. - Resultado. - Expiración. ### Fase 7 - HomeCore App - Home dashboard. - Habitaciones. - Favoritos. - Controles. - Estado en tiempo real. ### Fase 8 - Alertas - Reglas básicas. - Warning/Critical. - Acknowledge/Resolve. ### Fase 9 - Escenas - Crear escena. - Editar escena. - Ejecutar escena. ### Fase 10 - Automatizaciones - Trigger simple. - Condición simple. - Acción. - Habilitar/deshabilitar. ### Fase 11 - Hardening y deployment - TLS/WSS. - Firewall. - Servicios persistentes. - Backups. - Logs. - Pruebas de reconexión. - Revisión de permisos. --- ## 29. Criterios de aceptación del MVP El MVP se considera funcional cuando: 1. Un usuario puede registrarse e iniciar sesión. 2. Puede crear un hogar. 3. Puede crear al menos una habitación. 4. Puede registrar un dispositivo. 5. Una ESP32 puede autenticarse mediante WSS. 6. HomeCore muestra el dispositivo como Online. 7. La ESP32 envía una lectura de temperatura. 8. La lectura aparece en la app y se almacena. 9. El usuario autorizado envía un comando de encendido/apagado. 10. El comando llega a la ESP32. 11. La ESP32 devuelve ACK/resultado. 12. La interfaz refleja el nuevo estado. 13. Si la ESP32 se desconecta, HomeCore muestra Offline. 14. Un usuario no autorizado no puede acceder al hogar. 15. Se puede crear y ejecutar una escena básica. 16. Se puede crear una automatización simple. 17. Se puede generar una alerta básica. 18. Todo tráfico externo utiliza HTTPS/WSS. 19. La interfaz funciona correctamente en móvil. --- ## 30. Pruebas mínimas ### Backend - Registro válido/inválido. - Login correcto/incorrecto. - Acceso a hogares propios. - Acceso denegado a hogares ajenos. - Invitaciones y roles. - Validación de payloads. ### WebSocket - Auth válida. - Auth inválida. - UID inexistente. - Reconexión. - Socket duplicado. - Timeout de heartbeat. - Payload inválido. ### Comandos - Dispositivo Online. - Dispositivo Offline. - Comando expirado. - ACK. - Error del dispositivo. - Reintento sin doble ejecución. ### Firmware - Boot sin Wi-Fi. - Pérdida de Wi-Fi. - Pérdida de servidor. - Reconexión. - Reinicio durante comando. - Mensaje malformado. ### App - Responsive móvil. - Estado Online/Offline. - Favoritos. - Habitaciones. - Escenas. - Alertas. --- ## 31. Diferencias clave respecto a PropertyCore | Área | PropertyCore | HomeCore | |---|---|---| | Cliente | Empresas | Público general | | Estructura | Empresa -> propiedades | Usuario -> hogares | | Usuario principal | Administrador / mantenimiento | Residente / propietario | | UX | Operacional | Simple y cotidiana | | Vista principal | Portafolio de propiedades | Mi hogar | | Roles | Company Admin, Manager, Maintenance | Owner, Resident, Guest | | Organización | Propiedad / sistemas | Hogar / habitaciones | | Automatización | Operación y mantenimiento | Rutinas domésticas | | Lenguaje | Técnico-operacional | Familiar y simple | | Prioridad | Escala y auditoría empresarial | Experiencia, privacidad y comodidad | La infraestructura técnica puede compartir principios y componentes con PropertyCore, pero **HomeCore debe ser un producto independiente a nivel de experiencia, modelo de usuario y lenguaje comercial**. --- ## 32. Decisiones que Codex NO debe asumir sin documentar Antes de introducir una dependencia o patrón importante, documentar la decisión. En particular: - Framework PHP definitivo. - Estrategia de sesiones/JWT. - Biblioteca WebSocket Node. - ORM o SQL directo. - Migraciones. - Framework frontend. - PWA desde MVP o fase posterior. - Comunicación interna PHP <-> Node. - Estrategia de secretos. - Retención de telemetría. - OTA firmware. - Implementación de notificaciones push. - Estrategia de automatizaciones locales vs cloud. Preferir soluciones simples, mantenibles y compatibles con Bitnami. --- ## 33. Principios de desarrollo 1. Experiencia simple para usuarios no técnicos. 2. Seguridad y privacidad por defecto. 3. Mobile-first. 4. El dispositivo inicia la conexión. 5. No exponer ESP32 directamente a Internet. 6. No abrir el puerto interno de Node al público. 7. No almacenar secretos en Git. 8. No confiar en frontend para autorización. 9. Mantener controles físicos locales cuando sea posible. 10. Diseñar comandos para fallar de manera segura. 11. Automatizaciones críticas deben considerar ejecución local. 12. Evitar que una caída de Internet inutilice funciones esenciales. 13. Separar lógica de negocio del transporte WebSocket. 14. Evitar complejidad innecesaria en el MVP. 15. Mostrar al usuario conceptos del hogar, no detalles del hardware. --- # 34. Instrucciones iniciales para Codex Este documento es la especificación base del proyecto **HomeCore**. Al iniciar el repositorio: 1. Lee este documento completo antes de modificar archivos. 2. No implementes toda la plataforma de una sola vez. 3. Trabaja por fases pequeñas y verificables. 4. Mantén `docs/decisions.md` con decisiones arquitectónicas. 5. No incluyas credenciales reales en código, SQL, README o commits. 6. Genera `.env.example` solo con nombres de variables y valores ficticios. 7. Mantén compatibilidad con deployment Bitnami + Apache + MySQL + PHP + Node.js. 8. El WebSocket Server debe ejecutarse como proceso independiente en localhost. 9. Implementa permisos por hogar desde las primeras rutas. 10. Diseña la interfaz pensando primero en móvil. 11. No expongas términos técnicos de hardware al usuario final salvo en vistas de soporte. 12. Añade pruebas para flujos críticos antes de avanzar de fase. ## Primera tarea para Codex **Objetivo:** crear el esqueleto del repositorio y preparar la Fase 1 sin implementar todavía hardware real. ### Entregables 1. Crear estructura inicial del monorepo `homecore/`. 2. Crear `README.md` con instrucciones locales. 3. Crear `docs/architecture.md` a partir de este documento. 4. Crear `docs/decisions.md`. 5. Crear `docs/ux-principles.md`. 6. Crear `.gitignore` adecuado para PHP, Node, firmware y secretos. 7. Crear `.env.example` para backend y WebSocket Server. 8. Definir esquema/migraciones iniciales para: - users - homes - home_members - rooms - devices - sensor_channels - actuator_channels - sensor_readings - commands - alerts - scenes - scene_actions - automations - automation_actions - activity_logs 9. Crear endpoint de salud: `GET /api/v1/health`. 10. Crear servicio WebSocket mínimo con endpoint lógico `/ws` que pueda arrancar localmente sin aceptar comandos físicos todavía. 11. Crear una vista inicial mobile-first de login y Home dashboard con datos mock. 12. Crear pruebas básicas de arranque. 13. Documentar cómo ejecutar backend, app y WebSocket Server en desarrollo. ### Restricciones - No implementar hardware real todavía. - No integrar servicios de terceros todavía. - No usar credenciales reales. - No abrir Node.js directamente a Internet. - No implementar automatizaciones complejas todavía. - No avanzar a la siguiente fase hasta que el esqueleto, health checks y pruebas básicas funcionen correctamente. --- ## Prompt recomendado para iniciar en Codex > Lee `HomeCore_CODEX_START.md` completo. Resume primero la arquitectura, el modelo de usuario y el stack técnico que propones. Después ejecuta únicamente la sección “Primera tarea para Codex”. No avances a fases posteriores hasta que la base del repositorio arranque correctamente y las pruebas iniciales pasen. Mantén la experiencia mobile-first y evita exponer conceptos técnicos del hardware al usuario final.