# ⚖️ Judge Pole - Manual de Usuario y Arquitectura **Judge Pole** es una aplicación web *serverless*, ligera y portátil diseñada para arbitrar y evaluar proyectos durante "vibe coding" jams, hackathons y competiciones de desarrollo. --- ## 🚀 1. Filosofía y Arquitectura Técnica * **Cero Infraestructura**: No requiere backend, bases de datos SQL/NoSQL ni servicios en la nube. * **Persistencia Portátil (Base64)**: Todo el estado de la aplicación reside en `/Public/data/database.ecma.js` codificado en una cadena Base64 que contiene un JSON plano. * **Construcción DOM Nativa**: Construida íntegramente con Vanilla JS mediante el helper `judge_pole.html()`, evitando frameworks pesados y virtual DOMs. * **Sistema de Virtual DPI (Grid de 40 celdas)**: El diseño escala de manera uniforme adaptando la unidad base `em` al tamaño de la pantalla mediante un cálculo dinámico de `fontSize`. * **Internacionalización Dinámica**: Soporte reactivo multilingüe basado en atributos `data-i18n` y `data-i18n-without="true"`. --- ## 📁 2. Estructura del Proyecto ```text judge-pole/ ├── Dockerfile # Entorno de compilación SASS ├── build.sh / build.bat # Scripts de compilación de estilos └── Public/ ├── index.html # Punto de entrada HTML ├── data/ │ └── database.ecma.js # Archivo físico de la BDD en Base64 └── ecma/ ├── Application/ │ └── JudgePole.ecma.js # Orquestador del ciclo de vida y UI ├── Managers/ │ ├── DatabaseManager.ecma.js # Operaciones CRUD y serialización │ ├── I18NManager.ecma.js # Motor de traducción │ ├── SessionManager.ecma.js # Control de acceso y roles │ └── SettingsManager.ecma.js # Ajustes de visualización y FPS ├── Models/ # Definiciones de datos ├── Utils/ │ ├── Common.ecma.js # Inyección de estilos y helpers │ ├── I18N.ecma.js # Diccionarios de idiomas │ └── Styles.ecma.js # Estilos SCSS en JavaScript └── Views/ ├── UsersView.ecma.js # Gestión y filtrado de jueces/creadores ├── ProjectsView.ecma.js # Gestión y autoría de proyectos └── VotesView.ecma.js # Matriz de notas ponderada y ranking ``` --- ## 👥 3. Gestión de Participantes (Usuarios) La vista de **Usuarios** permite registrar tanto jueces como participantes: * **Tipos de Usuario**: * **Humano (`👤`)**: Por defecto. * **Inteligencia Artificial (`🤖`)**: Modelos LLM o agentes participantes. * **Avatar Adaptativo**: Si no se define una URL o ruta local, se genera automáticamente un placeholder centrado con las iniciales o el icono de tipo. * **Buscador Reactivo**: Filtra en tiempo real por nick, biografía o plataformas vinculadas. * **Seguridad / Contraseña**: * Puedes definir una contraseña opcional en cualquier participante. * En cuanto al menos un usuario tenga contraseña, la web bloqueará la edición pública. --- ## 📦 4. Gestión de Proyectos La vista de **Proyectos** permite administrar los trabajos presentados a la Jam: * **Coautoría Múltiple**: Los proyectos pueden pertenecer a uno o varios creadores simultáneamente (equipos humanos, equipos de IAs o formatos híbridos). * **Selector con Scroll y Filtro**: Al crear o editar un proyecto, la lista de autores cuenta con un buscador en vivo y altura restringida para no desbordar el formulario. * **Metadatos y Enlaces**: Soporta etiquetas (#tags), tecnologías utilizadas y enlaces externos (repositorios, demos, webs). --- ## ⚖️ 5. Tribunal de Evaluación y Ranking La vista de **Votaciones** es el núcleo de la aplicación: ### 5.1. Ranking en Vivo * **Posición Doble**: Muestra la posición **Global** (absoluta en la Jam) y la posición en el **Filtro** (según la búsqueda tecleada). * **Criterio de Orden**: Ordenado oficialmente por la **Media Ponderada**. * **Acordeón Desplegable**: Al hacer clic sobre cualquier fila del ranking, se despliegan: * El resumen de medias naturales y ponderadas de cada criterio. * La **Matriz Completa de Solo Lectura**, visible para cualquier visitante. ### 5.2. Matriz de Puntuaciones Transpuesta Al pulsar en **"+ Registrar Votación"** o al **Editar (✏️)**: * **Estructura Transpuesta**: * **Filas (Tuplas)**: Criterios de evaluación. * **Columnas**: Jueces participantes. * **Columnas Finales**: Media Natural y Media Ponderada por Criterio. * **Filas Inferiores (`tfoot`)**: Media Natural y Media Ponderada por Juez. * **Esquina Inferior Derecha**: Media Global Doblemente Ponderada. * **Cálculo de Pesos (Weights)**: * Tanto jueces como criterios admiten un **Peso entero** (por defecto `20`, mínimo `1`). * Las medias se recalculan automáticamente en el cliente a medida que se teclean notas o se modifican los pesos. * **Gestión de Criterios en Caliente**: * Es posible añadir nuevos criterios con `+ Nuevo Criterio`. * Los criterios existentes pueden renombrarse (✏️) o eliminarse (✕), propagándose el cambio en cascada sobre todas las notas históricas guardadas. --- ## 🔐 6. Control de Acceso (Modo Admin vs. Público) El sistema opera bajo dos estados dinámicos gestionados por `SessionManager`: 1. **Modo Libre / Desarrollo**: * Si ningún usuario de la base de datos tiene contraseña asignada, la web asume que estás en local y muestra todas las opciones administrativas (`+ Añadir`, `✏️ Editar`, `✕ Borrar`, exportar Base64). 2. **Modo Protegido (Visitante)**: * Se activa en cuanto un usuario recibe una contraseña. * La interfaz oculta todos los botones de creación, modificación y borrado. * La cabecera muestra el botón **"Acceder 🔐"**. * Al iniciar sesión con nick y clave, la sesión pasa a ser administradora y se restauran todos los botones de control. Al pulsar **"Salir 🚪"**, vuelve al modo protegido. --- ## 💾 7. Flujo de Guardado y Persistencia Al ser una aplicación sin servidor backend, los cambios realizados en el navegador se almacenan en la memoria local activa. Para hacerlos permanentes: 1. Inicia sesión como administrador. 2. Pulsa en el botón **"Base64 DB"** en la barra superior. 3. Copia el contenido generado (`const database = "...";`). 4. Abre el archivo `/Public/data/database.ecma.js` en tu editor y sobreescribe su contenido. 5. Haz commit o despliega los cambios en tu servidor estático (GitHub Pages, Vercel, Netlify o servidor local).