michangarrito/orchestration/analisis/historico/FASE-1-ANALISIS-PLANEACION-INICIAL-2026-01-10.md

# FASE 1: Analisis y Planeacion Inicial - Documentacion vision-general

---
id: ANALISIS-VISION-001
title: Analisis y Planeacion Inicial para Estandarizacion de Documentacion
type: Analysis
status: InProgress
priority: P0
version: 1.0.0
created_date: 2026-01-10
updated_date: 2026-01-10
perfil_ejecutor: DOCUMENTATION-MAINTAINER + REQUIREMENTS-ANALYST
---

## 1. Resumen Ejecutivo

Este documento presenta el analisis inicial de la documentacion en `docs/00-vision-general/` del proyecto MiChangarrito, comparando su estado actual contra los estandares SIMCO del workspace y los patrones de referencia de `template-saas` y `erp-core`.

### Alcance del Analisis

| Aspecto | Descripcion |
|---------|-------------|
| **Carpeta analizada** | `/projects/michangarrito/docs/00-vision-general/` |
| **Archivos evaluados** | 3 documentos principales |
| **Referencias utilizadas** | template-saas (14 modulos SaaS), erp-core (20 modulos ERP) |
| **Estandares aplicados** | SIMCO v3.7, SIMCO-DOCUMENTACION-PROYECTO, SIMCO-NOMENCLATURA |

---

## 2. Estado Actual de Documentacion

### 2.1 Inventario de Archivos en vision-general

| Archivo | Lineas | Ultima Actualizacion | Version | Proposito |
|---------|--------|---------------------|---------|-----------|
| `VISION-PROYECTO.md` | 291 | 2026-01-04 | 1.0.0 | Vision estrategica, modelo de negocio, roadmap |
| `REQUERIMIENTOS-FUNCIONALES.md` | 415 | 2026-01-04 | 1.0.0 | 17 requisitos funcionales (RF-001 a RF-017) |
| `ARQUITECTURA-TECNICA.md` | 531 | 2026-01-10 | 2.0.0 | Stack tecnologico, diagramas, infraestructura |

### 2.2 Contenido Identificado por Documento

#### VISION-PROYECTO.md
- Problema del mercado (1.2M tienditas en Mexico)
- Propuesta de valor ("WhatsApp First, App Second")
- Filosofia de diseno (3 principios)
- Mercado objetivo (5 segmentos)
- Perfil de usuario ("Dona Mary")
- Modelo de negocio (2 planes + tokens)
- Diferenciadores vs competencia
- Roadmap de alto nivel (4 fases)
- Stack tecnologico (11 componentes)
- KPIs principales y de producto
- Riesgos y mitigaciones
- Equipo necesario

#### REQUERIMIENTOS-FUNCIONALES.md
- RF-001: Punto de Venta (POS) - 4 subsecciones
- RF-002: Catalogo de Productos - 4 subsecciones
- RF-003: Inventario - 3 subsecciones
- RF-004: Sistema de Fiados/Credito - 3 subsecciones
- RF-005: Clientes - 3 subsecciones
- RF-006: Pedidos de Clientes - 4 subsecciones
- RF-007: Asistente IA (LLM) - 4 subsecciones + 27 tools MCP
- RF-008: WhatsApp Business - 4 subsecciones
- RF-009: Pagos y Suscripciones - 4 subsecciones
- RF-010: Reportes y Analytics - 3 subsecciones
- RF-011: Notificaciones - 3 subsecciones
- RF-012: Modo Offline - 2 subsecciones
- RF-013: Integraciones de Terminal - 3 subsecciones
- RF-014: Onboarding - 3 subsecciones
- RF-015: Seguridad y Acceso - 3 subsecciones
- RF-016: Programa de Referidos - 2 subsecciones
- RF-017: Soporte - 2 subsecciones

#### ARQUITECTURA-TECNICA.md
- Diagrama general de plataforma (ASCII)
- 5 componentes principales documentados:
  - App Movil (React Native)
  - Web Dashboard (React)
  - Backend API (NestJS)
  - MCP Server (LLM Gateway)
  - WhatsApp Service
