Logger_System.gs

/**
 * @file Logger_System.gs
 * @description Sistema centralizado de logging e tratamento de erros do EnSiSanar.
 *   Roteia mensagens para três destinos conforme nível de severidade:
 *
 *   Nível      │ console (Stackdriver) │ Aba SystemLogs │ E-mail admin
 *   ───────────┼──────────────────────┼────────────────┼──────────────
 *   DEBUG      │ console.log          │                │
 *   INFO       │ console.log          │                │
 *   WARN       │ console.warn         │ ✓              │
 *   ERROR      │ console.error        │ ✓              │ ✓ throttled (15 min)
 *   CRITICAL   │ console.error        │ ✓              │ ✓ imediato (sem throttle)
 *
 *   Principal entry point: Logger_System.logError(e, context)
 *     – Aceita qualquer Error object ou string.
 *     – Extrai mensagem, nome e stack automaticamente.
 *     – Roteia para Stackdriver + SystemLogs + e-mail ao admin.
 *
 *   Logger_System.logCritical(e, context)
 *     – Igual ao logError mas classifica como CRITICAL e ignora throttle.
 *     – Use para falhas que impedem o funcionamento (DB inacessível, etc.).
 *
 * @module    Logger_System
 * @namespace Logger_System
 * @author    EnSiSanar Dev Team
 * @version   1.0.0
 * @since     2026-04-16
 * @requires  Config        – APP_VERSION, ADMIN_EMAIL via PropertiesService
 * @requires  DB_Core       – getSheet() para aba SystemLogs
 * @requires  Email_Service – sendAlert() para notificações ao administrador
 */
