# Ballbox

Host app de Ballbox en Next.js.

## Qué hay hoy

- Marketing site en `/`
- Admin compartido en `/admin`
- Surface estudiante en `/classes`
- Módulo TVs operativo en Ballbox:
  - `/admin/tvs`
  - `/admin/screens`
  - `/player/[screenId]`
  - `/api/tvs/*`
- Integración de pagos parcial:
  - Ballbox recibe callbacks aprobados
  - Ballbox recibe webhooks de MercadoPago en `/notification/mercadopago`
  - Ballbox persiste `PaymentSession`
  - migración de QR/order lifecycle hacia host app en progreso
- Network con lectura/escritura real desde Postgres:
  - `/admin/network`
  - `/api/network`
  - `/api/network/[clubId]`
- Players ya tiene API/admin CRUD base sobre Postgres
- Sports ya tiene API/admin CRUD base para coaches, open matches y classes
- `/classes` ya tiene MVP autenticado con offers locales, request local y contexto ATC publico resiliente
- `/classes/me` ya muestra historial demo de solicitudes por email para seguimiento liviano del loop

## Stack

- Next.js 16
- React 19
- Prisma
- PostgreSQL
- pnpm

## Variables de entorno

Copiar `.env.example` a `.env.local` y completar:

- `DATABASE_URL`: Postgres local de desarrollo o Postgres remoto de Ballbox
- `BALLBOX_PAYMENTS_URL`: URL base de `ballbox-payment-integration`
- `BALLBOX_PAYMENTS_SHARED_SECRET`: bearer shared secret canónico para callback inbound y requests outbound hacia `ballbox-payment-integration`
- `BALLBOX_PAYMENTS_CALLBACK_TOKEN`: fallback legacy; todavía aceptado si no existe `BALLBOX_PAYMENTS_SHARED_SECRET`
- `BALLBOX_MERCADOPAGO_ACCESS_TOKEN`: access token de MercadoPago para fetch de order details
- `BALLBOX_MERCADOPAGO_WEBHOOK_SECRET`: secreto webhook de MercadoPago para validar `x-signature`
- `BALLBOX_MERCADOPAGO_EXTERNAL_POS_ID`: `external_pos_id` por defecto para creación de orders QR (se puede override por request)
- `BALLBOX_ADMIN_PASSWORD`: shared password para `/admin`
- `NEXT_PUBLIC_SITE_URL`: URL pública de Ballbox; usada para callback URLs y metadata
- `BALLBOX_SEED_COACH_PASSWORD`: password para coaches seeded
- `BALLBOX_SEED_CLUB_PASSWORD`: password para clubs seeded

## Comandos

```bash
pnpm db:local:up
pnpm db:local:down
pnpm db:local:logs
pnpm db:deploy
pnpm db:migrate --name <slug>
pnpm db:status
pnpm db:check-migrations
pnpm db:clone-prod-to-local
pnpm dev
pnpm lint
pnpm typecheck
pnpm test:contracts
pnpm test:unit
pnpm test:integration
pnpm test:e2e
pnpm build
pnpm db:generate
pnpm db:seed
pnpm dangerously-sync-without-migration
```

Nota:
- Prisma en este repo es migration-first. Para cambios de schema usar `pnpm db:migrate --name <slug>`; no usar `prisma db push` en flujo normal.
- `pnpm dev` siempre usa DB local: intenta arrancarla con Docker/Docker Compose primero y con paths no-Docker después, corre `db:deploy` + `db:generate`, y luego levanta Next dev.
- `pnpm db:clone-prod-to-local` reemplaza la DB local con un dump de producción, luego aplica las migraciones committeadas y regenera Prisma Client. Requiere `CLONE_LOCAL_DB_CONFIRM=1`.
- `pnpm dangerously-sync-without-migration` existe solo como escape hatch para trabajo descartable y requiere `ALLOW_UNSAFE_PRISMA_DB_PUSH=1`.
- Los wrappers Prisma de migrate/deploy/status rechazan por default `DATABASE_URL` no local; para override explícito usar `ALLOW_REMOTE_PRISMA_COMMANDS=1`.
- `pnpm db:check-migrations` siempre valida el schema Prisma y, cuando hay una `DATABASE_URL` local/CI segura, también corre `migrate status`.
- Los wrappers Prisma cargan `.env.local` si existe; en CI/otros entornos usan `DATABASE_URL` del entorno.
- Producción aplica `pnpm db:deploy` desde GitHub Actions al hacer push a `main`.
- Evitar `pnpm prisma ...` directo si el shell no tiene `DATABASE_URL` exportada.

## Postgres local

Para desarrollo local ya existe `docker-compose.yml` con Postgres 16.

1. opcional si quieres datos reales: `CLONE_LOCAL_DB_CONFIRM=1 pnpm db:clone-prod-to-local`
2. `pnpm dev`
3. si cambias schema, en otra terminal: `pnpm db:migrate --name <slug>`
4. refresca la app; si Next queda raro, reinicia `pnpm dev`
5. corre tests y luego commitea código + migraciones

