michangarrito/docs/_definitions/ANALISIS-DOCUMENTACION-VS-CODIGO.md

Análisis de Coherencia: Documentación vs Código

Fecha: 2026-01-17 Versión: 1.0.0 Tipo: Reporte de Análisis Proyecto: michangarrito

---

Resumen Ejecutivo

Este análisis identifica las discrepancias entre la documentación planificada y el código actualmente implementado en el proyecto MiChangarrito. El objetivo es determinar qué ajustes se requieren para alinear el desarrollo con la planeación documentada.

Métricas Clave

Métrica	Documentado	Implementado	Diferencia
Épicas totales	35	-	-
Módulos backend	24	17	-7
Entities	35+	38	+3
Services	30+	18	-12
Controllers	-	19	-
Páginas frontend	15+	12	-3

---

Estado Real del Código

Backend (NestJS)

17 Módulos Implementados:

1. auth - Autenticación y usuarios
2. billing - Facturación Stripe
3. categories - Categorías de productos
4. codi-spei - CoDi y SPEI (MOCK)
5. customers - Clientes y fiados
6. integrations - Integraciones externas
7. inventory - Control de inventario
8. invoices - Facturación SAT (MOCK)
9. marketplace - Proveedores
10. messaging - Mensajería
11. orders - Pedidos
12. payments - Métodos de pago
13. products - Productos
14. referrals - Programa de referidos
15. sales - Ventas
16. subscriptions - Suscripciones
17. widgets - Widgets y atajos

38 Entities Implementadas:

• Auth: user.entity.ts, tenant.entity.ts
• CoDi-SPEI: codi-transaction.entity.ts, spei-transaction.entity.ts, virtual-account.entity.ts
• Customers: customer.entity.ts, fiado.entity.ts, fiado-payment.entity.ts
• Invoices: invoice.entity.ts, invoice-item.entity.ts, tax-config.entity.ts
• Marketplace: 6 entities (supplier, products, orders, reviews, favorites)
• Sales: sale.entity.ts, sale-item.entity.ts
• Subscriptions: plan.entity.ts, subscription.entity.ts, token-balance.entity.ts, token-usage.entity.ts
• Otros: inventory, orders, messaging, categories, products, payments, referrals

Frontend (React + Vite)

12 Páginas Implementadas:

1. Dashboard.tsx - Panel principal
2. Login.tsx - Inicio de sesión
3. Register.tsx - Registro
4. Products.tsx - Gestión de productos
5. Customers.tsx - Gestión de clientes
6. Fiado.tsx - Sistema de fiados
7. Orders.tsx - Pedidos
8. Inventory.tsx - Inventario
9. Invoices.tsx - Facturación
10. Marketplace.tsx - Proveedores
11. Referrals.tsx - Programa de referidos
12. Settings.tsx - Configuración

48 Componentes distribuidos en múltiples carpetas.

Submodulos No Inicializados

Submodulo	Estado	Épica Relacionada
mcp-server/	Vacío	MCH-010
whatsapp-service/	Vacío	MCH-011
mobile/	Vacío	MCH-022

---

Hallazgos Críticos

1. Implementaciones Mock (Simuladas)

CoDi-SPEI Service (codi-spei.service.ts)

Estado documentado: MCH-024 "Completado (Base)" Estado real: MOCK - Sin integración real con Banxico/STP

// Línea 46-47: CLABE generada aleatoriamente
const mockClabe = `646180${Math.floor(Math.random() * 1000000000000).toString().padStart(12, '0')}`;

// Línea 74-81: QR data simulado
const qrData = JSON.stringify({
  type: 'codi',
  amount: dto.amount,
  reference,
  // NO ES UN QR CoDi REAL
});

Componentes faltantes para producción:

• Integración con Banxico CoDi API
• Integración con STP/Arcus para CLABE virtual
• Validación de firmas de webhook
• Certificados de seguridad

Invoices Service (invoices.service.ts)

Estado documentado: MCH-027 "Completado" Estado real: MOCK - Sin integración con PAC

// Línea 182-183: UUID generado localmente (NO ES VÁLIDO SAT)
const mockUuid = `${Date.now().toString(36)}-${Math.random().toString(36).substr(2, 9)}`.toUpperCase();

// Línea 228-229: Email no se envía realmente
// In production, this would send the email with PDF and XML
invoice.status = InvoiceStatus.SENT;

Componentes faltantes para producción:

• Integración con PAC (Facturapi, SW Sapien, Finkok)
• Generación de XML CFDI válido
• Generación de PDF con formato SAT
• Envío real de emails con adjuntos
• Manejo de e.firma

2. Submodulos Vacíos

Submodulo	Épicas Afectadas	Impacto
mcp-server/	MCH-010, MCH-012, MCH-013	BLOQUEANTE para asistente IA
whatsapp-service/	MCH-011, MCH-015, MCH-017	BLOQUEANTE para WhatsApp
mobile/	MCH-022, MCH-025	BLOQUEANTE para app móvil

3. Páginas Frontend Faltantes

Página	Módulo Backend	Estado
Billing/Suscripciones	billing, subscriptions	NO IMPLEMENTADA
Messaging	messaging	NO IMPLEMENTADA
CoDi/SPEI dedicada	codi-spei	Solo componente
Widgets	widgets	NO IMPLEMENTADA

