04 — Flujos de usuario — SURCO

Convenciones

• Actor: FARMER | TECHNICIAN | Guest
• Éxito: resultado observable
• Errores: UI + código HTTP cuando aplica

F1 — Descubrimiento y entrada (Guest)

Home (/) → CTA "Abrir cuaderno" | "Entrar" | "Soy agricultor/técnico"
        → Login (/login)

Éxito: formulario de login visible.
No hay registro público en v1 (solo seed).

F2 — Login JWT

/login → POST /api/auth/login { email, password }
      → 200 { accessToken, user } → localStorage → /app/tasks
      → 401 → mensaje error en form

Éxito: token guardado; user con role FARMER o TECHNICIAN.
Errores:

F3 — Listar tareas + stats

/app/tasks (guard token en cliente)
  → GET /api/tasks
  → GET /api/tasks/stats/summary
  → Render cards + 4 métricas

Orden: dueAt ASC.
Include: farmer, technician, parcel.

Variantes de UI

AC:

1. Sin token → redirect /login.
2. Técnico no ve botón “+ Tarea”.
3. Stats open = PENDING + ACTIVE.

F4 — Crear tarea (solo FARMER)

/app/tasks → + Tarea → /app/tasks/new
  → submit → POST /api/tasks
  → 201/200 task → navegar a lista o detalle
  → 403 si TECHNICIAN

Campos

Lógica de negocio

1. Buscar parcela del farmer por name; si no existe, crear con hectares: 1 y crop dado.
2. Si technicianEmail: buscar user role TECHNICIAN; si no, 404 “Técnico no encontrado”.
3. Generar code = SU- + MMDD + - + random 100–999.
4. Status inicial: PENDING sin técnico; ACTIVE con técnico.

Errores:

AC: FARMER con datos válidos ve la nueva tarea en la lista ordenada por dueAt.

F5 — Detalle y cambio de estado

/app/tasks/:id
  → GET /api/tasks/:id
  → usuario elige nuevo status
  → PATCH /api/tasks/:id/status { status }
  → UI actualiza badge

Permisos get

Permisos patch (resumen API)

• Debe ser parte (mismas reglas que get).
• TECHNICIAN: status permitido en subconjunto ACTIVE | DONE | CANCELLED (no impone PENDING según guard de servicio).
• FARMER: puede actualizar status de sus tareas (incluye cancelar).

Transiciones de diseño (happy)

PENDING ──► ACTIVE ──► DONE
    │           │
    └───────────┴──► CANCELLED

AC: tras DONE, la lista muestra badge “Hecha” y stats HECHAS incrementa al refrescar.

F6 — Logout

Click Salir → clear token/user → /login

AC: volver a /app/tasks redirige a login.

F7 — Flujos de error transversales

Diagrama resumen ( Mermaid )

flowchart TD
  H[Home] --> L[Login]
  L -->|JWT OK| T[Tasks list]
  L -->|401| L
  T -->|FARMER| N[New task]
  N -->|POST| T
  T --> D[Detail]
  D -->|PATCH status| D
  T -->|logout| L

Matriz flujo × rol