- Base de datos: 12 schemas, 49 tablas
- Integraciones externas: 3 categorias (Pagos, Comunicacion, IA/ML)
- Seguridad: Autenticacion, Multi-tenancy, Encriptacion
- Infraestructura AWS: ECS Fargate, RDS, ElastiCache, S3
- Performance y escalabilidad: 4 estrategias

---

## 3. Analisis de Brechas vs Estandares SIMCO

### 3.1 Matriz de Conformidad - Frontmatter YAML

| Campo Requerido | VISION-PROYECTO | REQUERIMIENTOS | ARQUITECTURA | Requerido Por |
|-----------------|-----------------|----------------|--------------|---------------|
| `id` | NO | NO | NO | SIMCO-DOCUMENTACION-PROYECTO |
| `title` | NO | NO | NO | SIMCO-DOCUMENTACION-PROYECTO |
| `type` | NO | NO | NO | SIMCO-DOCUMENTACION-PROYECTO |
| `status` | NO | NO | NO | SIMCO-DOCUMENTACION-PROYECTO |
| `priority` | NO | NO | NO | SIMCO-DOCUMENTACION-PROYECTO |
| `module` | NO | NO | NO | SIMCO-DOCUMENTACION-PROYECTO |
| `version` | SI (footer) | SI (footer) | SI (footer) | SIMCO-DOCUMENTACION-PROYECTO |
| `created_date` | NO | NO | NO | SIMCO-DOCUMENTACION-PROYECTO |
| `updated_date` | SI (footer) | SI (footer) | SI (footer) | SIMCO-DOCUMENTACION-PROYECTO |

**Resultado: 0% conformidad en frontmatter YAML**

### 3.2 Matriz de Conformidad - Nomenclatura

| Patron Esperado | Documento Actual | Cumple | Estandar |
|-----------------|------------------|--------|----------|
| `RF-{MODULO}-{NUM}.md` | Embebido en REQUERIMIENTOS-FUNCIONALES.md | PARCIAL | SIMCO-NOMENCLATURA |
| `ET-{TIPO}-{MODULO}.md` | ARQUITECTURA-TECNICA.md | NO | SIMCO-NOMENCLATURA |
| `VIS-{NUM}-{desc}.md` | VISION-PROYECTO.md | NO | SIMCO-NOMENCLATURA |
| `_MAP.md` en carpeta | NO EXISTE | NO | SIMCO-ESTRUCTURA-DOCS |

**Resultado: 25% conformidad parcial en nomenclatura**

### 3.3 Matriz de Conformidad - Estructura de Contenido

| Elemento Requerido | VISION | REQUERIMIENTOS | ARQUITECTURA | Estandar |
|--------------------|--------|----------------|--------------|----------|
| Metadata tabla al inicio | NO | NO | NO | SIMCO-DOCUMENTACION-PROYECTO |
| Descripcion clara | SI | SI | SI | SIMCO-DOCUMENTACION-PROYECTO |
| Referencias cruzadas | NO | NO | PARCIAL (1) | SIMCO-DOCUMENTACION-PROYECTO |
| Criterios de aceptacion | N/A | NO | N/A | SIMCO-DOCUMENTACION-PROYECTO |
| Dependencias documentadas | NO | NO | PARCIAL | SIMCO-DOCUMENTACION-PROYECTO |
| Status por seccion | NO | NO | NO | SIMCO-DOCUMENTACION-PROYECTO |

**Resultado: 33% conformidad en estructura de contenido**

### 3.4 Brechas Criticas Identificadas

