template-saas/orchestration/_archive/analisis-previo/FASE-5-PLAN-REFINADO-EJECUCION-2026-01-10.md

# FASE 5: Plan Refinado de Ejecucion

**Fecha:** 2026-01-10
**Estado:** APROBADO PARA EJECUCION
**Objetivo:** Plan consolidado y optimizado para ejecucion

---

## 1. Resumen del Plan Refinado

### 1.1 Metricas de Ejecucion

| Metrica | Valor |
|---------|-------|
| Total de archivos a modificar | 12 |
| Total de correcciones | 19 |
| Grupos de ejecucion | 6 |
| Tiempo estimado total | 3h 30min (optimizado) |

### 1.2 Archivos por Orden de Ejecucion

| Orden | Archivo | Correcciones Agrupadas |
|-------|---------|------------------------|
| 1 | SAAS-008-audit-logs.md | CRIT-007, ALTO-006 |
| 2 | SAAS-009-feature-flags.md | CRIT-007 |
| 3 | SAAS-012-crud-base.md | CRIT-003 |
| 4 | SAAS-002-tenants.md | ALTO-003 |
| 5 | SAAS-006-ai-integration.md | ALTO-007 |
| 6 | SAAS-003-users.md | MEDIO-004 |
| 7 | SAAS-001-auth.md | CRIT-004, CRIT-005, ALTO-002, MEDIO-001, MEDIO-002 |
| 8 | SAAS-004-billing.md | CRIT-002, ALTO-001, ALTO-005, MEDIO-003 |
| 9 | SAAS-007-notifications.md | ALTO-004 |
| 10 | MASTER_INVENTORY.yml | CRIT-001, CRIT-006, MEDIO-005 |
| 11 | DATABASE_INVENTORY.yml | CRIT-001, MEDIO-005 |
| 12 | Otros (PROJECT-STATUS, _MAP, CONTEXT-MAP) | CRIT-001, CRIT-006 |

---

## 2. Instrucciones Detalladas por Archivo

### EJECUCION-001: SAAS-008-audit-logs.md

**Ubicacion:** `docs/01-modulos/SAAS-008-audit-logs.md`

**Cambios a realizar:**

1. **Metadata - Cambiar estado:**
```markdown
# ANTES:
| Estado | Pendiente |

# DESPUES:
| Estado | Completado |
```

2. **Agregar nota sobre export (si existe endpoint documentado):**
```markdown
## Endpoints

### GET /audit/export
**Estado:** Pendiente de implementacion
**Descripcion:** Exportar logs en formato CSV o JSON
```

**Validacion:**
```bash
grep -E "Estado.*Completado" docs/01-modulos/SAAS-008-audit-logs.md
```

---

### EJECUCION-002: SAAS-009-feature-flags.md

**Ubicacion:** `docs/01-modulos/SAAS-009-feature-flags.md`

**Cambios a realizar:**

1. **Metadata - Cambiar estado:**
```markdown
# ANTES:
| Estado | Pendiente |

# DESPUES:
| Estado | Completado |
```

**Validacion:**
```bash
grep -E "Estado.*Completado" docs/01-modulos/SAAS-009-feature-flags.md
```

---

### EJECUCION-003: SAAS-012-crud-base.md

**Ubicacion:** `docs/01-modulos/SAAS-012-crud-base.md`

**Accion:** Reescribir completamente

**Nuevo contenido:**
```markdown
# SAAS-012: Patrones Base CRUD

## Metadata

| Campo | Valor |
|-------|-------|
| Codigo | SAAS-012 |
| Modulo | crud-base |
| Prioridad | P2 |
| Estado | Documentacion |
| Tipo | Guia de Patrones |
| Ultima Actualizacion | 2026-01-10 |

---

## Descripcion

Este documento describe los patrones CRUD utilizados en el proyecto template-saas.
Actualmente cada modulo implementa su propia logica CRUD de forma independiente,
siguiendo convenciones comunes.

---

## Patron Arquitectonico Actual

### Estructura por Modulo

Cada modulo backend contiene:

```
modules/[nombre]/
├── [nombre].controller.ts   # Endpoints REST
├── [nombre].module.ts       # Configuracion NestJS
├── [nombre].service.ts      # Logica de negocio
├── dto/
│   ├── create-[nombre].dto.ts
│   ├── update-[nombre].dto.ts
│   └── [nombre]-response.dto.ts
├── entities/
│   └── [nombre].entity.ts   # Entidad TypeORM
└── __tests__/
    └── [nombre].service.spec.ts
