michangarrito/orchestration/_archive/root-files/PLAN-IMPLEMENTACION.md

Plan de Implementación - MiChangarrito

Versión: 3.3.0 Última actualización: 2026-01-10 Responsable: @PERFIL_DEVENV

---

Resumen del Proyecto

MiChangarrito es un POS inteligente para micro-negocios con asistente IA vía WhatsApp.

---

Fases de Implementación

FASE 1: Infraestructura Base ✅ COMPLETADA

Objetivo: Establecer la base técnica del sistema.

Tarea	Estado	Fecha
Diseño de base de datos multi-tenant	✅ Completado	2026-01-04
Implementación de 9 schemas DDL	✅ Completado	2026-01-04
Seeds de datos iniciales	✅ Completado	2026-01-04
Scripts de gestión de BD	✅ Completado	2026-01-05
Backend NestJS con 12 módulos	✅ Completado	2026-01-05
WhatsApp Service	✅ Completado	2026-01-05
MCP Server con 15 herramientas	✅ Completado	2026-01-05
Frontend React con 9 páginas	✅ Completado	2026-01-05

Entregables:

• Base de datos: 29 tablas en 9 schemas
• Backend: Puerto 3141
• WhatsApp Service: Puerto 3143
• Frontend: Puerto 3140
• MCP Server: stdio transport

---

FASE 2: Integración y Pruebas ✅ COMPLETADA

Objetivo: Conectar todos los componentes y validar flujos.

Tarea	Estado	Fecha
Configurar TypeORM en backend	✅ Completado	2026-01-06
Conectar frontend con API	✅ Completado	2026-01-06
Configurar WhatsApp webhook en Meta	⏳ Pendiente	-
Pruebas de flujo de pedidos	✅ Completado	2026-01-06
Pruebas de flujo de fiado	✅ Completado	2026-01-06
Pruebas E2E completas	⏳ Pendiente	-

Nota: Webhooks de WhatsApp requieren cuenta Business de Meta (config externa).

---

FASE 3: Mobile App ✅ COMPLETADA

Objetivo: Desarrollar aplicación móvil con Expo.

Tarea	Estado	Fecha
Setup Expo con TypeScript	✅ Completado	2026-01-06
Pantalla de login	✅ Completado	2026-01-06
Dashboard móvil	✅ Completado	2026-01-06
Punto de venta rápido	✅ Completado	2026-01-06
Escaneo de código de barras	✅ Completado	2026-01-07
Modo offline con sync	✅ Completado	2026-01-07

Entregables Mobile (10 pantallas):

• LoginScreen: Autenticación con PIN de 4 dígitos
• DashboardScreen: KPIs, ventas del día, alertas
• SalesScreen: POS con carrito y cobro rápido
• BarcodeScannerScreen: Escaneo de productos (expo-barcode-scanner)
• ProductsScreen: CRUD completo de productos con categorías
• InventoryScreen: Control de stock con ajustes rápidos
• CustomersScreen: Gestión de clientes con fiado
• ReportsScreen: Reportes por período con métricas
• SettingsScreen: Preferencias y configuración
• MoreScreen: Navegación adicional

Servicios implementados:

• ApiService: Cliente axios con interceptors y refresh token
• OfflineStorage: AsyncStorage para datos offline
• OfflineSyncContext: Sincronización automática al reconectarse

---

FASE 4: Monetización ✅ COMPLETADA

Objetivo: Implementar sistema de pagos y suscripciones.

Tarea	Estado	Fecha
Integración Stripe	✅ Completado	2026-01-07
Planes de suscripción	✅ Completado	2026-01-07
Sistema de tokens	✅ Completado	2026-01-07
Paquetes de recarga	✅ Completado	2026-01-07

Módulo Billing implementado:

• BillingService: Gestión de suscripciones y tokens
• StripeService: SDK de Stripe para pagos
• WebhooksController: Procesamiento de eventos Stripe
• BillingController: Endpoints REST para billing

Endpoints disponibles:

• GET /billing/plans - Listar planes
• GET /billing/subscription - Obtener suscripción actual
• POST /billing/subscribe - Crear suscripción
• POST /billing/cancel - Cancelar suscripción
• GET /billing/tokens/balance - Balance de tokens
• POST /billing/tokens/consume - Consumir tokens
• POST /billing/tokens/recharge - Recargar tokens
• POST /billing/webhooks - Webhooks de Stripe

Esquema de BD subscriptions:

