[MCH-DOC] docs: Add coherence analysis report

Analysis of documentation vs code implementation: - Identified 2 mock implementations (CoDi-SPEI, Invoices) - Identified 3 empty submodules (mcp-server, whatsapp-service, mobile) - Identified 4 missing frontend pages - Updated _INDEX.yml with analysis reference Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-17 05:35:06 -06:00 · 2026-01-17 05:35:06 -06:00 · 46b8ef7441
commit 46b8ef7441
parent 58caa8aa29
2 changed files with 294 additions and 2 deletions
--- a/docs/_definitions/ANALISIS-DOCUMENTACION-VS-CODIGO.md
+++ b/docs/_definitions/ANALISIS-DOCUMENTACION-VS-CODIGO.md
@ -0,0 +1,281 @@
+# 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
+
+```typescript
+// 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
+
+```typescript
+// 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:**
+   ```bash
+   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
--- a/docs/_definitions/_INDEX.yml
+++ b/docs/_definitions/_INDEX.yml
@ -56,6 +56,17 @@ definiciones_locales:
    validado: true
    total_modules: 17  # VALIDADO vs codigo

+  analisis_coherencia:
+    archivo: "ANALISIS-DOCUMENTACION-VS-CODIGO.md"
+    alias: "@MCH_ANALISIS_COHERENCIA"
+    descripcion: "Analisis de gaps entre documentacion y codigo"
+    validado: true
+    fecha_analisis: "2026-01-17"
+    hallazgos:
+      implementaciones_mock: 2  # CoDi-SPEI, Invoices
+      submodulos_vacios: 3  # mcp-server, whatsapp-service, mobile
+      paginas_faltantes: 4  # billing, messaging, codi, widgets
+
 # ============================================================================
 # HERENCIA (Proyecto Independiente)
 # ============================================================================
@ -68,13 +79,13 @@ herencia:
 # ESTADISTICAS VALIDADAS
 # ============================================================================
 estadisticas:
-  total_definiciones: 4
+  total_definiciones: 5
  total_referencias_ws: 6
  ultima_actualizacion: "2026-01-17"
  validacion:
    fecha: "2026-01-17"
    metodo: "Comparacion directa con codigo fuente"
-    resultado: "COHERENTE"
+    resultado: "COHERENTE con GAPS identificados"

 # ============================================================================
 # METRICAS DEL CODIGO (VALIDADAS)