# FASE 3: PLAN DE EJECUCION - DOCUMENTACION TEMPLATE-SAAS

**Fecha:** 2026-01-10
**Proyecto:** template-saas
**Estado:** COMPLETADO
**Perfil:** ORQUESTADOR (TECH-LEADER)
**Referencia:** FASE-2-ANALISIS-DETALLADO-DOCUMENTACION-2026-01-10.md

---

## 1. RESUMEN DEL PLAN

### 1.1 Objetivo

Implementar los 52 cambios documentales identificados para elevar la documentacion del proyecto a cumplimiento total con SIMCO v3.7+.

### 1.2 Alcance

| Categoria | Archivos | Tipo de Cambio | Prioridad |
|-----------|----------|----------------|-----------|
| Frontmatter YAML | 26 | Modificar | P0 |
| Contenido INT | 7 | Modificar | P0 |
| ET Specs | 13 | Crear | P1 |
| ADRs | 6 | Crear | P1 |
| **TOTAL** | **52** | - | - |

---

## 2. ESTRUCTURA DE WAVES

### WAVE 1: FRONTMATTER YAML (26 archivos)

**Objetivo:** Agregar frontmatter YAML a todos los archivos de documentacion que carecen de el.

**Prioridad:** P0 - Prerequisito para otras waves

#### Subwave 1.1: docs/00-vision-general/ (4 archivos)

| # | Archivo | Cambio |
|---|---------|--------|
| 1.1.1 | README.md | Agregar frontmatter VIS-001 |
| 1.1.2 | VISION-TEMPLATE-SAAS.md | Agregar frontmatter VIS-002 |
| 1.1.3 | ESPECIFICACION-PLATAFORMA-SAAS.md | Agregar frontmatter VIS-003 |
| 1.1.4 | ARQUITECTURA-MULTI-TENANT.md | Agregar frontmatter VIS-004 |

#### Subwave 1.2: docs/02-especificaciones/ (2 archivos)

| # | Archivo | Cambio |
|---|---------|--------|
| 1.2.1 | ET-SAAS-007-notifications-v2.md | Agregar frontmatter ET-SAAS-007 |
| 1.2.2 | PLAN-IMPLEMENTACION-NOTIFICATIONS-V2.md | Agregar frontmatter PLAN-SAAS-007 |

#### Subwave 1.3: docs/02-integraciones/ (7 archivos)

| # | Archivo | Cambio |
|---|---------|--------|
| 1.3.1 | INT-001-stripe.md | Agregar frontmatter INT-001 |
| 1.3.2 | INT-002-oauth.md | Agregar frontmatter INT-002 |
| 1.3.3 | INT-003-email.md | Agregar frontmatter INT-003 |
| 1.3.4 | INT-004-push.md | Agregar frontmatter INT-004 |
| 1.3.5 | INT-005-storage.md | Agregar frontmatter INT-005 |
| 1.3.6 | INT-006-webhooks.md | Agregar frontmatter INT-006 |
| 1.3.7 | INT-007-redis.md | Agregar frontmatter INT-007 |

#### Subwave 1.4: docs/02-devops/ (2 archivos)

| # | Archivo | Cambio |
|---|---------|--------|
| 1.4.1 | CICD-GUIDE.md | Agregar frontmatter DEVOPS-001 |
| 1.4.2 | _MAP.md | Agregar frontmatter MAP-DEVOPS |

#### Subwave 1.5: docs/architecture/adr/ (6 archivos)

| # | Archivo | Cambio |
|---|---------|--------|
| 1.5.1 | ADR-001-multi-tenancy-rls.md | Agregar frontmatter ADR-001 |
| 1.5.2 | ADR-002-authentication-jwt-oauth.md | Agregar frontmatter ADR-002 |
| 1.5.3 | ADR-003-billing-stripe.md | Agregar frontmatter ADR-003 |
| 1.5.4 | ADR-004-notifications-realtime.md | Agregar frontmatter ADR-004 |
| 1.5.5 | ADR-005-feature-flags.md | Agregar frontmatter ADR-005 |
| 1.5.6 | _INDEX.md | Agregar frontmatter INDEX-ADR |

#### Subwave 1.6: docs/ raiz (2 archivos)

