# MATRIZ DE DEPENDENCIAS ENTRE CAPAS

**Version:** 1.0.0
**Fecha:** 2025-12-08
**Prioridad:** REFERENCIA - Consultar para entender impactos
**Sistema:** SIMCO + CAPVED

---

## PROPOSITO

Proporcionar una matriz completa de dependencias entre todos los componentes del sistema para que los agentes puedan identificar rapidamente que se debe actualizar cuando se modifica algo.

---

## 1. VISION GENERAL DE DEPENDENCIAS

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                         FLUJO DE DEPENDENCIAS                               │
│                                                                             │
│  ┌─────────┐     ┌─────────┐     ┌─────────┐     ┌─────────┐              │
│  │   DDL   │────▶│ Entity  │────▶│   DTO   │────▶│ Service │              │
│  │  (SQL)  │     │(TypeORM)│     │ (class) │     │ (logic) │              │
│  └─────────┘     └─────────┘     └─────────┘     └─────────┘              │
│       │              │               │               │                     │
│       │              │               │               ▼                     │
│       │              │               │         ┌─────────┐                 │
│       │              │               │         │Controller│                │
│       │              │               │         │ (REST)  │                 │
│       │              │               │         └─────────┘                 │
│       │              │               │               │                     │
│       │              │               │               ▼                     │
│       │              │               │     ┌─────────────────┐             │
│       │              │               │     │    SWAGGER      │             │
│       │              │               │     │ (API Contract)  │             │
│       │              │               │     └─────────────────┘             │
│       │              │               │               │                     │
│       │              │               ▼               ▼                     │
│       │              │         ┌─────────────────────────┐                 │
│       │              │         │       FRONTEND          │                 │
│       │              │         │  Types│Schema│Hooks│UI  │                 │
│       │              │         └─────────────────────────┘                 │
│       │              │                                                      │
│       ▼              ▼                                                      │
│  ┌─────────────────────────┐                                               │
│  │      INVENTARIOS        │                                               │
│  │  DB│BE│FE│MASTER        │                                               │
│  └─────────────────────────┘                                               │
└─────────────────────────────────────────────────────────────────────────────┘
```

---

## 2. MATRIZ DE DEPENDENCIA: DDL

### Cuando se modifica DDL (tablas, columnas)

| Componente Dependiente | Requiere Actualizacion | Prioridad | Detalle |
|------------------------|------------------------|-----------|---------|
| **Entity** | SI | 1 - Inmediato | Debe reflejar estructura DDL |
| **CreateDto** | SI | 2 | Campos nuevos/eliminados |
| **UpdateDto** | AUTO | 2 | Hereda de CreateDto |
| **ResponseDto** | SI | 2 | Campos en response |
| **Service** | POSIBLE | 3 | Si hay logica de campo |
| **Controller** | NO | - | Usa DTOs |
| **Frontend Types** | SI | 4 | Reflejar ResponseDto |
| **Frontend Schema** | SI | 4 | Reflejar CreateDto |
| **Frontend Components** | POSIBLE | 5 | Si muestran campo |
| **Swagger** | AUTO | - | Generado de DTOs |
| **DATABASE_INVENTORY** | SI | 6 | Registrar cambio |
| **Tests** | POSIBLE | 5 | Si prueban campo |

### Diagrama de Propagacion DDL

```
DDL Change
    │
    ├──▶ Entity (obligatorio)
    │       │
    │       ├──▶ CreateDto (obligatorio)
    │       │       │
    │       │       └──▶ Frontend Schema (obligatorio)
    │       │
    │       ├──▶ ResponseDto (obligatorio)
    │       │       │
    │       │       └──▶ Frontend Types (obligatorio)
    │       │               │
    │       │               └──▶ Frontend Components (si usa campo)
    │       │
    │       └──▶ Service (si logica de campo)
    │
    └──▶ DATABASE_INVENTORY (obligatorio)
