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 y Penalización General:** 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. El botón de **Penalizar** está habilitado en **todos** los proyectos e Incidencias activas durante el fin de trimestre, deduciendo la penalización del acumulado general.
    *   **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.
    *   **Corrección de Proyectos Descartados en `TablaProyectoGde`:** Se corrigió un error en `continuamos()` en [jsCode.js](file:///c:/CHV/ludotecaLocal/Colaborando/jsCode.js#L3435) que provocaba que un proyecto descartado que estuviera seleccionado en el cuadro grande (`TablaProyectoGde`) se reasignara por error al volver al tablero desde el resumen. Ahora la inicialización del tablero valida estrictamente que solo se carguen proyectos `En proceso`, removiendo el proyecto descartado inmediatamente sin necesidad de refrescar la página.
    *   **Persistencia de Botones de Acción 1 y 2 (`bAccion1` y `bAccion2`):** Se integró el estado de las acciones en `arregloGeneral.bAccion1` y `arregloGeneral.bAccion2`. Al hacer clic en los botones 1 y 2 o reiniciarse con el timer, se guarda el estado en el servidor y al volver del resumen a la vista del tablero se restaura automáticamente la selección activa (fondo azul y texto blanco).
    *   **Gráfica Mixta de Progresión (Barras + Línea) con Zoom 2.5X y Posicionamiento Ajustado:** Integración de gráfica HTML5 Canvas sin dependencias en el Bloque 3 de resumen. Representa los Objetivos del Trimestre (`arregloGeneral.objetivoT1..T4`, por defecto $100,000) mediante barras azules e Ingresos Reales mediante una línea roja con nodos. El panel flotante emergente desplegado en `mouseenter` se ajustó a escala **2.5X ampliado** (560px × 185px) y se reubicó dinámicamente sobre la tarjeta del Bloque 3, evitando recortes en el borde superior de la ventana del navegador. Se corrigió el alineamiento de texto de la leyenda (`textAlign = 'left'`) para que los textos "Objetivo Trimestre" e "Ingreso Real" no se solapen con sus respectivos iconos.
    *   **Redistribución de Layout en Resumen:** Se reestructuró la vista en 2 filas: Fila superior con 5 columnas horizontales para métricas/gráficos/controles y Fila inferior con Departamentos (20%), Proyectos Terminados (40%) y Proyectos Activos (40%).
*   **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.