| # | Archivo | Cambio |
|---|---------|--------|
| 1.6.1 | README.md | Agregar frontmatter DOCS-ROOT |
| 1.6.2 | _MAP.md | Agregar frontmatter MAP-DOCS |

#### Checkpoint Wave 1

- [ ] Verificar 26 archivos tienen frontmatter
- [ ] Verificar IDs unicos
- [ ] Verificar formato YAML valido

---

### WAVE 2: CONTENIDO INTEGRACIONES (7 archivos)

**Objetivo:** Agregar secciones faltantes (Endpoints/SDK, Fallbacks, etc.) a cada integracion.

**Prioridad:** P0 - Critico para cumplimiento SIMCO

#### Tarea 2.1: INT-001-stripe.md

| Seccion | Contenido |
|---------|-----------|
| Endpoints/SDK | Tabla 17 endpoints Stripe |
| Fallbacks | Estrategia timeout, webhook, dunning |
| Credenciales | Tabla 4 variables entorno |

#### Tarea 2.2: INT-002-oauth.md

| Seccion | Contenido |
|---------|-----------|
| Fallbacks | Degradacion graceful entre providers |

#### Tarea 2.3: INT-004-push.md

| Seccion | Contenido |
|---------|-----------|
| Fallbacks | Retry, token expirado, fallback email |

#### Tarea 2.4: INT-005-storage.md

| Seccion | Contenido |
|---------|-----------|
| Fallbacks | Failover S3->R2->MinIO |

#### Tarea 2.5: INT-006-webhooks.md

| Seccion | Contenido |
|---------|-----------|
| DLQ | Estrategia retry exponencial, dead letter |

#### Tarea 2.6: INT-007-redis.md

| Seccion | Contenido |
|---------|-----------|
| Endpoints/SDK | Tabla 18 comandos Redis |
| Fallbacks | Memory cache, Sentinel failover |

#### Checkpoint Wave 2

- [ ] Verificar todas INT tienen Rate Limits
- [ ] Verificar todas INT tienen Fallbacks
- [ ] Verificar todas INT tienen Multi-tenant
- [ ] Verificar todas INT tienen Testing
- [ ] Verificar todas INT tienen Monitoreo

---

### WAVE 3: ESPECIFICACIONES TECNICAS (13 archivos)

**Objetivo:** Crear 13 documentos ET-SAAS-* con estructura SIMCO completa.

**Prioridad:** P1 - Importante para cobertura documental

#### Tarea 3.1: ET-SAAS-001-authentication.md

| Seccion | Contenido Clave |
|---------|-----------------|
| Arquitectura | Flujo JWT, refresh tokens |
| Modelo de Datos | auth.sessions, auth.tokens |
| Endpoints | /auth/login, /auth/logout, /auth/refresh |
| Seguridad | Token rotation, blacklist |

#### Tarea 3.2: ET-SAAS-002-multi-tenancy.md

