# MATRICES DE TRAZABILIDAD - ERP GENÉRICO

**Fecha:** 2025-11-24
**Versión:** 1.0
**Total Módulos:** 14
**Total RF:** 80
**Total ET:** 160 (80 Backend + 80 Frontend)
**Total Tablas BD:** 93
**Total Test Cases estimados:** ~800

---

## Índice de Matrices de Trazabilidad

| Archivo YAML | Módulo | Nombre | RF | Story Points | Prioridad | Estado |
|--------------|--------|--------|-----|--------------|-----------|--------|
| [TRACEABILITY-MGN-001.yaml](TRACEABILITY-MGN-001.yaml) | MGN-001 | Fundamentos | 8 | 68 SP | P0 (MVP) | ✅ Completado |
| TRACEABILITY-MGN-002.yaml | MGN-002 | Empresas y Organizaciones | 5 | 34 SP | P0 (MVP) | ⏳ Pendiente |
| TRACEABILITY-MGN-003.yaml | MGN-003 | Catálogos Maestros | 6 | 29 SP | P0 (MVP) | ⏳ Pendiente |
| TRACEABILITY-MGN-004.yaml | MGN-004 | Financiero Básico | 8 | 81 SP | P0 (MVP) | ⏳ Pendiente |
| TRACEABILITY-MGN-005.yaml | MGN-005 | Inventario Básico | 7 | 66 SP | P0 (MVP) | ⏳ Pendiente |
| TRACEABILITY-MGN-006.yaml | MGN-006 | Compras Básico | 6 | 42 SP | P0/P1 | ⏳ Pendiente |
| TRACEABILITY-MGN-007.yaml | MGN-007 | Ventas Básico | 6 | 45 SP | P0 (MVP) | ⏳ Pendiente |
| TRACEABILITY-MGN-008.yaml | MGN-008 | Contabilidad Analítica | 5 | 35 SP | P0 (MVP) | ⏳ Pendiente |
| TRACEABILITY-MGN-009.yaml | MGN-009 | CRM Básico | 5 | 31 SP | P1 | ⏳ Pendiente |
| TRACEABILITY-MGN-010.yaml | MGN-010 | RRHH Básico | 5 | 29 SP | P1 | ⏳ Pendiente |
| TRACEABILITY-MGN-011.yaml | MGN-011 | Proyectos Genéricos | 5 | 40 SP | P1 | ⏳ Pendiente |
| TRACEABILITY-MGN-012.yaml | MGN-012 | Reportes y Analytics | 4 | 39 SP | P1 | ⏳ Pendiente |
| TRACEABILITY-MGN-013.yaml | MGN-013 | Portal de Usuarios | 4 | 29 SP | P1 | ⏳ Pendiente |
| TRACEABILITY-MGN-014.yaml | MGN-014 | Mensajería y Notificaciones | 6 | 47 SP | P0 (MVP) | ⏳ Pendiente |

**Total:** 14 archivos YAML | 80 RF | 673 SP

---

## Propósito de las Matrices de Trazabilidad

Las matrices de trazabilidad YAML sirven para:

### 1. **QA y Testing**
- Asegurar que cada RF tiene tests backend + frontend completos
- Verificar cobertura de test cases (unit, integration, e2e)
- Validar que criterios de aceptación tienen tests asociados
- Identificar gaps de testing antes de implementación

### 2. **Gestión de Proyecto**
- Rastrear implementación de RF (Backend + Frontend + Tests)
- Medir progreso por módulo (% RF completados)
- Identificar dependencias entre RFs y módulos
- Estimar duración de sprints con precisión

### 3. **Desarrollo**
- Referencias rápidas a archivos de código (services, controllers, components)
- Mapping claro RF → ET → Implementación → Tests
- Validar que reglas de negocio están implementadas y testeadas
- Documentación de endpoints y rutas frontend

### 4. **Auditoría y Compliance**
- Demostrar que cada RF tiene trazabilidad completa
- Vincular cada regla de negocio con su implementación y validación
- Justificar estimaciones de Story Points
- Reportes de cobertura para stakeholders

---

## Estructura de cada Archivo YAML

Cada archivo `TRACEABILITY-MGN-XXX.yaml` contiene:

