# TRACEABILITY.yml - MGN-009: Reports
# Matriz de trazabilidad: Documentacion -> Codigo
# Ubicacion: docs/02-fase-core-business/MGN-009-reports/implementacion/

epic_code: MGN-009
epic_name: Reports
phase: 2
phase_name: Core Business
story_points: 35
status: rf_documented

# =============================================================================
# DOCUMENTACION
# =============================================================================

documentation:

  requirements:
    - id: RF-REPORT-001
      title: Reportes Predefinidos
      file: ../requerimientos/RF-REPORT-001.md
      priority: P0
      story_points: 10
      status: documented
      traces_to:
        tables: [report_definitions, report_executions]
        services: [ReportsService, ExportService]
        endpoints: [GET /api/v1/reports, POST /api/v1/reports/:id/execute, GET /api/v1/reports/:id/export/:format]

    - id: RF-REPORT-002
      title: Dashboards
      file: ../requerimientos/RF-REPORT-002.md
      priority: P0
      story_points: 10
      status: documented
      traces_to:
        tables: [dashboards, dashboard_widgets]
        services: [DashboardsService, WidgetService]
        endpoints: [GET /api/v1/dashboards, POST /api/v1/dashboards, GET /api/v1/dashboards/:id/data]

    - id: RF-REPORT-003
      title: Report Builder
      file: ../requerimientos/RF-REPORT-003.md
      priority: P1
      story_points: 10
      status: documented
      traces_to:
        tables: [custom_reports]
        services: [ReportBuilderService, QueryBuilderService]
        endpoints: [POST /api/v1/reports/builder/preview, POST /api/v1/reports/builder/save]

    - id: RF-REPORT-004
      title: Reportes Programados
      file: ../requerimientos/RF-REPORT-004.md
      priority: P1
      story_points: 5
      status: documented
      traces_to:
        tables: [report_schedules, report_recipients]
        services: [SchedulerService]
        endpoints: [GET /api/v1/reports/schedules, POST /api/v1/reports/:id/schedule]

  specifications: []
  # Pendiente de documentacion

  user_stories: []
  # Pendiente de documentacion

# =============================================================================
# IMPLEMENTACION
# =============================================================================

