Colaborando/doc/PROYECTO.md

# Documentación General y Bitácora de Cambios - Co.Laborando

> [!IMPORTANT]
> **Regla de Mantenimiento:** Para evitar el consumo excesivo de tokens, este archivo debe mantenerse conciso, con un tamaño objetivo de **entre 150 y 250 líneas** en total. Al realizar nuevos cambios, se debe resumir o actualizar la información en lugar de añadir bloques redundantes de texto.

---

## 🎮 Concepto General del Proyecto
**Co.Laborando** es una aplicación interactiva de simulación y ludoteca empresarial. Los jugadores administran múltiples departamentos con recursos limitados (Tiempo, Personal, Capital) para completar proyectos en un tablero a lo largo de un ciclo temporal de **24 quincenas (4 trimestres)**.

---

## 🏗️ Arquitectura de Archivos Principal
*   **[colaborando2.php](file:///c:/CHV/ludotecaLocal/Colaborando/colaborando2.php) / [colaborando.php](file:///c:/CHV/ludotecaLocal/Colaborando/colaborando.php):** Vistas del tablero principal del juego, donde se colocan y arrastran los proyectos y recursos.
*   **[resumen.php](file:///c:/CHV/ludotecaLocal/Colaborando/resumen.php):** Pantalla del panel de control central (dashboard) que muestra métricas acumuladas, estado de departamentos, listado de activos y control de habilidades.
*   **[jsCode.js](file:///c:/CHV/ludotecaLocal/Colaborando/jsCode.js):** Lógica del lado del cliente que maneja las interacciones del tablero, transiciones de turnos y renders dinámicos.
*   **[manejoDeSesiones.js](file:///c:/CHV/ludotecaLocal/Colaborando/manejoDeSesiones.js) / [manejoDeSesiones.php](file:///c:/CHV/ludotecaLocal/Colaborando/manejoDeSesiones.php):** Sistema de persistencia que guarda y carga el estado del juego (en archivos `.json` en la raíz del proyecto).
*   **[sesiones.php](file:///c:/CHV/ludotecaLocal/Colaborando/sesiones.php):** Panel de administración para crear, inicializar o eliminar las sesiones guardadas.

---

## ⚙️ Mecánicas de Juego Clave

### 1. Departamentos y Recursos
Existen 6 departamentos: *Marketing y Ventas, Finanzas, Investigación y Desarrollo, Logística y Sistemas, Operaciones*, y *Recursos Humanos*. Cada uno posee recursos de **Tiempo, Personal** y **Capital**, representados dinámicamente en el tablero y resumen.

### 2. Ciclo de Vida de Proyectos
*   **En proceso:** Proyectos activos en los que se está trabajando.
*   **Completado:** Proyectos finalizados con éxito. Sus requerimientos y recursos recuperados se contabilizan.

### 3. Mantenimiento Trimestral y Penalizaciones
En los cierres de trimestre (quincenas 6, 12, 18 y 24), los proyectos activos en proceso requieren el pago de un coste de mantenimiento (`Tiempo`, `Personal`, `Capital`) o el pago de una **Penalización** financiera del acumulado de ingresos.
*   En cualquiera de los dos casos, el proyecto se mantiene activo (`En proceso`) y visible en el tablero y en el resumen.
*   En la pantalla de resumen, el proyecto se muestra en gris (deshabilitado) y sus botones de acción se bloquean una vez resuelto en el trimestre actual.

### 4. Habilidades Especiales (Acción Quincenal)
Los departamentos pueden comprar habilidades especiales con cooldown (periodicidad). Ejemplos clave:
*   **Logística y Sistemas:** Permite omitir el costo de mantenimiento de un proyecto activo (pagarlo sin gastar recursos).
*   **Operaciones:** Permite penalizar un proyecto en proceso sin costo de penalización.
*   **Ordenar proyectos:** Permite reordenar la cola de los próximos 5 proyectos en el tablero.

### 5. Contabilización de Activos
Los activos producidos por proyectos completados se dividen en 6 tipos: *Personal Calificado, Analistas, Flujo de Efectivo, Crédito e Inversión, Tecnología* y *Transporte y Maquinaria*. Se calculan dinámicamente y se clasifican en:
*   **Producidos:** Total de activos creados por proyectos completados.
*   **Recuperados:** Activos que fueron arrastrados con éxito de vuelta a los departamentos.
*   **Perdidos:** Activos que no se recuperaron a tiempo antes de cambiar de trimestre.

---

## 💾 Sistema de Sesiones
*   Las sesiones de juego se guardan localmente en archivos JSON en la raíz del proyecto.
*   Para evitar que estos archivos ensucien el repositorio Git, el archivo [.gitignore](file:///c:/CHV/ludotecaLocal/Colaborando/.gitignore) ignora todos los archivos `/*.json` de la raíz.
*   Se utiliza una técnica de *cache-busting* con el parámetro `_t` y la cabecera `cache: 'no-store'` para evitar cargas AJAX obsoletas entre pantallas.

---

## 📈 Bitácora Histórica de Cambios (Changelog)

*   **16/Jul/2026:**
    *   **Cambio de Desechar a Penalizar:** En la pantalla de resumen, se cambió el botón "Desechar" por "Penalizar".
    *   **Persistencia de Actividad:** Los proyectos penalizados ahora se mantienen activos (`En proceso`) en lugar de descartarse.
    *   **Actualización de Visualización:** Tanto al pagar mantenimiento como al penalizar, el proyecto permanece en la quincena actual; en el resumen, su tarjeta cambia a color gris y sus botones se bloquean. Se excluyeron de este bloqueo los proyectos con mantenimiento "N/A" (como "Capacitación Brigadas") y las Incidencias.
    *   **Descuentos de Habilidades en Mantenimiento:** Al pagar mantenimiento de forma normal, se aplican correctamente los beneficios/descuentos de recursos ganados por el departamento mediante sus habilidades compradas (`habilidadTiempo`, `habilidadPersonal`, `habilidadCapital`), reduciendo el costo cobrado en base a los beneficios definidos.
*   **03/Jul/2026:**
    *   Implementación de la ventana de mantenimiento trimestral (Q6, 12, 18, 24) en resumen y tablero.
    *   Integración de habilidades especiales para omitir costo de mantenimiento (Logística) y omitir penalizaciones por desecho (Operaciones).
    *   Bypass de caché del navegador (`cache: 'no-store'`) para la carga de datos del juego.
    *   Añadida regla `/*.json` en `.gitignore` para limpiar el repositorio de archivos de juego locales.
    *   **Nuevo botón de Pantalla Completa:** Integrado en los encabezados de la pantalla de Resumen y el Tablero mediante la API de Fullscreen de HTML5, actualizando su texto de forma reactiva a eventos del navegador.
    *   **Alineación de Departamentos:** Se fijó la altura (38px) de la celda de habilidad especial en el tablero y se restauró el tamaño de letra original (14px) con un line-height controlado (1.2) para evitar desfases de altura cuando el texto ocupa dos líneas sin perder legibilidad.
*   **11/Jun/2026:**
    *   Creación del módulo de contabilización de activos (Producidos, Recuperados, Perdidos) calculado dinámicamente e integrado en la esquina inferior izquierda de resumen.
    *   Ajustes y correcciones en la habilidad especial de reordenamiento de proyectos.
*   **10/Jun/2026:**
    *   Implementación de la habilidad para previsualizar y ordenar los siguientes 5 proyectos del tablero.
    *   Añadido botón de habilidades especiales y opción de descarte de proyectos básicos.