### Metadata del Módulo
```yaml
module:
  id: MGN-XXX
  name: "Nombre del Módulo"
  description: "Descripción breve"
  priority: P0 | P1 | P2
  story_points: XX
  status: Diseñado | En Desarrollo | Completado

metadata:
  total_rf: X
  total_et_backend: X
  total_et_frontend: X
  total_tables: X
  total_tests: Y
  coverage: 100%
```

### Por cada Requerimiento Funcional (RF)

```yaml
requirements:
  - rf_id: RF-MGN-XXX-YYY
    rf_title: "Título del RF"
    rf_file: "ruta/al/archivo.md"
    priority: P0 | P1 | P2
    story_points: X

    # Especificación Técnica Backend
    et_backend:
      file: "ruta/ET-BACKEND.md"
      endpoints: [...]
      services: [...]
      controllers: [...]
      dtos: [...]

    # Especificación Técnica Frontend
    et_frontend:
      file: "ruta/ET-FRONTEND.md"
      routes: [...]
      components: [...]
      api_client: [...]
      state_management: [...]

    # Tablas de Base de Datos
    database_tables:
      - schema: xxx
        table: yyy
        file: "ruta/schema.sql"
        operations: [SELECT, INSERT, UPDATE, DELETE]
        indices: [...]
        rls_policy: "policy_name"

    # Test Cases
    tests:
      backend:
        unit_tests: [...]
        integration_tests: [...]
      frontend:
        component_tests: [...]
        e2e_tests: [...]

    # Criterios de Aceptación
    acceptance_criteria:
      - id: AC-001
        description: "..."
        status: Pending | Passed | Failed
        test_reference: "archivo:línea"

    # Reglas de Negocio
    business_rules:
      - id: RN-001
        description: "..."
        implementation: "archivo:función/línea"
        test_reference: "archivo:test_case"

    # Dependencias
    dependencies:
      rf_dependencies: [RF-MGN-XXX-YYY]
      module_dependencies: [MGN-XXX]
      external_dependencies: [...]
```

### Métricas de Cobertura
```yaml
coverage:
  rf_to_et_backend: 100%
  rf_to_et_frontend: 100%
  rf_to_database: 100%
  rf_to_tests: 100%
  backend_tests: 100%
  frontend_tests: 100%

statistics:
  total_endpoints: X
  total_components: Y
  total_tables: Z
  total_test_cases: W
  estimated_duration_sprints: N
```

---

## Cómo Usar las Matrices de Trazabilidad

### Para QA Engineers

1. **Revisar Cobertura de Tests:**
   ```bash
   # Buscar RFs sin tests
   grep -r "total_tests: 0" trazabilidad/

   # Ver cobertura por módulo
   yq eval '.metadata.total_tests' TRACEABILITY-MGN-*.yaml
   ```

2. **Validar Criterios de Aceptación:**
   - Cada RF tiene `acceptance_criteria` con `test_reference`
   - Status debe cambiar de `Pending` → `Passed` al completar tests

3. **Generar Reportes de Cobertura:**
   ```python
   # Script para calcular % cobertura
   import yaml

   with open('TRACEABILITY-MGN-001.yaml') as f:
       data = yaml.safe_load(f)
       print(f"Cobertura RF→Tests: {data['coverage']['rf_to_tests']}")
   ```

### Para Desarrolladores

1. **Encontrar Implementación de un RF:**
   ```bash
   # Buscar RF específico
   grep -A 50 "RF-MGN-001-003" TRACEABILITY-MGN-001.yaml
   ```

2. **Ver Endpoints de un Módulo:**
   ```bash
   # Extraer todos los endpoints
   yq eval '.requirements[].et_backend.endpoints[]' TRACEABILITY-MGN-001.yaml
   ```

3. **Validar Reglas de Negocio:**
   - Cada RN tiene `implementation` (dónde está el código)
   - Cada RN tiene `test_reference` (dónde está el test)

### Para Project Managers

1. **Calcular Progreso:**
   ```bash
   # Contar RFs completados
   grep -c "status: Completed" TRACEABILITY-MGN-001.yaml
   ```

2. **Generar Burndown Chart:**
   - Usar `story_points` por módulo
   - Calcular velocity con RFs completados por sprint

