template-saas/orchestration/analisis/PLAN-MAESTRO-PURGA-DOCUMENTAL-2026-01-10.md

# PLAN MAESTRO: PURGA Y REESTRUCTURACION DOCUMENTAL
# Proyecto: template-saas
# Fecha: 2026-01-10
# Autor: Arquitecto de Documentacion / Tech Lead

---

## RESUMEN EJECUTIVO

Este documento establece el plan detallado para realizar una purga completa y reestructuracion de la documentacion del proyecto template-saas. El objetivo es eliminar discrepancias, consolidar definiciones duplicadas, actualizar referencias obsoletas y establecer una estructura documental coherente con el estado actual del desarrollo.

### Objetivos Principales

1. **Purga de contenido obsoleto**: Eliminar correcciones viejas, definiciones duplicadas y referencias desactualizadas
2. **Consolidacion de definiciones**: Unificar versiones multiples de la misma funcionalidad
3. **Reestructuracion documental**: Alinear documentacion con el desarrollo actual
4. **Validacion de dependencias**: Asegurar trazabilidad correcta entre modulos
5. **Historico resumido**: Mantener solo un breve historico de progresion

---

## DISCREPANCIAS IDENTIFICADAS EN ANALISIS INICIAL

### 1. Discrepancia de Numeracion de Modulos

| Ubicacion | SAAS-006 | SAAS-007 | SAAS-008 | SAAS-009 | SAAS-010 | SAAS-011 | SAAS-012 | SAAS-013 |
|-----------|----------|----------|----------|----------|----------|----------|----------|----------|
| _MAP.md | Onboarding | Notifications | Feature Flags | Audit | AI Integration | Portal User | Portal Admin | - |
| docs/01-modulos/ (real) | AI Integration | Notifications | Audit Logs | Feature Flags | Webhooks | Storage | CRUD Base | Email |
| CONTEXT-MAP.yml | Onboarding | Notifications | Feature Flags | Audit | AI Integration | Portal User | Portal Admin | - |

**Accion Requerida**: Homologar numeracion entre _MAP.md, CONTEXT-MAP.yml y los archivos reales en docs/01-modulos/

### 2. Estructura Propuesta vs Real

**_MAP.md propone**:
```
docs/01-modulos/SAAS-001-auth/
├── README.md
├── ESPECIFICACION.md
├── FLUJOS.md
├── IMPLEMENTACION.md
└── TESTS.md
```

**Realidad actual**:
```
docs/01-modulos/
├── SAAS-001-auth.md (archivo unico)
├── SAAS-002-tenants.md
└── ...
```

**Accion Requerida**: Decidir entre mantener archivos planos o migrar a estructura de carpetas

### 3. Documentacion Pendiente Marcada pero No Creada

