Rosver SAC — el proyecto explicado de punta a punta

Resumen ejecutivo

Qué es Rosver SAC y para quién es esta guía.

Rosver SAC es una empresa peruana de importación y comercialización de herramientas y ferretería. Este repositorio contiene dos productos en una sola aplicación: una tienda web de catálogo B2B/B2C (importaciones, cotizaciones y pedidos) y un panel de administración interno llamado SystemRSV — un ERP liviano para gestionar catálogo, precios, pedidos, cotizaciones, clientes, contenido y analítica.

El proyecto ya no está en fase de mocks: catálogo, pedidos, cotizaciones, leads y reseñas corren contra PostgreSQL real en producción, no datos de ejemplo.

Regla de fase del producto: todo lo visual se diseña primero con mocks alineados al dominio, pero los flujos críticos (auth, catálogo, carrito, pedidos, cotizaciones, admin) ya corren contra datos reales — no quedan mocks en el camino de compra.

Arquitectura general

Cómo se conectan las piezas del sistema — y qué pasa exactamente cuando alguien hace clic.

La aplicación es un monorepo de un solo servicio: un proceso Node.js (Hono) sirve la API y, en producción, también sirve el build estático de React (SPA) desde el mismo origen. Esto simplifica CORS, cookies de sesión y el despliegue — un único servicio en Railway, sin balanceador ni gateway adicional.

El viaje de una petición (animado)

Paso a paso

1. El navegador (React 19 + React Router 7) hace fetch a /api/... con cookies de sesión incluidas (credentials: "include").
2. Hono recibe la petición: aplica CORS, logger, y en rutas protegidas el middleware requireAuth + requireRole.
3. Los datos de entrada se validan con Zod antes de tocar la base de datos — nunca se confía en el body tal cual llega.
4. El acceso a Postgres se hace con el driver pg (pool de conexiones) — sin ORM; las queries son SQL explícito en cada archivo.
5. Home/destacados usan Redis como caché opcional — si no está configurado, se degrada a Postgres directo, nunca es un punto de falla dura.
6. Imágenes, PDFs y evidencias se guardan en Cloudflare R2 (bucket público para media, privado para documentos/evidencias).

Stack tecnológico

Librerías principales, versión y para qué se usan.

Frontend

Backend

Regla del proyecto: antes de instalar una librería nueva se revisa docs/architecture/04-stack-y-librerias.md — evita duplicar herramientas que ya existen (los iconos, por ejemplo, siempre van por cssvg-icons, nunca un paquete nuevo).

Estructura de carpetas

Dónde vive cada cosa en el monorepo.

Rosver-Web-1/
├── RosverSac/                 ← app (front + back)
│   ├── src/
│   │   ├── app/                shell, providers, layouts, rutas
│   │   ├── features/<nombre>/  un dominio de producto por carpeta
│   │   │     index.ts          ← único export público de la feature
│   │   │     ui/  model/  lib/
│   │   ├── shared/             UI/hooks/lib sin negocio de una feature
│   │   └── styles/             CSS global + tokens de marca
│   └── server/
│       ├── src/routes/         un archivo Hono por dominio de API
│       ├── src/lib/            lógica de negocio y helpers de servidor
│       ├── src/migrate.ts      corredor de migraciones (boot)
│       ├── src/seed.ts         RBAC + usuario admin/cliente demo
│       ├── sql/NNN_*.sql       migraciones numeradas, una por cambio
│       └── scripts/            scripts de operación (tests, imports, resets)
├── docs/                       toda la documentación viva del proyecto
│   ├── architecture/           stack, producto, paleta, despliegue
│   ├── changes/NNNN-slug.md    bitácora de cada cambio cerrado
│   ├── features/                ficha de cada feature
│   └── pendientes/             deudas y recomendaciones vivas
├── .claude/rules/  .cursor/rules/   reglas para agentes IA (Claude/Cursor)
└── scripts/railway-deploy.ps1  script de despliegue a Railway