implementation:

  database:
    schema: core_reports
    path: apps/database/ddl/schemas/core_reports/
    status: pending

    tables:
      - name: report_definitions
        file: apps/database/ddl/schemas/core_reports/tables/report_definitions.sql
        status: pending
        requirement: RF-REPORT-001
        columns:
          - {name: id, type: UUID, pk: true}
          - {name: tenant_id, type: UUID, fk: tenants, nullable: true}
          - {name: code, type: VARCHAR(100)}
          - {name: name, type: VARCHAR(255)}
          - {name: description, type: TEXT}
          - {name: category, type: VARCHAR(50)}
          - {name: query, type: TEXT}
          - {name: parameters, type: JSONB}
          - {name: columns, type: JSONB}
          - {name: default_filters, type: JSONB}
          - {name: export_formats, type: JSONB}
          - {name: is_system, type: BOOLEAN, default: false}
          - {name: is_active, type: BOOLEAN, default: true}
          - {name: created_at, type: TIMESTAMPTZ}
          - {name: updated_at, type: TIMESTAMPTZ}

      - name: report_executions
        file: apps/database/ddl/schemas/core_reports/tables/report_executions.sql
        status: pending
        requirement: RF-REPORT-001
        columns:
          - {name: id, type: UUID, pk: true}
          - {name: tenant_id, type: UUID, fk: tenants}
          - {name: report_id, type: UUID, fk: report_definitions}
          - {name: schedule_id, type: UUID, fk: report_schedules, nullable: true}
          - {name: user_id, type: UUID, fk: users}
          - {name: parameters, type: JSONB}
          - {name: status, type: VARCHAR(20)}
          - {name: file_url, type: TEXT}
          - {name: file_format, type: VARCHAR(20)}
          - {name: row_count, type: INTEGER}
          - {name: duration_ms, type: INTEGER}
          - {name: error, type: TEXT}
          - {name: created_at, type: TIMESTAMPTZ}
          - {name: completed_at, type: TIMESTAMPTZ}

      - name: dashboards
        file: apps/database/ddl/schemas/core_reports/tables/dashboards.sql
        status: pending
        requirement: RF-REPORT-002
        columns:
          - {name: id, type: UUID, pk: true}
          - {name: tenant_id, type: UUID, fk: tenants}
          - {name: user_id, type: UUID, fk: users}
          - {name: name, type: VARCHAR(255)}
          - {name: description, type: TEXT}
          - {name: layout, type: JSONB}
          - {name: refresh_interval, type: INTEGER}
          - {name: is_default, type: BOOLEAN, default: false}
          - {name: is_shared, type: BOOLEAN, default: false}
          - {name: shared_with, type: JSONB}
          - {name: created_at, type: TIMESTAMPTZ}
          - {name: updated_at, type: TIMESTAMPTZ}

      - name: dashboard_widgets
        file: apps/database/ddl/schemas/core_reports/tables/dashboard_widgets.sql
        status: pending
        requirement: RF-REPORT-002
        columns:
          - {name: id, type: UUID, pk: true}
          - {name: dashboard_id, type: UUID, fk: dashboards}
          - {name: widget_type, type: VARCHAR(50)}
          - {name: title, type: VARCHAR(255)}
          - {name: data_source, type: JSONB}
          - {name: config, type: JSONB}
          - {name: position, type: JSONB}
          - {name: refresh_interval, type: INTEGER}
          - {name: created_at, type: TIMESTAMPTZ}
          - {name: updated_at, type: TIMESTAMPTZ}

      - name: custom_reports
        file: apps/database/ddl/schemas/core_reports/tables/custom_reports.sql
        status: pending
        requirement: RF-REPORT-003
        columns:
          - {name: id, type: UUID, pk: true}
          - {name: tenant_id, type: UUID, fk: tenants}
          - {name: user_id, type: UUID, fk: users}
          - {name: name, type: VARCHAR(255)}
          - {name: description, type: TEXT}
          - {name: data_sources, type: JSONB}
          - {name: columns, type: JSONB}
          - {name: filters, type: JSONB}
          - {name: grouping, type: JSONB}
          - {name: sorting, type: JSONB}
          - {name: is_shared, type: BOOLEAN, default: false}
          - {name: created_at, type: TIMESTAMPTZ}
          - {name: updated_at, type: TIMESTAMPTZ}

      - name: report_schedules
        file: apps/database/ddl/schemas/core_reports/tables/report_schedules.sql
        status: pending
        requirement: RF-REPORT-004
        columns:
          - {name: id, type: UUID, pk: true}
          - {name: tenant_id, type: UUID, fk: tenants}
          - {name: report_id, type: UUID, fk: report_definitions}
          - {name: name, type: VARCHAR(255)}
          - {name: cron_expression, type: VARCHAR(100)}
          - {name: timezone, type: VARCHAR(50)}
          - {name: parameters, type: JSONB}
          - {name: export_format, type: VARCHAR(20)}
          - {name: is_active, type: BOOLEAN, default: true}
          - {name: last_run_at, type: TIMESTAMPTZ}
          - {name: next_run_at, type: TIMESTAMPTZ}
          - {name: created_by, type: UUID, fk: users}
          - {name: created_at, type: TIMESTAMPTZ}

      - name: report_recipients
        file: apps/database/ddl/schemas/core_reports/tables/report_recipients.sql
        status: pending
        requirement: RF-REPORT-004
        columns:
          - {name: id, type: UUID, pk: true}
          - {name: schedule_id, type: UUID, fk: report_schedules}
          - {name: recipient_type, type: VARCHAR(20)}
          - {name: recipient_id, type: UUID}
          - {name: email, type: VARCHAR(255)}
          - {name: created_at, type: TIMESTAMPTZ}

  backend:
    module: reports
    path: apps/backend/src/modules/reports/
    framework: NestJS
    status: pending

    entities:
      - name: ReportDefinition
        file: apps/backend/src/modules/reports/entities/report-definition.entity.ts
        status: pending
        requirement: RF-REPORT-001

      - name: ReportExecution
        file: apps/backend/src/modules/reports/entities/report-execution.entity.ts
        status: pending
        requirement: RF-REPORT-001

      - name: Dashboard
        file: apps/backend/src/modules/reports/entities/dashboard.entity.ts
        status: pending
        requirement: RF-REPORT-002

      - name: DashboardWidget
        file: apps/backend/src/modules/reports/entities/dashboard-widget.entity.ts
        status: pending
        requirement: RF-REPORT-002

      - name: CustomReport
        file: apps/backend/src/modules/reports/entities/custom-report.entity.ts
        status: pending
        requirement: RF-REPORT-003

      - name: ReportSchedule
        file: apps/backend/src/modules/reports/entities/report-schedule.entity.ts
        status: pending
        requirement: RF-REPORT-004

    services:
      - name: ReportsService
        file: apps/backend/src/modules/reports/reports.service.ts
        status: pending
        requirement: RF-REPORT-001
        methods:
          - {name: execute, description: Ejecutar reporte}
          - {name: getAvailable, description: Listar reportes disponibles}
          - {name: getExecution, description: Obtener resultado de ejecucion}

      - name: ExportService
        file: apps/backend/src/modules/reports/export.service.ts
        status: pending
        requirement: RF-REPORT-001
        methods:
          - {name: toPdf, description: Exportar a PDF}
          - {name: toExcel, description: Exportar a Excel}
          - {name: toCsv, description: Exportar a CSV}

      - name: DashboardsService
        file: apps/backend/src/modules/reports/dashboards.service.ts
        status: pending
        requirement: RF-REPORT-002
        methods:
          - {name: create, description: Crear dashboard}
          - {name: update, description: Actualizar dashboard}
          - {name: getData, description: Obtener datos de widgets}

      - name: WidgetService
        file: apps/backend/src/modules/reports/widget.service.ts
        status: pending
        requirement: RF-REPORT-002
        methods:
          - {name: getData, description: Obtener datos de widget}
          - {name: getAvailableTypes, description: Listar tipos de widgets}

      - name: ReportBuilderService
        file: apps/backend/src/modules/reports/report-builder.service.ts
        status: pending
        requirement: RF-REPORT-003
        methods:
          - {name: preview, description: Vista previa de reporte}
          - {name: save, description: Guardar reporte personalizado}
          - {name: getDataSources, description: Obtener fuentes de datos}

      - name: SchedulerService
        file: apps/backend/src/modules/reports/scheduler.service.ts
        status: pending
        requirement: RF-REPORT-004
        methods:
          - {name: schedule, description: Programar reporte}
          - {name: cancel, description: Cancelar programacion}
          - {name: executeScheduled, description: Ejecutar reportes programados}

    controllers:
      - name: ReportsController
        file: apps/backend/src/modules/reports/reports.controller.ts
        status: pending
        endpoints:
          - method: GET
            path: /api/v1/reports
            description: Listar reportes disponibles
            requirement: RF-REPORT-001

          - method: POST
            path: /api/v1/reports/:id/execute
            description: Ejecutar reporte
            requirement: RF-REPORT-001

          - method: GET
            path: /api/v1/reports/:id/export/:format
            description: Exportar reporte
            requirement: RF-REPORT-001

          - method: GET
            path: /api/v1/dashboards
            description: Listar dashboards
            requirement: RF-REPORT-002

          - method: POST
            path: /api/v1/dashboards
            description: Crear dashboard
            requirement: RF-REPORT-002

          - method: GET
            path: /api/v1/dashboards/:id/data
            description: Obtener datos de dashboard
            requirement: RF-REPORT-002

          - method: POST
            path: /api/v1/reports/builder/preview
            description: Vista previa de reporte
            requirement: RF-REPORT-003

          - method: POST
            path: /api/v1/reports/builder/save
            description: Guardar reporte personalizado
            requirement: RF-REPORT-003

          - method: GET
            path: /api/v1/reports/schedules
            description: Listar reportes programados
            requirement: RF-REPORT-004

          - method: POST
            path: /api/v1/reports/:id/schedule
            description: Programar reporte
            requirement: RF-REPORT-004

