# TRACEABILITY.yml - MGN-008: Notifications
# Matriz de trazabilidad: Documentacion -> Codigo
# Ubicacion: docs/02-fase-core-business/MGN-008-notifications/implementacion/

epic_code: MGN-008
epic_name: Notifications
phase: 2
phase_name: Core Business
story_points: 25
status: rf_documented

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

documentation:

  requirements:
    - id: RF-NOTIF-001
      title: Notificaciones In-App
      file: ../requerimientos/RF-NOTIF-001.md
      priority: P0
      story_points: 8
      status: documented
      traces_to:
        tables: [notifications]
        services: [InAppService, NotificationsGateway]
        endpoints: [GET /api/v1/notifications, PUT /api/v1/notifications/:id/read]

    - id: RF-NOTIF-002
      title: Notificaciones Email
      file: ../requerimientos/RF-NOTIF-002.md
      priority: P0
      story_points: 8
      status: documented
      traces_to:
        tables: [notification_templates, notification_queue, notification_logs]
        services: [EmailService, TemplateService]
        endpoints: [GET /api/v1/notifications/templates, POST /api/v1/notifications/templates]

    - id: RF-NOTIF-003
      title: Notificaciones Push
      file: ../requerimientos/RF-NOTIF-003.md
      priority: P1
      story_points: 5
      status: documented
      traces_to:
        tables: [push_subscriptions, notification_queue]
        services: [PushService]
        endpoints: [POST /api/v1/notifications/push/subscribe, DELETE /api/v1/notifications/push/unsubscribe]

    - id: RF-NOTIF-004
      title: Preferencias de Notificacion
      file: ../requerimientos/RF-NOTIF-004.md
      priority: P1
      story_points: 5
      status: documented
      traces_to:
        tables: [notification_preferences]
        services: [PreferencesService]
        endpoints: [GET /api/v1/notifications/preferences, PUT /api/v1/notifications/preferences]

  specifications: []
  # Pendiente de documentacion

  user_stories: []
  # Pendiente de documentacion

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

