# ADR-012: Política de Trazabilidad Completa

**Estado:** Aceptado
**Fecha:** 2025-11-24
**Decisores:** Architecture-Analyst, Tech Lead
**Contexto:** ERP Generic - Gestión de documentación y trazabilidad

---

## Contexto

El proyecto ERP Generic es un sistema empresarial complejo con múltiples capas (Base de Datos, Backend, Frontend) y cientos de objetos interrelacionados. Para mantener la coherencia, facilitar el mantenimiento y permitir análisis de impacto, necesitamos una política estricta de trazabilidad que conecte todos los artefactos del sistema.

## Decisión

**Adoptamos la política de "Trazabilidad Completa End-to-End" para todos los objetos del sistema.**

### Principio Fundamental

```
┌─────────────────────────────────────────────────────────────────────────┐
│                     TRAZABILIDAD COMPLETA                               │
│                                                                         │
│   RF (Requerimiento) ──→ ET-Backend ──→ ET-Frontend ──→ US (Stories)   │
│         │                    │               │              │           │
│         ▼                    ▼               ▼              ▼           │
│   ┌─────────┐          ┌─────────┐     ┌─────────┐    ┌─────────┐      │
│   │ Tablas  │◄────────►│ APIs    │◄───►│ Comps   │◄──►│ Tests   │      │
│   │ BD      │          │ Backend │     │ Frontend│    │ E2E     │      │
│   └─────────┘          └─────────┘     └─────────┘    └─────────┘      │
│                                                                         │
│   TODO OBJETO DEBE CONOCER:                                            │
│   • Su ORIGEN (RF/ET que lo define)                                    │
│   • Sus DEPENDENCIAS (de qué depende)                                  │
│   • Sus DEPENDIENTES (qué depende de él)                               │
│   • Sus RELACIONES con otras capas                                     │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘
```

### Inventarios Requeridos

| Inventario | Ubicación | Contenido |
|------------|-----------|-----------|
| Objetos BD | `trazabilidad/INVENTARIO-OBJETOS-BD.yml` | Tablas, funciones, triggers, enums, policies |
| Objetos Backend | `trazabilidad/INVENTARIO-OBJETOS-BACKEND.yml` | Controllers, services, DTOs, repositories |
| Objetos Frontend | `trazabilidad/INVENTARIO-OBJETOS-FRONTEND.yml` | Components, pages, hooks, stores |
| Matriz Completa | `trazabilidad/MATRIZ-TRAZABILIDAD-COMPLETA.md` | RF → ET → BD → Backend → Frontend → Tests |

### Estructura de Trazabilidad por Capa

#### Base de Datos
```yaml
tabla:
  nombre: financial.invoices
  schema: financial
  origen:
    rf: RF-MGN-004-005
    et_backend: ET-BACKEND-MGN-004-005
  dependencias:
    tablas:
      - auth.tenants
      - auth.companies
      - core.partners
      - core.currencies
    funciones:
      - calculate_invoice_totals()
  dependientes:
    tablas:
      - financial.invoice_lines
      - financial.payment_invoice
    triggers:
      - trg_invoices_updated_at
      - track_invoice_changes
  relacionados:
    backend:
      - InvoiceController
      - InvoiceService
      - InvoiceRepository
    frontend:
      - InvoiceForm.tsx
      - InvoiceList.tsx
```

#### Backend
```yaml
servicio:
  nombre: InvoiceService
  modulo: financial
  origen:
    rf: RF-MGN-004-005
    et_backend: ET-BACKEND-MGN-004-005
  dependencias:
    tablas:
      - financial.invoices
      - financial.invoice_lines
    servicios:
      - PartnerService
      - ProductService
      - TaxService
  dependientes:
    controllers:
      - InvoiceController
    otros_servicios:
      - PaymentService
      - ReportService
  relacionados:
    frontend:
      - useInvoice.hook.ts
      - invoice.api.ts
```

#### Frontend
```yaml
componente:
  nombre: InvoiceForm.tsx
  modulo: financial
  tipo: form
  origen:
    rf: RF-MGN-004-005
    et_frontend: ET-FRONTEND-MGN-004-005
    us: US-MGN-004-010
  dependencias:
    apis:
      - POST /api/v1/invoices
      - GET /api/v1/partners
      - GET /api/v1/products
    hooks:
      - useInvoice
      - usePartners
    stores:
      - invoiceStore
  dependientes:
    pages:
      - InvoicePage.tsx
    tests:
      - InvoiceForm.spec.tsx
```

### Reglas de Mantenimiento de Documentación