| Seccion | Contenido Clave |
|---------|-----------------|
| Arquitectura | RLS policies, tenant context |
| Modelo de Datos | tenants.*, RLS functions |
| Endpoints | /tenants/*, /settings/* |
| Seguridad | Tenant isolation |

#### Tarea 3.3: ET-SAAS-003-users-rbac.md

| Seccion | Contenido Clave |
|---------|-----------------|
| Arquitectura | RBAC model, permission system |
| Modelo de Datos | users.*, rbac.* |
| Endpoints | /users/*, /roles/*, /permissions/* |
| Seguridad | Role hierarchy |

#### Tarea 3.4: ET-SAAS-004-billing.md

| Seccion | Contenido Clave |
|---------|-----------------|
| Arquitectura | Stripe integration flow |
| Modelo de Datos | billing.* |
| Endpoints | /billing/*, /subscriptions/* |
| Seguridad | PCI compliance |

#### Tarea 3.5: ET-SAAS-005-plans.md

| Seccion | Contenido Clave |
|---------|-----------------|
| Arquitectura | Plan limits, quotas |
| Modelo de Datos | plans.* |
| Endpoints | /plans/* |
| Seguridad | Quota enforcement |

#### Tarea 3.6: ET-SAAS-006-ai-integration.md

| Seccion | Contenido Clave |
|---------|-----------------|
| Arquitectura | Multi-provider wrapper |
| Modelo de Datos | ai.* |
| Endpoints | /ai/* |
| Seguridad | Token counting, rate limiting |

#### Tarea 3.7: ET-SAAS-008-audit-logs.md

| Seccion | Contenido Clave |
|---------|-----------------|
| Arquitectura | Event sourcing, retention |
| Modelo de Datos | audit.* |
| Endpoints | /audit/* |
| Seguridad | Immutability |

#### Tarea 3.8: ET-SAAS-009-feature-flags.md

| Seccion | Contenido Clave |
|---------|-----------------|
| Arquitectura | Flag evaluation, targeting |
| Modelo de Datos | feature_flags.* |
| Endpoints | /feature-flags/* |
| Seguridad | Per-tenant overrides |

#### Tarea 3.9: ET-SAAS-010-webhooks.md

| Seccion | Contenido Clave |
|---------|-----------------|
| Arquitectura | BullMQ, retry strategy |
| Modelo de Datos | webhooks.* |
| Endpoints | /webhooks/* |
| Seguridad | Signature verification |

#### Tarea 3.10: ET-SAAS-011-storage.md

| Seccion | Contenido Clave |
|---------|-----------------|
| Arquitectura | S3 abstraction, multi-provider |
| Modelo de Datos | storage.* |
| Endpoints | /storage/* |
| Seguridad | Pre-signed URLs |

#### Tarea 3.11: ET-SAAS-012-crud-base.md

| Seccion | Contenido Clave |
|---------|-----------------|
| Arquitectura | Generic CRUD patterns |
| Modelo de Datos | Base entity |
| Endpoints | Pattern documentation |
| Seguridad | Base validations |

#### Tarea 3.12: ET-SAAS-013-email.md

| Seccion | Contenido Clave |
|---------|-----------------|
| Arquitectura | Multi-provider, templates |
| Modelo de Datos | notifications.email_* |
| Endpoints | /email/* |
| Seguridad | Bounce handling |

#### Tarea 3.13: ET-SAAS-014-whatsapp.md

| Seccion | Contenido Clave |
|---------|-----------------|
| Arquitectura | Meta Cloud API |
| Modelo de Datos | whatsapp.* |
| Endpoints | /whatsapp/* |
| Seguridad | Webhook verification |

#### Checkpoint Wave 3

- [ ] 13 archivos ET creados en docs/02-especificaciones/
- [ ] Todos tienen frontmatter YAML
- [ ] Todos tienen 8 secciones requeridas
- [ ] Referencias cruzadas validas

---

### WAVE 4: ADRs NUEVOS (6 archivos)

**Objetivo:** Crear 6 ADRs para decisiones arquitectonicas pendientes de formalizar.

**Prioridad:** P1 - Importante para trazabilidad arquitectonica

#### Tarea 4.1: ADR-006-ai-integration-multi-provider.md

| Seccion | Contenido |
|---------|-----------|
| Contexto | Necesidad multi-proveedor IA |
| Decision | OpenRouter como gateway |
| Alternativas | APIs directas, LangChain |
| Consecuencias | Latencia +50ms, costo +2-5% |

#### Tarea 4.2: ADR-007-storage-abstraction-layer.md

| Seccion | Contenido |
|---------|-----------|
| Contexto | Multi-storage requirement |
| Decision | AWS SDK v3 S3-compatible |
| Alternativas | Solo AWS, MinIO client |
| Consecuencias | Limitado a protocolo S3 |

#### Tarea 4.3: ADR-008-webhook-retry-strategy.md

| Seccion | Contenido |
|---------|-----------|
| Contexto | Webhooks pueden fallar |
| Decision | BullMQ + exponential backoff |
| Alternativas | Retry inmediato, lineal |
| Consecuencias | Delay max 1 hora |

#### Tarea 4.4: ADR-009-whatsapp-business-integration.md

| Seccion | Contenido |
|---------|-----------|
| Contexto | Integracion WhatsApp Business |
| Decision | Meta Cloud API directa |
| Alternativas | Twilio, MessageBird |
| Consecuencias | Setup complejo, 40% ahorro |

#### Tarea 4.5: ADR-010-audit-log-retention-policy.md

| Seccion | Contenido |
|---------|-----------|
| Contexto | Retencion de audit logs |
| Decision | Tiered Hot/Warm/Cold |
| Alternativas | Todo DB, solo archivos |
| Consecuencias | Queries lentas para logs antiguos |

#### Tarea 4.6: ADR-011-rate-limiting-strategy.md

| Seccion | Contenido |
|---------|-----------|
| Contexto | Proteccion API contra abuso |
| Decision | Token Bucket con Redis |
| Alternativas | Fixed window, sliding window |
| Consecuencias | Dependencia Redis |

#### Checkpoint Wave 4

- [ ] 6 archivos ADR creados en docs/architecture/adr/
- [ ] Todos tienen frontmatter YAML
- [ ] Todos tienen tabla metadata
- [ ] Todos tienen footer con fecha y autor
- [ ] _INDEX.md actualizado con nuevos ADRs

---

## 3. CRONOGRAMA DE EJECUCION

| Wave | Archivos | Orden | Dependencias |
|------|----------|-------|--------------|
| Wave 1 | 26 | 1ro | Ninguna |
| Wave 2 | 7 | 2do | Wave 1 (frontmatter en INT) |
| Wave 3 | 13 | 3ro | Wave 1, Wave 2 (referencias) |
| Wave 4 | 6 | 4to | Wave 1 (formato ADR) |

---

## 4. VALIDACIONES POST-EJECUCION

### 4.1 Checklist Global

#### Estructura
- [ ] Todos los archivos tienen frontmatter YAML
- [ ] IDs son unicos en todo el proyecto
- [ ] Fechas actualizadas a 2026-01-10

#### Contenido
- [ ] Integraciones tienen todas las secciones SIMCO
- [ ] ETs tienen las 8 secciones requeridas
- [ ] ADRs tienen tabla metadata y footer

#### Referencias
- [ ] Links internos validos
- [ ] Referencias a modulos correctas
- [ ] _INDEX.md y _MAP.md actualizados

### 4.2 Metricas Objetivo

| Metrica | Antes | Objetivo |
|---------|-------|----------|
| Archivos con frontmatter | 14 | 40 |
| Integraciones completas | 0 | 7 |
| ET Specs | 1 | 14 |
| ADRs | 5 | 11 |
| Cobertura SIMCO | ~80% | 100% |

---

## 5. RIESGOS Y MITIGACIONES

| Riesgo | Probabilidad | Impacto | Mitigacion |
|--------|--------------|---------|------------|
| Links rotos por nuevos archivos | Media | Medio | Validar post-creacion |
| IDs duplicados | Baja | Alto | Verificar antes de commit |
| Contenido incompleto en ET | Media | Medio | Template estandarizado |
| Inconsistencia de fechas | Baja | Bajo | Script de actualizacion |

---

## 6. PERFILES RECOMENDADOS

| Wave | Perfil Principal | Perfil Validador |
|------|------------------|------------------|
| Wave 1 | DOCUMENTATION-MAINTAINER | DOCUMENTATION-VALIDATOR |
| Wave 2 | INTEGRATION-VALIDATOR | DOCUMENTATION-VALIDATOR |
| Wave 3 | REQUIREMENTS-ANALYST | DOCUMENTATION-VALIDATOR |
| Wave 4 | ARCHITECTURE-ANALYST | DOCUMENTATION-VALIDATOR |

---

## 7. ENTREGABLES

### Por Wave

| Wave | Entregable | Formato |
|------|------------|---------|
| Wave 1 | 26 archivos modificados | MD con frontmatter YAML |
| Wave 2 | 7 archivos expandidos | MD con secciones nuevas |
| Wave 3 | 13 archivos creados | MD estructura ET |
| Wave 4 | 6 archivos creados | MD estructura ADR |

### Consolidado

- FASE-4: Documento de validacion plan vs analisis
- FASE-5: Plan refinado si hay ajustes
- FASE-6: Reporte de ejecucion
- FASE-7: Validacion final

---

## 8. RESUMEN

Este plan define la ejecucion de 52 cambios documentales en 4 waves priorizadas, con checkpoints de validacion entre cada wave.

**Objetivo:** Cobertura SIMCO 100% en documentacion de template-saas.

---

**Creado:** 2026-01-10
**Autor:** Claude Code (ORQUESTADOR)
**Sistema:** SIMCO v3.7
**Siguiente Fase:** FASE 4 - Validacion del Plan vs Analisis