# Directiva: Análisis de Impacto y Dependencias

**ID:** DV-IMPACTO
**Versión:** 1.0
**Fecha:** 2025-12-05
**Prioridad:** CRÍTICA - Cumplimiento obligatorio
**Aplicable a:** Todos los agentes y subagentes

---

## Objetivo

**PREVENIR modificaciones que rompan dependencias o generen duplicados.**

> "Antes de crear o modificar, validar qué existe y qué depende de ello."

---

## Principios Fundamentales

### 1. Nada se crea sin consultar inventarios
### 2. Nada se modifica sin analizar impacto
### 3. Toda dependencia debe documentarse
### 4. Todo cambio actualiza la documentación afectada

---

## Protocolo de Análisis Pre-Modificación

### Paso 1: Consultar Inventarios (OBLIGATORIO)

**ANTES de crear cualquier objeto, consultar:**

| Tipo de Objeto | Inventario a Consultar | Verificar |
|----------------|------------------------|-----------|
| Tabla/Schema | `DATABASE_INVENTORY.yml` | ¿Existe tabla con nombre similar? ¿Schema correcto? |
| Endpoint API | `BACKEND_INVENTORY.yml` | ¿Endpoint ya existe? ¿Módulo correcto? |
| Componente/Página | `FRONTEND_INVENTORY.yml` | ¿Componente similar existe? |
| Servicio ML | `ML_INVENTORY.yml` | ¿Modelo/feature ya existe? |
| **Cualquier objeto** | `TRACEABILITY.yml` de la épica | ¿Ya está mapeado? ¿Tiene dependencias? |

**Comando de verificación:**
```bash
# Buscar objetos similares en inventarios
grep -i "{nombre_objeto}" docs/90-transversal/inventarios/*.yml
grep -i "{nombre_objeto}" docs/02-definicion-modulos/*/implementacion/TRACEABILITY.yml
```

---

### Paso 2: Análisis de Dependencias (OBLIGATORIO)

**Para cada modificación, identificar:**

#### A. Dependencias UPSTREAM (de qué depende mi cambio)

```yaml
# Ejemplo: Crear tabla user_progress
dependencias_upstream:
  tablas:
    - name: users
      tipo: FK
      impacto: "Requiere que users exista"
    - name: courses
      tipo: FK
      impacto: "Requiere que courses exista"
  servicios:
    - name: AuthService
      impacto: "Necesita usuario autenticado"
  epicas:
    - id: OQI-001
      status: "Debe estar completada"
```

#### B. Dependencias DOWNSTREAM (qué depende de mi cambio)

```yaml
# Ejemplo: Modificar tabla users
dependencias_downstream:
  tablas:
    - name: enrollments
      tipo: FK
      accion: "Verificar constraint"
    - name: certificates
      tipo: FK
      accion: "Verificar constraint"
  servicios:
    - name: EducationService
      accion: "Actualizar tipos si cambian columnas"
    - name: InvestmentService
      accion: "Verificar compatibilidad"
  frontend:
    - name: UserProfile.tsx
      accion: "Actualizar si cambian campos"
```

---

### Paso 3: Matriz de Impacto

**Antes de ejecutar, generar matriz:**

```markdown
## Matriz de Impacto: {Nombre del Cambio}

| Capa | Objeto Afectado | Tipo de Impacto | Acción Requerida | Prioridad |
|------|-----------------|-----------------|------------------|-----------|
| DB | users | Modificación | Agregar columna | P0 |
| DB | enrollments | Dependencia FK | Verificar constraint | P1 |
| Backend | UserEntity | Sincronizar | Agregar propiedad | P0 |
| Backend | UserDTO | Sincronizar | Agregar campo | P0 |
| Frontend | UserProfile.tsx | Sincronizar | Agregar campo UI | P1 |
| Tests | user.service.spec | Actualizar | Agregar test | P1 |
| Docs | TRACEABILITY.yml | Actualizar | Registrar cambio | P0 |
```

---

## Validación Anti-Duplicación

### Checklist ANTES de Crear Cualquier Objeto

```markdown
## Checklist Anti-Duplicación

### Para Tablas/Schemas
- [ ] ¿Busqué en DATABASE_INVENTORY.yml?
- [ ] ¿Busqué tablas con nombre similar?
- [ ] ¿Verifiqué que no existe en otro schema?
- [ ] ¿El nombre sigue la nomenclatura del proyecto?

### Para Endpoints/Servicios
- [ ] ¿Busqué en BACKEND_INVENTORY.yml?
- [ ] ¿Verifiqué endpoints similares en el mismo módulo?
- [ ] ¿Verifiqué que la funcionalidad no existe en otro módulo?

### Para Componentes/Páginas
- [ ] ¿Busqué en FRONTEND_INVENTORY.yml?
- [ ] ¿Verifiqué componentes con propósito similar?
- [ ] ¿Puedo reutilizar un componente existente?

### Para Cualquier Objeto
- [ ] ¿Consulté el TRACEABILITY.yml de la épica?
- [ ] ¿El objeto está en la lista de "implementation"?
- [ ] ¿Tiene un RF/ET que lo respalde?
```

