# Guía de Réplica: Módulo Kanban de Incidentes Esta guía contiene la especificación completa para trasladar la funcionalidad del tablero Kanban de incidentes a un nuevo proyecto. --- ## 1. Arquitectura de Datos (Modelo de Incidente) Para que el sistema sea funcional, la base de datos debe almacenar los siguientes campos. Se recomienda el uso de tipos JSON para campos complejos para mantener la flexibilidad. ### Campos Principales - **ID**: Identificador único incrementable. - **Título**: Texto breve de la tarea (ej: "Error en login"). - **Descripción**: Texto largo con detalles técnicos. - **ColumnaID**: Identificador de la columna (ej: `column-proyecto-a`). - **ProyectoID**: Identificador del proyecto al que pertenece la columna. - **Estado**: Enumeración (`pendiente`, `en_progreso`, `bloqueado`, `completado`). - **Prioridad**: Enumeración (`baja`, `media`, `alta`, `urgente`). - **Orden**: Índice numérico para la posición vertical dentro de la columna. - **Archivado**: Booleano para ocultar de la vista activa. ### Campos Complejos (Formatos JSON sugeridos) - **Etiquetas**: Lista de IDs o referencias a objetos globales `{ id, nombre, color }`. Las etiquetas no pertenecen a una tarjeta única, sino que son parte de un catálogo global. - **Responsables**: Lista de objetos `{ id, nombre, avatar }` (Usuarios con autoría principal). - **Colaboradores**: Lista de objetos `{ id, nombre, avatar }` (Usuarios secundarios de apoyo). - **Checklists**: Lista de objetos `{ id, titulo, items: [{ id, titulo, completado }] }`. - **Adjuntos**: Lista de objetos `{ id, url, nombre, tipo, fecha }`. - **Log de Actividad**: Historial cronológico de cambios `{ fecha, accion, usuario, valor_anterior, valor_nuevo }`. - **Comentarios**: Lista de objetos `{ id, usuario, texto, fecha, ediciones: [] }`. Soporte para menciones `@usuario`. - **Recordatorios**: Configuración de alertas `{ fecha_aviso, canal (sistema/mail), estado }`. --- ## 2. Funcionalidades del Tablero (Frontend) ### Sistema de Arrastre (Drag & Drop) 1. **Vertical**: Reordenamiento de tarjetas dentro de la misma columna. Al soltar, se deben recalcular los índices de `orden` de todas las tarjetas de esa columna. 2. **Horizontal (Entre Columnas)**: Traslado de una tarjeta a otro proyecto. La tarjeta debe actualizar su `ColumnaID` y su `ProyectoID` inmediatamente. 3. **Columnas**: Las columnas mismas deben ser arrastrables para cambiar el orden de los proyectos en la pantalla. ### Lógica de Filtrado en Tiempo Real El tablero debe filtrar las tarjetas instantáneamente por: - Búsqueda de texto (título, descripción y nombre de proyecto). - Etiquetas seleccionadas. - Miembros asignados. - Nivel de prioridad y estado. - Rango de fechas. ### Vistas Alternativas - **Modo Calendario**: Mapeo de las mismas tarjetas en una cuadrícula de calendario basada en la `fecha_vencimiento`. --- ### Gestión Dinámica de Etiquetas El sistema debe contar con un **Repositorio Global de Etiquetas**: - Al editar una tarjeta, el usuario selecciona etiquetas de un catálogo existente. - Si la etiqueta no existe, se crea globalmente y queda disponible para el resto de las tarjetas del tablero. - Cambiar el nombre o color de una etiqueta en el catálogo debe reflejarse en todas las tarjetas que la utilicen. ## 3. Lógica del Modal de Detalle Al abrir una tarjeta, el modal debe permitir: 1. **Gestión de Checklists**: Añadir tareas secundarias con checkbox de completado. 2. **Subida de Archivos y Portapapeles (Ctrl + V)**: - Zona de drop para adjuntar archivos. - **Soporte nativo para pegar imágenes**: Al presionar `Ctrl + V` dentro del modal, el sistema debe capturar el evento `paste`, procesar el archivo del portapapeles y subirlo automáticamente como un nuevo adjunto. 3. **Roles Diferenciados**: Selectores específicos para la lista de **Responsables** (permite múltiples) y una lista de **Colaboradores**. 4. **Selección de Portada**: Permitir elegir un adjunto de imagen para que se vea en la miniatura del tablero. 5. **Edición Enriquecida (Markdown)**: Tanto la descripción como los comentarios deben soportar formato Markdown (negritas, listas, enlaces) con previsualización en tiempo real para mejorar la claridad. 6. **Hilos de Comentarios**: Espacio para discusión interna con capacidad de mencionar usuarios para disparar notificaciones. 7. **Recordatorios de Fecha**: Ajuste de alarmas específicas para no olvidar el vencimiento de una tarea. --- ## 4. Requerimientos de API (Endpoints) El backend debe proveer al menos estos servicios: - **`GET /api/incidents`**: Lista de tarjetas activas/archivadas. - **`POST /api/incidents`**: Creación de nueva tarjeta con valores base. - **`PUT /api/incidents/:id`**: Actualización de cualquier campo (incluyendo posición). - **`DELETE /api/incidents/:id`**: Eliminación física. - **`GET /api/labels`**: Obtiene el catálogo global de etiquetas reutilizables. - **`POST /api/labels`**: Crea o actualiza una etiqueta en el catálogo global. - **`GET/POST /api/preferences/:key`**: Para guardar el orden de las columnas del usuario (ej: clave `kanban_column_order`). --- ## 5. Elementos Visuales Clave - **Favicons**: El tablero debe intentar cargar el favicon del proyecto en la cabecera de cada columna. - **Contadores**: Cada columna muestra el número total de tarjetas que contiene. - **Badges de Estado**: Mini etiquetas visuales en la tarjeta para prioridad y estado. - **Indicadores de Progreso**: Si hay checklists, mostrar iconos tipo `2/5` para saber el avance sin abrir la tarjeta. - **Avatares de Roles**: Mostrar los avatares de los **Responsables** con un borde destacado y los **Colaboradores** agrupados en una lista superpuesta (stacking). - **Badge de Comentarios**: Icono con el número de mensajes no leídos o totales. - **Indicador de Recordatorio**: Icono de campana si la tarjeta tiene una alerta programada. --- ## 6. Funcionalidades Avanzadas (Nivel Trello Premium) Para que el módulo sea de nivel profesional, se deben implementar estas capacidades adicionales: ### Automatizaciones (Reglas de Negocio) - **Auto-asignación**: "Cuando una tarjeta se mueva a la columna X, asignar automáticamente al usuario Y como Responsable". - **Auto-cierre**: "Cuando todos los items de la checklist se marquen como completados, mover la tarjeta a la columna 'Finalizados'". ### Gestión y Seguimiento - **Notificaciones del Sistema**: Centro de avisos donde el usuario ve cuando ha sido mencionado o asignado a una tarea. - **Historial de Tiempos**: Registro opcional de cuánto tiempo ha permanecido una tarjeta en cada columna para detectar cuellos de botella en la gestión. ### Gestión de Productividad - **Plantillas de Tareas**: Definir formatos preestablecidos para consultas recurrentes, pedidos de soporte o tareas administrativas con checklists y etiquetas precargadas. - **Acciones en Lote**: Menú en la columna para "Archivar todas las tarjetas completadas" o "Mover todas a otro sector/proyecto". - **Tareas Recurrentes**: Opción para que una tarjeta se "autocreé" periódicamente (ej: "Revisión mensual de facturación").