3. **Identificar Dependencias:**
   - Ver `dependencies.module_dependencies` para orden de implementación
   - Ver `dependencies.rf_dependencies` para bloqueos

### Para Arquitectos

1. **Auditar Trazabilidad:**
   ```bash
   # Validar que cada RF tenga ET Backend y Frontend
   yq eval '.requirements[] | select(.et_backend == null or .et_frontend == null)' TRACEABILITY-*.yaml
   ```

2. **Analizar Complejidad:**
   - `total_endpoints` indica complejidad de API
   - `total_components` indica complejidad de UI
   - `total_test_cases` indica esfuerzo de testing

3. **Revisar Decisiones Técnicas:**
   - `external_dependencies` por módulo
   - `database_tables` y RLS policies
   - Patrones de arquitectura (FSD, DDD, etc.)

---

## Convenciones de Nomenclatura

### IDs de RF
- Formato: `RF-MGN-XXX-YYY`
- XXX: Número de módulo (001-014)
- YYY: Número secuencial de RF (001, 002, ...)
- Ejemplo: `RF-MGN-001-003` (Gestión de Usuarios en Fundamentos)

### Archivos de Especificación Técnica
- Backend: `ET-BACKEND-MGN-XXX-YYY-descripcion.md`
- Frontend: `ET-FRONTEND-MGN-XXX-YYY-descripcion.md`
- Ejemplo: `ET-BACKEND-MGN-001-003-gestión-de-usuarios.md`

### Endpoints de API
- Patrón: `/api/v1/{recurso}`
- Versionado: `/api/v1/`, `/api/v2/`
- Ejemplo: `/api/v1/auth/users`

### Rutas Frontend
- Patrón: `/{modulo}/{recurso}`
- Ejemplo: `/auth/users`, `/financial/invoices`

### Test Files
- Backend Unit: `{recurso}.service.spec.ts`
- Backend Integration: `{recurso}.controller.e2e-spec.ts`
- Frontend Component: `{Componente}.test.tsx`
- Frontend E2E: `{modulo}/{recurso}.spec.ts`

---

## Validación de Archivos YAML

### Verificar Sintaxis YAML
```bash
# Instalar yamllint
pip install yamllint

# Validar archivo
yamllint TRACEABILITY-MGN-001.yaml
```

### Validar Estructura con Schema
```bash
# Usar yq para validar estructura
yq eval '.module.id' TRACEABILITY-MGN-001.yaml
yq eval '.metadata.total_rf' TRACEABILITY-MGN-001.yaml
```

### Script de Validación Automática
```python
import yaml
import sys

def validate_traceability(file_path):
    with open(file_path) as f:
        data = yaml.safe_load(f)

    # Validar campos obligatorios
    assert 'module' in data
    assert 'metadata' in data
    assert 'requirements' in data
    assert 'coverage' in data

    # Validar cada RF
    for req in data['requirements']:
        assert 'rf_id' in req
        assert 'et_backend' in req
        assert 'et_frontend' in req
        assert 'database_tables' in req
        assert 'tests' in req
        assert 'acceptance_criteria' in req
        assert 'business_rules' in req

    # Validar cobertura 100%
    assert data['coverage']['rf_to_et_backend'] == '100%'
    assert data['coverage']['rf_to_et_frontend'] == '100%'

    print(f"✅ {file_path} válido")

if __name__ == '__main__':
    validate_traceability(sys.argv[1])
```

---

## Generación de Reportes

### Reporte de Cobertura Global
```python
import yaml
import glob

def generate_coverage_report():
    total_rf = 0
    total_tests = 0

    for file in glob.glob('TRACEABILITY-MGN-*.yaml'):
        with open(file) as f:
            data = yaml.safe_load(f)
            total_rf += data['metadata']['total_rf']
            total_tests += data['metadata']['total_tests']

    print(f"Total RF: {total_rf}")
    print(f"Total Tests: {total_tests}")
    print(f"Tests por RF: {total_tests / total_rf:.2f}")
```

