TE-DF - Sistema Integrado de Transporte Escolar do Distrito Federal

📌 Visão Geral

O TE-DF é uma plataforma robusta baseada em Google Apps Script, projetada para gerenciar o transporte escolar do Distrito Federal. O sistema integra Frontend moderno (HTML/JS), Backend escalável (GAS) e processamento avançado via Google Colab, oferecendo uma solução completa para gestão de rotas, frequências, eventos e relatórios inteligentes.

A arquitetura é modular e em camadas, garantindo separação de responsabilidades, testabilidade e facilidade de manutenção.

✨ Destaques

Arquitetura Enterprise: Implementação em camadas (Frontend, API Gateway, Business Logic, Data Layer).
Autenticação Robusta: Sistema de login seguro com controle de sessão, auditoria e múltiplos níveis de permissão (Monitor, Secretário, Admin).
Módulos MVP: Funcionalidades de ponta a ponta para Rotas, Frequência, Alunos e Relatórios com IA.
Integração Colab: Processamento pesado e análise de dados via scripts Python integrados (Polling/Automated).
Design System: Interface moderna e responsiva com componentes reutilizáveis e feedback visual rico.
Ferramentas de Desenvolvimento: Suite completa de scripts Python para análise de código, detecção de erros e geração de documentação.
CRUD Robusto: Sistema genérico de operações CRUD com validação de schema e tratamento de erros.
Smart Caching: Cache multi-layer (Memory, Script Cache, Properties) com invalidação inteligente.
Circuit Breaker: Proteção contra falhas em cascata com degradação graciosa.

🏗️ Arquitetura do Sistema

O sistema TE-DF é uma aplicação Google Apps Script com arquitetura em camadas:

┌─────────────────────────────────────┐
│         Frontend (HTML/JS)          │
│   MVP Modules, Components, Styles   │
├─────────────────────────────────────┤
│          API Gateway (GAS)          │
│      Handlers, Router, Auth         │
├─────────────────────────────────────┤
│         Business Logic (GAS)        │
│    Services, Validators, Events     │
├─────────────────────────────────────┤
│         Data Layer (GAS)            │
│  Repository, DAL, SpreadsheetAPI    │
├─────────────────────────────────────┤
│       Google Sheets (Storage)       │
└─────────────────────────────────────┘

Componentes Principais

Camada	Descrição	Arquivos Principais
Config	Configurações e constantes do sistema	`00_Config.gs`, `00_SectionConfig.gs`
Core	Utilitários, tratamento de erros, degradação	`03_Utils.gs`, `04_ErrorHandler.gs`
Services	Serviços de infraestrutura	`10_LoggerService.gs`, `12_CacheService.gs`
Data Layer	Camada de acesso a dados	`20_SpreadsheetProvider.gs`, `24_Repository.gs`
Auth	Autenticação, autorização e sessões	`44_SessionManager.gs`, `46_EnterpriseAuthService.gs`, `47_AuthService.gs`
Business	Lógica de negócios e eventos	`55_EventBus.gs`, `56_EventService.gs`
Features	Funcionalidades específicas	`73_CRUD_Functions.gs`, `73_ChatbotService.gs`
MVP	Módulos MVP do sistema	`MVP_CRUD.gs`, `MVP_Eventos.gs`, `MVP_RelatorioIA.gs`
Testing	Framework de testes	`85_TestFramework.gs`, `91_TestRunner.gs`

Integração Colab

O sistema possui integração com Google Colab para processamento avançado:

Colab_Automated.py: Processador de Jobs com Ativação Remota via webhook
Colab_Polling_Processor.py: Processador de Jobs via Polling (SEM WEBHOOK)

📂 Estrutura do Projeto

