/** * Laboratório da IA | Relatório semanal | versão 1.0 | 17/10/2026 * Exemplo editorial original. Copia para um projeto Apps Script ligado * a uma folha de TESTE. Lê LAB_Dados; escreve apenas LAB_Relatorios. * Sem email, chamadas HTTP, serviços de IA ou alteração da fonte. * Uma linha por tarefa concluída. Datas reais do Sheets; minutos numéricos. * @OnlyCurrentDoc */ const LAB_WEEKLY = Object.freeze({ source: 'LAB_Dados', destination: 'LAB_Relatorios', timezone: 'Europe/Lisbon', maxRows: 5000, inputHeaders: ['Id', 'DataConclusao', 'Minutos'], outputHeaders: ['Chave', 'Inicio', 'FimInclusivo', 'GeradoEm', 'TarefasConcluidas', 'MinutosTotal', 'MinutosMedia', 'Estado'] }); // Executa primeiro: mostra apenas o período, sem escrever na folha. function labInspectPeriod() { const book = labBook_(); const period = labPreviousWeek_(labDateKey_(new Date(), book.getSpreadsheetTimeZone())); console.log(JSON.stringify(period)); return period; } // Execução manual e função do gatilho: snapshot da semana completa anterior. function labWeeklyReport() { const lock = LockService.getScriptLock(); if (!lock.tryLock(30000)) throw new Error('Já existe uma execução ativa. Tenta mais tarde.'); try { const book = labBook_(); const now = new Date(); const period = labPreviousWeek_(labDateKey_(now, LAB_WEEKLY.timezone)); const rows = labReadRows_(book); const result = labSummarize_(rows, period); let output = book.getSheetByName(LAB_WEEKLY.destination); if (output && output.getLastRow() > 0) { if (output.getLastColumn() !== LAB_WEEKLY.outputHeaders.length) { throw new Error('A aba de relatórios tem uma estrutura diferente. Não foi alterada.'); } labHeaders_(output.getRange(1, 1, 1, LAB_WEEKLY.outputHeaders.length).getValues()[0], LAB_WEEKLY.outputHeaders, 'relatórios'); const count = output.getLastRow() - 1; if (count > LAB_WEEKLY.maxRows) throw new Error('Histórico acima do limite deste exemplo.'); const keys = count ? output.getRange(2, 1, count, 1).getValues().flat() : []; const matches = keys.filter(key => key === period.key).length; if (matches > 1) throw new Error('Existem chaves repetidas no histórico. Revê antes de continuar.'); if (matches === 1) { console.log('O período já tem um snapshot. Não foi criado nem substituído outro.'); return {status: 'existing', key: period.key}; } } if (!output) output = book.insertSheet(LAB_WEEKLY.destination); if (output.getLastRow() === 0) { output.getRange(1, 1, 1, LAB_WEEKLY.outputHeaders.length).setValues([LAB_WEEKLY.outputHeaders]); } const row = [period.key, period.start, period.lastDay, Utilities.formatDate(now, LAB_WEEKLY.timezone, "yyyy-MM-dd'T'HH:mm:ssZ"), result.count, result.minutes, result.average === null ? 'Sem tarefas' : result.average, 'RASCUNHO']; output.getRange(output.getLastRow() + 1, 1, 1, row.length).setValues([row]); SpreadsheetApp.flush(); console.log('Snapshot criado em LAB_Relatorios. Confere os valores antes de o utilizar.'); return {status: 'created', key: period.key}; } finally { lock.releaseLock(); } } // Só executa depois de conferir manualmente o primeiro relatório. // Segunda-feira, aproximadamente às 09:30 de Lisboa (+/- 15 minutos). // Usa uma única conta responsável. Não apaga gatilhos de outras funções. function labInstallWeeklyTrigger() { const lock = LockService.getScriptLock(); if (!lock.tryLock(30000)) throw new Error('Existe uma operação ativa. Tenta mais tarde.'); try { labReadRows_(labBook_()); const existing = ScriptApp.getProjectTriggers() .filter(trigger => trigger.getHandlerFunction() === 'labWeeklyReport'); if (existing.length > 1) throw new Error('Há vários gatilhos desta função na tua conta. Revê-os no editor.'); if (existing.length === 1) { if (existing[0].getEventType() !== ScriptApp.EventType.CLOCK) { throw new Error('Já existe um gatilho desta função que não é temporal. Revê-o no editor.'); } console.log('Já existe um gatilho temporal desta função na tua conta. Confere o horário no editor.'); return; } ScriptApp.newTrigger('labWeeklyReport').timeBased().everyWeeks(1) .onWeekDay(ScriptApp.WeekDay.MONDAY).atHour(9).nearMinute(30) .inTimezone(LAB_WEEKLY.timezone).create(); console.log('Gatilho semanal criado. Confere a primeira execução automática.'); } finally { lock.releaseLock(); } } function labBook_() { const book = SpreadsheetApp.getActiveSpreadsheet(); if (!book) throw new Error('Abre o Apps Script a partir da folha de cálculo de teste.'); if (book.getSpreadsheetTimeZone() !== LAB_WEEKLY.timezone) { throw new Error('Define o fuso da folha como Europe/Lisbon antes de continuar.'); } return book; } function labHeaders_(actual, expected, label) { if (actual.length !== expected.length || actual.some((value, index) => value !== expected[index])) { throw new Error('Cabeçalhos inesperados na aba de ' + label + '. Confere o exemplo.'); } } function labReadRows_(book) { const sheet = book.getSheetByName(LAB_WEEKLY.source); if (!sheet || sheet.getLastRow() < 1) throw new Error('Falta LAB_Dados com os cabeçalhos indicados.'); if (sheet.getLastColumn() !== 3) throw new Error('LAB_Dados deve ter exatamente três colunas preenchidas.'); if (sheet.getLastRow() > LAB_WEEKLY.maxRows + 1) throw new Error('Máximo de 5000 linhas de dados neste exemplo.'); const values = sheet.getRange(1, 1, sheet.getLastRow(), 3).getValues(); labHeaders_(values[0], LAB_WEEKLY.inputHeaders, 'dados'); const seen = new Set(); return values.slice(1).flatMap((row, index) => { if (row.every(value => value === '')) return []; const line = index + 2; const id = typeof row[0] === 'string' ? row[0].trim() : ''; if (!id || seen.has(id)) throw new Error('Id em falta ou repetido na linha ' + line + '.'); seen.add(id); if (!(row[1] instanceof Date) || !Number.isFinite(row[1].getTime())) { throw new Error('DataConclusao inválida na linha ' + line + '. Usa uma data real do Sheets.'); } if (typeof row[2] !== 'number' || !Number.isFinite(row[2]) || row[2] < 0 || row[2] > 1000000) { throw new Error('Minutos inválidos na linha ' + line + '. Usa um número de 0 a 1000000.'); } return [{id, day: labDateKey_(row[1], LAB_WEEKLY.timezone), minutes: row[2]}]; }); } function labDateKey_(date, timezone) { return Utilities.formatDate(date, timezone, 'yyyy-MM-dd'); } // Aritmética de DATAS de calendário em UTC; não subtrai blocos de 168 horas locais. function labPreviousWeek_(localDay) { if (!/^\d{4}-\d{2}-\d{2}$/.test(localDay)) throw new Error('Data de referência inválida.'); const current = new Date(localDay + 'T00:00:00Z'); if (!Number.isFinite(current.getTime()) || current.toISOString().slice(0, 10) !== localDay) { throw new Error('Data de referência inválida.'); } const sinceMonday = (current.getUTCDay() + 6) % 7; const end = new Date(current.getTime()); end.setUTCDate(end.getUTCDate() - sinceMonday); const start = new Date(end.getTime()); start.setUTCDate(start.getUTCDate() - 7); const last = new Date(end.getTime()); last.setUTCDate(last.getUTCDate() - 1); const startKey = start.toISOString().slice(0, 10); return {key: 'week:' + startKey, start: startKey, endExclusive: end.toISOString().slice(0, 10), lastDay: last.toISOString().slice(0, 10)}; } function labSummarize_(rows, period) { const selected = rows.filter(row => row.day >= period.start && row.day < period.endExclusive); const minutes = selected.reduce((sum, row) => sum + row.minutes, 0); return {count: selected.length, minutes: Math.round(minutes * 100) / 100, average: selected.length ? Math.round(minutes / selected.length * 100) / 100 : null}; }