# =============================================================================
# DEPENDENCIAS
# =============================================================================

dependencies:
  depends_on:
    - module: MGN-001
      type: hard
      reason: Autenticacion requerida
    - module: MGN-004
      type: hard
      reason: Aislamiento por tenant
    - module: MGN-008
      type: soft
      reason: Envio de reportes programados

  required_by:
    - module: VERTICALS
      type: soft
      reason: Verticales extienden con reportes especificos

# =============================================================================
# METRICAS
# =============================================================================

metrics:
  story_points:
    estimated: 35
    actual: null

  documentation:
    requirements: 4
    specifications: 0
    user_stories: 0

  files:
    database: 7
    backend: 14
    frontend: 8
    total: 29

# =============================================================================
# HISTORIAL
# =============================================================================

history:
  - date: "2025-12-05"
    action: "Creacion de estructura GAMILIT"
    author: Requirements-Analyst
    changes:
      - "Creacion de TRACEABILITY.yml"
      - "Definicion de estructura base"

  - date: "2025-12-05"
    action: "Documentacion de RF"
    author: Requirements-Analyst
    changes:
      - "RF-REPORT-001: Reportes Predefinidos"
      - "RF-REPORT-002: Dashboards"
      - "RF-REPORT-003: Report Builder"
      - "RF-REPORT-004: Reportes Programados"
      - "Actualizacion de trazabilidad RF -> implementacion"