---

## Proceso de Modificación con Impacto

### Flujo Completo

```
┌─────────────────────────────────────────────────────────────┐
│ 1. RECIBIR SOLICITUD DE CAMBIO                              │
│    "Crear tabla user_progress para tracking de educación"   │
└──────────────────────────┬──────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────────┐
│ 2. CONSULTAR INVENTARIOS (Anti-duplicación)                 │
│    - grep -i "progress" DATABASE_INVENTORY.yml              │
│    - grep -i "progress" BACKEND_INVENTORY.yml               │
│    - ¿Existe algo similar? → SI: Evaluar reutilización      │
│                            → NO: Continuar                   │
└──────────────────────────┬──────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────────┐
│ 3. IDENTIFICAR DEPENDENCIAS UPSTREAM                        │
│    - ¿De qué tablas depende? → users, courses, lessons      │
│    - ¿Qué épicas deben estar completadas? → OQI-001, OQI-002│
│    - ¿Existen las dependencias? → Verificar en inventario   │
└──────────────────────────┬──────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────────┐
│ 4. IDENTIFICAR DEPENDENCIAS DOWNSTREAM                       │
│    - ¿Qué servicios usarán esta tabla? → ProgressService    │
│    - ¿Qué frontend la mostrará? → ProgressBar, MyLearning   │
│    - ¿Qué otros objetos debo crear? → Entity, DTO, API      │
└──────────────────────────┬──────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────────┐
│ 5. GENERAR MATRIZ DE IMPACTO                                │
│    - Listar TODOS los objetos afectados                     │
│    - Priorizar por dependencia (P0 primero)                 │
│    - Documentar acciones requeridas                         │
└──────────────────────────┬──────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────────┐
│ 6. EJECUTAR EN ORDEN DE DEPENDENCIA                         │
│    P0: Crear tabla (si dependencias upstream existen)       │
│    P0: Crear Entity + DTO                                   │
│    P1: Crear Service + Controller                           │
│    P2: Crear componentes frontend                           │
└──────────────────────────┬──────────────────────────────────┘
                           ↓
┌─────────────────────────────────────────────────────────────┐
│ 7. ACTUALIZAR DOCUMENTACIÓN                                 │
│    - DATABASE_INVENTORY.yml (nueva tabla)                   │
│    - BACKEND_INVENTORY.yml (nuevo servicio)                 │
│    - FRONTEND_INVENTORY.yml (nuevos componentes)            │
│    - TRACEABILITY.yml (mapeo RF → implementación)           │
└─────────────────────────────────────────────────────────────┘
```

---

## Casos Especiales

### Caso 1: Modificar Tabla Existente

**ANTES de modificar:**
1. Buscar en `DATABASE_INVENTORY.yml` la tabla
2. Ver sección `related_backend_entity` y `related_frontend`
3. Buscar en código todas las referencias:
   ```bash
   grep -r "tabla_name" apps/backend/src/
   grep -r "TablaEntity" apps/backend/src/
   ```
4. Generar lista de archivos a actualizar

**Ejemplo de impacto:**
```yaml
modificar_tabla: users
agregar_columna: phone_verified
impacto:
  - apps/database/schemas/01_public_schema.sql
  - apps/backend/src/modules/users/entities/user.entity.ts
  - apps/backend/src/modules/users/dto/user.dto.ts
  - apps/backend/src/modules/auth/services/phone.service.ts
  - apps/frontend/src/types/user.types.ts
  - apps/frontend/src/modules/settings/pages/Profile.tsx
  - docs/90-transversal/inventarios/DATABASE_INVENTORY.yml
```

---

### Caso 2: Crear Nuevo Módulo/Feature

**ANTES de crear:**
1. Verificar en `TRACEABILITY.yml` que el RF existe
2. Verificar que épicas de dependencia están completadas
3. Listar TODOS los objetos a crear (tabla, entity, service, controller, componentes)
4. Verificar que ninguno existe ya

**Ejemplo de plan:**
```yaml
crear_feature: enrollment_system
rf_origen: RF-EDU-003
dependencias:
  - OQI-001 (auth) - status: completada
  - OQI-002 (courses) - status: en_progreso
objetos_a_crear:
  database:
    - schema: education
    - table: enrollments
    - table: lesson_progress
  backend:
    - entity: EnrollmentEntity
    - entity: LessonProgressEntity
    - service: ProgressService
    - controller: ProgressController
    - dto: CreateEnrollmentDTO
    - dto: UpdateProgressDTO
  frontend:
    - page: MyLearning.tsx
    - component: ProgressBar.tsx
    - component: EnrollmentButton.tsx
    - hook: useEnrollment.ts
    - store: education.store.ts
```