d:\TE-DF-PP
├── .clasp.json                 # Configuração do CLASP
├── appsscript.json             # Manifest do Apps Script
│
├── 00_*.gs                     # Configurações e constantes
├── 01_*.gs - 05_*.gs           # Core e utilitários
├── 10_*.gs - 13_*.gs           # Serviços de infraestrutura
├── 20_*.gs - 25_*.gs           # Data Layer
├── 30_*.gs - 38_*.gs           # Data Services
├── 40_*.gs - 48_*.gs           # Validação e Autenticação
├── 50_*.gs - 68_*.gs           # Business Logic e Infrastructure
├── 70_*.gs - 79_*.gs           # Sistema e Features
├── 80_*.gs - 89_*.gs           # Colab, Workflows e Testes
├── 90_*.gs - 99_*.gs           # Testes e Correções
├── MVP_*.gs                    # Módulos MVP Backend
│
├── Component-*.html            # Componentes HTML reutilizáveis
├── JS-*.html                   # Scripts frontend modularizados
├── Page-*.html                 # Páginas da aplicação
├── Styles-*.html               # Estilos CSS
├── index.html                  # Página principal (monolítica)
│
├── Colab_Automated.py          # Processador Colab com webhook
├── Colab_Polling_Processor.py  # Processador Colab com polling
│
├── docs/                       # Documentação gerada
│   ├── API_REFERENCE.md        # Referência de APIs
│   ├── ARCHITECTURE.md         # Arquitetura do sistema
│   ├── FUNCTIONS_REFERENCE.md  # Referência detalhada de funções
│   └── MVP_GUIDE.md            # Guia dos módulos MVP
│
├── tools/                      # Ferramentas de análise (Python)
│   ├── analyze_codebase.py
│   ├── check_best_practices.py
│   ├── detect_dependencies.py
│   ├── find_duplicates.py
│   └── generate_docs.py
│
└── tests/                      # Testes automatizados

💾 Schemas de Dados

O sistema utiliza schemas definidos em 43_SchemaMapping.gs para validação e estruturação dos dados:

Schema	Planilha	Descrição
`Alunos`	Alunos	Cadastro de alunos do transporte escolar
`Usuarios`	Usuarios	Usuários do sistema (admin, monitores, secretários)
`Rotas`	Rotas	Rotas de transporte com dados de otimização
`Veiculos`	Veiculos	Frota de veículos
`Frequencia`	Frequencia	Registro de frequência (IDA/VOLTA)
`Eventos`	Eventos	Eventos do calendário escolar
`Incidentes`	Incidentes	Registro de ocorrências
`Pessoal`	Pessoal	Cadastro de motoristas e monitores
`Logs`	Logs	Logs do sistema
`Auditoria`	Auditoria	Trilha de auditoria
`Sessoes`	Sessoes	Sessões de usuários
`JobQueue`	JobQueue	Fila de jobs assíncronos
`FeatureFlags`	FeatureFlags	Flags de funcionalidades

📖 Referência de Funções

Autenticação (Auth)

`Auth_login(emailOrUsername, password)` [PUBLIC]

Arquivo: 47_AuthService.gs

Função principal de autenticação, chamada pelo frontend via APIClient.run('Auth_login', email, password).

WORKFLOW ÚNICO:

Aceita Username OU Email
Senha em texto plano
Consulta aba Usuarios

// Exemplo de uso no frontend
APIClient.run('Auth_login', 'admin', 'minhasenha')
  .then(result => {
    if (result.success) {
      console.log('Logado como:', result.user.username);
      console.log('Token:', result.token);
    }
  });

@param {string} emailOrUsername - Email ou username do usuário
@param {string} password - Senha em texto plano
@return {Object} {success, user, token, message}

`authenticateUser(credentialsOrUsername, password)` [PUBLIC]

Arquivo: 47_AuthService.gs

Autentica usuário - WORKFLOW ÚNICO E PADRONIZADO.

FLUXO:

Recebe Username OU Email + Password (texto plano)
Consulta aba "Usuarios" na planilha centralizadora
Busca por Username OU Email (case-insensitive)
Compara senha em texto plano diretamente
Retorna objeto padronizado

