# 06 · Plan de Implementación **Proyecto:** Sistema Boutique (POS + Tienda Online) **Versión:** 1.0 Hoja de ruta **cronológica y estricta** para que un agente de IA (Claude Code) construya la app sin errores estructurales. El orden **no es negociable**: cada fase depende de la anterior. Construir la venta antes que el inventario, o el frontend antes que la API, garantiza retrabajo. Principio rector: **de adentro hacia afuera y de abajo hacia arriba.** Primero los cimientos (BD), luego el motor (backend), luego los tableros (frontends). Igual que no tapizas los asientos de un carro antes de montar el motor. --- ## Fase 0 · Andamiaje del proyecto **Meta:** repositorio que compila y corre vacío, con las herramientas listas. 1. Inicializar monorepo con workspaces: ``` /apps/api → backend Fastify + TS /apps/pos → frontend POS (React + Vite + TS) /apps/store → frontend tienda (React + Vite + TS) /packages/shared → tipos y esquemas Zod compartidos ``` 2. Configurar TypeScript estricto (`strict: true`, prohibido `any`) en los tres. 3. Configurar ESLint + Prettier comunes. 4. Configurar Prisma apuntando a PostgreSQL; `.env` fuera de Git; `.env.example` dentro. 5. Verificar que `api` levanta un health-check `GET /health → 200` y que ambos frontends muestran una página en blanco. **No avanzar hasta que:** los tres proyectos compilen y `/health` responda. --- ## Fase 1 · Base de datos y migraciones **Meta:** el esquema completo del documento 05, migrado y versionado. 1. Escribir el `schema.prisma` completo con **todos** los módulos (A→I) del documento 05. 2. Definir enums, FKs con sus reglas `on delete`, índices (`barcode`, `reference`, `product_id`, `sale.created_at`), y el `CHECK (stock >= 0)` en variantes. 3. Generar y correr la primera migración. 4. Escribir un **seed** mínimo real (no de relleno): 1 admin, 1 vendedor, 2 categorías, 2 proveedores, 3 productos con sus variantes y stock, la configuración de IVA=19% y moneda=COP. 5. Verificar en la BD que las relaciones existen y el seed cargó. **No avanzar hasta que:** la migración corra limpia y el seed cargue sin error. --- ## Fase 2 · Núcleo del backend (auth + base de Clean Architecture) **Meta:** un usuario puede registrarse, entrar y llamar un endpoint protegido. 1. Estructura de capas: `domain` (entidades, puertos), `application` (casos de uso), `infrastructure` (Prisma, Fastify, servicios externos). 2. Implementar hashing Argon2id, emisión/validación JWT (access + refresh rotatorio). 3. Endpoints: `POST /auth/register` (staff, solo admin), `POST /auth/login`, `POST /auth/refresh`, `POST /auth/logout`. 4. Middleware de autorización por rol (RBAC). Rate limiting en `/auth`. Helmet. CORS restringido. 5. Manejo de errores tipado (`AppError`) + logs estructurados (pino). **No avanzar hasta que:** login devuelva tokens y un endpoint protegido rechace (403) a un rol sin permiso. --- ## Fase 3 · Catálogo e inventario (backend) **Meta:** CRUD de catálogo y movimientos de stock con kardex. 1. Casos de uso: categorías, proveedores, productos y **variantes** (con su stock y código de barras). 2. Ingreso de mercancía → escribe en `inventory_movements` **y** actualiza `stock` en una transacción. 3. Ajuste/egreso de stock igual. 4. Cálculo de "total invertido" (suma de compras) y consulta de kardex por variante. 5. Endpoint de **avisos de stock mínimo y cero**. 6. Búsqueda de variante por `barcode` (endpoint que usará el escáner). **No avanzar hasta que:** ingresar mercancía suba el stock y deje su renglón en el kardex, atómicamente. --- ## Fase 4 · Ventas POS (backend) — la transacción crítica **Meta:** registrar una venta que descuenta stock sin sobreventa jamás. 1. Caso de uso `RegisterSale`, todo dentro de **una transacción serializable**: - valida stock de cada variante, - descuenta stock (y escribe movimiento `sale` en kardex), - crea `sale` + `sale_items` con precio congelado, - registra `payments` (incluye pago mixto y vuelto), - calcula y guarda `seller_commissions` según `commission_rules`, - si el cliente está asociado, suma fidelización. - **si cualquier paso falla, rollback total.** 2. Validar límite de descuento por rol (RB4). 3. Endpoint de anulación de venta (`voided`) que **revierte** stock y comisión. **No avanzar hasta que:** dos ventas concurrentes de la última unidad → una tiene éxito y la otra falla limpia (test de concurrencia). --- ## Fase 5 · Frontend POS **Meta:** el cajero vende de principio a fin. 1. Login del POS. 2. Terminal de venta: campo de escaneo **con foco permanente**, carrito, búsqueda manual. 3. Aplicar descuento (respetando el límite del rol, feedback claro si se excede). 4. Alta/selección rápida de cliente. 5. Pantalla de cobro: método(s), cálculo de vuelto, confirmar. 6. Recibo en PDF en pantalla. 7. Vista de inventario (ingreso/ajuste) y avisos de stock, según rol. **No avanzar hasta que:** una venta completa corra desde el navegador y el stock baje en la BD. --- ## Fase 6 · Tienda Online (backend + frontend) **Meta:** un cliente compra online con pago real. 1. Backend: catálogo público (solo variantes con stock), auth de `customers`, carrito, checkout. 2. **Reserva de stock** durante el checkout (evita sobreventa mientras el cliente paga). 3. Puerto `PaymentGateway` + implementación **Wompi**; webhook que confirma el pago → ejecuta la venta atómica (misma lógica de descuento que el POS) o libera la reserva. 4. Frontend tienda: catálogo con filtros, ficha con selector talla/color, carrito, checkout, confirmación. 5. Perfil de cliente: historial de pedidos, direcciones, fidelización. **No avanzar hasta que:** un pago aprobado en Wompi (modo sandbox) descuente stock y cree el pedido; un pago rechazado libere la reserva. --- ## Fase 7 · Gestión, reportes y dashboard **Meta:** el dueño ve y controla el negocio. 1. Dashboard: total en stock, gráficas por tipo/color/talla, más y menos vendidas, ventas por rango de fechas. 2. Reportes: facturación/ventas (por fecha, vendedor, tipo), ingresos brutos, comisiones por vendedor, cuentas por pagar a proveedores. Exportables CSV/PDF. 3. Promociones (vigencia por fecha) y kits/combos aplicables en la venta. **No avanzar hasta que:** los reportes cuadren con las ventas reales del seed + pruebas. --- ## Fase 8 · Endurecimiento y despliegue **Meta:** en producción sobre el VPS, seguro. 1. Repaso OWASP: revisar cada punto del TRD §4 contra el código real. 2. Rate limiting global, cabeceras Helmet, CORS final a los dominios reales. 3. Build de los tres proyectos; Apache como reverse proxy al backend + sirviendo los estáticos; PM2/systemd para el backend; TLS con Certbot. 4. Backups automáticos de PostgreSQL. 5. Logs y verificación de que no se filtran stacks al cliente. **Listo para producción cuando:** un pentest básico no encuentre inyección, XSS ni acceso sin rol, y los backups corran. --- ## Fase 9 (post-Fase 8) · Hardware físico **Diferido a propósito.** Las interfaces (puertos) ya existen desde Fase 1: - Cajón de efectivo (apertura vía impresora ESC/POS). - Impresora de etiquetas (código de barras, precio, logo, talla; plantillas A4/adhesivo). - Impresión térmica de recibos. Se implementan las clases concretas de esos puertos cuando el hardware esté disponible, **sin tocar el core** — ese es el beneficio de haberlos dejado como interfaces desde el principio. --- ## Regla de oro para el agente > Termina y **verifica** cada fase antes de empezar la siguiente. No escribas el frontend de una funcionalidad cuyo backend no pasa sus pruebas. No hay código de relleno: si una función no está lista para producción, no se entrega. Cada fase deja el sistema en un estado **funcional y probado**, no a medias.