```

---

## 3. MATRIZ DE DEPENDENCIA: ENTITY

### Cuando se modifica Entity

| Componente Dependiente | Requiere Actualizacion | Prioridad | Detalle |
|------------------------|------------------------|-----------|---------|
| **DDL** | VERIFICAR | 0 | DDL debe existir primero |
| **CreateDto** | SI | 1 | Reflejar campos |
| **UpdateDto** | AUTO | 1 | Hereda de CreateDto |
| **ResponseDto** | SI | 1 | Reflejar campos |
| **Service** | POSIBLE | 2 | Si usa campo directamente |
| **Controller** | NO | - | Usa DTOs |
| **Frontend Types** | SI | 3 | Reflejar ResponseDto |
| **Frontend Schema** | SI | 3 | Reflejar CreateDto |
| **Frontend Components** | POSIBLE | 4 | Si muestran campo |
| **BACKEND_INVENTORY** | SI | 5 | Registrar cambio |
| **Unit Tests** | SI | 4 | Actualizar mocks |

### Por Tipo de Cambio en Entity

| Cambio | DTOs | Service | Frontend | Tests |
|--------|------|---------|----------|-------|
| Agregar @Column | SI | NO | SI | SI |
| Eliminar @Column | SI | Verificar | SI | SI |
| Cambiar tipo @Column | SI | Posible | SI | SI |
| Agregar @ManyToOne | SI | SI | SI | SI |
| Agregar @OneToMany | SI | Posible | SI | Posible |
| Cambiar @Index | NO | NO | NO | NO |
| Cambiar nullable | SI | NO | SI | Posible |

---

## 4. MATRIZ DE DEPENDENCIA: DTO

### Cuando se modifica CreateDto

| Componente Dependiente | Requiere Actualizacion | Prioridad | Detalle |
|------------------------|------------------------|-----------|---------|
| **UpdateDto** | AUTO | 1 | Si usa PartialType |
| **Service** | NO | - | Recibe DTO |
| **Controller** | NO | - | Usa DTO |
| **Swagger** | AUTO | - | Generado |
| **Frontend Schema (Zod)** | SI | 2 | Mismas validaciones |
| **Frontend Forms** | POSIBLE | 3 | Si campos cambian |
| **Integration Tests** | SI | 3 | Fixtures |

### Cuando se modifica ResponseDto

| Componente Dependiente | Requiere Actualizacion | Prioridad | Detalle |
|------------------------|------------------------|-----------|---------|
| **Service** | SI | 1 | Si mapea a ResponseDto |
| **Controller** | NO | - | Retorna Service result |
| **Swagger** | AUTO | - | Generado |
| **Frontend Types** | SI | 2 | Interface debe coincidir |
| **Frontend Components** | POSIBLE | 3 | Si muestran campo |
| **Frontend Hooks** | NO | - | Usan Types |

---

## 5. MATRIZ DE DEPENDENCIA: SERVICE

### Cuando se modifica Service

| Componente Dependiente | Requiere Actualizacion | Prioridad | Detalle |
|------------------------|------------------------|-----------|---------|
| **Controller** | POSIBLE | 1 | Si cambia firma metodo |
| **Swagger** | POSIBLE | 2 | Si cambia response/errors |
| **Frontend** | POSIBLE | 2 | Si cambia contrato API |
| **Unit Tests** | SI | 1 | Tests del service |
| **Integration Tests** | POSIBLE | 2 | Si cambia comportamiento |

### Por Tipo de Cambio en Service

| Cambio | Controller | Frontend | Tests |
|--------|------------|----------|-------|
| Agregar metodo | SI (nuevo endpoint) | SI | SI |
| Eliminar metodo | SI | SI | SI |
| Cambiar firma | SI | SI | SI |
| Cambiar logica interna | NO | NO | SI |
| Agregar validacion | NO | Manejar error | SI |
| Cambiar error thrown | NO | Manejar error | SI |

---

## 6. MATRIZ DE DEPENDENCIA: CONTROLLER

### Cuando se modifica Controller

| Componente Dependiente | Requiere Actualizacion | Prioridad | Detalle |
|------------------------|------------------------|-----------|---------|
| **Service** | NO | - | Controller consume Service |
| **Swagger** | AUTO | - | Generado de decoradores |
| **Frontend Service** | SI | 1 | Si cambia ruta/metodo |
| **Frontend Hooks** | POSIBLE | 2 | Si cambia endpoint |
| **E2E Tests** | SI | 2 | Tests de endpoint |

### Por Tipo de Cambio en Controller

| Cambio | Frontend Service | Frontend Hooks | Tests |
|--------|------------------|----------------|-------|
| Agregar endpoint | SI (nuevo metodo) | SI (nuevo hook) | SI |
| Eliminar endpoint | SI | SI | SI |
| Cambiar ruta | SI | NO | SI |
| Cambiar metodo HTTP | SI | NO | SI |
| Cambiar decoradores Swagger | NO | NO | NO |
| Agregar guard | NO | Manejar 401/403 | SI |

---

## 7. MATRIZ DE DEPENDENCIA: FRONTEND

### Cuando se modifica Frontend Types

| Componente Dependiente | Requiere Actualizacion | Prioridad | Detalle |
|------------------------|------------------------|-----------|---------|
| **Zod Schema** | VERIFICAR | 1 | Debe ser consistente |
| **Hooks** | NO | - | Usan Types |
| **Components** | VERIFICAR | 2 | Si usan tipo |
| **Services** | NO | - | Usan Types |

### Cuando se modifica Frontend Schema (Zod)

| Componente Dependiente | Requiere Actualizacion | Prioridad | Detalle |
|------------------------|------------------------|-----------|---------|
| **Forms** | VERIFICAR | 1 | Si usan schema |
| **Types** | VERIFICAR | 1 | Deben coincidir |

### Cuando se modifica Frontend Hook

| Componente Dependiente | Requiere Actualizacion | Prioridad | Detalle |
|------------------------|------------------------|-----------|---------|
| **Components** | VERIFICAR | 1 | Si usan hook |
| **Pages** | VERIFICAR | 1 | Si usan hook |

---

## 8. MATRIZ RAPIDA DE REFERENCIA

### "Si cambio X, que debo actualizar?"

```
┌─────────────────┬─────┬────────┬─────────┬─────────┬────────┬─────────────┐
│ SI CAMBIO...    │ DDL │ Entity │DTO-Crea │DTO-Resp │Service │ Controller  │
├─────────────────┼─────┼────────┼─────────┼─────────┼────────┼─────────────┤
│ DDL columna     │ ──  │   SI   │   SI    │   SI    │ Posib  │    NO       │
│ DDL FK          │ ──  │   SI   │   SI    │   SI    │   SI   │  Posible    │
│ DDL indice      │ ──  │   NO   │   NO    │   NO    │   NO   │    NO       │
├─────────────────┼─────┼────────┼─────────┼─────────┼────────┼─────────────┤
│ Entity columna  │ Ver │   ──   │   SI    │   SI    │ Posib  │    NO       │
│ Entity relacion │ Ver │   ──   │   SI    │   SI    │   SI   │  Posible    │
├─────────────────┼─────┼────────┼─────────┼─────────┼────────┼─────────────┤
│ CreateDto campo │ NO  │   NO   │   ──    │   NO    │   NO   │    NO       │
│ CreateDto valid │ NO  │   NO   │   ──    │   NO    │   NO   │    NO       │
│ ResponseDto     │ NO  │   NO   │   NO    │   ──    │  Ver   │    NO       │
├─────────────────┼─────┼────────┼─────────┼─────────┼────────┼─────────────┤
│ Service metodo  │ NO  │   NO   │   NO    │ Posib   │   ──   │    SI       │
│ Service logica  │ NO  │   NO   │   NO    │   NO    │   ──   │    NO       │
├─────────────────┼─────┼────────┼─────────┼─────────┼────────┼─────────────┤
│ Controller ruta │ NO  │   NO   │   NO    │   NO    │   NO   │    ──       │
│ Controller meth │ NO  │   NO   │   NO    │   NO    │   NO   │    ──       │
└─────────────────┴─────┴────────┴─────────┴─────────┴────────┴─────────────┘