const Logger_System = {

  // ─── CONSTANTES INTERNAS ──────────────────────────────────────────────────

  /**
   * @private
   * Mapa de nível → valor numérico para comparação de severidade.
   */
  _LEVELS: { DEBUG: 0, INFO: 1, WARN: 2, ERROR: 3, CRITICAL: 4 },

  /** @private Nível mínimo para persistir na aba SystemLogs (WARN = 2). */
  _SHEET_MIN_LEVEL: 2,

  /** @private Nível mínimo para disparar e-mail de alerta (ERROR = 3). */
  _EMAIL_MIN_LEVEL: 3,

  /** @private Chave na ScriptProperty para throttle de e-mail entre alerts. */
  _THROTTLE_PROP: 'LOGGER_LAST_EMAIL_MS',

  /**
   * @private
   * Janela de throttle para e-mails de alerta (15 min).
   * CRITICAL ignora esta janela e sempre envia.
   */
  _THROTTLE_MS: 15 * 60 * 1000,

  /** @private Nome da aba de log persistente no Spreadsheet. */
  _SHEET_NAME: 'SystemLogs',

  /**
   * @private
   * Cabeçalhos da aba SystemLogs.
   * Deve estar em sincronia com DB_Core._SCHEMAS.SystemLogs.
   */
  _HEADERS: [
    'Timestamp', 'Level', 'Module',
    'Message', 'ErrorName', 'ErrorStack', 'Context'
  ],

  // ─── HELPERS PRIVADOS ─────────────────────────────────────────────────────

  /**
   * @private
   * Obtém a aba SystemLogs. DB_Core.getSheet() é idempotente e cria com
   * cabeçalhos se necessário (schema definido em DB_Core._SCHEMAS).
   * Envolto em try/catch para garantir que logging NUNCA lance exceções.
   *
   * @returns {GoogleAppsScript.Spreadsheet.Sheet|null}
   */
  _getSheet: function () {
    try {
      return DB_Core.getSheet(Logger_System._SHEET_NAME);
    } catch (e) {
      console['error']('[Logger_System._getSheet] Não foi possível acessar SystemLogs: ' + e.message);
      return null;
    }
  },

  /**
   * @private
   * Persiste uma entrada de log na aba SystemLogs via appendRow (atômico).
   * Chamado apenas para WARN, ERROR e CRITICAL.
   *
   * @param {Object} entry – objeto de log estruturado
   */
  _persistToSheet: function (entry) {
    try {
      const sheet = Logger_System._getSheet();
      if (!sheet) return;
      sheet.appendRow([
        entry.timestamp,
        entry.level,
        entry.module,
        entry.message,
        entry.errorName  || '',
        entry.errorStack || '',
        entry.context    || ''
      ]);
    } catch (e) {
      // Logging nunca pode lançar — erro aqui seria recursivo
      console['error']('[Logger_System._persistToSheet] ' + e.message);
    }
  },

  /**
   * @private
   * Verifica se o throttle de e-mail está ativo.
   * CRITICAL nunca é throttled — sempre envia.
   *
   * @param   {string} level
   * @returns {boolean} true = throttle ativo (não enviar)
   */
  _isThrottled: function (level) {
    if (level === 'CRITICAL') return false;
    try {
      const raw = PropertiesService.getScriptProperties()
                    .getProperty(Logger_System._THROTTLE_PROP);
      if (!raw) return false;
      return (Date.now() - Number(raw)) < Logger_System._THROTTLE_MS;
    } catch (e) {
      return false; // em caso de falha na prop, permite o envio
    }
  },

  /**
   * @private
   * Persiste o timestamp do último e-mail enviado (para throttle).
   */
  _markEmailSent: function () {
    try {
      PropertiesService.getScriptProperties()
        .setProperty(Logger_System._THROTTLE_PROP, String(Date.now()));
    } catch (e) {
      console['error']('[Logger_System._markEmailSent] ' + e.message);
    }
  },

  /**
   * @private
   * Envia e-mail de alerta ao administrador via Email_Service.
   * Respeita janela de throttle de 15 min (exceto CRITICAL).
   * Silencia erros de envio para não mascarar o erro original.
   *
   * @param {Object} entry – objeto de log estruturado
   */
  _sendEmailAlert: function (entry) {
    try {
      const adminEmail = Config.ADMIN_EMAIL;
      if (!adminEmail) return; // sem destinatário configurado

      if (Logger_System._isThrottled(entry.level)) {
        console['warn']('[Logger_System] Alerta throttled – último e-mail < 15 min atrás.');
        return;
      }

      const subject = '[EnSiSanar ' + entry.level + '] ' +
                      entry.module + ': ' +
                      entry.message.substring(0, 80);

      const lines = [
        '=== EnSiSanar – Alerta de Sistema ===',
        '',
        'Nível:   ' + entry.level,
        'Módulo:  ' + entry.module,
        'Data:    ' + entry.timestamp.toISOString(),
        'Versão:  ' + Config.APP_VERSION,
        '',
        '─── Mensagem ─────────────────────────',
        entry.message,
        ''
      ];
      if (entry.errorName)  lines.push('Tipo:    ' + entry.errorName);
      if (entry.context)    lines.push('Ctx:     ' + entry.context);
      if (entry.errorStack) {
        lines.push('', '─── Stack Trace ──────────────────────', entry.errorStack);
      }
      lines.push('', '─────────────────────────────────────',
                 'Acesse o Stackdriver para detalhes completos:',
                 'https://console.cloud.google.com/logs');

      Email_Service.sendAlert(adminEmail, subject, lines.join('\n'));
      Logger_System._markEmailSent();

    } catch (e) {
      console['error']('[Logger_System._sendEmailAlert] Falha ao enviar alerta: ' + e.message);
    }
  },

  /**
   * @private
   * Núcleo de roteamento: compõe a entrada de log e distribui aos destinos.
   *
   * @param {string}     level   – 'DEBUG'|'INFO'|'WARN'|'ERROR'|'CRITICAL'
   * @param {string}     message – texto da mensagem
   * @param {string}     module  – módulo/contexto (ex: 'Auth.login')
   * @param {Error|null} error   – objeto Error, se aplicável
   */
  _write: function (level, message, module, error) {
    const levelNum = Logger_System._LEVELS[level] !== undefined
      ? Logger_System._LEVELS[level] : 0;

    const entry = {
      timestamp:  new Date(),
      level:      level,
      module:     module  || 'System',
      message:    String(message),
      errorName:  error   ? (error.name  || 'Error') : '',
      errorStack: error   ? (error.stack || '')       : '',
      context:    module  || ''
    };

    // ── Destino 1: Google Cloud Logging via console ────────────────────────
    const tag = '[' + level + '][' + entry.module + '] ';
    if (levelNum >= Logger_System._LEVELS.ERROR) {
      console['error'](tag + entry.message +
        (entry.errorStack ? '\n' + entry.errorStack : ''));
    } else if (levelNum >= Logger_System._LEVELS.WARN) {
      console['warn'](tag + entry.message);
    } else {
      console['log'](tag + entry.message);
    }

    // ── Destino 2: Aba SystemLogs (WARN+) ─────────────────────────────────
    if (levelNum >= Logger_System._SHEET_MIN_LEVEL) {
      Logger_System._persistToSheet(entry);
    }

    // ── Destino 3: E-mail de alerta ao admin (ERROR+) ─────────────────────
    if (levelNum >= Logger_System._EMAIL_MIN_LEVEL) {
      Logger_System._sendEmailAlert(entry);
    }
  },

  // ─── API PÚBLICA: MÉTODOS DE LOG POR NÍVEL ────────────────────────────────

  /**
   * Mensagem de depuração — apenas Stackdriver. Use durante desenvolvimento.
   * @public
   * @param {string} message
   * @param {string} [module] – ex: 'EEG_Processor.calcBands'
   */
  debug: function (message, module) {
    Logger_System._write('DEBUG', message, module, null);
  },

  /**
   * Evento informativo — apenas Stackdriver. Use para operações normais.
   * @public
   * @param {string} message
   * @param {string} [module]
   */
  info: function (message, module) {
    Logger_System._write('INFO', message, module, null);
  },

  /**
   * Aviso — Stackdriver + SystemLogs. Situações anómalas mas não críticas.
   * @public
   * @param {string} message
   * @param {string} [module]
   */
  warn: function (message, module) {
    Logger_System._write('WARN', message, module, null);
  },

  /**
   * Erro — Stackdriver + SystemLogs + e-mail (throttled 15 min).
   * @public
   * @param {string} message
   * @param {string} [module]
   */
  error: function (message, module) {
    Logger_System._write('ERROR', message, module, null);
  },

  /**
   * Falha crítica — Stackdriver + SystemLogs + e-mail imediato (sem throttle).
   * Use quando o sistema não consegue funcionar: DB inacessível, credenciais
   * inválidas, perda de dados.
   * @public
   * @param {string} message
   * @param {string} [module]
   */
  critical: function (message, module) {
    Logger_System._write('CRITICAL', message, module, null);
  },

  // ─── API PÚBLICA: WRAPPERS DE EXCEÇÃO ─────────────────────────────────────

  /**
   * Wrapper principal para tratamento de exceções capturadas em blocos catch.
   * Extrai mensagem, nome e stack do Error automaticamente e classifica como ERROR.
   * Roteia para Stackdriver + SystemLogs + e-mail (throttled).
   *
   * @public
   * @param {Error|string} e       – exceção capturada
   * @param {string}       context – onde ocorreu: ex. 'Patient_CRUD.create'
   *
   * @example
   *   try {
   *     DB_Core.insert('Patients', data);
   *   } catch (e) {
   *     Logger_System.logError(e, 'Patient_CRUD.create');
   *     return { success: false, message: 'Erro interno.' };
   *   }
   */
  logError: function (e, context) {
    const isError = e && (e instanceof Error || typeof e.message !== 'undefined');
    Logger_System._write(
      'ERROR',
      isError ? e.message : String(e),
      context || 'Unknown',
      isError ? e : null
    );
  },

  /**
   * Wrapper para falhas críticas que exigem resposta imediata.
   * Classifica como CRITICAL — e-mail enviado sem throttle.
   *
   * @public
   * @param {Error|string} e
   * @param {string}       context
   *
   * @example
   *   // Em Backup_Service após falha total:
   *   Logger_System.logCritical(e, 'Backup_Service.run');
   */
  logCritical: function (e, context) {
    const isError = e && (e instanceof Error || typeof e.message !== 'undefined');
    Logger_System._write(
      'CRITICAL',
      isError ? e.message : String(e),
      context || 'Unknown',
      isError ? e : null
    );
  },

  // ─── API PÚBLICA: DIAGNÓSTICO ─────────────────────────────────────────────

  /**
   * Retorna as últimas N entradas de log da aba SystemLogs.
   * Leitura em lote — uma única chamada à API do Sheets.
   * Útil para painéis de diagnóstico no dashboard de admin.
   *
   * @public
   * @param   {number} [limit=50] – máximo de entradas a retornar
   * @returns {Object[]} entradas do mais recente ao mais antigo
   *
   * @example
   *   const logs = Logger_System.getRecentLogs(20);
   */
  getRecentLogs: function (limit) {
    try {
      const sheet = Logger_System._getSheet();
      if (!sheet || sheet.getLastRow() <= 1) return [];

      const n        = Math.min(limit || 50, sheet.getLastRow() - 1);
      const startRow = Math.max(2, sheet.getLastRow() - n + 1);
      const rows     = sheet
        .getRange(startRow, 1, n, Logger_System._HEADERS.length)
        .getValues();   // ← leitura em lote

      return rows.reverse().map(function (row) {
        return Logger_System._HEADERS.reduce(function (obj, h, i) {
          obj[h] = row[i];
          return obj;
        }, {});
      });
    } catch (e) {
      console['error']('[Logger_System.getRecentLogs] ' + e.message);
      return [];
    }
  },

  /**
   * Conta entradas por nível nas últimas 24 horas.
   * Útil para widgets de saúde do sistema no dashboard.
   *
   * @public
   * @returns {{ DEBUG: number, INFO: number, WARN: number,
   *             ERROR: number, CRITICAL: number }}
   */
  getSummary24h: function () {
    const counts = { DEBUG: 0, INFO: 0, WARN: 0, ERROR: 0, CRITICAL: 0 };
    try {
      const cutoff = new Date(Date.now() - 24 * 60 * 60 * 1000);
      const logs   = Logger_System.getRecentLogs(200);
      logs.forEach(function (entry) {
        const ts = entry['Timestamp'];
        if (ts && new Date(ts) >= cutoff && counts[entry['Level']] !== undefined) {
          counts[entry['Level']]++;
        }
      });
    } catch (e) {
      console['error']('[Logger_System.getSummary24h] ' + e.message);
    }
    return counts;
  }

}; // ── fim do namespace Logger_System ──────────────────────────────────────────