Credenciales demo que deja el seed:

- Coaches:
  - `juan.silva@ballbox.demo`
  - `valentina.acosta@ballbox.demo`
- Clubs:
  - `club.sanisidro@ballbox.demo`
  - `club.palermo@ballbox.demo`
- Password por default:
  - `demo-pass`

## Gate actual

Antes de handoff:

```bash
pnpm lint
pnpm typecheck
pnpm test:contracts
pnpm test:e2e
pnpm build
```

Push protection local:
- Hay hooks versionados en `.githooks/pre-commit` y `.githooks/pre-push`.
- `pre-commit` bloquea cambios en `prisma/schema.prisma` si no vienen acompañados por migración stageada.
- `pre-push` solo corre cuando el push incluye `main`.
- `pre-push` ejecuta `docs:check`, `db:local:up`, `db:deploy`, `db:check-migrations`, `lint`, `typecheck`, `test:contracts` y `build` antes de permitir el push a `main`.
- En branches no-main, la validación ocurre en CI al abrir/actualizar PR.

## Estado por dominio

### TVs

- Persistencia real en Ballbox Postgres
- Manifests, heartbeats e impressions activos
- Seed demo todavía usado como bootstrap local
- Contrato formal de APIs TVs protegido por tests de contrato

### Payments

- Callback aprobado implementado
- Webhook MercadoPago implementado en host app (`/notification/mercadopago`)
- Creación de orders QR implementada en host app (`/api/integrations/payments/orders`)
- Sesiones aprobadas listables desde Ballbox
- Callback inbound endurecido con bearer shared secret + validación de `payment:{vendingMachineId}:{machineTxnId}`
- Mapping `vendingMachine/slot/club/venue` pendiente
- Bridge externo en transición (compatibilidad temporal)
- Falta validación manual end-to-end con configuración real de MercadoPago y webhook público

### Network

- CRUD administrativo para clubs, venues y vending machines
- Shared core canónico para TVs y payments
- Naming canónico ya aplicado en schema, APIs y surface admin principal
- Clubs nuevos quedan arriba en admin para feedback inmediato

### Players

- API DB-backed para listado de players
- Modelos Prisma `Player` y `Membership` ya activos
- CRUD admin base activo
- Sin benefits/activity reales

## Playwright

- Cleanup determinístico before/after suite sobre fixtures `PW E2E` / `pw-e2e-*`, incluyendo `PaymentSession`
- Cobertura actual:
  - TVs runtime offline
  - active nav en admin
  - smoke mobile en `/admin/network` y `/admin/tvs`
  - CRUD completo de `network`
  - CRUD/reconciliation smoke de `payments`
  - CRUD de `players`
  - CRUD de `sports`

### Sports

- Admin/UI DB-backed para coaches, open matches y classes
- Modelos Prisma `Coach`, `OpenMatch`, `Class` ya activos
- MVP `/classes` con modelos Prisma `ClassOffer` y `ClassRequest`
- `/classes` es publico; si falla ATC public-read la UI cae a unavailable sin romper la pagina
- Validacion de experiencia de entrenadores en curso via formulario online; todavia sin suficiente evidencia de workflow real para fijar el wedge
- Sin ATC write/admin ni inbox operador todavia

## Docs

- Strategic company/discovery mirror for the current coaches track also lives in `~/ballbox-company-agent/projects/coaches-os/`; source of truth for this repo remains `PLAN.md` plus local product docs

- `PLAN.md`: estado y próximos pasos
- `docs/index.md`
- `PLAN.md`
- `docs/index.md`
- `docs/repo-map.md`
- `docs/coaches-discovery-stage.md`
- `docs/coaches-form-current.md`
- `docs/atc-integration-discovery.md`
- `docs/coaches-discovery-execution-plan.md`
- `docs/coaches-icp-segmentation.md`
- `docs/coaches-wedges-matrix.md`
- `docs/coaches-interview-script.md`
- `docs/coaches-jtbd-workflow-map.md`
- `docs/coaches-solution-thesis.md`
- `docs/atc-access-request-checklist.md`
- `docs/coaches-design-partner-outreach.md`
- `docs/atc-integration-spec-skeleton.md`
- `docs/coaches-coordination-gap-analysis.md`
- `docs/classes-subroute-plan.md`
- `docs/classes-mvp-rfc.md`
- `docs/coaches-opportunity-brief.md`
- `docs/coaches-research-repository.md`
- `docs/coaches-validation-checklist-2-weeks.md`
- `docs/atc-mock-integration-plan.md`
- `docs/demo-iteration-mode.md`
- `docs/implemented-host-app.md`
- `docs/implemented-network.md`
- `docs/implemented-tvs.md`
- `docs/implemented-payments.md`
- `docs/implemented-players.md`
- `docs/implemented-sports.md`
- `docs/ballbox-db-plan.md`
- `docs/domain-model-target.md`
- `docs/streetcast-parity.md`
- `docs/screen-runtime-delivery-investigation.md`