| ID | Brecha | Severidad | Impacto | Archivo(s) Afectado(s) |
|----|--------|-----------|---------|------------------------|
| GAP-001 | Falta frontmatter YAML completo | CRITICA | Imposible validar automaticamente, no se puede rastrear estado | Todos |
| GAP-002 | Falta _MAP.md en carpeta | ALTA | Sin indice navegable, dificulta onboarding | vision-general/ |
| GAP-003 | Requisitos sin criterios de aceptacion BDD | ALTA | No verificables automaticamente | REQUERIMIENTOS-FUNCIONALES.md |
| GAP-004 | Sin referencias cruzadas a epicas | ALTA | Trazabilidad rota | REQUERIMIENTOS-FUNCIONALES.md |
| GAP-005 | Sin status individual por requisito | MEDIA | No se sabe estado de implementacion | REQUERIMIENTOS-FUNCIONALES.md |
| GAP-006 | Sin prioridad por requisito | MEDIA | No se puede priorizar trabajo | REQUERIMIENTOS-FUNCIONALES.md |
| GAP-007 | Nomenclatura no estandarizada | MEDIA | Dificil busqueda y automatizacion | Todos |
| GAP-008 | Sin referencias a ADRs | MEDIA | Decisiones no trazables | ARQUITECTURA-TECNICA.md |

---

## 4. Analisis de Requisitos SaaS Faltantes (vs template-saas)

### 4.1 Comparacion de Modulos SaaS

El proyecto template-saas documenta 14 modulos SaaS core. Comparacion con MiChangarrito:

| Modulo template-saas | Codigo | Documentado en MCH | Completo | Brecha |
|---------------------|--------|-------------------|----------|--------|
| Auth | SAAS-001 | RF-015 (parcial) | 40% | Falta OAuth, MFA, API Keys |
| Tenants | SAAS-002 | ARQUITECTURA (parcial) | 60% | Falta tenant_config detallado |
| Users | SAAS-003 | RF-015 (parcial) | 50% | Falta RBAC granular |
| Billing | SAAS-004 | RF-009 | 70% | Falta webhook routing multi-tenant |
| Plans | SAAS-005 | RF-009 (parcial) | 60% | Falta feature_limits, quotas |
| AI Integration | SAAS-006 | RF-007 | 80% | Falta cost tracking por tenant |
| Notifications | SAAS-007 | RF-011 | 70% | Falta plantillas por tenant |
| Audit Logs | SAAS-008 | NO DOCUMENTADO | 0% | FALTA COMPLETAMENTE |
| Feature Flags | SAAS-009 | NO DOCUMENTADO | 0% | FALTA COMPLETAMENTE |
| Webhooks | SAAS-010 | NO DOCUMENTADO | 0% | FALTA COMPLETAMENTE |
| Storage | SAAS-011 | ARQUITECTURA (minimo) | 30% | Falta presigned URLs, quotas |
| CRUD Base | SAAS-012 | N/A (patron) | N/A | Patron, no modulo |
| Email | SAAS-013 | RF-011 (parcial) | 40% | Falta templates, tracking |
| WhatsApp | SAAS-014 | RF-008 | 90% | Bien documentado |

### 4.2 Requisitos SaaS Faltantes Criticos

| ID | Requisito SaaS | Prioridad | Justificacion |
|----|----------------|-----------|---------------|
| SAAS-REQ-001 | Sistema de Audit Logs | P1 | Requerido para compliance y debugging |
| SAAS-REQ-002 | Feature Flags por Plan/Tenant | P1 | Necesario para rollout gradual y planes |
| SAAS-REQ-003 | Webhooks Outbound | P2 | Permite integraciones de terceros |
| SAAS-REQ-004 | Rate Limiting por Plan | P1 | Previene abuso, diferencia planes |
| SAAS-REQ-005 | Storage con Quotas | P2 | Control de costos por tenant |
| SAAS-REQ-006 | Cost Tracking IA | P1 | Ya mencionado pero no detallado |
| SAAS-REQ-007 | OAuth/SSO | P3 | Para expansion enterprise |

### 4.3 Patrones template-saas a Adoptar

1. **Nomenclatura MCH-MODULO-SAAS.md**
   - Cada modulo SaaS con documento dedicado
   - Estructura: Metadata, Descripcion, Alcance, Modelo de Datos, API, Roadmap

2. **ADRs Estandarizados**
   - ADR-NNNN-descripcion.md
   - Estructura: Contexto, Opciones, Decision, Consecuencias