Regla de dependencias entre capas

app/         →  puede importar  features/*  y  shared/
features/A   →  puede importar  shared/  (nunca internos de features/B)
shared/      →  NO puede importar  features/*

El alias @ apunta a RosverSac/src (import { LoginPage } from '@/features/auth'). Cada feature expone únicamente lo que declara en su index.ts — importar un archivo interno de otra feature está prohibido por convención del proyecto.

Base de datos

PostgreSQL — 35 tablas en 5 dominios, 42 migraciones. Sin ORM: SQL explícito.

Cada migración es un archivo SQL plano en server/sql/NNN_slug.sql, numerado secuencialmente y pensado para ser idempotente (IF NOT EXISTS, ON CONFLICT) cuando es posible. server/src/migrate.ts las corre en orden en cada arranque del servidor — así el esquema nunca queda desincronizado del código.

Los 5 dominios (clic para expandir)

Convención para migraciones nuevas

• Un archivo nuevo por cambio: server/sql/043_slug_descriptivo.sql — nunca editar una migración ya desplegada.
• Usar IF NOT EXISTS / ON CONFLICT siempre que se pueda, para que correr la migración dos veces no falle.
• Si el cambio toca datos que ya existen en producción, documentarlo en docs/changes/ y, si aplica, escribir un script en server/scripts/.
• Correr npm run db:migrate localmente antes de subir — el boot de producción corre migrate → seed → seed-ubigeo, en ese orden, en cada deploy.

Autenticación, roles y seguridad

RBAC, sesiones, contraseñas y hallazgos de auditoría corregidos.

El sistema usa RBAC (control de acceso por rol) con dos roles de sistema —admin y client— respaldados por una matriz real en base de datos: modules → permissions → role_permissions → roles → users.

Sesión y credenciales

Rutas de administración

Las 10 familias de rutas bajo /api/admin/* aplican requireAuth + requireRole('admin') a nivel de router — no hay endpoints admin "huérfanos" sin ese guardia. Verificado archivo por archivo en la auditoría técnica del proyecto.

Hallazgos de la auditoría técnica y su corrección

Para quien continúe el proyecto: antes de dar por buena una funcionalidad de seguridad, probarla con una petición HTTP real — no basta con que el código "se vea correcto".

Módulos del frontend

Las 15 features de src/features/.

Cada feature sigue la misma anatomía: index.ts (export público), ui/ (páginas), model/ (estado/hooks), y opcionalmente api/ y lib/. Para crear una feature nueva existe la skill create-feature, que arma las carpetas, la ficha en docs/features/ y el registro del cambio.

API / Backend

Los 19 archivos de rutas en server/src/routes/.

Convención de una ruta admin nueva

export const adminXxxRoutes = new Hono<{ Variables: AuthVariables }>()
adminXxxRoutes.use('*', requireAuth, requireRole('admin'))

adminXxxRoutes.get('/', async (c) => { /* SELECT ... */ })
adminXxxRoutes.post('/', async (c) => {
  const body = createSchema.safeParse(await c.req.json().catch(() => null))
  if (!body.success) return c.json({ error: body.error.issues[0]?.message }, 400)
  // INSERT ...
})

Regla CRUD completo: al tocar una tabla o módulo de datos nuevo, se espera Create + Read + Update + Delete (o soft-delete) tanto en la API como en la pantalla de /admin correspondiente.

Sistema de diseño

Paleta oficial, tipografía, iconos y medidas de banners/imágenes.

Paleta de colores (tokens obligatorios)

Prohibido: hardcodear hex de marca en componentes o usar paletas genéricas — todo color pasa por estos tokens en RosverSac/src/styles/global.css.

Iconos y formularios

• Iconos de UI nuevos: únicamente cssvg-icons (catálogo en icon.cssvg.com) — no se agregan librerías de iconos nuevas.
• Formularios: toasts flotantes tipados (success/error/info/warning) vía FloatingToasts + useFormToasts — nunca alertas nativas del navegador.

