01 — Definición de proyecto — SURCO
1. Identidad
| Campo | Valor |
|---|
| Nombre | SURCO |
| Significado | Surco de labranza: la línea que ordena el campo; metáfora de orden digital del día agrícola |
| Eslogan | ”El campo, al día.” |
| Una frase | Cuaderno digital de parcelas y tareas para explotaciones familiares, con agricultor y técnico de campo. |
| Sector | Agricultura / explotación familiar |
| Tipo | Tool ops multi-rol (cuaderno de campo) — Nivel 2 |
| Plataforma | Web responsive (desktop planificación + móvil de campo) |
| Mercado demo | España (finca familiar mediterránea: olivo, almendro) |
| Idioma | es-ES |
| Fecha caso | 2026-08-07 |
2. Problema
Principal (hipótesis de diseño)
Las explotaciones familiares coordinan riego, poda, muestreos y revisiones de plagas con libretas, notas en el móvil y hilos de WhatsApp. No hay un estado compartido de la tarea ni un historial por parcela que agricultor y técnico vean a la vez.
Secundarios
| Problema | Quién lo sufre | Efecto |
|---|
| Tareas “en la cabeza” del dueño | FARMER | Olvidos, re-trabajo, visitas innecesarias |
| Técnico sin lista clara del día | TECHNICIAN | Llamadas para preguntar “¿qué hago en el bancal X?” |
| Sin código ni fecha de vencimiento | Ambos | Difícil priorizar con varios bancales |
| Papel mojado / ilegible en cabina | Ambos | Pérdida de notas de campo |
Supuestos (no investigación primaria propia)
- S1: En fincas familiares pequeñas–medianas (1–5 parcelas activas), la coordinación se hace sin software de gestión agrícola enterprise.
- S2: El técnico de campo (asesor o empleado) necesita una lista corta de asignaciones, no un ERP.
- S3: El valor inmediato está en estado de tarea + parcela + due date, no en SIG ni compliance legal del cuaderno oficial.
Hipótesis de producto
| ID | Hipótesis | Señal de validación (futura) |
|---|
| H1 | Un listado compartido con estados reduce llamadas de “¿ya regaste?” | ↓ mensajes de estado / semana |
| H2 | Asignar técnico en la creación acelera el paso a ACTIVE | % tareas con technicianId en <24 h |
| H3 | Códigos cortos SU-MMDD-XX facilitan referencia oral en campo | Uso del código en notas/llamadas |
No se afirman estadísticas de mercado inventadas. Todo lo anterior es razonamiento de diseño etiquetado.
3. Propuesta de valor
| Para | Valor |
|---|
| Agricultora (Inés) | Planifica el día de parcela, crea tareas, ve abiertas vs hechas, asigna técnico. |
| Técnico (Pol) | Entra y ve solo sus asignaciones; actualiza ACTIVE → DONE desde el móvil. |
| Explotación | Un cuaderno digital mínimo viable sin ERP ni GPS de flotas. |
No es SURCO
| Excluido | Por qué |
|---|
| Marketplace de insumos o servicios | Eso sería CORREA-like; no es tool de finca |
| Consola GPS / última milla | Eso es TROCHA |
| SaaS legal / expedientes | Eso es FIRME |
| Cuaderno oficial de explotación (compliance) | Alcance regulatorio > L2 |
| Multi-tenant SaaS agro enterprise | Complejidad L3/L4 |
4. Objetivos
Negocio / caso de estudio
- Demostrar vertical slice L2 agro con JWT multi-rol y dominio Parcel/FieldTask.
- Portfolio coherente: Paper + docs + app runnable.
Usuario
| Rol | Objetivo medible en demo |
|---|
| FARMER | Crear tarea en < 2 min; ver summary de abiertas |
| TECHNICIAN | Marcar DONE en < 3 taps desde la lista |
No objetivos v1 (explícitos)
- Mapas y geocercas
- Inventario de productos fitosanitarios
- Facturación o costes por tarea
- Chat in-app
- Roles ADMIN / multi-finca
5. Roles y permisos (resumen)
| Acción | FARMER | TECHNICIAN |
|---|
| Login JWT | Sí | Sí |
| Listar tareas propias | Sí (como farmer) | Sí (asignadas) |
| Ver stats summary | Sí | Sí |
| Crear tarea | Sí | No (403) |
| Ver detalle si es parte | Sí | Sí si technicianId |
| Cambiar status | Sí (todas las transiciones de su tarea) | ACTIVE / DONE / CANCELLED (no fuerza PENDING arbitrario según reglas API) |
6. Métricas (modelo, no instrumentadas en v1 salvo base)
| Tipo | Métrica | Definición |
|---|
| North Star | Tareas DONE / semana | Cierre real de trabajo de campo |
| Activación | 1ª tarea creada por FARMER | Post-login create |
| Engagement | % tareas con técnico asignado | ACTIVE con technicianId |
| Operativa | Tiempo PENDING → DONE | Mediana por parcela |
| Calidad | Tasa error API en list/create | 4xx/5xx |
7. Alcance funcional v1 (L2)
| Módulo | Incluido |
|---|
| Home pública | Hero, 3 pasos, CTAs |
| Auth | POST /api/auth/login → JWT |
| Tareas | GET list, GET by id, POST create, PATCH status, GET stats |
| Parcelas | Creadas implícitamente por nombre en create |
| UI estados | Loading implícito, empty, error de red |
| Seed | 2 usuarios, 2 parcelas, 5 tareas |
8. Criterios de aceptación de producto
- Un FARMER puede iniciar sesión y ver solo sus tareas ordenadas por
dueAt.
- Un TECHNICIAN ve solo tareas donde
technicianId = su id.
- Crear tarea exige título, nombre de parcela y fecha; opcional técnico por email → status ACTIVE.
- El detalle muestra código, parcela, cultivo, ha, notas y permite cambiar estado.
- Sin token, las rutas
/api/tasks* responden 401.
- La home comunica “cuaderno”, no marketplace ni flota.
9. Stack y artefactos
| Capa | Detalle |
|---|
| Frontend | Angular + Tailwind · puerto 4200 |
| Backend | NestJS · puerto 3007 |
| DB | Neon PostgreSQL · Prisma · project old-paper-48739086 |
| Auth | JWT (passport/strategy en API) |
| Diseño | Paper 01KZDGF3509TA4WDZTTQJW1V45 |
| Repo app | /Users/cristian/orca/surco-app/ |
10. Riesgos y mitigaciones
| Riesgo | Impacto | Mitigación v1 |
|---|
| Confundir con ERP agro | Expectativa inflada | Copy “cuaderno”, alcance L2 en docs |
| Offline real de campo | Técnico sin red | Documentado fuera de alcance; UI de error clara |
| Confusión de roles | 403 inesperado | Badge de rol en header; solo FARMER ve “+ Tarea” |
| Parcela duplicada por typo | Datos sucios | findFirst por nombre; mejora futura: selector |
11. Glosario
| Término | Definición en SURCO |
|---|
| Parcela / bancal | Unidad de tierra con nombre, cultivo y hectáreas |
| Tarea de campo | Trabajo planificado (riego, poda, muestreo…) con estado y vencimiento |
| Cuaderno | Vista principal de tareas + stats del usuario |
| Código SU- | Identificador corto oral (SU-0807-01) |