| Archivo | Estado en _MAP.md | Estado Real |
|---------|-------------------|-------------|
| docs/00-vision-general/VISION.md | [PENDIENTE] | NO EXISTE |
| docs/01-modulos/_MAP.md | [PENDIENTE] | NO EXISTE |
| docs/02-integraciones/_MAP.md | [PENDIENTE] | NO EXISTE |
| docs/02-integraciones/INT-001-STRIPE/ | Listado | CARPETA VACIA |
| docs/02-integraciones/INT-002-OAUTH/ | Listado | NO EXISTE |
| docs/02-integraciones/INT-003-EMAIL/ | Listado | NO EXISTE |
| docs/02-integraciones/INT-004-PUSH/ | Listado | NO EXISTE |
| docs/02-integraciones/INT-005-STORAGE/ | Listado | NO EXISTE |
| docs/97-adr/* | Listado | MOVIDO a architecture/adr/ |

### 4. ADRs en Ubicacion Duplicada

- **Ubicacion antigua**: `docs/97-adr/` (referenciada en _MAP.md)
- **Ubicacion nueva**: `docs/architecture/adr/` (donde estan realmente)
- **Accion**: Eliminar referencia a 97-adr y consolidar en architecture/adr/

### 5. Modulos Nuevos No Documentados

| Modulo | Estado Implementacion | Documentado |
|--------|----------------------|-------------|
| WhatsApp (Sprint 5) | 100% Backend + Frontend | NO |
| Webhooks Outbound | 100% | Parcial (SAAS-010-webhooks.md existe) |
| Email Multi-provider | 100% | SAAS-013-email.md existe |

### 6. Inconsistencias en PROJECT-STATUS.md vs _MAP.md

| Aspecto | PROJECT-STATUS.md | _MAP.md |
|---------|-------------------|---------|
| Total Schemas | 12 schemas | 12 schemas |
| Total Tablas | 35 tablas | 38 tablas |
| Notificaciones | 6 tablas (v2.0 implementado) | 6 tablas (v2.0 propuesto) |

---

## SEGMENTACION DE TAREAS POR FUNCIONALIDAD

### SEGMENTO 1: Documentacion de Vision y Arquitectura
- docs/00-vision-general/
- docs/architecture/

### SEGMENTO 2: Documentacion de Modulos Core
- SAAS-001-auth
- SAAS-002-tenants
- SAAS-003-users
- RBAC (integrado en users)

### SEGMENTO 3: Documentacion de Modulos Billing
- SAAS-004-billing
- SAAS-005-plans

### SEGMENTO 4: Documentacion de Modulos Experiencia
- SAAS-006 (Onboarding o AI?)
- SAAS-007-notifications
- SAAS-008 (Audit o Feature Flags?)
- SAAS-009 (Feature Flags o Audit?)

### SEGMENTO 5: Documentacion de Modulos Avanzados
- AI Integration
- Storage
- Webhooks
- Email
- WhatsApp (NUEVO - Sprint 5)

### SEGMENTO 6: Documentacion de Integraciones
- INT-001-STRIPE
- INT-002-OAUTH
- INT-003-EMAIL
- INT-004-PUSH
- INT-005-STORAGE
- INT-006-WEBHOOKS (nuevo)
- INT-007-REDIS (nuevo)

### SEGMENTO 7: Documentacion de Portales
- Portal User
- Portal Admin
- Portal Superadmin

### SEGMENTO 8: Documentacion Operacional (orchestration/)
- Inventarios
- Planes de Sprint
- Trazas
- Analisis
- Guidelines

---

## FASES DEL PLAN DE PURGA

```
┌─────────────────────────────────────────────────────────────────────────┐
│ FASE 1: ANALISIS Y PLANEACION POR SEGMENTO                              │
│ ├── 1.1 Lectura exhaustiva de cada archivo del segmento                 │
│ ├── 1.2 Identificacion de contenido actual vs esperado                  │
│ ├── 1.3 Mapeo de referencias cruzadas                                   │
│ └── 1.4 Documentacion de hallazgos                                      │
├─────────────────────────────────────────────────────────────────────────┤
│ FASE 2: ANALISIS DETALLADO                                              │
│ ├── 2.1 Comparacion con codigo fuente real                              │
│ ├── 2.2 Validacion de endpoints documentados vs implementados           │
│ ├── 2.3 Validacion de tablas DDL documentadas vs existentes             │
│ └── 2.4 Identificacion de discrepancias especificas                     │
├─────────────────────────────────────────────────────────────────────────┤
│ FASE 3: PLANEACION BASADA EN ANALISIS                                   │
│ ├── 3.1 Definicion de acciones por archivo                              │
│ ├── 3.2 Priorizacion de cambios                                         │
│ ├── 3.3 Identificacion de archivos a eliminar                           │
│ └── 3.4 Definicion de nuevos archivos requeridos                        │
├─────────────────────────────────────────────────────────────────────────┤
│ FASE 4: VALIDACION DE PLANEACION                                        │
│ ├── 4.1 Verificacion de cobertura completa                              │
│ ├── 4.2 Analisis de dependencias afectadas                              │
│ ├── 4.3 Validacion contra requisitos originales                         │
│ └── 4.4 Identificacion de riesgos                                       │
├─────────────────────────────────────────────────────────────────────────┤
│ FASE 5: REFINAMIENTO DEL PLAN                                           │
│ ├── 5.1 Ajustes basados en validacion                                   │
│ ├── 5.2 Ordenamiento de ejecucion                                       │
│ └── 5.3 Definicion de checkpoints                                       │
├─────────────────────────────────────────────────────────────────────────┤
│ FASE 6: EJECUCION DEL PLAN                                              │
│ ├── 6.1 Ejecucion por segmento                                          │
│ ├── 6.2 Validacion post-modificacion                                    │
│ └── 6.3 Documentacion de cambios realizados                             │
├─────────────────────────────────────────────────────────────────────────┤
│ FASE 7: VALIDACION DE EJECUCION                                         │
│ ├── 7.1 Comparacion contenido final vs esperado                         │
│ ├── 7.2 Validacion de referencias cruzadas                              │
│ ├── 7.3 Verificacion de integridad                                      │
│ └── 7.4 Generacion de reporte final                                     │
└─────────────────────────────────────────────────────────────────────────┘
```

---

## DETALLE DE TAREAS POR SEGMENTO Y FASE

### SEGMENTO 1: Vision y Arquitectura

#### FASE 1.1 - Analisis y Planeacion
| Tarea | Descripcion | Archivos Involucrados |
|-------|-------------|----------------------|
| S1-F1-01 | Leer docs/00-vision-general/README.md | README.md |
| S1-F1-02 | Leer docs/00-vision-general/VISION-TEMPLATE-SAAS.md | VISION-TEMPLATE-SAAS.md |
| S1-F1-03 | Leer docs/00-vision-general/ESPECIFICACION-PLATAFORMA-SAAS.md | ESPECIFICACION-PLATAFORMA-SAAS.md |
| S1-F1-04 | Leer docs/00-vision-general/ARQUITECTURA-MULTI-TENANT.md | ARQUITECTURA-MULTI-TENANT.md |
| S1-F1-05 | Verificar si existe docs/00-vision-general/VISION.md (marcado como PENDIENTE) | VISION.md |
| S1-F1-06 | Leer docs/architecture/adr/ADR-001 a ADR-005 | 5 archivos ADR |
| S1-F1-07 | Verificar si existe docs/97-adr/ y su contenido | 97-adr/ |
| S1-F1-08 | Documentar hallazgos de duplicados o inconsistencias | HALLAZGOS-S1.md |

#### FASE 1.2 - Analisis Detallado
| Tarea | Descripcion | Validar Contra |
|-------|-------------|----------------|
| S1-F2-01 | Validar arquitectura multi-tenant documentada vs implementada | apps/database/ddl/schemas/*/rls/ |
| S1-F2-02 | Validar modulos listados en vision vs modulos reales | apps/backend/src/modules/ |
| S1-F2-03 | Validar portales listados vs implementados | apps/frontend/src/portals/ |
| S1-F2-04 | Validar ADRs vs decisiones implementadas | Codigo fuente |

