CAYLA Retail

Sistema de inventario multi-sede, producción y compras para CAYLA — proyecto nuevo y separado de cayla-dynamic (asistencia/planilla). Reemplaza, cuando esté probado, a CAYLA Inventario (Google Sheets/Apps Script).

Sedes reales

TRU (Trujillo, tienda) · AQP (Arequipa, tienda) · LIM (Lima, tienda) · Taller (Lima, fábrica) "Online" es un canal de venta, no una sede — despacha desde el stock real de alguna sede.

Estructura

• apps/web — Next.js: catálogo, stock por sede, movimientos (Fase 1).
• packages/shared — Zod schemas, enums (sedes, roles, tipos de movimiento).
• packages/database — cliente Supabase tipado.
• supabase/ — migraciones.

Desarrollo

Somos varias personas con acceso de escritura — el flujo completo (ramas, PR, convención de migraciones) vive en CONTRIBUTING.md. Esta sección es solo cómo levantar tu entorno local.

pnpm install

Antes que nada: en esta máquina hay DOS Supabase locales

No es un error, y no apagues ninguno. Son dos repos distintos, cada uno con su stack:

Repo	API	DB	Studio
cayla-retail — este	54421	54422	54423
cayla-dynamic (asistencia/planilla, ~/cayla-dynamic)	54321	54322	54323

54321 es el default de Supabase, y NO es el nuestro. Apuntar ahí no explota: la base local de Dynamic es la foto de la producción unificada, así que también tiene un schema retail, pero con menos tablas y más atrasado. Catálogo, stock y ventas responden normal; lo que falta son las tablas posteriores a la unificación (comprobantes, conteos, colores, stock_almacen…). O sea que Facturación y Conteo fallan mientras el resto anda, y eso se diagnostica como bug del repo. Costó una hora, cuatro veces distintas (BITACORA 2026-09-09).

Antes de creerle a cualquier síntoma raro en local, pregunta con qué base estás hablando:

pnpm local:donde

Contesta en un segundo qué stacks corren, cuál declara este repo, cuál va a leer la app —incluyendo el caso feo: una NEXT_PUBLIC_SUPABASE_URL exportada en tu terminal le gana al archivo— y qué puerto trae de verdad el bundle que sirve el :3000 que ya tengas corriendo, que es el único testigo que no opina.

Levantar el entorno local completo

Hasta el 2026-09-05 la app no podía correr contra el Supabase local (ver ADR-0010). Ya sí. Desde cero, primero el stub local de Dynamic (una sola vez, ver ADR-0033 — el archivo destino queda fuera de git a propósito, así que cada quien lo genera localmente desde la plantilla):

cp supabase/0000_local_stub_dynamic.sql.example supabase/migrations/0000_local_stub_dynamic.sql

Y ahora sí, el entorno completo:

npx supabase start

Eso levanta Postgres, la API, Auth y Studio; aplica todas las migraciones de supabase/migrations/ (con el stub de arriba ya adentro); y corre supabase/seed.sql, que siembra lo mínimo para entrar: dos personas (Felipe, líder en LIM; Micaela, integrante en TRU — para poder probar que RLS de verdad acota por ubicación) y un catálogo de prueba con movimiento real.

Copia las claves que imprime a apps/web/.env.local (plantilla en apps/web/.env.example):

cp apps/web/.env.example apps/web/.env.local   # y pega API_URL y PUBLISHABLE_KEY

pnpm dev

Entra en http://localhost:3000 con [email protected] / cayla-local (líder) o [email protected] / cayla-local (integrante).

Para volver la base a cero (rehace migraciones + seed):

npx supabase db reset

Qué NO funciona en local: subir fotos de producto — el servicio de Storage está apagado a propósito en supabase/config.toml porque es el único que queda "unhealthy" y hacía abortar supabase start entero. Todo lo demás que existe hoy en V2 (catálogo, ventas, caja/pagos múltiples, cambios de talla/color, facturación) funciona igual que en producción. Comercial, Finanzas, Producción y Taxonomía universal quedaron fuera del corte V1→V2 (0af2f1b, 2026-09-12) — no tenían pantalla propia en V2 y su data en retail era de prueba, no de operación real. Vuelven en una fase futura si se decide reconstruirlos sobre V2.

El catálogo no se siembra: son SKUs reales que se cargan por la pantalla de Recibir mercadería (docs/GUIA-CARGA-CATALOGO.md). Un catálogo de juguete haría que el módulo de Inteligencia mienta.

Revisión antes de cada commit

pnpm install deja activado un hook de git (.githooks/pre-commit) que, antes de cada commit, revisa solo los archivos que estás commiteando: tipos, tests y lint. Tarda ~19 s cuando hay código en el commit y ~0,5 s cuando no lo hay (documentación, SQL, configuración).

Se eligió revisar solo lo del commit por una razón medida: eslint sobre el proyecto entero tarda 4 min 15 s en la máquina de Felipe. Un hook de cuatro minutos se saltea con --no-verify a la tercera vez, y entonces tampoco corren los tests.

Los errores de tipos en archivos que no son de tu commit avisan pero no te frenan — en este repo suele haber más de una sesión trabajando a la vez, y no tiene sentido que el trabajo a medias de otra persona bloquee tu commit terminado. El build de producción sí los va a rechazar, así que el aviso importa.

Para saltarlo en una emergencia real:

git commit --no-verify

Si el hook no corre, es que falta apuntar git a la carpeta (lo hace pnpm install):

git config core.hooksPath .githooks