3. **Documentacion de Integraciones INT-XXX**
   - Multi-tenant config
   - Testing strategy
   - Rate limits
   - Error handling

---

## 5. Analisis de Flujos de Negocio Faltantes (vs erp-core)

### 5.1 Comparacion de Modulos Core

erp-core tiene 20 modulos de negocio. Comparacion relevante con MiChangarrito:

| Modulo erp-core | Codigo | Relevante para MCH | Documentado en MCH | Brecha |
|-----------------|--------|-------------------|-------------------|--------|
| Auth | MGN-001 | SI | RF-015 | Ver SAAS-001 |
| Users | MGN-002 | SI | RF-015 | Ver SAAS-003 |
| Roles | MGN-003 | SI | RF-015.2 (futuro) | No detallado |
| Tenants | MGN-004 | SI | ARQUITECTURA | Ver SAAS-002 |
| Catalogs | MGN-005 | SI | RF-002.3 (templates) | Parcial |
| Settings | MGN-006 | SI | NO | FALTA |
| Audit | MGN-007 | SI | NO | FALTA |
| Notifications | MGN-008 | SI | RF-011 | OK |
| Reports | MGN-009 | SI | RF-010 | OK |
| Financial | MGN-010 | NO | N/A | No aplica ERP completo |
| Partners (CRM) | MGN-017 | PARCIAL | RF-005 (clientes) | Solo clientes, no proveedores |
| Products | MGN-005 | SI | RF-002 | OK |
| Inventory | MGN-006 | SI | RF-003 | OK |
| Purchases | MGN-012 | PARCIAL | NO | Falta compras a proveedor |
| Sales | MGN-013 | SI | RF-001 | OK |

### 5.2 Flujos de Negocio Faltantes

| ID | Flujo | Prioridad | Descripcion | Referencia erp-core |
|----|-------|-----------|-------------|---------------------|
| FLOW-001 | Settings/Configuracion centralizada | P1 | Configuracion de negocio en un lugar | MGN-006 |
| FLOW-002 | Compras a proveedores | P2 | Registro de compras, notas de proveedor | MGN-012 |
| FLOW-003 | Categorias jerarquicas | P2 | Arbol de categorias | MGN-005 |
| FLOW-004 | Roles y permisos granulares | P2 | RBAC completo | MGN-003 |
| FLOW-005 | Dashboard metricas avanzadas | P3 | KPIs en tiempo real | MGN-009 |

### 5.3 Patrones erp-core a Adoptar

1. **Estructura de documentacion por fase**
   ```
   docs/
   ├── 01-fase-foundation/     # Auth, Tenants, Users
   ├── 02-fase-core-business/  # Products, Sales, Inventory
   ├── 03-fase-inteligencia/   # IA, WhatsApp, MCP
   └── 04-fase-expansion/      # SPEI, SAT, Multi-idioma
   ```

2. **User Stories por modulo**
   - Carpeta dedicada: `docs/05-user-stories/mch-XXX/`
   - Nomenclatura: `US-MCH-XXX-YYY-descripcion.md`

3. **Grafo de dependencias**
   - Documentar dependencias entre modulos
   - Visualizar con Mermaid diagrams

---

## 6. Dependencias Identificadas

### 6.1 Dependencias Internas (dentro de vision-general)

```
VISION-PROYECTO.md
├── → REQUERIMIENTOS-FUNCIONALES.md (define los RF)
└── → ARQUITECTURA-TECNICA.md (define el stack)

REQUERIMIENTOS-FUNCIONALES.md
├── → ARQUITECTURA-TECNICA.md (schema, API)
├── → docs/01-epicas/*.md (implementacion)
└── → docs/02-especificaciones/*.md (detalles tecnicos)

ARQUITECTURA-TECNICA.md
├── → docs/02-especificaciones/ARQUITECTURA-DATABASE.md
├── → docs/02-integraciones/*.md
└── → docs/97-adr/*.md (decisiones)
```

### 6.2 Dependencias Externas (otros archivos del proyecto)

