# TRACEABILITY.yml - MGN-006: Settings
# Matriz de trazabilidad: Documentacion -> Codigo
# Ubicacion: docs/02-fase-core-business/MGN-006-settings/implementacion/

epic_code: MGN-006
epic_name: Settings
phase: 2
phase_name: Core Business
story_points: 25
status: rf_documented

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

documentation:

  requirements:
    - id: RF-SETTINGS-001
      title: Configuracion del Sistema
      file: ../requerimientos/RF-SETTINGS-001.md
      priority: P0
      story_points: 8
      status: documented
      traces_to:
        tables: [system_settings]
        services: [SystemSettingsService]
        endpoints: [GET /api/v1/settings/system, PUT /api/v1/settings/system/:key]

    - id: RF-SETTINGS-002
      title: Configuracion por Tenant
      file: ../requerimientos/RF-SETTINGS-002.md
      priority: P0
      story_points: 8
      status: documented
      traces_to:
        tables: [tenant_settings]
        services: [TenantSettingsService]
        endpoints: [GET /api/v1/settings/tenant, PUT /api/v1/settings/tenant/:key]

    - id: RF-SETTINGS-003
      title: Preferencias de Usuario
      file: ../requerimientos/RF-SETTINGS-003.md
      priority: P1
      story_points: 5
      status: documented
      traces_to:
        tables: [user_preferences]
        services: [UserPreferencesService]
        endpoints: [GET /api/v1/settings/user/preferences, PUT /api/v1/settings/user/preferences]

    - id: RF-SETTINGS-004
      title: Feature Flags
      file: ../requerimientos/RF-SETTINGS-004.md
      priority: P1
      story_points: 5
      status: documented
      traces_to:
        tables: [feature_flags, feature_flag_rules]
        services: [FeatureFlagsService]
        endpoints: [GET /api/v1/settings/features, GET /api/v1/settings/features/:key/evaluate]

  specifications: []
  # Pendiente de documentacion

  user_stories: []
  # Pendiente de documentacion

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

