clickup-8horas/CLAUDE.md

CLAUDE.md

Guía para trabajar en Mis 8 horas: dashboard personal de ClickUp (NestJS + Angular) para cumplir 8 horas diarias de tareas completadas. La especificación completa está en README.md; léela antes de implementar algo nuevo. Este archivo solo recoge lo que no debe romperse.

Estado del proyecto

Fase de planificación: el prototipo prototipo-html/ es la referencia de comportamiento. backend/, frontend/ y contracts/ se crean siguiendo el plan de la sección 10 del README (empezar por contracts/ y MetricsService con sus pruebas).

Estructura

• backend/: NestJS. Único lugar con la API key y con las reglas de negocio.
• frontend/: Angular 18+, standalone, signals, @if/@for. Solo muestra y envía acciones.
• contracts/: tipos TypeScript compartidos, importados con @contracts/*.
• prototipo-html/: respaldo autónomo. No tocar salvo que se pida.

Reglas que no se negocian

• La API key de ClickUp vive solo en backend/.env. Nunca en Angular, en respuestas de /api/*, en logs ni en git. prototipo-html/config.js también la contiene: no subirlo ni mostrarlo.
• Las métricas se calculan solo en el backend (MetricsService). Angular no recalcula HPC, deuda ni rendimiento.
• MetricsService es puro: sin HTTP, sin leer el reloj. "Hoy" entra como parámetro para que las pruebas sean deterministas.
• Fechas con Luxon y zona America/Lima (TZ). Nunca new Date() sin zona para agrupar por día.
• El día de una tarea es su due_date. start_date no se usa. La tarea se cuenta completa en ese día.
• Día libre: meta, hueco y deuda en 0, y no cuenta como día transcurrido en el rendimiento semanal. Feriado y vacaciones se tratan igual.
• Sprint de un día: se saca del nombre de la lista (Sprint 19 (10/5 - 10/19)), nunca de start_date/due_date de la lista. En un día límite gana el Sprint que empieza más tarde.
• Al mover o crear una tarea, fijar las 12:00 hora local con due_date_time: false.
• Crear tarea: estado asignado, estimado > 0, y Clientes, Jefatura, Sprint y asignado obligatorios. Los avisos (día libre, pasarse de la meta) no bloquean.
• Custom Field "Jefatura" es de tipo users: se escribe como { add: [id], rem: [] }. Una lista simple da 400 Invalid Value.
• Sin "deshacer" en las acciones sobre tareas; los errores se corrigen en ClickUp.

Convenciones

• Idioma: textos de interfaz, mensajes de error, commits y documentación en español. Identificadores de código en inglés. Textos en minúsculas tipo oración, sin mayúsculas sostenidas.
• Horas: siempre H:MM en pantalla; los campos aceptan 2:30, 2.5 o 2. Internamente, milisegundos (...Ms).
• Frontend: los componentes leen signals de PlannerStore y llaman a sus acciones; no usan ApiService directamente. Respetar los tokens de color del README (sección 9) y prefers-color-scheme.
• Backend: validar entradas con class-validator; errores con formato Nest ({ statusCode, message }) y los códigos 401/400/502/429 del README. Caché con @nestjs/cache-manager, invalidada al crear, mover, estimar o cerrar.
• Los ajustes y días libres se guardan en backend/data/settings.json y backend/data/days-off.json.

Pruebas

• Jest. MetricsService debe tener todas las pruebas de la sección 5.4 del README antes de pasar al resto del backend.
• SprintsService y ClickupClient (paginación, mapeo de Clientes, envío de Jefatura) también tienen pruebas obligatorias.
• Probar contra ClickUp real solo con tareas de prueba que se borren después.

Pendiente de confirmar (no asumir)

Estas decisiones dependen de quien mantiene el dashboard de la empresa; no cambiar el comportamiento sin confirmarlo (README, 2.2):

• Qué estados cuentan como completados (hoy closed o done, lo que incluye cancelado).
• Si las subtareas suman por separado o se descuentan del padre.
• Si las horas cerradas en un día libre suman como extra o se excluyen.
• Día por fecha de vencimiento o de inicio.