#### FASE 1.3 - Planeacion
| Tarea | Accion Propuesta |
|-------|------------------|
| S1-F3-01 | Eliminar referencia a docs/97-adr/ en _MAP.md |
| S1-F3-02 | Crear o eliminar docs/00-vision-general/VISION.md segun necesidad |
| S1-F3-03 | Actualizar numeros de tablas en documentacion (35 vs 38) |
| S1-F3-04 | Actualizar estado de Notifications v2.0 (de "propuesto" a "implementado") |

---

### SEGMENTO 2: Modulos Core (Auth, Tenants, Users)

#### FASE 2.1 - Analisis y Planeacion
| Tarea | Descripcion | Archivos |
|-------|-------------|----------|
| S2-F1-01 | Leer SAAS-001-auth.md completo | docs/01-modulos/SAAS-001-auth.md |
| S2-F1-02 | Leer SAAS-002-tenants.md completo | docs/01-modulos/SAAS-002-tenants.md |
| S2-F1-03 | Leer SAAS-003-users.md completo | docs/01-modulos/SAAS-003-users.md |
| S2-F1-04 | Verificar referencia a RBAC (puede estar en users o separado) | RBAC documentation |

#### FASE 2.2 - Analisis Detallado
| Tarea | Validar Contra |
|-------|----------------|
| S2-F2-01 | Validar endpoints auth documentados vs auth.controller.ts | apps/backend/src/modules/auth/ |
| S2-F2-02 | Validar tablas auth documentadas vs DDL | apps/database/ddl/schemas/auth/ |
| S2-F2-03 | Validar endpoints tenants vs tenants.controller.ts | apps/backend/src/modules/tenants/ |
| S2-F2-04 | Validar tablas tenants vs DDL | apps/database/ddl/schemas/tenants/ |
| S2-F2-05 | Validar endpoints users vs users.controller.ts | apps/backend/src/modules/users/ |
| S2-F2-06 | Validar tablas users vs DDL | apps/database/ddl/schemas/users/ |

---

### SEGMENTO 3: Modulos Billing

