workspace-v1/projects/erp-core/docs/04-modelado/trazabilidad

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	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

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)

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

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:

   # 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:

   # 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:

   # Buscar RF específico
   grep -A 50 "RF-MGN-001-003" TRACEABILITY-MGN-001.yaml
   

2. Ver Endpoints de un Módulo:

   # 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:

   # 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:

   # 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

# Instalar yamllint
pip install yamllint

# Validar archivo
yamllint TRACEABILITY-MGN-001.yaml

Validar Estructura con Schema

# 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

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

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

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

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