// Exemplo
authenticateUser('admin', 'minhasenha');
authenticateUser('admin@email.com', 'minhasenha');
authenticateUser({ username: 'admin', password: 'minhasenha' });

@param {Object|string} credentialsOrUsername - Username, Email ou {username, password}
@param {string} password - Senha em texto plano
@return {Object} {success, user, token, message}

`getCurrentUser()` [PUBLIC]

Arquivo: 47_AuthGlobals.gs

Obtém o usuário atualmente logado. Wrapper global para EnterpriseAuthService.getCurrentUser().

const result = getCurrentUser();
if (result.success) {
  console.log('Usuário:', result.user.username);
  console.log('Role:', result.user.role);
  console.log('Rota Vinculada:', result.user.idRotaVinculada);
}

@return {Object} { success, user: { id, username, email, role, permissions, idRotaVinculada }, message }

`changePassword(username, currentPassword, newPassword, isFirstAccess)` [PUBLIC]

Arquivo: 47_AuthService.gs

Troca de senha do usuário.

@param {string} username - Username ou Email
@param {string} currentPassword - Senha atual (texto plano)
@param {string} newPassword - Nova senha (texto plano)
@param {boolean} isFirstAccess - Se é primeiro acesso (ignora senha atual)
@return {Object} {success, message}

`logout(token)` [PUBLIC]

Arquivo: 47_AuthService.gs

Finaliza a sessão do usuário.

@param {string} token - Token da sessão
@return {Object} {success, message}

Gerenciamento de Sessão

`createSession(user, options)` [PUBLIC]

Arquivo: 44_SessionManager.gs

Cria nova sessão enterprise com recursos avançados.

ENTERPRISE FEATURES:

Session fingerprinting com device detection
Idle timeout com grace period
Concurrent session control com eviction policy
Token rotation automático
Activity tracking detalhado
@param {Object} user - Dados do usuário
@param {Object} options - Opções adicionais
@return {Object} {success, token, sessionId, refreshToken, expiresAt, expiresIn}

`validateSession(token, options)` [PUBLIC]

Arquivo: 44_SessionManager.gs

Valida se uma sessão é válida e ativa.

@param {string} token - Token da sessão
@param {Object} options - Opções de validação
@return {Object} {valid, session, user, newToken, error}

`refreshSession(refreshToken)` [PUBLIC]

Arquivo: 44_SessionManager.gs

Renova sessão usando refresh token.

@param {string} refreshToken - Refresh token
@return {Object} {success, token, refreshToken, expiresAt}

`revokeSession(token)` [PUBLIC]

Arquivo: 44_SessionManager.gs

Revoga uma sessão específica.

@param {string} token - Token da sessão
@return {Object} {succe 10BC8 ss, message}

`revokeAllSessions(email)` [PUBLIC]

Arquivo: 44_SessionManager.gs

Revoga todas as sessões de um usuário.

@param {string} email - Email do usuário
@return {Object} {success, count, message}

`getUserActiveSessions(email)` [PUBLIC]

Arquivo: 44_SessionManager.gs

Obtém sessões ativas de um usuário.

@param {string} email - Email do usuário
@return {Object} {success, sessions}

Autorização

`hasPermission(permission)` [PUBLIC]

Arquivo: 47_AuthService.gs

Verifica se o usuário atual possui a permissão solicitada.

@param {string} permission - Permissão a verificar
@return {boolean} True se permitido

`hasRole(roles)` [PUBLIC]

Arquivo: 47_AuthService.gs

Verifica se o usuário atual possui o role especificado.

@param {string|Array} roles - Role(s) a verificar
@return {boolean} True se possui o role

`requireAuth()` [PUBLIC]

Arquivo: 47_AuthGlobals.gs

Requer que o usuário esteja autenticado. Lança erro se não estiver.

@return {Object} { success, user } ou erro

`requireRole(roles)` [PUBLIC]