#### FASE 3.1 - Analisis y Planeacion
| Tarea | Descripcion | Archivos |
|-------|-------------|----------|
| S3-F1-01 | Leer SAAS-004-billing.md completo | docs/01-modulos/SAAS-004-billing.md |
| S3-F1-02 | Leer SAAS-005-plans.md completo | docs/01-modulos/SAAS-005-plans.md |

#### FASE 3.2 - Analisis Detallado
| Tarea | Validar Contra |
|-------|----------------|
| S3-F2-01 | Validar integracion Stripe documentada vs implementada | apps/backend/src/modules/billing/ |
| S3-F2-02 | Validar tablas billing (6 tablas) vs DDL | apps/database/ddl/schemas/billing/ |
| S3-F2-03 | Validar tablas plans vs DDL | apps/database/ddl/schemas/plans/ |
| S3-F2-04 | Verificar si payment_methods esta documentado | billing DDL vs docs |

---

### SEGMENTO 4: Modulos Experiencia

#### FASE 4.1 - Analisis y Planeacion
| Tarea | Descripcion | Prioridad |
|-------|-------------|-----------|
| S4-F1-01 | RESOLVER: SAAS-006 es Onboarding o AI Integration? | CRITICO |
| S4-F1-02 | RESOLVER: SAAS-008 es Audit Logs o Feature Flags? | CRITICO |
| S4-F1-03 | RESOLVER: SAAS-009 es Feature Flags o Audit? | CRITICO |
| S4-F1-04 | Leer SAAS-007-notifications.md | Alto |
| S4-F1-05 | Leer ET-SAAS-007-notifications-v2.md | Alto |

#### Conflicto de Numeracion a Resolver

**Segun docs/01-modulos/ (archivos reales):**
- SAAS-006-ai-integration.md
- SAAS-007-notifications.md
- SAAS-008-audit-logs.md
- SAAS-009-feature-flags.md

**Segun _MAP.md y CONTEXT-MAP.yml:**
- SAAS-006: Onboarding
- SAAS-007: Notifications
- SAAS-008: Feature Flags
- SAAS-009: Audit
- SAAS-010: AI Integration

**DECISION REQUERIDA**: Cual nomenclatura es la correcta?

---

### SEGMENTO 5: Modulos Avanzados

#### FASE 5.1 - Analisis
| Tarea | Descripcion | Estado Doc |
|-------|-------------|------------|
| S5-F1-01 | Leer documentacion AI Integration | Existe |
| S5-F1-02 | Leer SAAS-011-storage.md | Existe |
| S5-F1-03 | Leer SAAS-010-webhooks.md | Existe |
| S5-F1-04 | Leer SAAS-013-email.md | Existe |
| S5-F1-05 | Verificar documentacion WhatsApp | NO EXISTE |

#### FASE 5.2 - Acciones Requeridas
| Tarea | Accion |
|-------|--------|
| S5-F2-01 | Crear documentacion para WhatsApp Business API (Sprint 5) |
| S5-F2-02 | Validar que webhooks.md refleje BullMQ integration |
| S5-F2-03 | Validar que storage.md refleje S3/R2/MinIO providers |

---

### SEGMENTO 6: Integraciones

#### FASE 6.1 - Analisis
| Integracion | Estado _MAP.md | Estado Real | Accion |
|-------------|----------------|-------------|--------|
| INT-001-STRIPE | Listado | Carpeta vacia | Crear o eliminar |
| INT-002-OAUTH | Listado | No existe | Crear o eliminar |
| INT-003-EMAIL | Listado (pendiente) | No existe | Ya cubierto en SAAS-013 |
| INT-004-PUSH | Listado (pendiente) | No existe | Ya cubierto en Notifications v2 |
| INT-005-STORAGE | Listado | No existe | Ya cubierto en SAAS-011 |
| INT-006-WEBHOOKS | Mencionado | No existe | Ya cubierto en SAAS-010 |
| INT-007-REDIS | Mencionado | No existe | Evaluar necesidad |

**DECISION REQUERIDA**: Mantener estructura INT-XXX separada o consolidar en modulos SAAS-XXX?

---

### SEGMENTO 7: Portales

#### FASE 7.1 - Analisis
| Tarea | Descripcion |
|-------|-------------|
| S7-F1-01 | Verificar si existe SAAS-011-portal-user.md o SAAS-012-portal-admin.md |
| S7-F1-02 | Documentar estructura de portales vs frontend/src/portals/ |
| S7-F1-03 | Validar rutas documentadas vs router configuration |

---