---

### Caso 3: Eliminar/Deprecar Objeto

**ANTES de eliminar:**
1. Buscar TODAS las referencias en código
2. Buscar en todos los inventarios
3. Verificar dependencias downstream
4. Si tiene dependencias → NO eliminar, deprecar primero

**Proceso de deprecación:**
```yaml
deprecar_objeto: LegacyUserService
paso_1:
  - Marcar como @deprecated en código
  - Agregar fecha de eliminación planeada
paso_2:
  - Notificar en documentación
  - Crear alternativa si no existe
paso_3:
  - Migrar dependencias a alternativa
  - Verificar que no hay referencias
paso_4:
  - Eliminar objeto
  - Actualizar inventarios
```

---

## Template de Análisis de Impacto

```markdown
# Análisis de Impacto: {Nombre del Cambio}

**Fecha:** YYYY-MM-DD
**Solicitante:** {Usuario/Agente}
**Épica:** OQI-XXX
**RF relacionado:** RF-XXX-NNN

---

## 1. Descripción del Cambio
{Qué se va a hacer}

## 2. Consulta de Inventarios

### ¿Objeto similar existe?
- [ ] DATABASE_INVENTORY.yml: {resultado}
- [ ] BACKEND_INVENTORY.yml: {resultado}
- [ ] FRONTEND_INVENTORY.yml: {resultado}
- [ ] TRACEABILITY.yml: {resultado}

### Conclusión Anti-Duplicación
{Proceder / Reutilizar existente / Modificar existente}

## 3. Dependencias UPSTREAM

| Dependencia | Tipo | Status | Acción |
|-------------|------|--------|--------|
| ... | ... | ... | ... |

## 4. Dependencias DOWNSTREAM

| Objeto Afectado | Capa | Acción Requerida |
|-----------------|------|------------------|
| ... | ... | ... |

## 5. Matriz de Impacto Completa

| # | Capa | Objeto | Acción | Prioridad | Archivo |
|---|------|--------|--------|-----------|---------|
| 1 | DB | ... | Crear | P0 | ... |
| 2 | Backend | ... | Crear | P0 | ... |
| ... | ... | ... | ... | ... | ... |

## 6. Plan de Ejecución

### P0 (Crítico - Primero)
1. {acción}
2. {acción}

### P1 (Alto - Segundo)
1. {acción}

### P2 (Medio - Tercero)
1. {acción}

## 7. Documentación a Actualizar

- [ ] DATABASE_INVENTORY.yml
- [ ] BACKEND_INVENTORY.yml
- [ ] FRONTEND_INVENTORY.yml
- [ ] TRACEABILITY.yml de {épica}
- [ ] _MAP.md si se crean carpetas

## 8. Checklist de Validación Post-Cambio

- [ ] Todos los objetos creados en orden correcto
- [ ] Inventarios actualizados
- [ ] TRACEABILITY.yml actualizado
- [ ] Build pasando
- [ ] Tests pasando
- [ ] Sin referencias rotas
```

---

## Integración con Otras Directivas

Esta directiva complementa:

| Directiva | Relación |
|-----------|----------|
| `DIRECTIVA-VALIDACION-DOCUMENTACION.md` | Este análisis es parte del ANTES |
| `DIRECTIVA-DOCUMENTACION-OBLIGATORIA.md` | Actualización de inventarios es obligatoria |
| `PROCESO-VALIDACION.md` | Validación de dependencias en cada momento |
| `DIRECTIVAS-PRINCIPALES.md` | DV-001 a DV-004 requieren este análisis |

---

## Consecuencias de No Cumplir

### Riesgos

- **Objetos duplicados** - Crear tabla que ya existe con otro nombre
- **Referencias rotas** - Modificar objeto sin actualizar dependientes
- **Inconsistencia de tipos** - Backend y Frontend desincronizados
- **Tests fallando** - Cambios no reflejados en tests
- **Documentación obsoleta** - Inventarios que no reflejan realidad

### Indicadores de Violación

- Errores de FK en base de datos
- TypeScript errors por tipos no sincronizados
- Componentes frontend mostrando datos incorrectos
- Tests E2E fallando por cambios no propagados

---

## Criterio de Éxito

**Un cambio se considera completo SI Y SOLO SI:**

1. Se consultaron inventarios ANTES de crear
2. Se identificaron TODAS las dependencias upstream
3. Se identificaron TODAS las dependencias downstream
4. Se generó matriz de impacto
5. Se ejecutó en orden de prioridad
6. Se actualizaron TODOS los inventarios
7. Se actualizaron TODOS los TRACEABILITY.yml afectados
8. Build y tests pasando
9. Sin referencias rotas

---

**Versión:** 1.0
**Última actualización:** 2025-12-05
**Autor:** Requirements-Analyst
**Estado:** ACTIVA Y OBLIGATORIA
