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:**
```python
# 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:**
```bash
npm install @modelcontextprotocol/server zod
```

**Ejemplo basico:**
```typescript
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:**
```bash
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):**
```javascript
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:**
```bash
npm install stripe
```

**OXXO References:**
```javascript
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:**
```javascript
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