taskbot/docs/plan-web-fases.md

# Plan de trabajo — Web (SvelteKit) orientado a móvil y acciones de tareas

Contexto y objetivos
- Reforzar la utilidad móvil, mostrar grupos y responsables correctamente, y simplificar acciones prioritarias (completar/undo) manteniendo seguridad (gating) alineada con el backend.
- Mantener el diseño sin truncar descripciones; ofrecer orden por fecha o por grupo; y mostrar TODAS las abiertas en /app/groups.
- Evitar regresiones, con cambios iterativos y fácilmente revertibles.

Decisiones globales
- No truncar descripciones en TaskItem; envolver en varias líneas. Acciones secundarias se desplazan a una segunda línea/menú contextual en móvil.
- “Completar” se promueve como acción principal (checkbox/botón destacado). Incluir “Deshacer completar” con ventana configurable (24h por defecto).
- “Mis tareas” tendrá dos secciones: 
  1) Asignadas a mí (todas abiertas). 
  2) Sin responsable de mis grupos (todas abiertas).
- “Grupos” mostrará secciones por grupo, con TODAS las tareas abiertas, expandibles/colapsables, y con toggle “Unassigned first”.
- Búsqueda por texto desaparece de la UI (se reserva a futuro si fuese necesaria).
- Orden conmutado por el usuario: Fecha (due asc, NULL al final) | Grupo (agrupación por grupo y dentro por fecha).
- Seguridad: endurecer PATCH de tareas sin grupo para exigir ser responsable (y opcionalmente creador si el esquema lo permite).
- Ventana de uncomplete (deshacer completar): configurable por variable de entorno UNCOMPLETE_WINDOW_MIN (1440 por defecto).

Medición de impacto y riesgos
- N+1 inicial en /app (al agregar “sin responsable” de todos los grupos) tolerable en MVP, mitigado luego con endpoint “overview”.
- Posible crecimiento de DOM en /app/groups: se mitiga con secciones colapsables.
- Cambios de gating en PATCH requieren revisar casos edge (tareas personales sin asignados previos).

Archivos ya disponibles para edición (confirmados)
- UI: 
  - apps/web/src/lib/ui/layout/AppShell.svelte
  - apps/web/src/lib/ui/data/TaskItem.svelte
  - apps/web/src/lib/ui/data/GroupCard.svelte
  - apps/web/src/routes/app/+page.svelte
  - apps/web/src/routes/app/+page.server.ts
  - apps/web/src/routes/app/groups/+page.svelte
  - apps/web/src/routes/app/groups/+page.server.ts
- API:
  - apps/web/src/routes/api/me/tasks/+server.ts
  - apps/web/src/routes/api/me/groups/+server.ts
  - apps/web/src/routes/api/groups/[id]/tasks/+server.ts
  - apps/web/src/routes/api/tasks/[id]/+server.ts (PATCH)
  - apps/web/src/routes/api/tasks/[id]/claim/+server.ts
  - apps/web/src/routes/api/tasks/[id]/unassign/+server.ts
  - apps/web/src/routes/api/tasks/[id]/complete/+server.ts
- Infra web:
  - apps/web/src/lib/server/env.ts
  - apps/web/src/lib/server/db.ts
- Núcleo:
  - src/db.ts