| Archivo vision-general | Depende de | Tipo |
|------------------------|------------|------|
| REQUERIMIENTOS-FUNCIONALES.md | docs/01-epicas/MCH-001 a MCH-028 | Implementacion |
| REQUERIMIENTOS-FUNCIONALES.md | orchestration/inventarios/MASTER_INVENTORY.yml | Estado |
| ARQUITECTURA-TECNICA.md | docs/02-especificaciones/ARQUITECTURA-DATABASE.md | Detalle tecnico |
| ARQUITECTURA-TECNICA.md | docs/02-integraciones/INT-*.md | Integraciones |
| ARQUITECTURA-TECNICA.md | docs/97-adr/ADR-*.md | Decisiones |

### 6.3 Archivos que Deben Actualizarse al Modificar vision-general

| Si se modifica | Actualizar tambien |
|----------------|-------------------|
| RF-001 (POS) | MCH-004-punto-venta, BACKEND_INVENTORY.yml |
| RF-002 (Productos) | MCH-003-productos, DATABASE_INVENTORY.yml |
| RF-007 (IA) | MCH-010-mcp-server, MASTER_INVENTORY.yml |
| RF-008 (WhatsApp) | MCH-011-whatsapp-service, INT-001-whatsapp-meta.md |
| ARQUITECTURA-TECNICA (schema) | ARQUITECTURA-DATABASE.md, DATABASE_INVENTORY.yml |

---

## 7. Resumen de Hallazgos

### 7.1 Metricas de Conformidad

| Categoria | Conformidad Actual | Meta | Brecha |
|-----------|-------------------|------|--------|
| Frontmatter YAML | 0% | 100% | 100% |
| Nomenclatura | 25% | 100% | 75% |
| Estructura contenido | 33% | 100% | 67% |
| Modulos SaaS documentados | 50% | 100% | 50% |
| Criterios aceptacion | 0% | 100% | 100% |
| Referencias cruzadas | 10% | 100% | 90% |

### 7.2 Prioridades de Correccion

| Prioridad | Cantidad | Items |
|-----------|----------|-------|
| P0 (Critica) | 2 | Frontmatter YAML, _MAP.md |
| P1 (Alta) | 4 | Criterios aceptacion, referencias epicas, audit logs, rate limiting |
| P2 (Media) | 5 | Nomenclatura, status por RF, feature flags, webhooks, storage |
| P3 (Baja) | 2 | OAuth, dashboards avanzados |

### 7.3 Estimacion de Esfuerzo

| Fase | Archivos | Cambios | Complejidad |
|------|----------|---------|-------------|
| Frontmatter + Metadata | 3 | Agregar YAML header | Baja |
| Crear _MAP.md | 1 nuevo | Indice completo | Media |
| Reestructurar RF | 1 | Dividir en archivos individuales O agregar metadata | Alta |
| Agregar criterios aceptacion | 1 | 17 secciones BDD | Alta |
| Referencias cruzadas | 3 | Links a epicas, ADRs | Media |
| Documentar SaaS faltantes | 4 nuevos | Audit, Feature Flags, Webhooks, Rate Limits | Alta |

---

## 8. Proximos Pasos (FASE 2)

La siguiente fase (Analisis Detallado) debera:

1. **Crear matriz de cambios por archivo** - Linea por linea que debe modificarse
2. **Definir estructura final** - Como quedara cada documento
3. **Documentar criterios de aceptacion** - Para cada RF
4. **Crear templates** - Para documentos faltantes (Audit, Feature Flags, etc.)
5. **Validar dependencias** - Confirmar que archivos dependientes existen y estan actualizados

---

## 9. Aprobaciones

| Rol | Nombre | Fecha | Status |
|-----|--------|-------|--------|
| DOCUMENTATION-MAINTAINER | Agent | 2026-01-10 | Completado |
| REQUIREMENTS-ANALYST | Agent | 2026-01-10 | Completado |
| Tech Lead | Pendiente | - | Pendiente |

---

**Documento generado por**: DOCUMENTATION-MAINTAINER + REQUIREMENTS-ANALYST
**Sistema**: SIMCO v3.7.0
**Metodologia**: CAPVED (Fase A - Analisis)