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

```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