```
┌─────────────────────────────────────────────────────────────────────────┐
│  REGLA 1: CREAR → DOCUMENTAR                                           │
│  ─────────────────────────────                                          │
│  Al crear cualquier objeto nuevo:                                       │
│  ✅ Agregar al inventario correspondiente                               │
│  ✅ Documentar RF/ET/US de origen                                       │
│  ✅ Mapear dependencias y dependientes                                  │
│  ✅ Vincular con objetos de otras capas                                 │
├─────────────────────────────────────────────────────────────────────────┤
│  REGLA 2: MODIFICAR → ACTUALIZAR                                       │
│  ─────────────────────────────────                                      │
│  Al modificar cualquier objeto:                                         │
│  ✅ Actualizar inventario si cambió estructura                         │
│  ✅ Verificar impacto en dependientes                                   │
│  ✅ Actualizar documentación relacionada                                │
│  ✅ Notificar cambios en capas afectadas                               │
├─────────────────────────────────────────────────────────────────────────┤
│  REGLA 3: ELIMINAR → LIMPIAR                                           │
│  ──────────────────────────────                                         │
│  Al eliminar o deprecar objeto:                                         │
│  ✅ Eliminar del inventario                                             │
│  ✅ Actualizar dependientes que lo usaban                               │
│  ✅ Eliminar referencias huérfanas                                      │
│  ✅ Documentar razón de eliminación                                     │
├─────────────────────────────────────────────────────────────────────────┤
│  REGLA 4: PR → VALIDAR TRAZABILIDAD                                    │
│  ────────────────────────────────────                                   │
│  Todo PR debe incluir:                                                  │
│  ✅ Actualización de inventarios si aplica                             │
│  ✅ Actualización de matriz de trazabilidad                            │
│  ✅ Verificación de dependencias actualizadas                          │
├─────────────────────────────────────────────────────────────────────────┤
│  REGLA 5: REVISIÓN SEMANAL                                             │
│  ────────────────────────────                                           │
│  Semanalmente verificar:                                                │
│  ✅ Consistencia documentación vs código                               │
│  ✅ Objetos huérfanos (sin traza)                                      │
│  ✅ Referencias rotas                                                   │
│  ✅ Inventarios completos                                               │
└─────────────────────────────────────────────────────────────────────────┘
```

### Formato de Trazabilidad en Documentos

Todo documento de especificación (RF, ET, US) debe incluir esta sección:

```markdown
## Trazabilidad

### Origen
- **RF:** RF-MGN-004-005 (Gestión de facturas de cliente)

### Dependencias (De qué depende)
| Capa | Objetos |
|------|---------|
| BD | financial.invoices, invoice_lines, core.partners |
| Backend | PartnerService, ProductService, TaxService |
| Frontend | PartnerSelect, ProductSearch |

### Dependientes (Qué depende de esto)
| Capa | Objetos |
|------|---------|
| BD | financial.payment_invoice |
| Backend | PaymentService, ReportService |
| Frontend | PaymentForm, InvoiceReport |

### Objetos Implementados
| Capa | Objeto | Archivo |
|------|--------|---------|
| BD | financial.invoices | ddl/04-financial.sql:L100 |
| Backend | InvoiceController | src/modules/financial/invoice.controller.ts |
| Backend | InvoiceService | src/modules/financial/invoice.service.ts |
| Frontend | InvoiceForm | src/components/financial/InvoiceForm.tsx |
| Test | invoice.e2e | tests/e2e/invoice.spec.ts |
```

### Herramientas de Validación

```bash
# Validar consistencia de inventarios (futuro script)
./scripts/validate-traceability.sh

# Generar reporte de objetos huérfanos
./scripts/find-orphan-objects.sh

# Verificar referencias cruzadas
./scripts/check-cross-references.sh
```

## Consecuencias

### Positivas

1. **Análisis de impacto**: Saber qué afecta un cambio antes de hacerlo
2. **Debugging eficiente**: Trazar errores desde UI hasta BD
3. **Onboarding rápido**: Nuevos devs entienden relaciones rápidamente
4. **Refactoring seguro**: Conocer todos los dependientes antes de cambiar
5. **Documentación viva**: Siempre actualizada y útil
6. **Auditoría**: Saber origen y justificación de cada objeto

### Negativas (Manejables)

1. **Overhead inicial**: Requiere disciplina para documentar
   - *Mitigación*: Templates y automatización
2. **Tiempo adicional**: Cada cambio requiere actualizar docs
   - *Mitigación*: Incluir en Definition of Done
3. **Curva de aprendizaje**: Entender estructura de trazabilidad
   - *Mitigación*: Guías y ejemplos claros

## Directiva para Agentes

Esta decisión es **OBLIGATORIA** para todos los agentes:

```
🔴 DIRECTIVA ADR-012 - TRAZABILIDAD COMPLETA

Los agentes DEBEN:
✅ Verificar trazabilidad antes de crear objetos nuevos
✅ Actualizar inventarios al crear/modificar/eliminar objetos
✅ Documentar dependencias y dependientes
✅ Mantener referencias cruzadas entre capas
✅ Incluir sección de trazabilidad en documentos

Los agentes NO DEBEN:
❌ Crear objetos sin documentar origen (RF/ET/US)
❌ Modificar objetos sin actualizar dependientes
❌ Eliminar objetos sin limpiar referencias
❌ Ignorar impacto en otras capas
❌ Dejar documentación desactualizada

ANTES DE IMPLEMENTAR, VERIFICAR:
1. ¿El objeto tiene RF/ET que lo define?
2. ¿Están mapeadas sus dependencias?
3. ¿Están identificados sus dependientes?
4. ¿Está en el inventario correspondiente?
5. ¿La documentación está actualizada?
```

## Referencias

- [ADR-011: Database Clean Load Strategy](./ADR-011-database-clean-load-strategy.md)
- [PROMPT-ARCHITECTURE-ANALYST.md](../../../shared/orchestration/prompts/PROMPT-ARCHITECTURE-ANALYST.md)
- [INVENTARIO-OBJETOS-BD.yml](../02-modelado/trazabilidad/INVENTARIO-OBJETOS-BD.yml)
- [MATRIZ-TRAZABILIDAD-RF-ET-BD.md](../02-modelado/trazabilidad/MATRIZ-TRAZABILIDAD-RF-ET-BD.md)

---

**Aprobado por:** Architecture-Analyst
**Fecha de aprobación:** 2025-11-24