Medidas de banners e imágenes

Responsive (obligatorio en toda pantalla nueva)

Cómo seguir desarrollando

El flujo que sigue el proyecto para cada cambio.

Antes de escribir código

• Leer docs/architecture/02-producto-rosver-sac.md y 03-vistas-y-flujos.md para entender el dominio antes de tocar una pantalla.
• Revisar docs/changes/ — el último NNNN — para saber qué se hizo justo antes.
• Feature nueva: usar la skill/checklist create-feature antes de codear.

Al cerrar cualquier tarea

• Crear docs/changes/NNNN-slug.md con qué cambió, por qué, cómo, archivos tocados y cómo verificarlo.
• Si el cambio necesita persistencia nueva: migración server/sql/NNN_*.sql en el mismo trabajo.
• Si se tocó una tabla/módulo de datos: verificar que el CRUD esté completo (Create+Read+Update+Delete) en API y en /admin.
• Actualizar docs/pendientes/PENDIENTES.md y RECOMENDACIONES.md si quedó algo a medias.

Comandos de verificación

cd RosverSac
npx tsc -b                 # typecheck frontend
npm run typecheck:server   # typecheck backend
npm run lint                # oxlint
npm run build                # build de producción
npm run db:migrate           # aplica migraciones nuevas
npm run test:security        # tests de reglas de precio/seguridad
npm run test:oauth-state     # tests de OAuth state anti-CSRF
npm run test:promo-calc      # tests de cálculo de combos 2x1/3x2

Despliegue

Railway — web, Postgres, Redis y R2. GitHub como fuente de verdad.

Infraestructura

Línea de tiempo de un deploy

Variables de entorno mínimas

Comandos

# Desde RosverSac/, con RAILWAY_API_TOKEN en .env
railway up --detach          # sube el código actual y despliega
railway variables --set KEY=value   # configura variables de entorno
railway logs --build <id>    # ver el log de un build

# Verificación post-deploy
curl https://rosversac.com/api/health   # debe responder { ok: true, commitSha: ... }

Regla de oro: todo cambio cerrado debe terminar con push a GitHub main y deploy a Railway probado en línea — nunca dejar trabajo importante solo en local.

Estado actual y próximos pasos

Qué queda para quien continúe. El detalle siempre vigente vive en docs/pendientes/README.md.

Bloqueado por acción humana (no es deuda de código)

• Credenciales de Google Cloud OAuth para habilitar "Continuar con Google" en producción.
• Cutover de DNS de rosversac.com hacia el dominio custom de Railway (Cloudflare).

Recomendado para las próximas sesiones

• Revisar el code-splitting de quotes/complaints-book — hoy se importan estático y dinámico a la vez y el chunk no se separa (bundle inicial ~634 KB).
• Validar el tipo real de archivo (magic bytes) al subir avatar y evidencias de pedido, no solo el MIME declarado por el navegador.
• Ejecutar npm audit periódicamente — xlsx (importador de Excel) tiene una vulnerabilidad conocida sin parche; su uso está limitado a /admin.
• Sumar tests E2E (Playwright ya está instalado — npm run test:e2e) para checkout y panel admin.

Glosario y comandos rápidos

Referencia de una página.

Comandos del día a día

cd RosverSac
npm run dev        # UI en :5173 (Vite)
npm run dev:api     # API en :8787 (tsx watch)
npm run db:setup    # migrate + seed + seed-ubigeo, todo de una
npm run build        # build de producción
npm start             # build + migrate + seed + servidor único (como Railway)

Dónde seguir leyendo

• docs/architecture/02-producto-rosver-sac.md — el producto explicado a fondo
• docs/architecture/03-vistas-y-flujos.md — cada pantalla y su flujo
• docs/pendientes/README.md — estado real y siempre vigente del proyecto
• CLAUDE.md / AGENTS.md — instrucciones para agentes de IA que trabajen en este repo