Arquivo: 47_AuthGlobals.gs

Requer que o usuário tenha um role específico.

@param {string|Array} roles - Role(s) permitido(s)
@return {Object} { success, user } ou erro

`requireAdmin()` [PUBLIC]

Arquivo: 47_AuthGlobals.gs

Requer que o usuário seja Administrador.

@return {Object} { success, user } ou erro

`requireSecretario()` [PUBLIC]

Arquivo: 47_AuthGlobals.gs

Requer que o usuário seja Secretário (ou Admin).

@return {Object} { success, user } ou erro

`isAdmin()` / `isMonitor()` / `isSecretario()` [PUBLIC]

Arquivo: 47_AuthGlobals.gs

Funções helper para verificar roles específicos.

@return {boolean}

CRUD Genérico

`genericCreate(entityType, data, options)` [PUBLIC]

Arquivo: 02_GenericCRUD.gs

Cria registro genérico. Substitui funções duplicadas como createAluno, createRota, createVeiculo.

genericCreate('Alunos', {
  Nome_Completo: 'João Silva',
  RA_Aluno: '12345',
  ID_Rota: 'ROTA-001'
});

@param {string} entityType - Tipo da entidade (Alunos, Rotas, etc)
@param {Object} data - Dados do registro
@param {Object} options - Opções adicionais
@return {Object} Resultado da operação

`genericRead(entityType, filters, options)` [PUBLIC]

Arquivo: 02_GenericCRUD.gs

Lê registros genéricos com filtros.

// Ler todos
genericRead('Alunos');

// Com filtros
genericRead('Alunos', { ID_Rota: 'ROTA-001', Status_Ativo: 'Ativo' });

// Com paginação
genericRead('Alunos', {}, { limit: 50, offset: 0 });

@param {string} entityType - Tipo da entidade
@param {Object} filters - Filtros de busca
@param {Object} options - Opções (limit, offset, orderBy)
@return {Object} Resultado com dados

`genericUpdate(entityType, id, data, options)` [PUBLIC]

Arquivo: 02_GenericCRUD.gs

Atualiza registro genérico.

@param {string} entityType - Tipo da entidade
@param {string} id - ID do registro
@param {Object} data - Novos dados
@param {Object} options - Opções adicionais
@return {Object} Resultado da operação

`genericDelete(entityType, id, options)` [PUBLIC]

Arquivo: 02_GenericCRUD.gs

Deleta registro genérico.

@param {string} entityType - Tipo da entidade
@param {string} id - ID do registro
@param {Object} options - Opções (softDelete, etc)
@return {Object} Resultado da operação

`handleCRUDRobusto(sheetName, action, id, data, filters)` [PUBLIC]

Arquivo: 99_CRUD_Fix.gs

Handler CRUD robusto que usa os headers reais da planilha para evitar discrepâncias de schema.

@param {string} sheetName - Nome da planilha
@param {string} action - Ação: 'create', 'read', 'update', 'delete'
@param {string} id - ID do registro
@param {Object} data - Dados do registro
@param {Object} filters - Filtros para read
@return {Object} Resultado da operação

Serviços de Dados

`getData(sheetName, filters)` [PUBLIC]

Arquivo: 73_APIHelpers.gs

Obtém dados de uma planilha.

// Frontend
google.script.run.getData('Alunos');
APIService.getData('Alunos');

@param {string} sheetName - Nome da planilha
@param {Object} [filters] - Filtros opcionais
@return {Object} { success: boolean, data?: Array, error?: string }

`getRecordById(sheetName, id)` [PUBLIC]

Arquivo: 73_APIHelpers.gs

Obtém registro por ID.

@param {string} sheetName - Nome da planilha
@param {string} id - ID do registro
@return {Object} { success: boolean, data?: Object, error?: string }

`createRecordAPI(params)` [PUBLIC]

Arquivo: 73_APIHelpers.gs

Cria registro - Aceita objeto params do frontend.