Continuacion → Frontend

┌─────────────────┬───────┬────────┬───────┬───────────┬───────────┐
│ SI CAMBIO...    │ Types │ Schema │ Hooks │Components │ Inventory │
├─────────────────┼───────┼────────┼───────┼───────────┼───────────┤
│ DDL columna     │  SI   │   SI   │  NO   │  Posible  │  DB+MAST  │
│ DDL FK          │  SI   │   SI   │  SI   │  Posible  │  DB+MAST  │
│ DDL indice      │  NO   │   NO   │  NO   │    NO     │    DB     │
├─────────────────┼───────┼────────┼───────┼───────────┼───────────┤
│ Entity columna  │  SI   │   SI   │  NO   │  Posible  │  BE+MAST  │
│ Entity relacion │  SI   │   SI   │  SI   │  Posible  │  BE+MAST  │
├─────────────────┼───────┼────────┼───────┼───────────┼───────────┤
│ CreateDto campo │  NO   │   SI   │  NO   │  Posible  │    BE     │
│ CreateDto valid │  NO   │   SI   │  NO   │    NO     │    NO     │
│ ResponseDto     │  SI   │   NO   │  NO   │  Posible  │    BE     │
├─────────────────┼───────┼────────┼───────┼───────────┼───────────┤
│ Service metodo  │ Posib │ Posib  │  SI   │  Posible  │    BE     │
│ Service logica  │  NO   │   NO   │  NO   │    NO     │    NO     │
├─────────────────┼───────┼────────┼───────┼───────────┼───────────┤
│ Controller ruta │  NO   │   NO   │  SI   │    NO     │    BE     │
│ Controller meth │  NO   │   NO   │  SI   │    NO     │    NO     │
├─────────────────┼───────┼────────┼───────┼───────────┼───────────┤
│ Frontend Types  │  ──   │  Ver   │  NO   │    Ver    │    FE     │
│ Frontend Schema │  Ver  │   ──   │  NO   │    Ver    │    FE     │
│ Frontend Hook   │  NO   │   NO   │  ──   │    Ver    │    FE     │
│ Frontend Comp   │  NO   │   NO   │  NO   │    ──     │    FE     │
└─────────────────┴───────┴────────┴───────┴───────────┴───────────┘