### SEGMENTO 8: Documentacion Operacional (orchestration/)

#### FASE 8.1 - Analisis
| Archivo | Proposito | Estado |
|---------|-----------|--------|
| PROJECT-STATUS.md | Estado actual | Actualizado 2026-01-10 |
| CONTEXT-MAP.yml | Aliases y navegacion | Tiene discrepancias con realidad |
| PROXIMA-ACCION.md | Siguiente paso | Verificar vigencia |
| inventarios/*.yml | Estado artefactos | Validar vs codigo |
| planes/PLAN-SPRINT-*.md | Historico sprints | Consolidar en historico resumido |
| trazas/TRAZA-*.md | Trazas ejecucion | Evaluar que mantener |
| analisis/*.md | Analisis previos | Archivar o eliminar |

#### FASE 8.2 - Acciones de Consolidacion
| Tarea | Accion |
|-------|--------|
| S8-F2-01 | Crear HISTORICO-SPRINTS-RESUMIDO.md con lo esencial de cada sprint |
| S8-F2-02 | Archivar planes individuales en carpeta _historico/ |
| S8-F2-03 | Actualizar CONTEXT-MAP.yml con numeracion correcta |
| S8-F2-04 | Validar inventarios contra codigo fuente |

---

## MATRIZ DE DEPENDENCIAS

```
┌─────────────────┬─────────────────────────────────────────────────────────┐
│ Documento       │ Depende De / Afecta A                                   │
├─────────────────┼─────────────────────────────────────────────────────────┤
│ _MAP.md         │ TODOS los documentos - ACTUALIZAR AL FINAL              │
│ CONTEXT-MAP.yml │ _MAP.md, modulos SAAS-XXX                               │
│ PROJECT-STATUS  │ Inventarios, Planes, Estado modulos                     │
│ SAAS-001-auth   │ DDL auth/, backend/auth/, RBAC, Tenants                 │
│ SAAS-002-tenants│ DDL tenants/, Users, Billing                            │
│ SAAS-003-users  │ Auth, RBAC, Tenants, Invitations                        │
│ SAAS-004-billing│ Plans, Stripe, Tenants                                  │
│ SAAS-007-notif  │ Email, Push, WebSocket, WhatsApp                        │
│ ADR-001 a 005   │ Vision, Arquitectura, Modulos relacionados              │
│ Inventarios     │ DDL, Backend modules, Frontend components               │
└─────────────────┴─────────────────────────────────────────────────────────┘
```

---

## HISTORICO RESUMIDO PROPUESTO

El historico consolidado debe contener SOLO:

1. **Resumen de cada Sprint** (maximo 5 lineas por sprint)
   - Objetivo
   - Entregables principales
   - Metricas clave
   - Fecha de completitud

2. **Linea de tiempo visual**
```
Sprint 1 (Tests) ─── Sprint 2 (Onboarding) ─── Sprint 3 (E2E) ─── Sprint 4 (ADRs) ─── Sprint 5 (WhatsApp)
     │                      │                       │                   │                    │
   776 tests            Wizard BE              47 E2E tests        5 ADRs            WhatsApp API
   76% cov              4 endpoints            Playwright          Decisions          22 tests
```

3. **Decisiones arquitectonicas** (solo referencias a ADRs)

4. **Lecciones aprendidas** (maximo 10 items globales)

---

## CRITERIOS DE VALIDACION

### Para cada archivo modificado:

1. **Contenido Actualizado**: Refleja estado actual del codigo
2. **Referencias Validas**: Todos los links y referencias funcionan
3. **Sin Duplicados**: No hay definiciones repetidas
4. **Nomenclatura Consistente**: Usa misma convencion en todo el proyecto
5. **Fechas Actualizadas**: Ultima actualizacion refleja realidad

### Para el proyecto completo:

1. **Cobertura Documental**: Todo modulo implementado tiene documentacion
2. **Trazabilidad**: Se puede navegar de doc a codigo y viceversa
3. **Historico Limpio**: Solo informacion relevante y resumida
4. **Indice Actualizado**: _MAP.md refleja estructura real

---

## SIGUIENTE PASO

Proceder con **FASE 1** para cada segmento, comenzando por **Segmento 1 (Vision y Arquitectura)** para establecer la base correcta antes de validar modulos individuales.

---

**Estado**: PENDIENTE APROBACION
**Fecha creacion**: 2026-01-10
**Version**: 1.0.0