Onboarding de desarrolladores

Cómo levantar cada repo localmente y el flujo de trabajo del equipo. Para el diseño general del sistema ver Arquitectura.

Requisitos previos

• Node.js + npm (backend, admin, docs)
• Docker + Docker Compose (backend: PostgreSQL + Redis)
• Flutter (Dart 3.9 — no una versión más nueva, ver nota de Drift más abajo)

camaroneras_backend

docker compose up -d          # levanta PostgreSQL (puerto host 5433) + Redis
cp .env.template .env         # completar valores (JWT secrets, Mailtrap, etc.)
npm install
npx prisma migrate dev        # crea/aplica migraciones
npm run start:dev             # http://localhost:3000, Swagger en /api/docs

Variables de entorno (.env.template es la lista completa y versionada; .env real no se versiona ni lo edita el asistente):

Grupo	Variables
Base de datos	DATABASE_URL
Servidor	PORT, WEB_URL
CORS	CORS_ORIGINS
Cookies	COOKIE_SECURE
Redis	REDIS_URL (+ REDIS_FAMILY, solo en redes IPv6-only)
Swagger	SWAGGER_ENABLED
JWT	JWT_ACCESS_SECRET / _EXPIRES_IN, JWT_REFRESH_*, JWT_ONBOARDING_*
Email	MAIL_HOST, MAIL_PORT, MAIL_USER, MAIL_PASSWORD, MAIL_FROM

CORS_ORIGINS son orígenes separados por coma, sin espacios (http://localhost:5173,https://admin.camaroneras.com). Vacío = permite todos los orígenes — solo aceptable en desarrollo, nunca en producción. Solo afecta al navegador (admin); mobile no usa CORS.

Comandos frecuentes

npm run lint          # eslint check-only (gate; usa lint:fix para aplicar cambios)
npm run test           # unitarios
npm run test:e2e       # e2e (requiere Docker arriba; mockea servicios externos)
npx prisma studio       # explorar la BD (GUI)
npx prisma generate      # regenerar el cliente Prisma

Gotcha: tras npx prisma migrate dev, si el editor sigue marcando propiedades del modelo como inexistentes (Property 'X' does not exist on PrismaService), correr npx prisma generate explícito — el cliente generado no siempre se refresca solo.

Repoblar con datos de demo

Tras un npx prisma migrate reset (o para tener datos de ejemplo en un ambiente nuevo):

npm run start:dev    # una vez, para que el onModuleInit siembre catálogos (equipos, RBAC)
npm run seed:demo    # crea 2 organizaciones con datos en todos los módulos de negocio

prisma/seed.ts es idempotente por piscina: si una piscina demo ya tiene un ciclo sembrado, se omite su historia completa (no duplica). Se niega a correr si NODE_ENV=production o si DATABASE_URL no aparenta ser una base de dev/demo (override explícito: SEED_DEMO_FORCE=true). Las fechas de los registros (muestreos, alimentación, parámetros, eventos, cosechas) se calculan relativas a "hoy" cada vez que se corre, para que la actividad más reciente de cada ciclo quede siempre cerca de la fecha actual.

Credenciales fijas de demo — cada organización tiene un usuario por cada rol por defecto:

Organización	Administrador	Técnico	Bodeguero	Password (todos)
Camaronera Demo Uno	[email protected]	[email protected]	[email protected]	12345678
Camaronera Demo Dos	[email protected]	[email protected]	[email protected]	12345678

camaroneras_admin

cp .env.template .env   # VITE_API_URL=http://localhost:3000/api/v1
npm install
npm run dev              # http://localhost:5173

npm run lint
npm run test:run     # unit + componente, una sola corrida (gate de cierre)
npm run test:e2e      # Playwright — pesado, fuera del gate, correr manual

camaroneras_mobile

flutter pub get
dart run build_runner build --delete-conflicting-outputs   # codegen Drift
flutter run

La URL del backend se configura en lib/core/config/env.dart (no hardcodear en widgets).

flutter analyze
flutter test

Drift está fijado a >=2.28 <2.31: las versiones 2.31+ exigen sqlite3 3.0, que a su vez requiere Dart 3.10+, y el entorno del equipo usa Dart 3.9. Subir Drift implica subir Dart primero (ADR-0023).

Para generar un APK de release: skill local build-apk → deja el instalable en _builds/ (ignorado por git, no se versiona).

Flujo de trabajo del equipo (kit pm)

El proyecto se gestiona con el kit global pm (skills en ~/.claude/skills/). Config del proyecto en .claude/pm.json (repos, comandos de test/build, convención de rama/commits, rutas).

1. /pm-crear-tarea [nombre] — recopila contexto pregunta por pregunta, crea _planning/[tarea]-plan.md + -progress.md, define repos y rama. Stop obligatorio: no se escribe código hasta aprobación explícita del plan.
2. Implementar en la rama feat/[tarea], actualizando progress.md en tiempo real.
3. /pm-cerrar-tarea [nombre] — corre el gate de cada repo afectado; solo si pasa, sugiere el commit (Conventional Commits, en inglés), verifica CLAUDE.md, registra derivados en el backlog y archiva la tarea.

/pm-doc-endpoints [modulo] genera/actualiza la documentación de endpoints de un módulo parseando el controller NestJS. El humano siempre hace el commit, el PR y el merge — las skills solo sugieren.

Gates de cierre por repo

Una tarea no se cierra si sus tests no pasan (ADR-0024).

Repo	Gate
camaroneras_backend	npm run lint && npm run test && npm run test:e2e
camaroneras_admin	npm run lint && npm run build && npm run test:run
camaroneras_mobile	flutter analyze && flutter test

Los E2E de Playwright (admin) quedan fuera del gate por pesados — se corren manual.

Troubleshooting común

• Backend — Prisma client desactualizado: ver nota en la sección de backend más arriba.
• Backend — e2e falla intermitente: carrera de conexiones en la BD de dev compartida; re-correr. Se confirma estabilidad con 2 corridas verdes seguidas antes de cerrar.
• Mobile — flutter analyze falla tras cambiar el schema de Drift: falta regenerar .g.dart con dart run build_runner build --delete-conflicting-outputs. Nunca editar esos archivos a mano.