Leyenda:
SI     = Siempre actualizar
NO     = No requiere actualizacion
Ver    = Verificar DDL primero
Posib  = Posiblemente, depende del caso
──     = No aplica (mismo componente)
```

---

## 9. DEPENDENCIAS POR MODULO

### Modulo Tipico NestJS

```
modules/user/
├── entities/
│   └── user.entity.ts          ← Depende de: DDL
│                                  Impacta: DTOs, Service
├── dto/
│   ├── create-user.dto.ts      ← Depende de: Entity
│   │                              Impacta: Frontend Schema
│   ├── update-user.dto.ts      ← Depende de: CreateDto
│   │                              Impacta: Frontend Schema
│   └── user-response.dto.ts    ← Depende de: Entity
│                                  Impacta: Frontend Types
├── services/
│   └── user.service.ts         ← Depende de: Entity, DTOs
│                                  Impacta: Controller
├── controllers/
│   └── user.controller.ts      ← Depende de: Service, DTOs
│                                  Impacta: Frontend Hooks
└── user.module.ts              ← Depende de: Todo lo anterior
```

### Modulo Tipico Frontend

```
shared/
├── types/
│   └── user.types.ts           ← Depende de: ResponseDto
│                                  Impacta: Hooks, Components
├── schemas/
│   └── user.schema.ts          ← Depende de: CreateDto
│                                  Impacta: Forms
└── services/
    └── user.service.ts         ← Depende de: Controller routes
                                   Impacta: Hooks

apps/web/
├── hooks/
│   └── useUsers.ts             ← Depende de: Service, Types
│                                  Impacta: Pages, Components
├── components/
│   └── UserCard.tsx            ← Depende de: Types, Hooks
│                                  Impacta: Pages
└── pages/
    └── UsersPage.tsx           ← Depende de: Hooks, Components
```

---

## 10. COMANDOS DE VERIFICACION DE DEPENDENCIAS

```bash
# Ver todas las importaciones de un archivo
grep -n "import" src/modules/user/user.service.ts

# Ver quien importa un archivo
grep -rn "from.*user.entity" src/

# Ver dependencias de modulo
grep -rn "UserModule" src/

# Ver uso de tipo en frontend
grep -rn "User" apps/web/

# Arbol de dependencias (si usa herramientas)
npx madge --image graph.svg src/modules/user/

# TypeScript: ver errores de tipo despues de cambio
npm run typecheck 2>&1 | head -50
```

---

## 11. ESCENARIOS COMUNES

### Escenario 1: Agregar campo a tabla existente

```
1. DDL: ALTER TABLE ADD COLUMN
2. Entity: Agregar @Column
3. CreateDto: Agregar campo + validacion
4. ResponseDto: Agregar campo
5. Service: Solo si hay logica especial
6. Frontend Types: Agregar a interface
7. Frontend Schema: Agregar validacion Zod
8. Frontend Components: Agregar UI si necesario
9. Inventarios: DB, BE, FE, MASTER
```

### Escenario 2: Crear nuevo modulo/feature

```
1. DDL: CREATE TABLE
2. Entity: Crear archivo
3. DTOs: Crear Create, Update, Response
4. Service: Crear con CRUD basico
5. Controller: Crear con endpoints REST
6. Module: Crear y registrar en AppModule
7. Frontend Types: Crear interface
8. Frontend Schema: Crear Zod schema
9. Frontend Service: Crear API service
10. Frontend Hook: Crear useQuery/useMutation
11. Frontend Components: Crear UI
12. Inventarios: TODOS
```

### Escenario 3: Refactorizar nombre de campo

```
1. EVALUAR: ¿Es breaking change?
2. OPCION A (breaking): Cambiar en cadena DDL→Entity→DTO→FE
3. OPCION B (seguro):
   a. Agregar nuevo campo
   b. Migrar datos
   c. Actualizar codigo para usar nuevo
   d. Eliminar campo viejo
```

---

## 12. ANTI-PATRON: DEPENDENCIAS CIRCULARES

```
❌ INCORRECTO: Dependencia circular entre Services
UserService ──▶ OrderService
     ▲               │
     └───────────────┘

✅ CORRECTO: Extraer a servicio compartido
UserService ──▶ SharedService ◀── OrderService
```

```
❌ INCORRECTO: Frontend importa de Backend
apps/web/types/user.ts
import { UserEntity } from '@backend/modules/user';

✅ CORRECTO: Frontend tiene sus propios tipos
apps/web/types/user.ts
export interface User { ... }  // Definido independiente
```

---

**Version:** 1.0.0 | **Sistema:** SIMCO | **Tipo:** Matriz de Referencia