---

Mapeo Épicas vs Implementación

FASE 1: MVP CORE ✅ (Mayormente completo)

Épica	Estado Doc	Estado Real	Notas
MCH-001	Completado	✅ COMPLETO	Infraestructura funcional
MCH-002	Completado	✅ COMPLETO	Auth JWT + PIN
MCH-003	Completado	✅ COMPLETO	Catálogo productos
MCH-004	Completado	✅ COMPLETO	POS funcional
MCH-005	Completado	⚠️ PARCIAL	Solo efectivo y Stripe

FASE 2: INTELIGENCIA ⚠️ (Parcial)

Épica	Estado Doc	Estado Real	Notas
MCH-006	En progreso	❌ NO IMPLEMENTADO	Sin onboarding inteligente
MCH-007	En progreso	❌ NO IMPLEMENTADO	Sin templates
MCH-008	Completado	✅ COMPLETO	Fiados funcional
MCH-009	Completado	⚠️ PARCIAL	Alertas básicas

FASE 3: ASISTENTE IA ❌ (No implementado)

Épica	Estado Doc	Estado Real	Notas
MCH-010	Documentado	❌ VACÍO	Submodulo no inicializado
MCH-011	Documentado	❌ VACÍO	Submodulo no inicializado
MCH-012	Documentado	❌ NO EXISTE	Depende de MCH-010/011
MCH-013	Documentado	❌ NO EXISTE	Depende de MCH-012

FASE 4: PEDIDOS Y CLIENTES ✅ (Mayormente completo)

Épica	Estado Doc	Estado Real	Notas
MCH-014	Completado	✅ COMPLETO	Clientes funcional
MCH-015	Documentado	⚠️ BACKEND ONLY	Sin WhatsApp
MCH-016	Documentado	❌ NO IMPLEMENTADO	Entregas
MCH-017	Documentado	⚠️ PARCIAL	Messaging module existe

FASE 5: MONETIZACIÓN ⚠️ (Parcial)

Épica	Estado Doc	Estado Real	Notas
MCH-018	Completado	✅ COMPLETO	Planes Stripe
MCH-019	Completado	✅ COMPLETO	Tokens funcional
MCH-020	Completado	⚠️ PARCIAL	Solo Stripe, falta OXXO/IAP
MCH-021	Completado	✅ COMPLETO	Dashboard web

FASE 6: CRECIMIENTO ⚠️ (Parcial - Mock)

Épica	Estado Doc	Estado Real	Notas
MCH-022	Documentado	❌ NO EXISTE	Mobile vacío
MCH-023	Completado	✅ COMPLETO	Referidos funcional
MCH-024	Completado	⚠️ MOCK	Sin integración real
MCH-025	Documentado	⚠️ PARCIAL	Widgets module existe

FASE 7: EXPANSIÓN ❌ (Mayormente no implementado)

Épica	Estado Doc	Estado Real	Notas
MCH-026	Documentado	❌ NO IMPLEMENTADO	i18n
MCH-027	Completado	⚠️ MOCK	Sin PAC real
MCH-028	Completado	✅ COMPLETO	Marketplace
MCH-029-035	Documentado	⚠️ PARCIAL	Varios estados

---

Recomendaciones

Prioridad 1: Correcciones Inmediatas

1. Actualizar estados de épicas mock:

   • MCH-024: Cambiar de "Completado (Base)" a "Implementación Base - Requiere Integración"
   • MCH-027: Cambiar de "Completado" a "Implementación Base - Requiere PAC"

2. Documentar módulos como "Estructural" vs "Funcional":

   • Agregar campo implementation_status: structural | functional | mock | complete

Prioridad 2: Alineación de Código

1. Inicializar submodulos críticos:

   cd projects/michangarrito
   git submodule update --init mcp-server
   git submodule update --init whatsapp-service
   

2. Completar páginas frontend faltantes:

   • Billing/Suscripciones
   • Panel de Widgets

Prioridad 3: Decisiones de Negocio

Decisión	Opciones	Impacto
CoDi/SPEI	A) Completar integración B) Remover épica	Alto - Afecta pagos
Facturación SAT	A) Integrar PAC B) Marcar como futuro	Medio - Compliance
MCP/WhatsApp	A) Implementar B) Replantear IA	Alto - Core diferenciador

---

Conclusión

El proyecto MiChangarrito tiene una base sólida para las funcionalidades core (POS, inventario, clientes, fiados, suscripciones). Sin embargo, existe una brecha significativa entre lo documentado como "Completado" y la implementación real en:

1. Integraciones externas (CoDi, SPEI, SAT) - Solo mock
2. Asistente IA (MCP, WhatsApp) - No inicializado
3. Aplicación móvil - No existe

Acción Recomendada

Opción A: Ajustar Documentación

• Reflejar estado real del código
• Marcar épicas mock como "Parcial - Requiere Integración"
• Mantener roadmap pero con estados precisos

Opción B: Completar Desarrollo

• Priorizar integraciones reales (PAC para SAT)
• Inicializar MCP/WhatsApp
• Timeline: 8-12 semanas adicionales

---

Generado por: Análisis de Validación SIMCO 4.0.1 Validado: 2026-01-17