Archivos que solicitaremos añadir al chat cuando toque editar
- Documentación: docs/operations.md (para documentar UNCOMPLETE_WINDOW_MIN y notas UX).
- Tests: tests/web/* y tests/unit/* (para cubrir uncomplete y cambios de gating).
- (Opcional) Migraciones: src/db/migrations/* si llegamos a necesitar created_by en gating de PATCH.

Fase 1 — UX base en páginas y TaskItem (sin backend nuevo)
Objetivos
- /app: añadir sección “Sin responsable de mis grupos”, quitar búsqueda, añadir conmutador de orden (Fecha | Grupo).
- /app/groups: mostrar TODAS las tareas por grupo en secciones expandibles/colapsables; toggle “Unassigned first”.
- TaskItem: mostrar chip de grupo; mantener descripción sin truncar; reorganizar acciones para móvil.
Archivos a editar
- apps/web/src/routes/app/+page.server.ts
  - Cargar /api/me/tasks (open, asignadas a mí).
  - Cargar /api/me/groups; para cada grupo, solicitar /api/groups/:id/tasks?onlyUnassigned=true&limit=0 y reunir la lista “unassigned”.
  - Construir map {groupId → groupName} para la UI.
  - Gestionar query param order=due|group.
- apps/web/src/routes/app/+page.svelte
  - Renderizar dos secciones (asignadas y sin responsable). Añadir conmutador de orden. Eliminar campo de búsqueda.
- apps/web/src/routes/app/groups/+page.server.ts
  - En vez de previews, cargar /api/groups/:id/tasks?limit=0 para cada grupo (todas abiertas).
  - Permitir query unassignedFirst=true (por grupo o global).
- apps/web/src/routes/app/groups/+page.svelte
  - Reemplazar cuadrícula de GroupCard por secciones por grupo (cabecera con +/– para colapsar).
  - Dentro de cada sección, lista de TaskItem reutilizando las mismas acciones.
- apps/web/src/lib/ui/data/TaskItem.svelte
  - Mostrar chip con el nombre del grupo si group_id != null; “Personal” si no tiene grupo (usar map pasado desde el server o prop groupName).
  - Promover “Completar” visualmente (sin cambiar aún la API).
- apps/web/src/lib/ui/data/GroupCard.svelte
  - Mantener para posibles resúmenes; la página de grupos dejará de usarla de forma principal.
Decisiones
- Orden “por grupo” inicialmente puede agruparse en cliente para el agregado “sin responsable”; “asignadas” ya vienen por fecha. En fases posteriores, endpoint overview dará orden estable en servidor.

Fase 2 — Backend: Uncomplete (24h configurable) + seguridad de PATCH
Objetivos
- Añadir POST /api/tasks/:id/uncomplete (idempotente) con gating simétrico a /complete y ventana configurable.
- Endurecer PATCH /api/tasks/:id para tareas sin group_id: exigir que el usuario sea asignado (y, si luego confirmamos schema, permitir también si created_by = usuario).
Archivos a editar/crear
- apps/web/src/lib/server/env.ts
  - Añadir export const UNCOMPLETE_WINDOW_MIN = ... (leer de env, default 1440). Exponer helper uncompleteWindowMs si conviene.
- apps/web/src/routes/api/tasks/[id]/uncomplete/+server.ts (nuevo)
  - Validar sesión, id, existencia de tarea.
  - Gating: 
    - Con group_id: miembro activo de grupo allowed.
    - Sin group_id: debe estar asignado a la tarea.
  - Validar ventana: completed=1 y completed_at >= now - UNCOMPLETE_WINDOW_MIN.
  - UPDATE: completed=0, completed_at=NULL (y opcional completed_by=NULL).
  - Respuesta: status ('updated'|'already'|'not_found'|'forbidden'), tarea resultante.
- apps/web/src/routes/api/tasks/[id]/+server.ts (PATCH)
  - Añadir chequeo cuando group_id IS NULL: exigir que exista asignación del user sobre la tarea (alineado con complete/unassign).
- UI
  - apps/web/src/lib/ui/data/TaskItem.svelte — añadir acción “Deshacer completar” (usando el nuevo endpoint) y toast con feedback.
  - apps/web/src/routes/app/+page.svelte — en la sección “Completadas (24 h)” añadir botón “Deshacer completar”.
Documentación y configuración (solicitaremos permiso para editar)
- docs/operations.md — documentar UNCOMPLETE_WINDOW_MIN (minutos; default 1440), semántica e idempotencia.

Fase 3 — Navegación móvil (barra de pestañas) y jerarquía de acciones
Objetivos
- Evitar que el header rebose en móvil. Añadir barra inferior con iconos (tabs) para Tareas, Grupos, Integraciones (calendario), Preferencias (alarma). Reducir peso visual de “Integraciones” en móvil.
- Consolidar “Completar” como acción primaria (checkbox/botón destacado); otras acciones (Reclamar/Soltar/Editar/Fecha) en segunda línea o menú contextual.
Archivos a editar/crear
- apps/web/src/lib/ui/layout/AppShell.svelte
  - Añadir barra inferior sticky (solo en viewport ≤768px), con safe-area, iconos (SVG inline o emojis inicialmente), aria-labels y foco accesible.
  - Mantener header para desktop.
- (Opcional) apps/web/src/lib/ui/icons/* (nuevos)
  - CalendarIcon.svelte, AlarmIcon.svelte, TasksIcon.svelte, GroupsIcon.svelte (si prefieres SVGs en vez de emojis).
- apps/web/src/lib/ui/data/TaskItem.svelte
  - Ajustar layout mobile-first: acciones secundarias y espaciado compacto.

Fase 4 — Optimización: endpoint “overview” y orden en servidor
Objetivos
- Evitar N peticiones en /app para el bloque “sin responsable”.
- Servir orden “por grupo” ya resuelto en servidor.
Archivos a crear/editar
- apps/web/src/routes/api/me/tasks/overview/+server.ts (nuevo)
  - Respuesta: { assigned: Task[], unassigned: Task[] } (open).
  - Params: order=due|group_then_due (por defecto due).
  - Cada Task incluye: id, description, due_date, group_id, group_name, display_code, assignees[].
  - Gating: igual que /api/me/tasks.
- apps/web/src/routes/api/me/tasks/+server.ts
  - (Opcional) Añadir order=group_then_due y group_name via JOIN; mantener compatibilidad con tests existentes.
- apps/web/src/routes/app/+page.server.ts
  - Consumir overview para reducir llamadas y aplicar el orden de servidor.

Fase 5 — Responsables: conteo, marca “tú” y popover con wa.me
Objetivos
- Mostrar de forma compacta cuántas personas están asignadas; marcar si el usuario actual está entre ellas; listar números y permitir mensaje directo (wa.me) bajo demanda.
Archivos a editar/crear
- apps/web/src/lib/ui/data/TaskItem.svelte
  - Badge “Responsables: n” + “tú” si corresponde; al pulsar, abrir popover/modal con lista.
- apps/web/src/lib/ui/feedback/Popover.svelte (nuevo) o reutilizar un modal ligero existente
  - Accesibilidad: rol="dialog", focus trap, cierre con ESC.
- (Opcional) apps/web/src/lib/utils/phone.ts (nuevo)
  - Helpers para abreviar números y construir URL segura wa.me.

Fase 6 — Pulido y peso visual de “Integraciones”
Objetivos
- Mantener “Integraciones” accesible pero de menor jerarquía en móvil.
- Ajustar densidad, estados vacíos y mensajes, y recordar colapsado por grupo en localStorage.
Archivos a editar
- apps/web/src/lib/ui/layout/AppShell.svelte (tono/estilo de pestaña Integraciones).
- apps/web/src/routes/app/groups/+page.svelte (estado colapsado persistente).
- apps/web/src/routes/app/+page.svelte (estados vacíos claros).

Criterios de aceptación resumidos
- /app muestra dos secciones con todas las tareas requeridas; sin truncar descripciones; orden conmutado.
- /app/groups muestra todas las tareas abiertas por grupo; secciones colapsables; “Unassigned first” operativo.
- Completar y Deshacer completar funcionan desde ambas páginas; ventana de 24h configurable; gating correcto.
- PATCH no permite editar tareas sin grupo si no eres responsable (o creador, si se habilita).
- Navegación móvil no rebosa; barra inferior accesible.
- Asignados: conteo visible, “tú” resaltado y lista en popover con wa.me.

Notas de implementación y buenas prácticas
- Mantener cabeceras cache-control: no-store en endpoints de listas/acciones.
- Reutilizar el gating ya presente en claim/unassign/complete; factorizar si conviene (pero sin sobre-ingeniería).
- Idempotencia en endpoints de mutación (claim, unassign, complete, uncomplete).
- Evitar dependencias externas para UI; usar SVG inline o emojis como placeholder.
- Accesibilidad: aria-label en iconos, focus visible, roles correctos en popovers/diálogos.

Siguientes pasos
1) Implementar Fase 1 (UI base) con los archivos listados.
2) Implementar Fase 2 (uncomplete + PATCH gating).
3) Validar en móvil; luego abordar Fase 3 (tabs inferiores).
4) Optimizar con overview (Fase 4) y cerrar UX de responsables (Fase 5).
5) Pulido y documentación (Fase 6).