20 — Implementación — SURCO
1. Resumen ejecutivo técnico
| Campo | Valor |
|---|
| App path | /Users/cristian/orca/surco-app/ |
| API | NestJS · puerto 3007 · prefijo /api |
| Web | Angular standalone · puerto 4200 |
| DB | Neon PostgreSQL · Prisma · old-paper-48739086 |
| Auth | JWT Bearer · roles FARMER | TECHNICIAN |
| Dominio | User, Parcel, FieldTask |
| Fecha | 2026-08-07 |
2. Cómo arrancar
cd /Users/cristian/orca/surco-app
npm install --prefix apps/api
npm install --prefix apps/web
# Configurar apps/api/.env con DATABASE_URL y JWT_SECRET
npm run db:migrate
npm run db:seed
npm run api # http://localhost:3007
npm run web # http://localhost:4200
Credenciales
3. Módulos API implementados
Auth
POST /api/auth/login- Valida email/password; compara bcrypt; emite JWT con
sub, email, role.
JwtStrategy + JwtAuthGuard protegen tasks.
Tasks
| Método | Ruta | Notas |
|---|
| GET | /api/tasks | filtro por rol |
| GET | /api/tasks/stats/summary | total, open, byStatus |
| GET | /api/tasks/:id | ownership check |
| POST | /api/tasks | solo FARMER; parcela upsert; tech opcional |
| PATCH | /api/tasks/:id/status | ownership + reglas tech |
Prisma
Enums Role, TaskStatus; modelos alineados a doc 05; migración init; seed con 2 parcelas y 5 tareas.
4. Frontend implementado
| Página | Responsabilidad |
|---|
| HomePage | marketing, hero, pasos, footer demo |
| LoginPage | form → ApiService.login → navigate tasks |
| TasksPage | stats + list + empty/error + logout |
| TaskNewPage | form create (farmer) |
| TaskDetailPage | get + patch status |
ApiService centraliza base URL, token storage, métodos HTTP tipados (FieldTask, TaskStats, User).
5. Decisiones de implementación
| Decisión | Razón |
|---|
| Puerto API 3007 | Evitar colisión con otros daily apps |
| Soft auth en páginas | Simple L2; API sigue siendo autoridad |
| Parcela por nombre en create | Menos pantallas CRUD en L2 |
| Status ACTIVE al asignar tech | Señal de “en marcha” sin paso extra |
| Templates inline standalone | Velocidad de entrega daily; componentes autocontenidos |
| Stats en endpoint propio | Evita recalcular en cliente y permite evolución |
6. Variables de entorno
| Variable | Servicio | Descripción |
|---|
DATABASE_URL | API | Neon connection string |
JWT_SECRET | API | Firma tokens |
PORT | API | opcional, 3007 |
Web: URL de API configurable en service (default localhost:3007).
7. Smoke de implementación (mínimo)
- Seed OK en consola (
SURCO seed OK).
- Login farmer 200.
- List length ≥ 1.
- Create task 201/200.
- Login tech ve tarea si asignada.
- Patch DONE 200.
- Web muestra badges en español.
8. Estructura de ficheros clave
apps/api/src/main.ts
apps/api/src/auth/*
apps/api/src/tasks/*
apps/api/prisma/schema.prisma
apps/api/prisma/seed.ts
apps/web/src/app/app.routes.ts
apps/web/src/app/core/api.service.ts
apps/web/src/app/pages/**/**
apps/web/tailwind.config.js
apps/web/src/styles.css
9. Despliegue (notas)
No obligatorio para cierre local del case. Sugerencia:
| Pieza | Opción |
|---|
| API | Railway / Fly / Render |
| Web | Netlify / Vercel (static Angular) |
| DB | Neon (ya) |
| CORS | orígenes del front deploy |
10. Criterios de aceptación de implementación
- Comandos del README reproducen el entorno.
- Ambos roles demuestran flujos distintos.
- 403/401 correctos en pruebas de authz.
- UI usa tokens de marca (no default blue Tailwind).
- Case docs enlazan Paper, Neon id, puertos y demos.