• plans: 4 planes (gratuito, emprendedor, negocio, enterprise)
• subscriptions: Suscripciones de tenants con Stripe
• tenant_token_balance: Balance de tokens por tenant
• token_usage: Historial de consumo de tokens
• token_packages: Paquetes de recarga disponibles

---

FASE 5: Despliegue ✅ COMPLETADA

Objetivo: Preparar para producción.

Tarea	Estado	Fecha
Docker Compose completo	✅ Completado	2026-01-07
CI/CD con GitHub Actions	✅ Completado	2026-01-07
Dockerfiles para cada servicio	✅ Completado	2026-01-07
Nginx reverse proxy	✅ Completado	2026-01-07
Scripts de deployment	✅ Completado	2026-01-07
Documentación de despliegue	✅ Completado	2026-01-07

Entregables de Despliegue:

Archivos Docker:

• docker-compose.yml - Orquestación de todos los servicios
• apps/backend/Dockerfile - Multi-stage build NestJS
• apps/frontend/Dockerfile - Build React + nginx
• apps/whatsapp-service/Dockerfile - Multi-stage build NestJS
• .env.docker - Template de variables de entorno

CI/CD:

• .github/workflows/ci.yml - Pipeline completo (lint, test, build, deploy)
• Publicación automática de imágenes a GitHub Container Registry
• Deploy automático en push a main

Nginx:

• deploy/nginx/nginx.conf - Configuración principal
• deploy/nginx/conf.d/default.conf - Reverse proxy con rate limiting

Scripts:

• deploy/scripts/deploy.sh - Script de despliegue
• deploy/scripts/backup.sh - Backup y restore de BD

Documentación:

• docs/90-transversal/GUIA-DESPLIEGUE.md - Guía completa

---

FASE 5.1: Integraciones Multi-Tenant ✅ COMPLETADA

Objetivo: Permitir a cada tenant configurar sus propias credenciales de integraciones (WhatsApp, LLM) con fallback a plataforma.

Tarea	Estado	Fecha
Schema BD tenant_integration_credentials	✅ Completado	2026-01-07
Entidades TypeORM para integraciones	✅ Completado	2026-01-07
TenantIntegrationsService con fallback	✅ Completado	2026-01-07
Endpoints CRUD de credenciales	✅ Completado	2026-01-07
API interna para whatsapp-service	✅ Completado	2026-01-07
Refactorización WhatsApp Service	✅ Completado	2026-01-07
Refactorización LLM Service	✅ Completado	2026-01-07
Resolución de tenant en webhooks	✅ Completado	2026-01-07
Documentación de arquitectura	✅ Completado	2026-01-07

Componentes implementados:

Backend (apps/backend/src/modules/integrations/):

• entities/tenant-integration-credential.entity.ts - Entidad de credenciales con enums
• entities/tenant-whatsapp-number.entity.ts - Mapeo phoneNumberId → tenantId
• services/tenant-integrations.service.ts - CRUD + resolución con fallback
• controllers/integrations.controller.ts - API REST para tenants
• controllers/internal-integrations.controller.ts - API interna protegida
• dto/integration-credentials.dto.ts - DTOs de validación

WhatsApp Service (apps/whatsapp-service/src/):

• common/credentials-provider.service.ts - Cache de credenciales con TTL
• common/common.module.ts - Módulo global
• Refactorización de whatsapp.service.ts - tenantId en todos los métodos
• Refactorización de llm.service.ts - Config LLM por tenant
• Refactorización de webhook.service.ts - Resolución de tenant

Base de datos:

• database/schemas/12-integrations.sql - ENUMs + tablas + índices

Endpoints disponibles:

Públicos (requieren JWT):

• GET /integrations/status - Estado de todas las integraciones
• GET /integrations/whatsapp - Config de WhatsApp
• PUT /integrations/whatsapp - Configurar WhatsApp propio
• DELETE /integrations/whatsapp - Eliminar WhatsApp propio
• GET /integrations/llm - Config de LLM
• PUT /integrations/llm - Configurar LLM propio
• DELETE /integrations/llm/:provider - Eliminar LLM

Internos (requieren X-Internal-Key):

• GET /internal/integrations/:tenantId/whatsapp - Credenciales WhatsApp
• GET /internal/integrations/:tenantId/llm - Config LLM
• GET /internal/integrations/resolve-tenant/:phoneNumberId - Resolver tenant

Proveedores LLM soportados:

