Tareas

Tareas es el módulo dónde Ballista convierte pendientes operativos en trabajo asignado. No es una lista decorativa: es el lugar dónde una orden, un problema de inventario, una revisión de facturación o una acción de soporte se vuelve una tarea con responsable, fecha, estado, prioridad, comentarios, asignados y notificaciones.

La ruta principal es /tasks. Desde ahí la página puede mostrar tres vistas: Centro, Tablero y Calendario. Si se abre una tarea especifica, la ruta cambia a /tasks/{id} y aparece el detalle profundo de esa tarea.

Rutas del flujo

Estructura general de /tasks

La pantalla TasksDesktop decide que mostrar:

El encabezado muestra tres botones: Centro, Tablero y Calendario. Estos botones si son acciones reales: cambian el query param y por eso cambian la vista.

Para qué sirve cada vista

Criterio útil: usa Centro para trabajar el día a día, Tablero para crear y buscar, Calendario para planificar capacidad, y Detalle para explicar una tarea especifica de principio a fin.

Permisos visibles

Tareas respeta permisos del usuario.

Si una persona ve tareas pero no puede escribir comentarios, guardar cambios o asignar usuarios, normalmente falta tasks:write o el permiso que habilita esa acción en la vista.

Centro de tareas

Centro es la vista que aparece en la captura. Su objetivo es concentrar tareas activas, responsables, notas y seguimiento sin mezclarlo con el formulario de creación.

Contadores superiores

Arriba del bloque aparecen dos conteos:

Estos conteos vienen de /tasks/mine. Sirven para saber rápidamente si el usuario/equipo tiene trabajo abierto o cerrado.

Filtros Pendientes, Completadas y Todas

Si la pantalla viene enfocada desde una notificación o un taskId, el centro cambia a Todas para que la tarea pueda aparecer aunque ya este cerrada.

Columna Tarea

Cada fila muestra:

El link del título abre el detalle. El botón Notas no cambia de página: abre historial y escritura de notas en un modal.

Columna Estado

Si el usuario tiene tasks:write, el estado se puede cambiar desde un selector.

Cambiar el selector no guarda solo. Para persistir el cambio también se usa Actualizar tarea en la columna de prioridad, porque el update manda estado y prioridad juntos.

Columna Prioridad

La prioridad se edita junto con el estado.

El botón Actualizar tarea se habilita cuando cambia el estado o la prioridad. Al presionarlo, el interfaz llama /tasks/update, refresca my-tasks, task-detail, notifications-feed y notification-counter, y muestra una alerta local de exito.

Columna Assignees / Responsable

Esta columna aparece cuando el usuario puede asignar.

Responsable y assignees no son lo mismo:

Notas en Centro de tareas

El botón Notas abre un modal con dos partes: historial y nueva nota.

Guardar una nota llama /tasks/comments/create. El servidor valida que la tarea exista y que el comentario no este vacío. Luego inserta en core.task_comments, emite en tiempo real task:comment-created y crea notificaciones para usuarios relacionados con la tarea.

Tablero de tareas

Tablero es la vista para buscar y crear tareas. Se abre con /tasks?view=board.

Tabla del tablero

El tablero muestra una DataGrid con búsqueda, paginación y columnas:

La búsqueda filtra por id, título, descripción, estado, prioridad, responsable, orden y fecha.

Botón Create task

Create task abre un modal. Este formulario crea trabajo nuevo desde cero o asociado a una orden.

Qué pasa al guardar una tarea desde Tablero

1. El usuario presiona Guardar.
2. El interfaz valida título, descripción y due date.
3. El interfaz llama /tasks/create.
4. El servidor exige tasks:write.
5. El servidor exige salesOrderId valido y que la orden exista.
6. El servidor inserta en core.tasks.
7. Si no se envío responsable, usa como responsable al usuario que creo la tarea.
8. El servidor emite en tiempo real task:created.
9. El servidor crea notificación persistente para usuarios de la tarea si hay usuarios relacionados.
10. Si se marcaron usuarios asignados, el interfaz llama /tasks/assign-users.
11. El servidor inserta/activa filas en core.task_assignments.
12. El servidor emite en tiempo real task:users-assigned y task:assigned-to-me.
13. El servidor crea notificaciones de asignacion para usuarios relacionados.
14. El interfaz muestra alerta local task created.
15. El interfaz refresca queries tasks y my-tasks.

Importante: crear la tarea y asignar usuarios son dos llamadas distintas desde el interfaz. Por eso puede existir una tarea creada aunque falle la asignacion posterior. En soporte, revisa si fallo /tasks/create o /tasks/assign-users.

Detalle de tarea

El detalle se abre desde el título de una tarea o desde una notificación. La ruta es /tasks/{id}.

Acciones superiores

Información visible sin editar

Modo edición

Cuando se presiona Editar task, el detalle permite cambiar:

Al guardar, el interfaz llama /tasks/update y después llama /tasks/assign-users o /tasks/remove-users solo para las diferencias. Luego invalida task-detail, my-tasks y tasks.

Calendario

Calendario se abre con /tasks?view=calendar. Usa el calendario asignado del panel para planificar por tiempo y persona.

Esta vista no reemplaza Centro. Sirve para planificar capacidad. Si quieres cambiar responsable, prioridad, estado o notas, abre la tarea o vuelve a Centro.