implementation:

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

    tables:
      - name: system_settings
        file: apps/database/ddl/schemas/core_settings/tables/system_settings.sql
        status: pending
        requirement: RF-SETTINGS-001
        columns:
          - {name: id, type: UUID, pk: true}
          - {name: category, type: VARCHAR(50)}
          - {name: key, type: VARCHAR(100), unique: true}
          - {name: value, type: JSONB}
          - {name: value_type, type: VARCHAR(20)}
          - {name: description, type: TEXT}
          - {name: is_sensitive, type: BOOLEAN, default: false}
          - {name: is_editable, type: BOOLEAN, default: true}
          - {name: created_at, type: TIMESTAMPTZ}
          - {name: updated_at, type: TIMESTAMPTZ}

      - name: tenant_settings
        file: apps/database/ddl/schemas/core_settings/tables/tenant_settings.sql
        status: pending
        requirement: RF-SETTINGS-002
        columns:
          - {name: id, type: UUID, pk: true}
          - {name: tenant_id, type: UUID, fk: tenants}
          - {name: category, type: VARCHAR(50)}
          - {name: key, type: VARCHAR(100)}
          - {name: value, type: JSONB}
          - {name: source, type: VARCHAR(20)}
          - {name: created_at, type: TIMESTAMPTZ}
          - {name: updated_at, type: TIMESTAMPTZ}

      - name: user_preferences
        file: apps/database/ddl/schemas/core_settings/tables/user_preferences.sql
        status: pending
        requirement: RF-SETTINGS-003
        columns:
          - {name: id, type: UUID, pk: true}
          - {name: user_id, type: UUID, fk: users}
          - {name: category, type: VARCHAR(50)}
          - {name: key, type: VARCHAR(100)}
          - {name: value, type: JSONB}
          - {name: created_at, type: TIMESTAMPTZ}
          - {name: updated_at, type: TIMESTAMPTZ}

      - name: feature_flags
        file: apps/database/ddl/schemas/core_settings/tables/feature_flags.sql
        status: pending
        requirement: RF-SETTINGS-004
        columns:
          - {name: id, type: UUID, pk: true}
          - {name: key, type: VARCHAR(100), unique: true}
          - {name: name, type: VARCHAR(255)}
          - {name: description, type: TEXT}
          - {name: flag_type, type: VARCHAR(20)}
          - {name: default_value, type: JSONB}
          - {name: is_active, type: BOOLEAN, default: true}
          - {name: created_at, type: TIMESTAMPTZ}
          - {name: updated_at, type: TIMESTAMPTZ}

      - name: feature_flag_rules
        file: apps/database/ddl/schemas/core_settings/tables/feature_flag_rules.sql
        status: pending
        requirement: RF-SETTINGS-004
        columns:
          - {name: id, type: UUID, pk: true}
          - {name: flag_id, type: UUID, fk: feature_flags}
          - {name: rule_type, type: VARCHAR(50)}
          - {name: conditions, type: JSONB}
          - {name: value, type: JSONB}
          - {name: priority, type: INTEGER}
          - {name: is_active, type: BOOLEAN, default: true}

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

    entities:
      - name: SystemSetting
        file: apps/backend/src/modules/settings/entities/system-setting.entity.ts
        status: pending
        requirement: RF-SETTINGS-001

      - name: TenantSetting
        file: apps/backend/src/modules/settings/entities/tenant-setting.entity.ts
        status: pending
        requirement: RF-SETTINGS-002

      - name: UserPreference
        file: apps/backend/src/modules/settings/entities/user-preference.entity.ts
        status: pending
        requirement: RF-SETTINGS-003

      - name: FeatureFlag
        file: apps/backend/src/modules/settings/entities/feature-flag.entity.ts
        status: pending
        requirement: RF-SETTINGS-004

    services:
      - name: SystemSettingsService
        file: apps/backend/src/modules/settings/system-settings.service.ts
        status: pending
        requirement: RF-SETTINGS-001
        methods:
          - {name: getAll, description: Obtener todas las configuraciones}
          - {name: get, description: Obtener configuracion por key}
          - {name: set, description: Actualizar configuracion}

      - name: TenantSettingsService
        file: apps/backend/src/modules/settings/tenant-settings.service.ts
        status: pending
        requirement: RF-SETTINGS-002
        methods:
          - {name: getEffective, description: Obtener configuracion efectiva}
          - {name: get, description: Obtener configuracion del tenant}
          - {name: set, description: Actualizar configuracion}

      - name: UserPreferencesService
        file: apps/backend/src/modules/settings/user-preferences.service.ts
        status: pending
        requirement: RF-SETTINGS-003
        methods:
          - {name: getAll, description: Obtener todas las preferencias}
          - {name: set, description: Actualizar preferencia}
          - {name: reset, description: Restablecer a valores por defecto}

      - name: FeatureFlagsService
        file: apps/backend/src/modules/settings/feature-flags.service.ts
        status: pending
        requirement: RF-SETTINGS-004
        methods:
          - {name: isEnabled, description: Verificar si feature esta habilitado}
          - {name: evaluate, description: Evaluar feature flag con contexto}
          - {name: getAll, description: Obtener todos los feature flags}

    controllers:
      - name: SettingsController
        file: apps/backend/src/modules/settings/settings.controller.ts
        status: pending
        endpoints:
          - method: GET
            path: /api/v1/settings/system
            description: Obtener configuraciones del sistema
            requirement: RF-SETTINGS-001

          - method: PUT
            path: /api/v1/settings/system/:key
            description: Actualizar configuracion del sistema
            requirement: RF-SETTINGS-001

          - method: GET
            path: /api/v1/settings/tenant
            description: Obtener configuraciones del tenant
            requirement: RF-SETTINGS-002

          - method: PUT
            path: /api/v1/settings/tenant/:key
            description: Actualizar configuracion del tenant
            requirement: RF-SETTINGS-002

          - method: GET
            path: /api/v1/settings/user/preferences
            description: Obtener preferencias del usuario
            requirement: RF-SETTINGS-003

          - method: PUT
            path: /api/v1/settings/user/preferences
            description: Actualizar preferencias del usuario
            requirement: RF-SETTINGS-003

          - method: GET
            path: /api/v1/settings/features
            description: Listar feature flags
            requirement: RF-SETTINGS-004

          - method: GET
            path: /api/v1/settings/features/:key/evaluate
            description: Evaluar feature flag
            requirement: RF-SETTINGS-004

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

dependencies:
  depends_on:
    - module: MGN-001
      type: hard
      reason: Autenticacion requerida
    - module: MGN-004
      type: hard
      reason: Aislamiento por tenant

  required_by:
    - module: ALL
      type: soft
      reason: Todos los modulos consumen configuraciones

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

metrics:
  story_points:
    estimated: 25
    actual: null

  documentation:
    requirements: 4
    specifications: 0
    user_stories: 0

  files:
    database: 5
    backend: 8
    frontend: 4
    total: 17

# =============================================================================
# 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-SETTINGS-001: Configuracion del Sistema"
      - "RF-SETTINGS-002: Configuracion por Tenant"
      - "RF-SETTINGS-003: Preferencias de Usuario"
      - "RF-SETTINGS-004: Feature Flags"
      - "Actualizacion de trazabilidad RF -> implementacion"
