Monolito

Última actualización: 06-01-2026 09:01 PM

pAVANTI — CONTEXTO (Monolito) v2

pAVANTI existe para dar continuidad: una lista viva que te recuerda en qué estás trabajando, te permite ejecutar sin fricción y deja una evidencia mínima de avance cuando la sensación subjetiva es “no hice nada”. No busca perfección ni burocracia; busca claridad y ritmo. Por eso, los nombres pueden ser informales y los grupos son, sobre todo, una herramienta de orden visual (colapsar, reducir ruido, mantener foco). Lo verdaderamente valioso —y por tanto “sagrado”— son los datos que permiten mirar atrás: en cada reto, fecha + minutos; de ahí salen el calendario y las gráficas. Esta filosofía manda sobre lo técnico: al importar o migrar, la app debe rescatar y normalizar sin perder información, incluso si el formato viene “raro”.

Propósito de este documento: concentrar el contexto operativo + técnico de pAVANTI para iterar sin perder decisiones. Aquí registramos qué es, qué NO es, reglas de negocio, arquitectura, persistencia, y pendientes reales.

Esta versión incorpora tus respuestas: persistencia doble, grupos sin fecha, sin subgrupos, sin retos en raíz, y colapsado que debe persistir.

1) Ficha técnica

Nombre interno: pAVANTI (módulo src/proyectos/*).
Dominio: gestor personal de Proyectos → Grupos → Retos (2 niveles).
- Sin subgrupos.
- Sin retos en raíz (todo reto vive dentro de un grupo).
- Un proyecto puede tener muchos grupos: funcionan como carpetas de organización.
Plataforma: Web.
Modo de ejecución: 100% client-side (componentes React con "use client").
Stack base: Next.js (App Router), React, TypeScript, Tailwind CSS.
Librerías clave:
- uuid (IDs)
- lucide-react (iconos)
Persistencia:
- Automática en localStorage (clave datos: pweb_proyectos_v1).
- Manual vía Descargar (snapshot JSON pavanti-export.v2.json).
- Indicador “pendiente de descargar” = cambiaste datos y aún no exportaste (no significa que no esté guardado localmente).
Estado UI adicional (preferencias):
- Colapsado de grupos: ya persiste siempre.
  - En local (para que al recargar quede igual): localStorage → pweb_proyectos_ui_v1.
  - En el JSON (para que al importar/exportar se conserve el layout): bloque ui dentro del export.
- Formato de export (v2):
```
{
  "schema": "pavanti-proyectos-export",
  "v": 2,
  "exportedAt": "<ISO>",
  "proyectos": [ ... ],
  "ui": {
    "v": 1,
    "collapsedByProyecto": {
      "<proyectoId>": ["<grupoId>", "<grupoId>"]
    }
  }
}
```
- Compatibilidad de import:
  - v1 (legacy): Proyecto[] (archivos antiguos sin ui).
  - v2: objeto con proyectos + ui (restaura colapsado).

2) Qué es (definición operativa)

pAVANTI es un mini‑gestor personal para organizar trabajo en proyectos, dividirlo en grupos y ejecutarlo como retos con progreso tipo checklist. La prioridad es velocidad de edición y claridad visual.

3) Usuario objetivo y casos de uso

Usuario: 1 persona (uso personal).
Casos típicos:
- abrir y continuar exactamente donde quedó (persistencia local),
- marcar retos como hechos,
- ajustar minutos y notas,
- mover un reto de un grupo a otro,
- exportar un snapshot JSON (backup/portabilidad).

Significado práctico (por qué existe):

No es un “registro perfecto”. Es un sistema de lista de chequeo para no olvidar trabajo pendiente.
Sirve para ver de un vistazo que sí hay proyectos en marcha.
El registro es “suficiente”: nombres pueden ser informales; lo que se busca es continuidad y evidencia de avance.

Dato más importante (sagrado):

En los retos, la fecha y el tiempo (minutos) son lo más valioso porque habilitan análisis posterior (calendario y gráficas).

4) Alcance (lo que SÍ hace)

Gestionar múltiples Proyectos.
Dentro de un proyecto:
- crear/renombrar/eliminar Grupos,
- crear/editar/mover/eliminar Retos dentro de grupos.
Edición en línea:
- título (grupo/reto)
- estado (todo/done)
- fecha (día) solo en retos
- minutos solo en retos (±15)
- notas solo en retos
Progreso por proyecto con % y barra.
Contadores de completados/pendientes y minutos acumulados.
Import/Export JSON.
Colapsar/expandir grupos (persistente):
- se conserva al recargar,
- y se conserva al exportar/importar (si el archivo trae ui).
Sidebar derecha (Actividad Global): calendario anual por meses con selector de año. Suma minutos por día desde todos los proyectos y muestra el valor en horas/día (máx. 1 decimal) dentro de cada celda, con intensidad en verdes degradados.

5) No‑objetivos (fuera a propósito)

Multiusuario, cuentas, login.
Backend, nube, sync multi‑dispositivo.
Recurrencias y recordatorios automáticos.
Prioridades, etiquetas, dependencias.
Reportes/analytics avanzados.

6) Principios de diseño del producto

Checklist binario: todo/done.
Cero fricción: edición inline y acciones inmediatas.
Estructura simple: 2 niveles (grupo→reto), sin jerarquía profunda.
Datos por encima de la forma: lo importante es capturar qué hice y cuándo.
Datos sagrados: al importar/migrar, la prioridad es preservar la información (nunca “botarla”).
Portabilidad directa: JSON como formato único.
Preferencias UI separadas: lo visual (colapsado) no debería ensuciar el modelo principal.

7) Modelo mental y reglas de negocio

7.1 Entidades

Proyecto: contenedor principal.
Grupo: contenedor de retos dentro de un proyecto.
Reto: unidad mínima ejecutable.

7.2 Invariantes (reglas duras)

Un reto siempre pertenece a un grupo.
Un proyecto contiene grupos en raíz.
No existen subgrupos.

Nota técnica: el código histórico del modelo soporta árbol (grupos dentro de grupos). A nivel producto lo restringimos a 2 niveles. Esto afecta import/migración y validaciones.

7.3 Progreso y conteo

Progreso actual: cada nodo vale 1 en el porcentaje (total = grupos + retos).
done suma 1 si ese nodo está done.
Minutos: solo retos aportan minutos; el grupo muestra la suma de sus retos.

7.4 Estado del grupo

El estado done/todo del grupo es manual (no se autocompleta por hijos).
El grupo muestra “X retos / Y pendientes” para lectura rápida.
El grupo existe principalmente para orden visual (agrupar, colapsar y reducir ruido).

7.5 Política de importación y migración (datos sagrados)

Nunca rechazar import por cambios de formato si es posible rescatar datos.
Estrategia: best‑effort.
- Interpretar el JSON “viejo” y mapearlo al esquema actual.
- Si hay campos desconocidos, preservarlos (en un bloque legacy/unknown) para no perder información.
- Si hay estructuras fuera de regla (subgrupos, retos en raíz), migrar:
  - aplanar subgrupos a grupos válidos,
  - mover retos en raíz a un grupo creado al vuelo (p.ej. “Sin grupo”),
  - mantener fecha y minutos siempre que existan.
Tras importar, al volver a Descargar, el archivo debe salir ya normalizado al esquema actual.

8) UX y estructura de pantalla

8.1 Layout

Sidebar izquierda: lista de proyectos (ordenada por actualizado), con barra de progreso + contadores + minutos + timestamp.
- acciones globales: Importar / Descargar / Nuevo.
Main: editor del proyecto seleccionado.
- header con renombrar/eliminar,
- fila de métricas + botón “+ Grupo”,
- tabla editable con scroll.
Sidebar derecha (Actividad Global): calendario por meses en bloques (12 secciones) con selector de año.
- cada celda representa un día y muestra horas/día (máx. 1 decimal),
- el color es un degradado verde según intensidad (relativa al máximo del año),
- el panel hace auto-scroll al mes actual cuando el año seleccionado es el actual (si no, al primer mes con actividad).

8.2 Interacciones clave

Crear/renombrar/eliminar hoy usa prompt/confirm (temporal).
Colapsar grupo: persiste al recargar y también puede viajar en export/import (v2 con bloque ui).
Mover reto: solo entre grupos (no existe opción “(Raíz)” por regla).
Notas en popover (cierre por click fuera / Escape).

9) Arquitectura técnica (cómo está construido)

types/ → tipos del dominio.
lib/ → lógica pura (operaciones + cálculos).
hooks/ → estado React + persistencia local + flag “pendiente de descargar”.
components/ → UI.

Flujo: UI → handlers → setProyectos(prev => ops(prev)) → persistencia local automática.

10) Persistencia, privacidad y seguridad

Todo se queda en el navegador (localStorage) + export manual.
Riesgo esperado: si se borra almacenamiento del navegador, se pierde lo no exportado.
No hay cifrado (es un tool personal local).

Pendientes clave (los que más impactan tu uso)

Calendario global (sidebar derecha): base implementada (por meses, selector de año, horas/día dentro de cada celda, degradado verde, auto-focus al mes actual).

pendientes opcionales: click en día para filtrar/centrar retos de esa fecha, botón “Ir a hoy”, mejoras de legibilidad (densidad/tamaño de número) y accesibilidad (tooltip/teclado).

Gráficas a partir de los mismos datos (tendencia semanal/mensual).
Import robusto con migración “datos sagrados” (validación tolerante + normalización).
Reemplazar prompt/confirm por modales internos.

12) Decisiones cerradas

Colapsado: debe guardarse en local y también viajar en el JSON.
Importación/migración: regla máxima: salvar los datos.
- No se rechaza el archivo si hay forma razonable de interpretarlo.
- fecha y minutos de los retos son prioridad absoluta.
- La app debe normalizar y volver a exportar en el formato vigente.