Cómo se crean tareas desde Pedidos

Hay dos formas principales de que Pedidos alimente Tareas.

Cuando una tarea viene de una orden, debe quedar con salesOrderId. Eso permite que:

Cómo interactua con Pedidos

Tareas no descuenta inventario ni factura. Su papel es coordinar trabajo alrededor de otros módulos.

Ejemplo: ventas crea el pedido #506 y activa una tarea "Cerrar pedido". En Tareas, aparece Pedido #506. Si soporte abre la tarea, puede usar Abrir pedido para revisar líneas, inventario y facturación del pedido.

Notificaciones: dos capas distintas

En Ballista hay que distinguir dos cosas:

Si una persona dice "no me llego notificación", primero hay que preguntar si habla del toast temporal o de la notificación persistente del panel.

Cuando se activan notificaciones persistentes de Tareas

El servidor crea notificaciones de sistema para usuarios relacionados con la tarea en estos casos:

La funcion clave del servidor es notifyTaskUsers. Primero busca usuarios relacionados por core.task_assignments y por owner_user_id; luego crea una notificación para cada uno.

Cómo abre una notificación el lugar correcto

El panel de notificaciones lee metadata. La navegación se decide asi:

Cuando el usuario hace click en una notificación no leída, el interfaz primero llama /notifications/mark-read. Si eso sale bien, navega al destino. Si no hay destino resoluble, la notificación se muestra pero no funciona como link.

Requisitos antes de crear una tarea

Aunque el formulario muestra Responsable cómo opcional, el servidor usa el usuario creador como responsable si no se envía responsable. En cambio, salesOrderId si es obligatorio para crear o guardar una tarea desde el flujo actual.

Reglas de validación importantes

Qué se guarda en base de datos

Flujo recomendado para operar

1. Entrar a /tasks.
2. Revisar Pendientes en Centro.
3. Abrir Notas si necesitas contexto rápido.
4. Cambiar Estado y Prioridad si el trabajo avanzo.
5. Usar Actualizar tarea para guardar.
6. Cambiar responsable si la responsabilidad principal cambio.
7. Asignar usuarios si alguien más debe participar.
8. Abrir el título de la tarea si necesitas detalle completo.
9. Usar Abrir pedido si la tarea depende de un pedido.
10. Agregar comentario cuando haya decisión, bloqueo o avance.
11. Usar Tablero para crear una tarea nueva o buscar histórico.
12. Usar Calendario para planificar carga semanal.
13. Revisar notificaciones para saltar a tareas, pedidos o lotes afectados.

Ejemplos reales

Ejemplo 1: tarea de pedido pendiente

Un pedido queda pendiente porque falta confirmar entrega.

1. En /orders/{id}, el usuario crea Nueva tarea.
2. Selecciona responsable de operaciones.
3. Define due date para el día siguiente.
4. La tarea aparece en /tasks.
5. Operaciones cambia estado a in_progress.
6. Deja una nota: "Cliente confirma entrega manana".
7. Cuando termina, cambia estado a done.

Ejemplo 2: notificación por comentario

Una persona agrega una nota a una tarea dónde hay responsable y asignados.

1. El interfaz llama /tasks/comments/create.
2. Servidor guarda en core.task_comments.
3. Servidor emite en tiempo real task:comment-created.
4. Servidor crea notificaciones persistentes para responsable/asignados.
5. El feed de notificaciones se refresca cada 5 segundos.
6. Al hacer click, la notificación abre /tasks/{id}.

Ejemplo 3: cambio de orden asociada

Una orden con tareas cambia desde Pedidos/Facturación.

1. Se actualiza el pedido.
2. El servicio llama notifyTaskUsersForOrderUpdate(orderId, action).
3. Servidor busca tareas con ese sales_order_id.
4. Para cada tarea, notifica responsable/asignados.
5. La metadata incluye salesOrderId y taskId.
6. El usuario puede abrir la tarea o el pedido según el tipo de metadata.

Problemas comunes

Para soporte

Cuando reportes un problema de Tareas, incluye:

• ruta exacta: /tasks, /tasks?view=center, /tasks?view=board, /tasks?view=calendar o /tasks/{id};
• id de la tarea;
• id del pedido asociado;
• usuario responsable y usuarios asignados esperados;
• estado y prioridad antes/después;
• si el problema fue en Centro, Tablero, Calendario, Detalle o Notificaciones;
• si fue alerta local o notificación persistente;
• metadata de la notificación si el problema es navegación;
• mensaje de error del servidor si aparece.

Cómo se conecta

Tareas conecta con Pedidos y ventas, porque una tarea puede nacer desde una orden y volver a ella. También conecta con Inventario y producción, porque las tareas pueden coordinar preparación, compras, faltantes o revisión de lotes. Finalmente conecta con Reportes y decisiones, porque estados, fechas, responsables y tareas cerradas alimentan seguimiento operativo.

Resumen

Tareas es el centro de seguimiento de Ballista. Centro sirve para trabajar pendientes, cambiar estado/prioridad, responsable, asignados y notas. Tablero sirve para crear y buscar tareas. Calendario sirve para planificar. /tasks/{id} sirve para entender una tarea completa. Las notificaciones persistentes se crean desde servidor cuando se crea, actualiza, comenta, asigna o cambia responsable de una tarea, y también cuando cambia una orden asociada.