@param {Object} params - { sheetName, data }
@return {Object} { success, id, message }

`updateRecordAPI(params)` [PUBLIC]

Arquivo: 73_APIHelpers.gs

Atualiza registro.

@param {Object} params - { sheetName, id, data }
@return {Object} { success, message }

`deleteRecordAPI(params)` [PUBLIC]

Arquivo: 73_APIHelpers.gs

Deleta registro.

@param {Object} params - { sheetName, id }
@return {Object} { success, message }

`readRecordsAPI(params)` [PUBLIC]

Arquivo: 73_APIHelpers.gs

Lê registros - Aceita objeto params do frontend.

// Exemplos
readRecords({ sheetName: 'Alunos' });
readRecords({ sheetName: 'Alunos', id: 'ALU-001' });
readRecords({ sheetName: 'Alunos', filters: { Status: 'Ativo' } });

@param {Object|string} params - { sheetName, id?, filters? }
@return {Object} { success, data, count }

Frequência

`getAlunosParaFrequenciaV2(idRota)` [PUBLIC]

Arquivo: 99_FixFrequenciaAlunos.gs

Obtém alunos de uma rota específica para registro de frequência. Versão aprimorada com validação robusta.

@param {string} idRota - ID da rota selecionada
@return {Object} {success, alunos, total, debug}

`getAlunosDaRotaCompleto(idRota)` [PUBLIC]

Arquivo: 74_DataPopulatorService.gs

Obtém alunos de uma rota de forma robusta, tentando múltiplas estratégias de busca.

@param {string} idRota - ID da rota
@return {Object} {success, alunos, total, idRota}

`salvarFrequenciaV2(dados)` [PUBLIC]

Arquivo: 99_Frontend_Backend_Bridge.gs

Salva frequência V2 (chamado por MVP-Integration.html).

@param {Object} dados - Dados da frequência
@return {Object} Resultado da operação

`getResumoFrequenciaDia(data)` [PUBLIC]

Arquivo: 35_FrequenciaService.gs

Obtém resumo da frequência de um dia específico.

@param {string} [data] - Data no formato YYYY-MM-DD (default: hoje)
@return {Object} Resumo da frequência

`getCardFrequenciaDia(data)` [PUBLIC]

Arquivo: 74_DataPopulatorService.gs

Obtém dados para card de frequência do dia.

@param {string} [data] - Data no formato YYYY-MM-DD (default: hoje)
@return {Object} { success, card: {...} }

Eventos

`getEvents(filter)` [PUBLIC]

Arquivo: 99_Frontend_Backend_Bridge.gs

Obtém eventos com filtros opcionais.

@param {Object} filter - Filtros { tipo: '...' }
@return {Object} {success, data}

`createEvent(payload)` [PUBLIC]

Arquivo: 99_Frontend_Backend_Bridge.gs

Cria um novo evento a partir do modal.

@param {Object} payload - Dados do formulário

`updateEvento(id, data)` [PUBLIC]

Arquivo: MVP_Eventos.gs

Atualiza evento existente.

`deleteEvento(id)` [PUBLIC]

Arquivo: MVP_Eventos.gs

Remove evento.

`getEventStats()` [PUBLIC]

Arquivo: MVP_Eventos.gs

Obtém estatísticas de eventos.

Rotas e Otimização

`getRotas()` [PUBLIC]

Arquivo: 73_RealTimeTracking.gs

Obtém rotas ativas.

@return {Object} Lista de rotas

`getRotasCompletas()` [PUBLIC]

Arquivo: 99_Frontend_Backend_Bridge.gs

Obtém rotas com dados enriquecidos (contagem de alunos, veículo, motorista).

@return {Object} {success, data: Array}

`getRotasEstatisticas()` [PUBLIC]

Arquivo: 99_Frontend_Backend_Bridge.gs

Obtém estatísticas gerais de rotas para dashboard/KPIs.

@return {Object} {success, stats: {...}}