Revisión vigente: 2026-08-05 · versión 1.5.0 · cierre técnico c8e8c3c. La referencia de preparación incluida en el control inferior se conserva como antecedente documental; el estado vigente está en Documentos/ESTADO_ACTUAL_PROYECTO.md.
1. Control documental
Documentos/ANEXO_EXPEDIENTE_DERECHOS_AUTOR.md con datos del titular, commit liberado y capturas finales.2. Producto y alcance
La aplicación web permite usar el simulador desde un navegador moderno, con sesiones independientes para ejecutar scripts, editar mundos y observar la telemetría del robot EV3 simulado.
- Expone simulación, editor de mundos, ayuda y diagnóstico mediante una interfaz responsive.
- Mantiene el aislamiento entre sesiones y ejecuta scripts con un worker controlado.
- Comparte motor, modelo de dominio, API Pybricks virtual y catálogos con el cliente de escritorio.
- Puede usarse localmente sin red externa o desplegarse en un entorno configurado con HTTPS.
3. Arquitectura técnica
La capa Flask gestiona rutas y sesión; el contrato de aplicación protege al dominio de los detalles HTTP. La ejecución del script se realiza fuera del proceso de la interfaz.
| Componente | Responsabilidad | Ubicación |
|---|---|---|
| Web Flask | Plantillas, rutas, API HTTP, sesiones, actualizaciones y diagnóstico. | simulador_ev3/web/ |
| Contrato de sesión | Comandos, snapshots, errores, depuración e idempotencia. | simulador_ev3/application/ |
| Runtime aislado | IPC, límites de ejecución y cancelación de scripts. | simulador_ev3/runtime/ |
| Dominio y motor | Mundo, robot, sensores, cinemática, colisiones y Brick. | simulador_ev3/core/, domain/ |
| Persistencia | Mundos, ejemplos, perfiles, trazas y configuración de sesión. | worlds/, examples/, persistence/ |
4. Funcionalidades y rutas
| Ruta | Uso |
|---|---|
/ | Simulación, editor de código, Brick virtual, telemetría, perfiles, trazas y depuración. |
/worlds | Editor de mundos, assets, robot, validación y persistencia JSON. |
/help | Ayuda por tarea, búsqueda y recuperación de errores. |
| Salud y métricas | Diagnóstico operativo disponible según la configuración de despliegue. |
El mapa conserva 32 px = 100 mm; el contenedor permite desplazamiento cuando el mundo no cabe. La interfaz se adapta a escritorio, tableta y móvil sin alterar la escala física del mundo.
5. Instalación y arranque local
Requiere Python 3.11 o superior (la validación actual usa Python 3.12) y un navegador moderno como Chrome o Edge.
git clone <URL_DEL_REPOSITORIO_AUTORIZADO> cd Codex_SimuladorLegoEV3 py -3.12 -m venv .venv .\.venv\Scripts\Activate.ps1 python -m pip install --upgrade pip python -m pip install -r requirements.txt .\scripts\start_web.cmd # Abrir http://127.0.0.1:5050/
Para detener el servicio local use .\scripts\stop_web.cmd. Las guías de Windows, Linux y cPanel contienen procedimientos específicos de cada entorno.
6. Configuración y despliegue
| Variable | Propósito |
|---|---|
EV3_WEB_APP_ENV | Selecciona el comportamiento local o de producción. |
EV3_WEB_SECRET_KEY | Clave de sesión de producción; debe ser única y no publicarse. |
EV3_WEB_SCRIPT_MAX_RUNTIME_S | Límite máximo de ejecución de scripts. |
EV3_WEB_SESSION_COOKIE_SECURE | Activa cookies seguras cuando se utiliza HTTPS. |
EV3_LOCAL_RUNTIME_ENABLED | Habilita el modo local explícito para desarrollo o pruebas. |
$env:EV3_WEB_APP_ENV = "production" $env:EV3_WEB_SECRET_KEY = "secreto-unico-de-al-menos-32-caracteres" $env:EV3_WEB_SCRIPT_MAX_RUNTIME_S = "30" $env:EV3_WEB_SESSION_COOKIE_SECURE = "true"
En producción configure HTTPS, un secreto seguro y un proceso servidor adecuado. Consulte GUIA_WEB_FLASK_WINDOWS.md, GUIA_DESPLIEGUE_LINUX.md y GUIA_INSTALACION_CPANEL.md.
7. Operación y monitoreo
- Inicie el servicio y verifique la ruta de salud configurada.
- Abra la aplicación, cree o cargue un mundo y ejecute un script.
- Supervise el estado de sesión, snapshots, trazas y errores de ejecución.
- Use Detener y reiniciar para cancelar la ejecución y restaurar el mundo activo.
- Ante incidentes, exporte las trazas y conserve el commit, la configuración no sensible y la fecha de la evidencia.
Redis es opcional según el modo de despliegue. Consulte la referencia de configuración antes de cambiar persistencia, sesiones o límites.
8. Seguridad, privacidad y límites
- El worker aislado, los límites de tiempo y la cancelación protegen la ejecución de scripts.
- Las sesiones separadas y la correlación de comandos reducen cruces de estado entre usuarios.
- No exponga el servicio públicamente sin autenticación apropiada, HTTPS y secretos de producción.
- No publique
EV3_WEB_SECRET_KEY, cookies, trazas con datos sensibles ni archivos de configuración privados. - La simulación no sustituye pruebas en hardware: sensores y actuadores representan modelos educativos.
La política de aula está en Documentos/SEGURIDAD_Y_USO_EN_AULA.md.
9. Calidad y evidencia técnica
La validación cubre pruebas unitarias, integración, contrato, UI, E2E web con Playwright, análisis estático, seguridad y auditoría de dependencias.
py -3.12 -m pytest -q py -3.12 -m pytest --cov=simulador_ev3 --cov-report=term -q py -3.12 -m ruff check simulador_ev3 tests py -3.12 -m mypy py -3.12 -m bandit -q -c pyproject.toml -r simulador_ev3 --severity-level medium py -3.12 -m pip_audit
Para evidencia de una entrega, conserve resultados fechados, capturas de rutas clave, configuración no sensible, el commit y el hash SHA-256 del paquete. Los resultados históricos no sustituyen una ejecución sobre el commit entregado.