• OpenAI (gpt-4o, gpt-4o-mini)
• OpenRouter (acceso a múltiples modelos)
• Anthropic (Claude)
• Azure OpenAI
• Ollama (local)

Documentación:

• docs/90-transversal/ARQUITECTURA-MULTI-TENANT-INTEGRACIONES.md

---

Arquitectura Técnica

┌─────────────────────────────────────────────────────────────┐
│                        CLIENTES                             │
├──────────────┬──────────────┬──────────────┬───────────────┤
│  Mobile App  │  Web Admin   │   WhatsApp   │   MCP Tools   │
│  (Expo)      │  (React)     │   (Meta)     │   (Claude)    │
│  :8081       │  :3140       │              │               │
└──────┬───────┴──────┬───────┴──────┬───────┴───────┬───────┘
       │              │              │               │
       └──────────────┼──────────────┼───────────────┘
                      │              │
              ┌───────▼───────┐ ┌────▼────┐
              │  Backend API  │ │WhatsApp │
              │  (NestJS)     │ │ Service │
              │  :3141        │ │  :3143  │
              └───────┬───────┘ └────┬────┘
                      │              │
                      └──────┬───────┘
                             │
                      ┌──────▼──────┐
                      │ PostgreSQL  │
                      │   :5432     │
                      │ (9 schemas) │
                      └─────────────┘

---

Métricas de Progreso

Fase	Completado	Pendiente	%
Fase 1: Infraestructura	8	0	100%
Fase 2: Integración	4	2	67%
Fase 3: Mobile	6	0	100%
Fase 4: Monetización	4	0	100%
Fase 5: Despliegue	6	0	100%
Fase 5.1: Multi-Tenant Integraciones	9	0	100%
TOTAL	37	2	95%

---

Dependencias Externas

Servicio	Estado	Notas
PostgreSQL 15	✅ Disponible	localhost:5432 (9 schemas, 29 tablas)
Redis 7	✅ Disponible	localhost:6379 DB 8
Meta WhatsApp API	⏳ Pendiente	Requiere cuenta Business verificada
Stripe	✅ Integrado	Requiere API keys en .env
OpenRouter/OpenAI	✅ Multi-tenant	Soporte para credenciales por tenant

---

FASE 6: Configuracion Externa (Consecuente)

Objetivo: Configurar servicios externos para produccion.

Estado: Pendiente (requiere accion del usuario)

Tarea	Estado	Dependencia	Perfil
Configurar Meta Business para WhatsApp	⏳ Pendiente	Cuenta Business verificada	@PERFIL_DEVOPS
Configurar Stripe produccion	⏳ Pendiente	Cuenta Stripe activada	@PERFIL_DEVOPS
Configurar LLM Provider	⏳ Pendiente	API key del proveedor	@PERFIL_BACKEND
Desplegar en servidor produccion	⏳ Pendiente	Servidor con Docker	@PERFIL_DEVOPS

Documentacion detallada: TAREAS-PENDIENTES-INTEGRACIONES.md

Script de validacion:

./database/scripts/validate-integrations.sh

Notas:

• Estas tareas requieren configuracion externa que depende del usuario
• Se recomienda completar en orden: Servidor -> Stripe -> Meta -> LLM
• Ver documento de tareas pendientes para instrucciones paso a paso
• Usar script de validacion para verificar configuraciones

---

Proximas Acciones

1. Inmediato: Configurar servidor de produccion con Docker
2. Corto plazo: Obtener cuenta Business de Meta para WhatsApp
3. Corto plazo: Configurar Stripe API keys en produccion
4. Opcional: Pruebas E2E automatizadas

---

Referencias

• Contexto del Proyecto
• Environment Inventory
• Reporte de Implementacion
• Tareas Pendientes Integraciones
• Arquitectura Database
• Especificacion de Componentes

---

Historial de Cambios

Version	Fecha	Cambios
1.0.0	2026-01-05	Version inicial con FASE 1 completada
2.0.0	2026-01-07	Actualizacion con FASES 2, 3 y 4 completadas
3.0.0	2026-01-07	FASE 5 completada - Docker, CI/CD, deployment
3.1.0	2026-01-07	FASE 5.1 - Integraciones Multi-Tenant (WhatsApp/LLM por tenant)
3.2.0	2026-01-07	Validacion builds, BD, y documentacion FASE 6 consecuente
3.3.0	2026-01-10	Sincronizacion con inventarios v2.0.0 (9 schemas, 29 tablas, 12 modulos, 9 paginas)

---

Fin del Plan