14 — Handoff a desarrollo — SURCO

1. Fuentes de verdad

Artefacto	Ubicación
Case UX	`/Users/cristian/orca/ux-projects/2026-08-07-surco/`
Paper	https://app.paper.design/file/01KZDGF3509TA4WDZTTQJW1V45
Código	`/Users/cristian/orca/surco-app/`
Schema	`apps/api/prisma/schema.prisma`
Seed	`apps/api/prisma/seed.ts`
Tokens UI	`apps/web/tailwind.config.js` + docs 07–08

2. Arranque local

cd /Users/cristian/orca/surco-app
cp apps/api/.env.example apps/api/.env   # si existe; configurar DATABASE_URL + JWT_SECRET
npm install --prefix apps/api
npm install --prefix apps/web
npm run db:migrate
npm run db:seed
npm run api    # :3007
npm run web    # :4200

Demo: campo@surco.agro / tecnico@surco.agro · password123

3. Mapa de pantallas → código

UI	Ruta	Archivo
Home	`/`	`apps/web/src/app/pages/home/home.page.ts`
Login	`/login`	`.../login/login.page.ts`
Tasks	`/app/tasks`	`.../tasks/tasks.page.ts`
New	`/app/tasks/new`	`.../task-new/task-new.page.ts`
Detail	`/app/tasks/:id`	`.../task-detail/task-detail.page.ts`
API client	—	`apps/web/src/app/core/api.service.ts`
Routes	—	`apps/web/src/app/app.routes.ts`

4. Mapa API → código

Endpoint	Controller/Service
POST `/api/auth/login`	`auth.controller.ts` / `auth.service.ts`
JWT guard/strategy	`jwt-auth.guard.ts` / `jwt.strategy.ts`
Tasks *	`tasks.controller.ts` / `tasks.service.ts`

5. Contratos (resumen)

// POST /api/auth/login
{ "email": "campo@surco.agro", "password": "password123" }

// 200
{ "accessToken": "<jwt>", "user": { "id": "...", "email": "...", "name": "Inés Roura", "role": "FARMER" } }

Create task

{
  "title": "string min 3",
  "parcelName": "string min 2",
  "crop": "optional string",
  "dueAt": "ISO-8601",
  "notes": "optional",
  "technicianEmail": "optional email"
}

Status

{ "status": "PENDING" | "ACTIVE" | "DONE" | "CANCELLED" }

6. Reglas de negocio a no romper

Solo FARMER crea tareas.
List/get filtrados por rol (no “list all”).
Parcela se resuelve por nombre + farmerId.
Técnico válido → status inicial ACTIVE.
Código SU-… único.
TECHNICIAN no fuerza estados fuera de su subconjunto permitido en service.

7. Checklist de paridad Paper ↔ app

Frame	Paridad mínima
C-0 Home	hero, eslogan, 3 pasos, CTAs
D-0 Login	email/password, error
F-0 Tasks	stats + lista + rol
G-0 Detail	meta + status actions
H-0 New	form completo
L/M states	empty + error copy

8. Definition of Done (feature nueva)

Endpoint con DTO + authz
UI con tokens SURCO (no gris genérico)
Empty/error si aplica
Seed o fixture actualizado
Doc 04/05 tocados si cambia flujo o modelo
Smoke del flujo en QA 13

9. Deuda técnica conocida (no alcance L2 bloqueante)

Ítem	Nota
Guard de rutas Angular formal	Hoy check en página
Refresh token	No
Tests e2e automatizados	Plan manual en doc 13
Selector parcela	Texto libre
i18n	Solo es-ES

10. Contacto de decisión de producto

Para cambios de alcance L2 vs L3: ver docs/00-day-brief.md y docs/15-roadmap.md.
No reintroducir marketplace ni GPS fleet sin cambio explícito de brief de diversidad.