Kardex Digital

Aplicación web para llevar el kardex de alimentos y la lista de mercado semanal de las casas de Aldeas Infantiles SOS Colombia. Reemplaza el formato en papel «Movimiento Diario de Alimentos» y los libros de Excel que las colaboradoras mandaban por correo, y le da a la nutricionista una vista de todas las comunidades.

Estado (3 de octubre de 2026): en producción con datos reales, como piloto dentro de una propuesta comercial en curso con la organización. Lo construye y mantiene una sola persona (Lucho); este documento resume dónde está el proyecto, cómo correrlo y dónde está cada cosa. El detalle de cada decisión vive en planes/.

Qué hace

Para las colaboradoras de cada comunidad (entran con el PIN de 4 dígitos de su casa):

• Kardex diario: entradas, salidas y saldos por producto, por semana (5 semanas, más una semana 6 de cierre en los meses que no caben, como el 30 y 31 de marzo de 2026). El saldo se recalcula solo, avisa cuando una salida supera el saldo y permite corregir un saldo con motivo (queda en el historial). Catálogo de 240 productos en 5 categorías.
• Buscador de productos por nombre (sin importar tildes ni mayúsculas), combinable con la categoría.
• Guardado automático con indicador y aviso si no se pudo guardar. Si se cae el internet, lo escrito se conserva en la página y se envía solo al volver la conexión (no se pierde mientras no se cierre ni recargue la pestaña). Descarga a Excel y PDF.
• Enviar semana a la nutricionista, con confirmación; la semana queda marcada y avisa si cambia después.
• Lista de mercado semanal (fruver y lácteos, carnes, abarrotes, aseo): cantidades por producto, número de participantes, plazo del viernes, notas de cambios para la nutricionista y sus respuestas (con campanita).
• Cambiar su propio PIN.
• Pensado para personas adultas mayores y para computador o portátil: barra de accesibilidad (letra grande, alto contraste), textos con contraste AA, avisos que se cierran al tocar y confirmaciones propias de la app (no ventanas del navegador).

Para la nutricionista (/admin, contraseña propia con cambio obligatorio y código de recuperación de un solo uso): ver el kardex de cualquier comunidad (solo lectura), campanita de semanas enviadas, resumen semanal consolidado para el pedido a proveedores, listas de mercado por comunidad y consolidadas, y respuesta a las notas de cambios.

Para el desarrollador (/dev, sin enlace desde ninguna parte): los errores del navegador agrupados y explicados en lenguaje natural, con botón «resuelto». Además, alertas por correo y Telegram (Edge Function dev-alert) cuando se acumulan errores. Es la parte de «vigilancia del servicio» de la propuesta. Lo que falta de este panel (estado de comunidades y acciones remotas) está en el plan 007.

Cómo está hecho

Pieza	Detalle
App	Next.js 16 (App Router) + React 19 + TypeScript. Sitio 100 % estático (output: "export"): no hay servidor propio.
Datos	Supabase (Postgres). La app solo llama a funciones RPC security definer; las tablas están cerradas (RLS) y el rol público solo ejecuta funciones.
Sesiones	Un token de 12 h por comunidad (PIN con bcrypt, 5 intentos fallidos = 15 minutos de bloqueo), uno aparte para la nutricionista y otro para el desarrollador: ninguno sirve en las otras pantallas.
Exportación	ExcelJS y jsPDF, en el navegador.
Seguridad web	public/_headers con la política de contenido; sin rutas de API ni acciones de servidor (lo comprueba una prueba).
Hosting	Hoy en Vercel; migración a Cloudflare Pages planeada antes del primer cobro (plan 010).

Estructura del código:

src/app          páginas: / (comunidades), /admin (nutricionista), /dev (desarrollador) y sus hojas de estilo
src/components   pantallas y piezas (kardex, lista de mercado, admin, dev, diálogos, avisos)
src/hooks        estado y carga de datos de cada pantalla
src/lib          lógica pura (saldos, calendario, búsqueda), servicios de Supabase y exportadores
supabase         todo el SQL (se corre a mano, en orden) y la Edge Function dev-alert
tests            unit, integration, db (SQL en Postgres local) y manual
planes           un plan por cambio importante: decisiones, estado y qué tocó

Cómo correrlo

Requisitos: Node 22 y un .env.local con NEXT_PUBLIC_SUPABASE_URL y NEXT_PUBLIC_SUPABASE_ANON_KEY. Los secretos nunca van en el repositorio (.env* está ignorado).

npm ci
npm run dev        # http://localhost:3000
npm run build      # exporta el sitio estático a out/

Pruebas

Comando	Qué corre
npm test	Pruebas unitarias y de pantalla (sin red).
npx tsc --noEmit y npm run lint	Tipos y lint (lo mismo que el CI).
npm run test:db	Los scripts SQL en un Postgres local desechable, con mutaciones para comprobar que las pruebas detectan fallos.
npm run test:integration	Contra el Supabase real, solo con comunidades ZZZ_TEST_BORRAR_AUTO_*. Algunas son opt-in porque usan las cuentas de la nutricionista o del desarrollador.
tests/manual/checklist.md	Lista de verificación a mano antes de desplegar.

El CI de GitHub corre tipos, lint, pruebas unitarias, build y las pruebas SQL en cada push a main. Cómo correr cada tipo y las precauciones están en tests/README.md.

Base de datos

No hay migraciones automáticas ni copia del esquema de producción: cada cambio es un .sql en supabase/ que se corre a mano en el SQL Editor, en el orden de ese README. Los datos de prueba se borran con supabase/cleanup_test_data.sql.

Lo que hay que tener presente

• Dos personas de la misma casa: en el kardex, si otra persona cambió un producto mientras tú escribías, el guardado no la pisa: la pantalla avisa y carga lo último (plan 012, desplegado). La lista de mercado todavía guarda sin esa comprobación (hallazgo H2b), así que ahí sigue valiendo «una sola persona a la vez».
• PIN de 4 dígitos: es una desviación consciente respecto a un mínimo de 8 caracteres, por la comodidad de las colaboradoras; se compensa con el bloqueo por intentos y con que los datos solo se leen con el token de sesión.
• Copias de seguridad: el plan gratuito de Supabase no tiene copias automáticas. Está pendiente decidir entre una copia semanal propia, un botón de descarga de datos o pasar al plan de pago (plan 007, B3).
• Ubicación de los datos: Supabase en la región oeste de EE. UU. (fuera de Colombia).
• Datos personales de los niños: la aplicación no los guarda; está pendiente de confirmarlo formalmente con la organización.
• Pendientes del proyecto: logo de Aldeas (requiere su autorización escrita), IVA de la cuenta de cobro, migración a Cloudflare, y las siguientes etapas del panel /dev. La minuta patrón del ICBF (plan 011) es una función futura, aplazada a propósito para no complicar el trabajo de las colaboradoras. La corrección de meses anteriores (plan 013) está en pausa hasta que la gerencia apruebe el proyecto: su SQL ya está en producción pero con los interruptores apagados, así que no cambia nada de lo que ven las colaboradoras.

Más documentación

• planes/README.md: índice de planes con su estado y los hallazgos abiertos.
• supabase/README.md: orden y propósito de cada script SQL.
• tests/README.md: qué prueba cada archivo y cómo correrlas.
• CLAUDE.md: reglas de trabajo para el asistente de programación (zonas que requieren aprobación, comandos verificados).