rckrdmrd/template-saas
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
50a821a415
template-saas/orchestration/analisis/PLAN-MAESTRO-PURGA-DOCUMENTAL-2026-01-10.md
rckrdmrd 50a821a415
Some checks failed
CI / Backend CI (push) Has been cancelled
Details
CI / Frontend CI (push) Has been cancelled
Details
CI / Security Scan (push) Has been cancelled
Details
CI / CI Summary (push) Has been cancelled
Details
[SIMCO-V38] feat: Actualizar a SIMCO v3.8.0 
- HERENCIA-SIMCO.md actualizado con directivas v3.7 y v3.8
- Actualizaciones de configuracion

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
2026-01-10 08:53:08 -06:00

20 KiB
Raw Blame History

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
S2-F2-02 Validar tablas auth documentadas vs DDL
S2-F2-03 Validar endpoints tenants vs tenants.controller.ts
S2-F2-04 Validar tablas tenants vs DDL
S2-F2-05 Validar endpoints users vs users.controller.ts
S2-F2-06 Validar tablas users vs DDL

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
S3-F2-02 Validar tablas billing (6 tablas) vs DDL
S3-F2-03 Validar tablas plans vs DDL
S3-F2-04 Verificar si payment_methods esta documentado

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

  1. Decisiones arquitectonicas (solo referencias a ADRs)

  2. 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