```

### Campos Base Comunes

Todas las entidades incluyen estos campos base:

| Campo | Tipo | Descripcion |
|-------|------|-------------|
| id | UUID | Primary key, auto-generado |
| tenant_id | UUID | Foreign key a tenants (RLS) |
| created_at | TIMESTAMP | Fecha de creacion |
| updated_at | TIMESTAMP | Fecha ultima modificacion |
| deleted_at | TIMESTAMP | Soft delete (nullable) |
| created_by | UUID | Usuario que creo (opcional) |
| updated_by | UUID | Usuario que modifico (opcional) |

### Patron de Paginacion

Todos los endpoints de listado soportan:

```typescript
interface PaginationQuery {
  page?: number;      // default: 1
  limit?: number;     // default: 10, max: 100
  sort?: string;      // campo a ordenar
  order?: 'ASC' | 'DESC';  // default: 'DESC'
}

interface PaginatedResponse<T> {
  data: T[];
  meta: {
    page: number;
    limit: number;
    total: number;
    totalPages: number;
  };
}
```

### Patron de Filtros

```typescript
interface FilterQuery {
  search?: string;    // busqueda full-text
  status?: string;    // filtro por estado
  from?: string;      // fecha inicio (ISO)
  to?: string;        // fecha fin (ISO)
}
```

---

## Endpoints REST Estandar

Cada modulo CRUD expone:

| Metodo | Ruta | Descripcion |
|--------|------|-------------|
| GET | /[recurso] | Listar con paginacion |
| GET | /[recurso]/:id | Obtener por ID |
| POST | /[recurso] | Crear nuevo |
| PATCH | /[recurso]/:id | Actualizar parcial |
| DELETE | /[recurso]/:id | Eliminar (soft delete) |

---

## Roadmap: Clases Base

### Implementacion Futura Planificada

Se planea implementar clases base reutilizables:

1. **BaseEntity** - Campos comunes (id, timestamps, tenant_id)
2. **BaseCrudService<T>** - Operaciones CRUD genericas
3. **BaseCrudController<T>** - Endpoints REST estandar
4. **BaseDto** - Validaciones comunes

**Estado:** Pendiente de implementacion
**Prioridad:** Baja (cada modulo funciona correctamente de forma independiente)

---

## Referencias

- Ver implementaciones en: `apps/backend/src/modules/*/`
- Ejemplo recomendado: `modules/storage/` (patron mas limpio)
```

**Validacion:**
```bash
grep "Estado.*Documentacion" docs/01-modulos/SAAS-012-crud-base.md
```

---

### EJECUCION-004: SAAS-002-tenants.md

**Ubicacion:** `docs/01-modulos/SAAS-002-tenants.md`

**Cambios a realizar:**

Agregar seccion sobre Settings:

```markdown
## Configuraciones de Tenant

Las configuraciones de cada tenant se almacenan en el campo `settings` (JSONB)
de la tabla `tenants.tenants`.

### Acceso via API

Las configuraciones se obtienen y actualizan junto con el tenant:

| Metodo | Ruta | Descripcion |
|--------|------|-------------|
| GET | /tenants/current | Obtiene tenant actual (incluye settings) |
| PATCH | /tenants/current | Actualiza tenant (puede incluir settings) |

### Estructura del Campo Settings

```json
{
  "branding": {
    "logo_url": "https://...",
    "primary_color": "#3B82F6",
    "company_name": "Mi Empresa"
  },
  "notifications": {
    "email_enabled": true,
    "push_enabled": false,
    "digest_frequency": "daily"
  },
  "features": {
    "ai_enabled": true,
    "whatsapp_enabled": false
  }
}
```

### Nota sobre Endpoints Dedicados

Los endpoints dedicados `/tenants/current/settings` estan planificados pero
no implementados actualmente. Usar PATCH `/tenants/current` para actualizar settings.
```

**Validacion:**
```bash
grep "settings.*JSONB" docs/01-modulos/SAAS-002-tenants.md
```

---

### EJECUCION-005: SAAS-006-ai-integration.md

**Ubicacion:** `docs/01-modulos/SAAS-006-ai-integration.md`

**Cambios a realizar:**

Agregar campos adicionales en tabla ai.usage:

```markdown
## Tabla: ai.usage

| Campo | Tipo | Descripcion |
|-------|------|-------------|
| id | UUID | Identificador unico |
| tenant_id | UUID | Tenant propietario |
| config_id | UUID | Configuracion usada |
| model | VARCHAR | Modelo utilizado |
| model_type | ai_model_type | chat, completion, embedding, image |
| request_id | VARCHAR | ID unico de request |
| endpoint | VARCHAR | Endpoint llamado |
| input_tokens | INTEGER | Tokens de entrada |
| output_tokens | INTEGER | Tokens de salida |
| cost | DECIMAL | Costo estimado |
| latency_ms | INTEGER | Latencia en ms |
| status | usage_status | pending, completed, failed, cancelled |
| error_message | TEXT | Mensaje de error (si fallo) |
| metadata | JSONB | Metadata adicional |
| created_at | TIMESTAMP | Fecha de uso |
```

**Validacion:**
```bash
grep "model_type" docs/01-modulos/SAAS-006-ai-integration.md
```

---

### EJECUCION-006: SAAS-003-users.md

**Ubicacion:** `docs/01-modulos/SAAS-003-users.md`

**Cambios a realizar:**

Actualizar seccion de roles para reflejar modelo flexible:

```markdown
## Sistema de Roles (RBAC)

### Modelo de Datos

El sistema usa un modelo flexible de roles basado en tablas:

- `users.roles` - Definicion de roles (custom por tenant)
- `users.user_roles` - Asignacion usuario-rol (many-to-many)
- `users.permissions` - Permisos disponibles
- `users.role_permissions` - Permisos por rol

### Roles Sugeridos

Aunque los roles son flexibles, se recomienda crear:

| Rol | Descripcion | Permisos Tipicos |
|-----|-------------|------------------|
| owner | Propietario del tenant | Todos |
| admin | Administrador | Gestion usuarios, billing, settings |
| member | Miembro estandar | Lectura, escritura propia |
| viewer | Solo lectura | Lectura |

### Nota

Los roles NO son un enum fijo. Cada tenant puede definir sus propios roles
con permisos personalizados.
```

**Validacion:**
```bash
grep "modelo flexible" docs/01-modulos/SAAS-003-users.md
```

---

### EJECUCION-007: SAAS-001-auth.md

**Ubicacion:** `docs/01-modulos/SAAS-001-auth.md`

**Cambios a realizar (multiples):**

1. **Metadata - verificar estado Completado**

2. **Mover OAuth a Roadmap:**
```markdown
## Roadmap

### OAuth 2.0 (Planificado)

Autenticacion con proveedores externos:

| Proveedor | Estado |
|-----------|--------|
| Google | Planificado |
| Microsoft | Planificado |
| GitHub | Planificado |
| Apple | Planificado |

**Endpoints planificados:**
- POST /auth/oauth/:provider - Iniciar flujo OAuth
- GET /auth/oauth/:provider/callback - Callback OAuth

### MFA - Multi-Factor Authentication (Planificado)

Autenticacion de dos factores via TOTP:

**Endpoints planificados:**
- POST /auth/mfa/setup - Configurar MFA
- POST /auth/mfa/verify - Verificar codigo
- DELETE /auth/mfa - Desactivar MFA

### Session Management (Planificado)

Gestion de sesiones activas:

**Endpoints planificados:**
- GET /auth/sessions - Listar sesiones activas
- DELETE /auth/sessions/:id - Revocar sesion especifica
```

3. **En seccion Endpoints, mantener solo los implementados:**
- POST /auth/register
- POST /auth/login
- POST /auth/logout
- POST /auth/logout-all
- POST /auth/refresh
- POST /auth/password/forgot
- POST /auth/password/reset
- POST /auth/verify-email
- GET /auth/me

4. **Agregar nota en User Entity:**
```markdown
## Entidad User

### Campos Implementados

| Campo | Tipo | Descripcion |
|-------|------|-------------|
| id | UUID | Identificador |
| tenant_id | UUID | Tenant |
| email | VARCHAR | Email unico |
| password_hash | VARCHAR | Hash bcrypt |
| first_name | VARCHAR | Nombre |
| last_name | VARCHAR | Apellido |
| status | user_status | pending, active, suspended, deleted |
| email_verified | BOOLEAN | Email verificado |
| created_at | TIMESTAMP | Creacion |
| updated_at | TIMESTAMP | Actualizacion |

### Campos Planificados (No Implementados)

- mfa_secret, mfa_enabled - Para MFA
- failed_login_attempts, locked_until - Para proteccion brute force
```

**Validacion:**
```bash
grep "Roadmap" docs/01-modulos/SAAS-001-auth.md
grep "Planificado" docs/01-modulos/SAAS-001-auth.md
```

---

### EJECUCION-008: SAAS-004-billing.md

**Ubicacion:** `docs/01-modulos/SAAS-004-billing.md`

**Cambios a realizar (multiples):**

1. **Agregar seccion Enums con ambos subscription_status:**
```markdown
## Enums de Billing

### tenants.subscription_status

Estado general del tenant respecto a su suscripcion:

| Valor | Descripcion |
|-------|-------------|
| trialing | En periodo de prueba |
| active | Suscripcion activa |
| past_due | Pago atrasado |
| cancelled | Cancelado |
| unpaid | Sin pago |

### billing.subscription_status

Estado interno del sistema de billing:

| Valor | Descripcion |
|-------|-------------|
| trial | En trial |
| active | Activo |
| past_due | Pago atrasado |
| cancelled | Cancelado |
| expired | Expirado |

**Nota:** El sistema usa `tenants.subscription_status` para el estado visible
al usuario y `billing.subscription_status` para logica interna de billing.
```

2. **Agregar tabla payment_methods:**
```markdown
## Tabla: billing.payment_methods

| Campo | Tipo | Descripcion |
|-------|------|-------------|
| id | UUID | Identificador |
| tenant_id | UUID | Tenant propietario |
| type | payment_method_type | card, bank_transfer, oxxo |
| provider | VARCHAR | stripe, conekta, etc. |
| external_payment_method_id | VARCHAR | ID en proveedor |
| card_brand | VARCHAR | Visa, Mastercard, etc. |
| card_last4 | VARCHAR | Ultimos 4 digitos |
| card_exp_month | INTEGER | Mes expiracion |
| card_exp_year | INTEGER | Año expiracion |
| is_default | BOOLEAN | Metodo por defecto |
| created_at | TIMESTAMP | Creacion |

### Endpoints Payment Methods

| Metodo | Ruta | Descripcion |
|--------|------|-------------|
| GET | /billing/payment-methods | Listar metodos de pago |
| POST | /billing/payment-methods | Agregar metodo (via Stripe) |
| DELETE | /billing/payment-methods/:id | Eliminar metodo |
| PATCH | /billing/payment-methods/:id/default | Establecer por defecto |
```

3. **Completar campos de Invoice:**
```markdown
## Tabla: billing.invoices

| Campo | Tipo | Descripcion |
|-------|------|-------------|
| id | UUID | Identificador |
| tenant_id | UUID | Tenant |
| subscription_id | UUID | Suscripcion relacionada |
| stripe_invoice_id | VARCHAR | ID en Stripe |
| invoice_number | VARCHAR | Numero factura (INV-YYYYMM-XXXXXX) |
| subtotal | DECIMAL | Subtotal |
| tax | DECIMAL | Impuestos |
| discount | DECIMAL | Descuento |
| total | DECIMAL | Total |
| amount_paid | DECIMAL | Monto pagado |
| amount_due | DECIMAL | Monto pendiente |
| currency | VARCHAR | Moneda (USD, MXN, etc.) |
| status | invoice_status | draft, open, paid, void, uncollectible |
| invoice_date | DATE | Fecha de factura |
| due_date | DATE | Fecha de vencimiento |
| period_start | TIMESTAMP | Inicio periodo |
| period_end | TIMESTAMP | Fin periodo |
| paid_at | TIMESTAMP | Fecha de pago |
| invoice_pdf_url | VARCHAR | URL del PDF |
| hosted_invoice_url | VARCHAR | URL factura Stripe |
| customer_name | VARCHAR | Nombre cliente |
| customer_email | VARCHAR | Email cliente |
| billing_address | JSONB | Direccion de facturacion |
| created_at | TIMESTAMP | Creacion |
```

4. **Corregir nomenclatura trial:**
```markdown
### Campos de Trial en Subscriptions

| Campo | Tipo | Descripcion |
|-------|------|-------------|
| trial_start | TIMESTAMP | Inicio del trial |
| trial_end | TIMESTAMP | Fin del trial |
```

**Validacion:**
```bash
grep "payment_methods" docs/01-modulos/SAAS-004-billing.md
grep "tenants.subscription_status" docs/01-modulos/SAAS-004-billing.md
```

---

### EJECUCION-009: SAAS-007-notifications.md

**Ubicacion:** `docs/01-modulos/SAAS-007-notifications.md`

**Cambios a realizar:**

Agregar seccion Version 2.0:

```markdown
## Version 2.0 (Implementada)

### Nuevos Componentes

#### DevicesController

Gestion de dispositivos para push notifications:

| Metodo | Ruta | Descripcion |
|--------|------|-------------|
| GET | /notifications/devices | Listar dispositivos |
| POST | /notifications/devices | Registrar dispositivo |
| DELETE | /notifications/devices/:id | Eliminar dispositivo |

#### NotificationsGateway (WebSocket)

Gateway para notificaciones en tiempo real:

- Namespace: `/notifications`
- Eventos: `notification`, `read`, `delete`
- Autenticacion via JWT en handshake

#### NotificationQueueService

Procesamiento asincrono de notificaciones:

- Cola BullMQ para envios masivos
- Reintentos automaticos
- Dead letter queue

### Tablas Adicionales v2.0

| Tabla | Descripcion |
|-------|-------------|
| notifications.user_devices | Dispositivos registrados para push |
| notifications.notification_queue | Cola de envio |
| notifications.notification_logs | Historial de envios |

### Integracion WhatsApp

Las notificaciones pueden enviarse via WhatsApp usando el canal `whatsapp`.
Ver [SAAS-014-whatsapp.md](./SAAS-014-whatsapp.md) para configuracion.
```

**Validacion:**
```bash
grep "Version 2.0" docs/01-modulos/SAAS-007-notifications.md
grep "WebSocket" docs/01-modulos/SAAS-007-notifications.md
```

---

### EJECUCION-010: MASTER_INVENTORY.yml

**Ubicacion:** `orchestration/inventarios/MASTER_INVENTORY.yml`

**Cambios a realizar:**

1. **Corregir conteo de tablas:**
```yaml
metricas:
  database_tables: 24  # Era 39
```

2. **Agregar seccion modulos_infraestructura:**
```yaml
modulos_infraestructura:
  - id: "INFRA-001"
    nombre: "health"
    descripcion: "Health check y liveness probes"
    estado: "completado"
    backend: "apps/backend/src/modules/health/"

  - id: "INFRA-002"
    nombre: "onboarding"
    descripcion: "Wizard de onboarding para nuevos tenants"
    estado: "completado"
    backend: "apps/backend/src/modules/onboarding/"
    sp: 8

  - id: "INFRA-003"
    nombre: "rbac"
    descripcion: "Role-Based Access Control"
    estado: "completado"
    backend: "apps/backend/src/modules/rbac/"
    nota: "Sub-modulo integrado con SAAS-003"

  - id: "INFRA-004"
    nombre: "superadmin"
    descripcion: "Portal de super administracion"
    estado: "completado"
    backend: "apps/backend/src/modules/superadmin/"
    frontend: "apps/frontend/src/pages/superadmin/"
```

**Validacion:**
```bash
grep "database_tables: 24" orchestration/inventarios/MASTER_INVENTORY.yml
grep "modulos_infraestructura" orchestration/inventarios/MASTER_INVENTORY.yml
```

---

### EJECUCION-011: DATABASE_INVENTORY.yml

**Ubicacion:** `orchestration/inventarios/DATABASE_INVENTORY.yml`

**Cambios a realizar:**

1. **Corregir conteo de tablas:**
```yaml
resumen:
  total_tablas: 24  # Era 39
```

2. **Actualizar conteo de enums:**
```yaml
resumen:
  total_enums: 32  # Era 29
```

**Validacion:**
```bash
grep "total_tablas: 24" orchestration/inventarios/DATABASE_INVENTORY.yml
grep "total_enums: 32" orchestration/inventarios/DATABASE_INVENTORY.yml
```

---

### EJECUCION-012: Archivos Adicionales

**PROJECT-STATUS.md:**
```markdown
| Database | Completado | 12 schemas, 24 tablas (incluye WhatsApp), RLS |
```

**_MAP.md:**
```markdown
**Total:** 12 schemas, 24 tablas
```

**CONTEXT-MAP.yml:**
Agregar referencia a modulos_infraestructura si aplica.

---

## 3. Orden Final de Ejecucion

| Paso | Archivo | Tiempo | Acumulado |
|------|---------|--------|-----------|
| 1 | SAAS-008-audit-logs.md | 10 min | 10 min |
| 2 | SAAS-009-feature-flags.md | 5 min | 15 min |
| 3 | SAAS-012-crud-base.md | 25 min | 40 min |
| 4 | SAAS-002-tenants.md | 15 min | 55 min |
| 5 | SAAS-006-ai-integration.md | 10 min | 1h 05min |
| 6 | SAAS-003-users.md | 15 min | 1h 20min |
| 7 | SAAS-001-auth.md | 35 min | 1h 55min |
| 8 | SAAS-004-billing.md | 40 min | 2h 35min |
| 9 | SAAS-007-notifications.md | 25 min | 3h 00min |
| 10 | MASTER_INVENTORY.yml | 15 min | 3h 15min |
| 11 | DATABASE_INVENTORY.yml | 5 min | 3h 20min |
| 12 | Otros (STATUS, MAP, CONTEXT) | 10 min | 3h 30min |

**Total:** 3h 30min

---

## 4. Checklist de Ejecucion

- [ ] EJECUCION-001: SAAS-008-audit-logs.md
- [ ] EJECUCION-002: SAAS-009-feature-flags.md
- [ ] EJECUCION-003: SAAS-012-crud-base.md
- [ ] EJECUCION-004: SAAS-002-tenants.md
- [ ] EJECUCION-005: SAAS-006-ai-integration.md
- [ ] EJECUCION-006: SAAS-003-users.md
- [ ] EJECUCION-007: SAAS-001-auth.md
- [ ] EJECUCION-008: SAAS-004-billing.md
- [ ] EJECUCION-009: SAAS-007-notifications.md
- [ ] EJECUCION-010: MASTER_INVENTORY.yml
- [ ] EJECUCION-011: DATABASE_INVENTORY.yml
- [ ] EJECUCION-012: Archivos adicionales

---

**Estado:** LISTO PARA EJECUCION

---

**Creado por:** Claude Code
**Fecha:** 2026-01-10