Plan — InventoryPilot

Volver a README · 08 Proyectos

Objetivo: construir una API multi-tenant de inventario que controle productos, movimientos de stock y dispare alertas automáticas cuando un producto baja del mínimo.

Estado: planificación. Proyecto de cierre en 4 semanas.

1. Alcance

1. Registro e inicio de sesión con JWT.
2. Workspaces con miembros y roles.
3. CRUD de proveedores, almacenes y productos.
4. Movimientos de stock (entrada, salida y ajuste).
5. Cálculo de stock por producto y almacén.
6. Reglas de alerta de stock bajo.
7. Webhooks de salida con firma HMAC.
8. Reportes de rotación y valor de inventario.
9. Job programado que revisa stock y dispara alertas.

2. Fuera de alcance

• Facturación electrónica.
• Compras y órdenes de compra completas.
• Integración con marketplaces.
• App móvil nativa.
• Escaneo de códigos de barras.

3. Arquitectura

Next.js (dashboard)
        │
        ▼
API Fastify ──────────────► PostgreSQL
        │
        ├── Cron (node-cron) → revisa stock → alert_events
        │
        └── Webhook outbound (HMAC) → sistemas externos

4. Modelo de datos

Tabla	Campos principales
users	id, email, password_hash, created_at
workspaces	id, name, owner_id, created_at
workspace_members	workspace_id, user_id, role
api_keys	id, workspace_id, name, key_hash
suppliers	id, workspace_id, name, contact
warehouses	id, workspace_id, name, location
products	id, workspace_id, sku, name, price_cents, cost_cents, min_stock
stock_movements	id, product_id, warehouse_id, type, quantity, reason, created_by, created_at
stock_levels	product_id, warehouse_id, quantity
alert_rules	id, workspace_id, product_id, threshold, channel, active
alert_events	id, alert_rule_id, triggered_at, payload, status
webhook_endpoints	id, workspace_id, url, secret, events

5. Componentes

Componente	Responsabilidad
Auth	Registro, login y JWT
Workspaces	Aislamiento de datos por workspace
Products	CRUD de productos con SKU y stock mínimo
Movements	Registrar entradas, salidas y ajustes
Stock levels	Mantener cantidad actual por producto/almacén
Alert rules	Definir umbral y canal de alerta
Scheduler	Revisar stock periódicamente
Webhooks	Enviar alertas firmadas a sistemas externos
Reports	Rotación y valor del inventario

6. Hitos

Semana	Entregable	Criterio de cierre
1	Auth + multi-tenant + CRUD de proveedores/almacenes/productos	Se crea un workspace, un producto y un proveedor
2	Movimientos de stock + stock levels + alertas + webhooks	Una salida bajo el mínimo genera una alerta
3	Reportes + job programado + dashboard	El cron detecta stock bajo y el reporte muestra rotación
4	Docker + CI/CD + deploy + docs + demo	URL pública con alerta automática y CI verde

7. Criterios de aceptación

• Registro e inicio de sesión.
• Workspace con al menos un miembro.
• CRUD de proveedores, almacenes y productos.
• Registrar entrada y salida de stock.
• El stock actual se calcula correctamente.
• Una salida que baja del mínimo genera una alerta.
• La alerta se envía por webhook con firma HMAC.
• Se genera un reporte de inventario.
• Tests en backend.
• CI verde.
• README con capturas y URL de demo.

8. Decisiones técnicas

• JavaScript + Fastify: API liviana y rápida para CRUD intensivo.
• PostgreSQL: integridad de movimientos y consultas de reportes.
• Movimientos inmutables: el stock se corrige con un movimiento inverso, no editando el historial.
• stock_levels materializado: evita sumar todo el historial en cada consulta.
• Cron + webhooks: alertas simples y compatibles con cualquier sistema.
• JSDoc + // @ts-check: tipado sin migrar a TypeScript.

9. Riesgos

Riesgo	Mitigación
Condiciones de carrera en stock	Transacciones y bloqueo por producto
Alertas duplicadas	Ventana de silencio por regla
Webhooks caídos	Reintentos con backoff
Multi-tenant mal aislado	workspace_id obligatorio en todas las consultas
Tiempo insuficiente	Priorizar CRUD + movimientos + alerta y dejar reportes como segundo paso

10. Próximo paso

1. Inicializar monorepo y Git.
2. Crear el esquema de base de datos y las migraciones.
3. Implementar auth y workspaces.
4. Crear el CRUD de productos y almacenes.
5. Primer commit con README y CI mínima.

Enlaces

• README
• 08 Proyectos
• Portafolio
• 000 Índice