michangarrito/backups/docs-backup-2026-01-10/docs/02-especificaciones/INVESTIGACION-REFERENCIAS.md

MiChangarrito - Investigacion de Referencias

Resumen Ejecutivo

Este documento consolida la investigacion realizada sobre:

1. Modulos ERP existentes reutilizables
2. Integraciones de WhatsApp Business
3. Model Context Protocol (MCP) para LLM
4. Integraciones de pago para Mexico

---

1. Modulos ERP Reutilizables

1.1 POS-Micro (RECOMENDADO COMO BASE)

Ubicacion: /workspace-v1/projects/erp-suite/apps/products/pos-micro/

Nivel de Completitud: 80% - Funcionalmente completo

Componente	Estado	Reutilizable
Auth Module (JWT, multi-tenant)	100%	SI
Sales Module	90%	SI
Products Module	90%	SI
Categories Module	100%	SI
Payments Module (base)	40%	PARCIAL
Database Schema	80%	SI + EXTENDER
Frontend React	75%	SI

Stack Tecnico (compatible con MiChangarrito):

• NestJS 10.3.0
• TypeORM 0.3.19
• PostgreSQL 8.11
• React 18.2.0
• Vite 5.0.0
• Zustand 4.4.7
• TailwindCSS 3.3.5

Tablas existentes:

1. tenants - Multi-tenant root
2. users - Usuarios
3. categories - Categorias
4. products - Catalogo
5. sales - Ventas
6. sale_items - Detalle venta
7. payments - Metodos pago
8. inventory_movements - Stock
9. daily_closures - Cortes caja

Archivos clave para copiar:

pos-micro/backend/src/modules/auth/         -> COPIAR COMPLETO
pos-micro/backend/src/modules/sales/        -> COPIAR + ADAPTAR
pos-micro/backend/src/modules/products/     -> COPIAR COMPLETO
pos-micro/backend/src/modules/categories/   -> COPIAR COMPLETO
pos-micro/database/ddl/00-schema.sql        -> COPIAR + EXTENDER
pos-micro/frontend/src/store/               -> COPIAR COMPLETO
pos-micro/frontend/src/components/          -> ADAPTAR

1.2 Gamilit (Patrones de Arquitectura)

Ubicacion: /workspace-v1/projects/gamilit/

Utilidad: Patrones de arquitectura avanzados

Patrones reutilizables:

• Guards, decorators, interceptors
• Shared utilities structure
• Error handling robusto
• Sistema de notificaciones
• WebSocket para tiempo real
• Health checks y monitoring

Archivos de referencia:

gamilit/apps/backend/src/shared/            -> PATRONES (no copiar directo)
gamilit/apps/frontend/src/                  -> ESTRUCTURA

1.3 Trading-Platform (LLM Agent)

Ubicacion: /workspace-v1/projects/trading-platform/apps/llm-agent/

Utilidad: Arquitectura agnostica de LLM

Componentes reutilizables:

• LLM Client Factory Pattern (adaptador multi-proveedor)
• Tool System (function calling)
• Prompt Management
• SSE Streaming para chat

Archivos clave:

# Traducir a TypeScript:
src/core/llm_client.py        -> Adaptador agnostico LLM
src/tools/base.py             -> Base class para tools
src/api/routes.py             -> SSE streaming endpoints

Client TypeScript existente:

trading-platform/apps/backend/src/shared/clients/llm-agent.client.ts

1.4 Shared-Libs Core (Utilidades Base)

Ubicacion: /workspace-v1/projects/erp-suite/apps/shared-libs/core/

Utilidades reutilizables:

• Base entities (id, createdAt, updatedAt)
• Tenant middleware (RLS)
• Auth middleware
• Error handling base
• BaseTypeOrmService (CRUD generico)
• Factory patterns

---

2. WhatsApp Business Integration

2.1 Opcion Principal: Meta Cloud API

Documentacion oficial:

• https://business.whatsapp.com/developers/developer-hub
• https://developers.facebook.com/

Caracteristicas:

• API oficial de Meta
• Webhooks para mensajes entrantes
• Templates pre-aprobados para iniciar conversaciones
• Mensajes de sesion (24h window)
• Multimedia: texto, imagenes, videos, documentos, ubicacion

Rate Limits:

• 80 msg/seg (default)
• Hasta 1,000 msg/seg para cuentas elegibles
• Numeros nuevos: 250-1,000 msg/dia inicialmente

Modelo de precios (Julio 2025):

• Cobro por mensaje entregado (no por conversacion)
• Marketing: mas caro
• Utility: medio
• Authentication: medio
• Service (respuestas): gratis en ventana 24h

2.2 Multi-Tenant WhatsApp

Opciones:

A. Tech Provider de Meta (RECOMENDADO)

• Requiere aprobacion de Meta
• Embedded Signup para onboarding self-service
• Trabaja con BSP (Twilio, Infobip, MessageBird)

B. Numero Compartido de Plataforma

• Un numero para multiples negocios
• Deteccion de tenant por:
  • Keyword inicial ("Hola, busco [Nombre Negocio]")
  • Contexto de conversacion
  • Base de datos de clientes

2.3 Librerias de Referencia

Libreria	GitHub	Notas
Baileys	WhiskeySockets/Baileys	WebSocket API, multi-device
whatsapp-web.js	pedroslopez/whatsapp-web.js	Puppeteer, 20k+ stars
NestWhats	NedcloarBR/NestWhats	Wrapper NestJS

