Areto
Aplicación web para la gestión de un club de fútbol sala: personas, equipos,
calendario, cuotas y comunicación en una sola herramienta.
Stack
- Next.js 16 (App Router) + React 19 + TypeScript
- Tailwind CSS v4 + shadcn/ui (base-ui, estilo
nova)
- PostgreSQL + Drizzle ORM
- Supabase Auth (email+contraseña) con roles
Entornos
El proyecto usa dos proyectos Supabase separados:
- producción: datos reales de socios y jugadores. Solo lo usa el entorno
"Production" de Vercel.
- areto-dev: usado en local (
.env.local) y por los entornos "Preview" y
"Development" de Vercel (incluidos los Preview Deployments de cada PR).
Nunca apuntes .env.local al proyecto de producción. Ver Puesta en
marcha para crear areto-dev.
Los PRs a main corren CI (.github/workflows/ci.yml): lint, typecheck,
db:check, comprobación de que src/db/schema.ts no tiene cambios sin
migración generada, db:migrate contra areto-dev y next build.
Las migraciones a producción se aplican automáticamente al mergear un PR
que traiga ficheros en drizzle/ (migrate-prod.yml, que hace un backup
cifrado justo antes). El mismo workflow sigue siendo lanzable a mano desde
Actions para relanzarlo tras un fallo. El disparo es el push a main y no el
final del despliegue por una razón concreta: con cacheComponents: true,
next build ejecuta consultas reales, así que el esquema nuevo tiene que
estar aplicado antes de que Vercel termine de construir el código nuevo. Si
alguna vez el build sale antes que la migración, falla, producción sigue
sirviendo el despliegue anterior y basta con pulsar Redeploy en Vercel.
Flujo de trabajo (ramas y PRs)
La rama main está protegida: no se puede empujar directamente a ella.
Todo desarrollo va en su propia rama y entra a main mediante un Pull Request:
git switch -c feat/nombre-corto # o fix/…, chore/…
# … trabajo, commits …
git push -u origin feat/nombre-corto
Abre el PR contra main en GitHub, espera a que pase el CI y mergéalo. El PR
genera además un Preview Deployment en Vercel (contra areto-dev) para probar
los cambios antes de mergear.
El procedimiento detallado (comandos, decisión expand/contract al tocar el
esquema y recetas para cuando algo falla) vive en
.claude/skills/desarrollar-funcionalidad/, como skill de Claude Code.
Puesta en marcha
- Instala dependencias:
pnpm install
- Crea un proyecto en Supabase llamado, por ejemplo,
areto-dev (nunca reutilices el de producción para desarrollo local) y
configura el entorno. Copia el ejemplo y rellena DATABASE_URL,
NEXT_PUBLIC_SUPABASE_URL y la clave pública:
cp .env.example .env.local
- Crea el esquema en la base de datos y siembra datos iniciales:
pnpm run db:push
pnpm run db:seed
Con eso la app arranca, pero casi todas las pantallas salen vacías. Para
trabajar con un club entero inventado (plantillas, socios, patrocinadores,
calendario, inscripciones) siembra además el juego de demostración:
pnpm run db:seed:demo
- Configura la autenticación (ver Autenticación más abajo):
ejecuta
supabase/setup.sql en el SQL Editor de Supabase.
- Arranca el servidor de desarrollo:
pnpm run dev
Abre http://localhost:3000.
La app arranca aunque Supabase no esté configurado: la landing pública funciona
y las rutas internas redirigen a /login.
Red corporativa y puerto 6543
Si al abrir cualquier página que lea datos ves un 500 con este error:
Failed query: select ... from "club_settings"
[cause]: write CONNECT_TIMEOUT aws-N-[region].pooler.supabase.com:6543
no es un problema del proyecto ni de Supabase: hay una red que filtra toda
salida TCP que no sea 80/443. Auth y Storage siguen funcionando (van por HTTPS
al dominio [ref].supabase.co), pero la conexión Postgres de Drizzle
(src/db/index.ts) no puede abrirse. Para comprobarlo:
Test-NetConnection aws-1-eu-west-1.pooler.supabase.com -Port 6543 # falla
Test-NetConnection aws-1-eu-west-1.pooler.supabase.com -Port 443 # conecta
Solución definitiva: pedir al departamento de Sistemas la apertura de los
puertos 6543 y 5432 salientes hacia *.pooler.supabase.com.
Apaño mientras tanto: conectar un hotspot móvil y enrutar por él solo el
tráfico al pooler, con scripts/dev-route-supabase.ps1:
# 1. Conecta el hotspot (sin desconectar el cable corporativo).
# 2. En PowerShell COMO ADMINISTRADOR, en la raíz del repo:
pnpm run dev:route
# 3. En tu terminal habitual:
pnpm run dev
El script crea rutas /32 hacia las IPs actuales del pooler por el adaptador
Wi-Fi, así que el resto del tráfico —incluida la red interna— sigue saliendo por
el cable. Detalles a tener en cuenta:
- Las IPs del pooler son de un balanceador de AWS y rotan. Si vuelve el
CONNECT_TIMEOUT, lo primero es re-ejecutar pnpm run dev:route.
- Reconectar el hotspot cambia el gateway → re-ejecutar.
postgres-js reutiliza la conexión entre recargas, así que las rutas deben
estar puestas antes de arrancar next dev; si no, reinicia el servidor.- Para deshacerlo:
powershell -File scripts/dev-route-supabase.ps1 -Remove.
Conectar el portátil corporativo a una red ajena conviene contrastarlo antes con
Sistemas, por si la política interna no permite el dual-homing.
Autenticación y acceso
Auth con Supabase (email+contraseña). El acceso a la
aplicación es por invitación: no hay alta pública. Un administrador invita
desde /administracion/usuarios y la persona recibe un correo con un enlace
para poner su contraseña.
Roles y permisos
Los roles viven en la tabla roles y se crean y editan desde
/administracion/roles. El club arranca con cuatro de fábrica —Administrador,
Secretaría, Entrenador y Socio—, que no se pueden borrar pero cuyos permisos sí
se ajustan.
El catálogo de permisos está en el código (src/lib/permissions.ts), no en
la base de datos: un permiso solo significa algo si hay un
requirePermission() que lo comprueba. La base de datos guarda únicamente qué
rol tiene cuál (role_permissions). Añadir un permiso nuevo es tocar ese array
y sus traducciones; no hace falta migración.
La autorización en servidor se hace con los helpers de src/lib/auth.ts
(getCurrentUser, requireUser, requirePermission, hasPermission). El
refresco de sesión y el corte de las rutas privadas está en src/proxy.ts, que
solo comprueba que haya sesión: los permisos se miran en cada página y en cada
Server Action, y el estado de la cuenta (activa, pendiente o desactivada) lo
comprueba requireUser en cada petición.
Puesta en marcha del proyecto Supabase
- Migraciones primero:
pnpm run db:migrate (crea roles,
role_permissions y siembra los cuatro roles de fábrica).
- Esquema de auth: ejecuta
supabase/setup.sql en el SQL Editor. Crea el
trigger que genera el perfil al registrarse, publica
public.user_has_permission() y escribe con ella las políticas de Storage.
El propio fichero falla en claro si lo lanzas antes que las migraciones.
- Ajustes del dashboard que el SQL no puede hacer, y sin los cuales las
invitaciones no llegan: plantillas de correo apuntando a
/auth/confirm,
/auth/confirm en la lista de Redirect URLs, "Allow new users to sign up"
apagado y un SMTP propio. Están detallados en la cabecera de
supabase/setup.sql.
- Primer administrador: regístrate una vez en
/login y promociónate a
mano (es la última operación en SQL que queda; a partir de ahí, el alta del
resto se hace desde la aplicación):
update public.users
set role_id = (select id from public.roles where key = 'admin'),
status = 'active'
where email = '[email protected]';
Scripts
| Script | Descripción |
|---|
pnpm run dev | Servidor de desarrollo |
pnpm run build | Build de producción |
pnpm run db:generate | Genera archivos de migración SQL desde el esquema |
pnpm run db:migrate | Aplica las migraciones |
pnpm run db:check | Valida el historial de migraciones (colisiones) |
pnpm run db:push | Empuja el esquema directamente (rápido en dev) |
pnpm run db:studio | Abre Drizzle Studio (explorador de la BD) |
pnpm run db:seed | Datos iniciales (temporada y equipos de ejemplo) |
pnpm run db:seed:demo | Juego de datos completo inventado, para desarrollo |
Datos de demostración
pnpm run db:seed:demo llena areto-dev con un club entero inventado —dos
temporadas, seis equipos, 116 personas con sus tutores, 39 socios, 14
patrocinadores con sus facturas, la temporada de cancha y once inscripciones—
para poder ver las pantallas con datos delante en vez de vacías.
Todo es inventado: los nombres, los DNI, los IBAN y las empresas los genera
src/db/seed-data.ts, y los DNI e IBAN llevan su dígito de control correcto
para que la app no los marque como erróneos. Los emails van sobre el dominio
reservado .test, que no resuelve.
- Cada fila lleva un id determinista, así que el seed reconoce lo suyo: correrlo
dos veces deja exactamente el mismo estado y no duplica nada.
pnpm run db:seed:demo -- --clean borra lo que sembró y no siembra nada.- Corta si la base de datos tiene más de 25 fichas que no son del seed (eso son
datos de verdad, no un entorno de pruebas).
-- --force se lo salta.
- Siembra cinco incoherencias a propósito (fichas sin DNI, dorsales duplicados,
dos capitanes, un jugador huérfano y un duplicado por errata) para que las
tarjetas del dashboard y los avisos de plantilla se puedan probar. Están
numeradas en la cabecera de
src/db/seed-demo.ts.
Estructura
src/
├─ app/
│ ├─ page.tsx # Portal público (landing)
│ ├─ layout.tsx # Layout raíz
│ └─ (app)/ # App interna (con barra lateral)
│ ├─ layout.tsx
│ ├─ dashboard/
│ ├─ personas/
│ ├─ equipos/
│ ├─ calendario/
│ ├─ cuotas/
│ └─ avisos/
├─ components/
│ ├─ app-sidebar.tsx # Navegación de la app interna
│ ├─ section-placeholder.tsx
│ └─ ui/ # Componentes shadcn/ui
├─ db/
│ ├─ schema.ts # Esquema de datos
│ ├─ index.ts # Cliente de base de datos
│ ├─ seed.ts # Datos iniciales
│ ├─ seed-demo.ts # Juego de datos de demostración
│ └─ seed-data.ts # Catálogos y generadores del seed de demostración
└─ lib/utils.ts
Modelo de datos
Aplicación de club único: seasons, teams, persons, memberships,
events, attendances, fees, payments, announcements, users, roles
y role_permissions. Sin capa de multi-club ni catálogo de deportes — todo el
modelo es específico de fútbol sala.
Temporadas: la gestión es multi-temporada. seasons es el ancla de la que
cuelgan teams.seasonId y fees.seasonId — cada temporada tiene sus propios
equipos, jugadores (vía memberships → teams) y economía. Una única
temporada puede tener isCurrent = true (índice único parcial); la UI filtra
por ella por defecto y permite consultar temporadas pasadas.
Roadmap
- ✅ Cimientos: proyecto, UI, esquema de datos.
- ✅ Autenticación, roles editables y gestión de usuarios.
- CRUD de personas y equipos.
- Calendario y convocatorias.
- Económico + integración con Stripe.
- Portal público (resultados y avisos).
- Estadísticas de competición.