### Reporte de Dependencias
```python
def analyze_dependencies():
    dependencies_graph = {}

    for file in glob.glob('TRACEABILITY-MGN-*.yaml'):
        with open(file) as f:
            data = yaml.safe_load(f)
            module_id = data['module']['id']

            for req in data['requirements']:
                if req['dependencies']['module_dependencies']:
                    dependencies_graph[module_id] = req['dependencies']['module_dependencies']

    return dependencies_graph
```

---

## Integración con CI/CD

### GitHub Actions Workflow
```yaml
name: Validate Traceability Matrices

on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Install yamllint
        run: pip install yamllint

      - name: Validate YAML syntax
        run: yamllint docs/02-modelado/trazabilidad/*.yaml

      - name: Validate structure
        run: python scripts/validate_traceability.py docs/02-modelado/trazabilidad/*.yaml

      - name: Generate coverage report
        run: python scripts/generate_coverage_report.py
```

---

## Estadísticas Globales del Proyecto

### Resumen por Prioridad
| Prioridad | Módulos | RF | Story Points | % Total |
|-----------|---------|-----|--------------|---------|
| **P0 (MVP)** | 8 | 52 | 462 SP | 69% |
| **P1 (Post-MVP)** | 6 | 23 | 169 SP | 25% |
| **P2 (Futuro)** | - | 5 | 42 SP | 6% |
| **TOTAL** | **14** | **80** | **673 SP** | **100%** |

### Distribución de RF por Módulo
```
MGN-001 (Fundamentos):       ████████ 8 RF (68 SP)
MGN-002 (Empresas):          █████ 5 RF (34 SP)
MGN-003 (Catálogos):         ██████ 6 RF (29 SP)
MGN-004 (Financiero):        ████████ 8 RF (81 SP)
MGN-005 (Inventario):        ███████ 7 RF (66 SP)
MGN-006 (Compras):           ██████ 6 RF (42 SP)
MGN-007 (Ventas):            ██████ 6 RF (45 SP)
MGN-008 (Analítica):         █████ 5 RF (35 SP)
MGN-009 (CRM):               █████ 5 RF (31 SP)
MGN-010 (RRHH):              █████ 5 RF (29 SP)
MGN-011 (Proyectos):         █████ 5 RF (40 SP)
MGN-012 (Reportes):          ████ 4 RF (39 SP)
MGN-013 (Portal):            ████ 4 RF (29 SP)
MGN-014 (Mensajería):        ██████ 6 RF (47 SP)
```

### Estimaciones de Duración
- **Velocity estimada:** 20 SP/sprint (equipo 5 personas)
- **Duración MVP (P0):** ~23 sprints = **46 semanas** (11.5 meses)
- **Duración total (P0+P1):** ~34 sprints = **68 semanas** (17 meses)
- **Sprint duration:** 2 semanas

---

## Próximos Pasos

1. **✅ Fase 2 - Diseño Completado:**
   - Domain Models (9 archivos) ✅
   - Database Design (10 archivos, 93 tablas) ✅
   - Requerimientos Funcionales (80 archivos) ✅
   - Especificaciones Técnicas (160 archivos) ✅
   - Matrices de Trazabilidad (14 archivos) ⏳ **EN PROGRESO**

2. **Fase 3 - Implementación (Próxima):**
   - Setup de proyectos (NestJS + React)
   - Implementación por sprints (comenzar con MGN-001)
   - TDD: Tests → Implementación → Refactor
   - Code reviews por módulo
   - QA testing continuo

3. **Herramientas Recomendadas:**
   - **Gestión de Tareas:** Jira, Linear, GitHub Projects
   - **Testing:** Jest, Vitest, Playwright, Cypress
   - **CI/CD:** GitHub Actions, GitLab CI, Jenkins
   - **Monitoreo:** Sentry, DataDog, New Relic
   - **Documentación:** Swagger, Storybook, Docusaurus

---

## Contacto y Soporte

Para dudas o issues relacionados con las matrices de trazabilidad:
- **GitHub Issues:** [Link al repositorio]
- **Slack Channel:** #erp-generico-qa
- **Email:** qa-team@example.com

---

**Documento creado:** 2025-11-24
**Versión:** 1.0
**Autor:** QA Architect / Traceability Specialist
**Estado:** ✅ **1/14 Matrices Completadas** (MGN-001)
**Próximo:** Completar MGN-002 a MGN-014