implementation:

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

    tables:
      - name: notifications
        file: apps/database/ddl/schemas/core_notifications/tables/notifications.sql
        status: pending
        requirement: RF-NOTIF-001
        columns:
          - {name: id, type: UUID, pk: true}
          - {name: tenant_id, type: UUID, fk: tenants}
          - {name: user_id, type: UUID, fk: users}
          - {name: type, type: VARCHAR(50)}
          - {name: category, type: VARCHAR(50)}
          - {name: priority, type: VARCHAR(20)}
          - {name: title, type: VARCHAR(255)}
          - {name: message, type: TEXT}
          - {name: data, type: JSONB}
          - {name: action_url, type: VARCHAR(500)}
          - {name: is_read, type: BOOLEAN, default: false}
          - {name: read_at, type: TIMESTAMPTZ}
          - {name: expires_at, type: TIMESTAMPTZ}
          - {name: created_at, type: TIMESTAMPTZ}

      - name: notification_templates
        file: apps/database/ddl/schemas/core_notifications/tables/notification_templates.sql
        status: pending
        requirement: RF-NOTIF-002
        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: channel, type: VARCHAR(20)}
          - {name: locale, type: VARCHAR(10)}
          - {name: subject, type: VARCHAR(255)}
          - {name: body_html, type: TEXT}
          - {name: body_text, type: TEXT}
          - {name: variables, 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: notification_queue
        file: apps/database/ddl/schemas/core_notifications/tables/notification_queue.sql
        status: pending
        requirements: [RF-NOTIF-002, RF-NOTIF-003]
        columns:
          - {name: id, type: UUID, pk: true}
          - {name: tenant_id, type: UUID, fk: tenants}
          - {name: notification_id, type: UUID, fk: notifications}
          - {name: channel, type: VARCHAR(20)}
          - {name: recipient, type: VARCHAR(255)}
          - {name: payload, type: JSONB}
          - {name: status, type: VARCHAR(20)}
          - {name: attempts, type: INTEGER, default: 0}
          - {name: max_attempts, type: INTEGER, default: 3}
          - {name: scheduled_at, type: TIMESTAMPTZ}
          - {name: sent_at, type: TIMESTAMPTZ}
          - {name: error, type: TEXT}
          - {name: created_at, type: TIMESTAMPTZ}

      - name: push_subscriptions
        file: apps/database/ddl/schemas/core_notifications/tables/push_subscriptions.sql
        status: pending
        requirement: RF-NOTIF-003
        columns:
          - {name: id, type: UUID, pk: true}
          - {name: user_id, type: UUID, fk: users}
          - {name: device_id, type: VARCHAR(255)}
          - {name: platform, type: VARCHAR(20)}
          - {name: endpoint, type: TEXT}
          - {name: keys, type: JSONB}
          - {name: is_active, type: BOOLEAN, default: true}
          - {name: last_used_at, type: TIMESTAMPTZ}
          - {name: created_at, type: TIMESTAMPTZ}

      - name: notification_preferences
        file: apps/database/ddl/schemas/core_notifications/tables/notification_preferences.sql
        status: pending
        requirement: RF-NOTIF-004
        columns:
          - {name: id, type: UUID, pk: true}
          - {name: user_id, type: UUID, fk: users}
          - {name: notification_type, type: VARCHAR(50)}
          - {name: channel_inapp, type: BOOLEAN, default: true}
          - {name: channel_email, type: BOOLEAN, default: true}
          - {name: channel_push, type: BOOLEAN, default: true}
          - {name: quiet_hours_start, type: TIME}
          - {name: quiet_hours_end, type: TIME}
          - {name: digest_enabled, type: BOOLEAN, default: false}
          - {name: digest_frequency, type: VARCHAR(20)}
          - {name: created_at, type: TIMESTAMPTZ}
          - {name: updated_at, type: TIMESTAMPTZ}

      - name: notification_logs
        file: apps/database/ddl/schemas/core_notifications/tables/notification_logs.sql
        status: pending
        requirement: RF-NOTIF-002
        columns:
          - {name: id, type: UUID, pk: true}
          - {name: queue_id, type: UUID, fk: notification_queue}
          - {name: event, type: VARCHAR(50)}
          - {name: metadata, type: JSONB}
          - {name: created_at, type: TIMESTAMPTZ}

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

    entities:
      - name: Notification
        file: apps/backend/src/modules/notifications/entities/notification.entity.ts
        status: pending
        requirement: RF-NOTIF-001

      - name: NotificationTemplate
        file: apps/backend/src/modules/notifications/entities/notification-template.entity.ts
        status: pending
        requirement: RF-NOTIF-002

      - name: NotificationQueue
        file: apps/backend/src/modules/notifications/entities/notification-queue.entity.ts
        status: pending
        requirements: [RF-NOTIF-002, RF-NOTIF-003]

      - name: PushSubscription
        file: apps/backend/src/modules/notifications/entities/push-subscription.entity.ts
        status: pending
        requirement: RF-NOTIF-003

      - name: NotificationPreference
        file: apps/backend/src/modules/notifications/entities/notification-preference.entity.ts
        status: pending
        requirement: RF-NOTIF-004

    services:
      - name: NotificationsService
        file: apps/backend/src/modules/notifications/notifications.service.ts
        status: pending
        requirements: [RF-NOTIF-001, RF-NOTIF-002, RF-NOTIF-003]
        methods:
          - {name: send, description: Enviar notificacion}
          - {name: sendBulk, description: Enviar notificacion masiva}
          - {name: getUserNotifications, description: Obtener notificaciones de usuario}

      - name: InAppService
        file: apps/backend/src/modules/notifications/channels/in-app.service.ts
        status: pending
        requirement: RF-NOTIF-001
        methods:
          - {name: create, description: Crear notificacion in-app}
          - {name: markAsRead, description: Marcar como leida}
          - {name: getUnreadCount, description: Obtener conteo de no leidas}

      - name: EmailService
        file: apps/backend/src/modules/notifications/channels/email.service.ts
        status: pending
        requirement: RF-NOTIF-002
        methods:
          - {name: send, description: Enviar email}
          - {name: sendWithTemplate, description: Enviar con template}
          - {name: sendBulk, description: Enviar emails masivos}

      - name: PushService
        file: apps/backend/src/modules/notifications/channels/push.service.ts
        status: pending
        requirement: RF-NOTIF-003
        methods:
          - {name: send, description: Enviar push notification}
          - {name: subscribe, description: Registrar suscripcion}
          - {name: unsubscribe, description: Eliminar suscripcion}

      - name: PreferencesService
        file: apps/backend/src/modules/notifications/preferences.service.ts
        status: pending
        requirement: RF-NOTIF-004
        methods:
          - {name: getPreferences, description: Obtener preferencias}
          - {name: updatePreferences, description: Actualizar preferencias}
          - {name: shouldNotify, description: Verificar si debe notificar}

    gateways:
      - name: NotificationsGateway
        file: apps/backend/src/modules/notifications/notifications.gateway.ts
        status: pending
        requirement: RF-NOTIF-001
        description: WebSocket gateway para notificaciones en tiempo real

    controllers:
      - name: NotificationsController
        file: apps/backend/src/modules/notifications/notifications.controller.ts
        status: pending
        endpoints:
          - method: GET
            path: /api/v1/notifications
            description: Listar notificaciones del usuario
            requirement: RF-NOTIF-001

          - method: GET
            path: /api/v1/notifications/unread/count
            description: Obtener conteo de no leidas
            requirement: RF-NOTIF-001

          - method: PUT
            path: /api/v1/notifications/:id/read
            description: Marcar como leida
            requirement: RF-NOTIF-001

          - method: PUT
            path: /api/v1/notifications/read-all
            description: Marcar todas como leidas
            requirement: RF-NOTIF-001

          - method: GET
            path: /api/v1/notifications/templates
            description: Listar templates
            requirement: RF-NOTIF-002

          - method: POST
            path: /api/v1/notifications/templates
            description: Crear template
            requirement: RF-NOTIF-002

          - method: POST
            path: /api/v1/notifications/push/subscribe
            description: Suscribir a push
            requirement: RF-NOTIF-003

          - method: DELETE
            path: /api/v1/notifications/push/unsubscribe
            description: Desuscribir de push
            requirement: RF-NOTIF-003

          - method: GET
            path: /api/v1/notifications/preferences
            description: Obtener preferencias
            requirement: RF-NOTIF-004

          - method: PUT
            path: /api/v1/notifications/preferences
            description: Actualizar preferencias
            requirement: RF-NOTIF-004

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

dependencies:
  depends_on:
    - module: MGN-001
      type: hard
      reason: Autenticacion requerida
    - module: MGN-002
      type: hard
      reason: Referencia a usuarios
    - module: MGN-004
      type: hard
      reason: Aislamiento por tenant
    - module: MGN-006
      type: soft
      reason: Configuracion de canales

  required_by:
    - module: BUSINESS_MODULES
      type: soft
      reason: Modulos de negocio envian notificaciones

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

metrics:
  story_points:
    estimated: 25
    actual: null

  documentation:
    requirements: 4
    specifications: 0
    user_stories: 0

  files:
    database: 6
    backend: 12
    frontend: 5
    total: 23

# =============================================================================
# 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-NOTIF-001: Notificaciones In-App"
      - "RF-NOTIF-002: Notificaciones Email"
      - "RF-NOTIF-003: Notificaciones Push"
      - "RF-NOTIF-004: Preferencias de Notificacion"
      - "Actualizacion de trazabilidad RF -> implementacion"
