Conceptos de Plan

Esta página es un glosario con enlaces. La introducción explica el modelo una vez (organización, proyecto, tablero, tarea); aquí cada objeto tiene un párrafo y un enlace a los endpoints que lo gestionan.

Proyectos, objetivos y tableros

• Proyecto: qué es un conjunto de trabajo. Tiene un responsable principal, salud, fechas, notas de estado (actualizaciones) e hitos. Endpoints: Plan · Proyectos.
• Objetivo: para qué es el trabajo, con un período y un status declarado. Los objetivos apuntan a proyectos; nada vive dentro de un objetivo. El progreso cuenta solo lo que puedes ver, y is_partial: true avisa de trabajo oculto. Endpoints: Plan · Objetivos.
• Tablero: dónde se sigue el trabajo, dentro de un proyecto. Un tablero tiene una clave (ENG), una visibility y una effective_visibility: un tablero dentro de un proyecto members figura como members, mientras que visibility sigue siendo el ajuste almacenado del propio tablero. Endpoints: Plan · Tableros.

La privacidad es membresía, no rol de la organización: un proyecto, tablero o tarea members es 404 para quien no tiene un permiso. Ver Autenticación para Plan.

Columnas: estados de flujo y categorías

Las columnas de un tablero son sus estados de flujo. Cada uno tiene una de cinco categorías fijas (backlog, todo, in_progress, done, canceled), y la categoría es la que dice si el trabajo está abierto o terminado en cualquier tablero. Un tablero debe conservar al menos una columna done activa. Retirar una columna la archiva y se puede restaurar. El estado de una tarea solo cambia moviéndola, respecto a sus vecinas.

Tareas

Una tarea es una unidad de trabajo, direccionada por uuid o por clave (ENG-142). Tiene título, descripción en Markdown, prioridad, estimación, fechas, etiquetas, una version para ediciones concurrentes y un estado. Archivar es borrar, y es reversible. Endpoints: Plan · Tareas.

Responsable, ejecutor y ejecutores

Campo	Significado
owner	La persona responsable
executor	El actor que hace el trabajo ahora, cuando es distinto del responsable: quien tiene la pelota
executors	Cada agente que ejecutó una escritura en la tarjeta en nombre de alguien, del más reciente al más antiguo, con first_at y last_at. En el detalle de la tarea y en las respuestas de escritura de una tarea, no en las filas de listas
created_by	Quién creó la tarea

executors es distinto del executor singular. Ver Agentes en Plan.

Participantes y observadores

Los participantes son las personas a las que se notifica sobre una tarea; deben poder ver el tablero. Un observador sigue las notificaciones de una tarea sin estar en ella (subscription). Una persona también puede silenciar una tarea en la que está. Gestionar participantes es una acción solo para personas.

Relaciones y subtareas

Las tareas se pueden vincular con relaciones (blocks, relates_to, duplicates; pueden aparecer más, así que ignora los valores que no conozcas). “Bloqueada” se deriva de las relaciones. Las subtareas anidan un nivel, viven en el mismo tablero que su tarea padre y se listan con el endpoint de hijas de la tarea.

Adjuntos

Las tareas, comentarios, objetivos y proyectos admiten adjuntos. En una tarea puedes presignar, subir los bytes y confirmar; también sirve una sola solicitud multipart. Descarga por el endpoint content/ del adjunto en vez de guardar su url. Los límites y tipos aceptados están en Errores de Plan.

Comentarios

Los comentarios son Markdown, mencionan personas con <@DB@{uuid}>, se encadenan un nivel y llevan reacciones. Cada uno tiene una provenance y, cuando lo ejecutó un agente, executed_by_agent. Endpoints: Plan · Comentarios y archivos.

Hitos

Un hito es un compromiso con fecha dentro de un proyecto. Las tareas pueden apuntar a un hito del proyecto de su tablero. Completar, reabrir y retirar son operaciones separadas; retirar lo archiva y las tareas siguen apuntándole. La lista de hitos de toda la organización muestra todos los que puedes ver. Un hito retirado se puede restaurar. Los hitos admiten adjuntos (hasta 5 MiB cada uno): refiérete a uno desde la description del hito con un marcador attachment:{uuid} y lee attachment_count en el hito.

Actualizaciones de proyecto

Una actualización de proyecto es una nota de estado sobre un proyecto, la más reciente primero, con un valor de health y menciones. Hay un resumen de las actualizaciones más recientes de todos los proyectos que puedes ver. Una actualización se puede leer, editar y eliminar una por una: solo su autor o autora la edita (update_not_author), y la persona autora o un administrador de la organización la elimina. Lleva edited_at, provenance, executed_by_agent y sus attachments, y un agente puede coescribir una actualización enviando agent_name (ver Agentes en Plan).

Etiquetas

Las etiquetas son de toda la organización. Agrega, quita o reemplaza las etiquetas de una tarea en una sola llamada por lote. Gestionar las etiquetas de la organización es una acción solo para personas. Los filtros aceptan hasta 50 uuids de etiqueta.

Vistas guardadas y favoritos

Una vista guardada guarda cómo miras un tablero o proyecto: filtros, orden, agrupación y modo de vista. Las vistas personales son tuyas; un gestor del tablero puede compartir una o hacerla la predeterminada. Guardar reemplaza toda tu lista y requiere If-Match con el ETag de tu última lectura. Los favoritos fijan tableros y vistas guardadas en tu lista y se pueden reordenar.

Bandeja y cursor de actividad

La bandeja lista los eventos que merecen una notificación para ti (el filtro mentioned=true deja las menciones), con operaciones de leído, leer todo y conteo de no leídos. El cursor de actividad es tu marca de lectura en el feed de actividad de la organización: avánzalo para decir “estoy al día”. Para tableros en vivo usa el feed delta; consulta la receta de tablero en vivo.

Siguientes pasos

• Agentes en Plan para que un agente trabaje una tarjeta como una persona.
• Convenciones de Plan para filtros, paginación y concurrencia.