ADVERTENCIA: Librerias no oficiales pueden resultar en bloqueo de numero.

---

3. Model Context Protocol (MCP)

3.1 Que es MCP

Protocolo abierto de Anthropic (Nov 2024) para integrar LLMs con fuentes de datos/herramientas externas.

Arquitectura: Cliente-Servidor basado en JSON-RPC 2.0

Componentes:

• Hosts: Aplicaciones LLM (Claude Desktop, VS Code)
• Clients: Conectores dentro del host
• Servers: Servicios que proveen contexto

3.2 Primitivas del Protocolo

Primitiva	Descripcion
Tools	Funciones ejecutables (APIs, DB queries)
Resources	Datos de solo lectura
Prompts	Templates reutilizables
Sampling	Comportamientos agentivos

3.3 SDK TypeScript

Instalacion:

npm install @modelcontextprotocol/server zod

Ejemplo basico:

import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

const server = new Server({
  name: "michangarrito-mcp",
  version: "1.0.0"
}, {
  capabilities: { tools: {} }
});

// Registrar tools...

3.4 Tools para MiChangarrito

Categoria	Tools
Ventas	registrar_venta, obtener_ventas, generar_corte
Productos	buscar_producto, crear_producto, actualizar_precio
Inventario	consultar_stock, registrar_entrada, alertas_stock
Clientes	buscar_cliente, crear_cliente, historial_cliente
Fiados	registrar_fiado, obtener_fiados, marcar_pagado
Pedidos	crear_pedido, obtener_pedidos, actualizar_estado
Reportes	generar_reporte, enviar_whatsapp, exportar_excel

3.5 Integracion Multi-Provider

Provider	Estado MCP
Claude	Nativo (creador)
ChatGPT/OpenAI	Completo (marzo 2025)
Gemini	Soportado
OpenRouter	Compatible

---

4. Integraciones de Pago Mexico

4.1 Mercado Pago Point

Documentacion: https://www.mercadopago.com.mx/developers/es/docs/mp-point/overview

SDK Node.js:

npm install mercadopago

Flujo:

1. Crear Payment Intent
2. Enviar a terminal Point
3. Procesar pago
4. Webhook de confirmacion

Comisiones:

• Inmediato: 3.49% + $4 MXN + IVA
• 30 dias: 2.95% + $4 MXN + IVA

4.2 Clip

Documentacion: https://developer.clip.mx/

SDK: Solo REST API (no SDK Node.js oficial)

Endpoints principales:

POST /paymentrequest/           - Crear solicitud
DELETE /paymentrequest/code/X   - Cancelar
GET /payments/receipt-no/X      - Detalles
GET /payments?from=X&to=Y       - Lista

Comisiones:

• Estandar: 3.6% + IVA
• MSI: +1% a +24% segun meses

4.3 CoDi (Banxico)

Documentacion: https://www.codi.org.mx/

Integracion via: Openpay, dapp (recomendado vs directo Banxico)

SDK Node.js (Openpay):

openpay.charges.create({
  method: 'codi',
  amount: 100.00,
  codi_options: { mode: 'QR_CODE' }
});

Flujo:

1. Generar QR dinamico
2. Cliente escanea con app bancaria
3. Autoriza pago
4. Webhook de confirmacion

Comisiones: Gratis con Banxico (intermediarios pueden cobrar)

4.4 Stripe (OXXO + Suscripciones)

Documentacion: https://docs.stripe.com/payments/oxxo

SDK Node.js:

npm install stripe

OXXO References:

const paymentIntent = await stripe.paymentIntents.create({
  amount: 10000, // centavos
  currency: 'mxn',
  payment_method_types: ['oxxo']
});

Limitaciones OXXO:

• Min: $10 MXN, Max: $10,000 MXN
• Vigencia: 1-7 dias
• NO soporta suscripciones

Suscripciones:

const subscription = await stripe.subscriptions.create({
  customer: 'cus_xxx',
  items: [{ price: 'price_xxx' }]
});

Comisiones:

• Tarjetas/OXXO: 3.6% + $3 MXN + IVA

---

5. Matriz de Decision

Reutilizacion de Codigo

Fuente	% Reutilizable	Prioridad	Esfuerzo
POS-Micro Backend	80%	CRITICO	Bajo
POS-Micro Frontend	60%	ALTO	Medio
Shared-Libs Core	100%	CRITICO	Bajo
Trading-Platform LLM	70%	ALTO	Medio
Gamilit Patterns	40%	MEDIO	Bajo

Integraciones de Pago

Proveedor	Prioridad	Complejidad	Costo
Stripe (suscripciones)	P0	Media	3.6%
Stripe OXXO	P0	Baja	3.6%
Mercado Pago Point	P1	Media	2.95-3.49%
Clip	P2	Media	3.6%
CoDi	P2	Alta	Gratis

---

6. Proximos Pasos

1. FASE 1: Copiar y adaptar POS-Micro como base
2. FASE 2: Extender schema BD (customers, fiados, orders, subscriptions, tokens)
3. FASE 3: Implementar WhatsApp Service con Meta Cloud API
4. FASE 4: Implementar MCP Server con tools basicos
5. FASE 5: Integrar Stripe (suscripciones + OXXO)
6. FASE 6: Integrar terminales (Mercado Pago, Clip)
7. FASE 7: Desarrollar app mobile React Native

---

Version: 1.0.0 Fecha: 2026-01-04