145 lines
6.5 KiB
Markdown
145 lines
6.5 KiB
Markdown
# ⚖️ 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).
|
|
|