psychotables

Imported from dadoming/psychotables (AGENTS.md). Install upstream with npx skills add dadoming/psychotables. Copyright stays with the author.

Gestao de Consultas - Google Sheets + Apps Script

Sistema de gestao financeira para psicologas que trabalham em varios consultorios. Automatiza o tracking de consultas, pagamentos, recibos e gera resumos anuais.

Contexto

Uma psicologa trabalha em 4-5 consultorios diferentes. Cada paciente:

• Tem um preco por consulta (pode variar por paciente E por localizacao)
• Tem um custo pessoal associado (valor que a psicologa paga ao consultorio por cada consulta realizada la)
• Pode ser paciente de Seguranca Social (preco fixo mensal, sem custo pessoal)

O sistema precisa de:

• Registar presencas mensais por paciente
• Controlar pagamentos e envio de recibos
• Calcular automaticamente valores a receber e lucro liquido
• Gerar resumo anual agregado

Estrutura da Spreadsheet

Sheet: Configuracoes

Primeira sheet, contem a configuracao base:

Tabela Localizacoes (linhas 1-12 por defeito):

• 1 coluna: nome do consultorio
• Ate 6 localizacoes (configuravel via MAX_LOCALIZACOES)
• Quando editada, atualiza automaticamente os dropdowns em todas as sheets

Tabela Pessoas (posicao dinamica, logo apos Localizacoes): | Nome | Localizacao | Preco | Seguranca Social | Despesas | A decorrer |

• Ate 30 pacientes
• Localizacao tem dropdown vinculado a tabela de localizacoes
• Preco: se SS desativado = preco por consulta; se SS ativado = preco fixo por mes
• Seguranca Social: checkbox (coluna 4) — paciente SS aparece apenas na tabela SS, nao na principal
• Despesas: valor que a psicologa paga ao consultorio por consulta (ignorado para SS)
• A decorrer: checkbox (coluna 6) que indica se o paciente esta ativo
• Apenas pacientes com A decorrer marcado sao incluidos nas sheets mensais

Sheets Mensais (ex: "Janeiro 2026")

Tabela Principal (consultas privadas): | Nome | Localizacao | Preco p/ Consulta | Quantidade Consultas | Despesas | Pagou | Recibo Enviado | Total a Receber | Total | Notas |

• Apenas os pacientes ativos sao incluidos — sem linhas vazias
• Pagou e Recibo Enviado: checkboxes nativos
• Total a Receber (formula): Preco x Quantidade Consultas
• Total (formula): Total a Receber - (Despesas x Quantidade Consultas)
• Linha de TOTAIS no final com somas automaticas
• Localizacao tem dropdown vinculado as Configuracoes
• Linhas alternadas com cor para facilitar leitura
• Titulo: nome do mes em MAIUSCULAS, alinhado a esquerda
• Cor do titulo: unica por mes (janeiro=azul navy, fevereiro=rosa, marco=verde, ...) via constante CORES_MESES

Tabela Seguranca Social (abaixo da tabela principal): | Nome | Localizacao | Preco p/ Mes | Total | Pagou | Recibo Enviado | Notas |

• Apenas os pacientes SS ativos sao incluidos — sem linhas vazias
• Total (formula): = Preco p/ Mes (valor fixo mensal)
• Pagou e Recibo Enviado: checkboxes nativos
• Linha de TOTAIS SS no final
• Pacientes SS aparecem APENAS nesta tabela (nao na principal)
• Titulo com fundo verde (#2e7d32)
• A posicao da tabela SS e dinamica (depende do numero de pacientes na tabela principal)

Sheet: Resumo Anual (ex: "Resumo Anual 2026")

| Nome | Localizacao | Tipo | Preco | Meses / Consultas | Total Despesas | Total Bruto | Total Liquido | Notas |

• Agrega dados de todas as 12 sheets mensais (tabela principal + tabela SS)
• Agrupa por combinacao Nome+Localizacao
• Tipo: Privado ou SS — indica a origem do paciente
• Meses / Consultas: numero de consultas (Privado) ou meses com preco registado (SS)
• Pacientes SS tem sempre Total Despesas = 0 (sem custo de consultorio)
• Total Liquido e a coluna unificada de resultado final (= Total Bruto - Total Despesas para todos)
• Linha de TOTAIS globais
• Tema amarelo (#fbbc04 titulo, #fff9c4 headers, #ffe082 totais)

Menu Customizado

Ao abrir a spreadsheet, aparece o menu "Gestao Consultas" com:

Como Instalar

1. Criar uma nova Google Spreadsheet em branco
2. Ir a Extensoes > Apps Script
3. Apagar o conteudo do ficheiro Code.gs que aparece
4. Copiar e colar todo o conteudo do ficheiro Code.gs deste projeto
5. Guardar (Ctrl+S)
6. Voltar a spreadsheet e recarregar a pagina (F5)
7. O menu "Gestao Consultas" aparece na barra

Nota: Na primeira vez que executar uma funcao, o Google vai pedir permissoes. Clicar "Revisar permissoes" > escolher a conta > "Avancado" > "Ir para (nome do projeto)" > "Permitir".

Como Usar (Passo a Passo)

1. Configuracao Inicial

1. Clicar em Gestao Consultas > Configuracao Inicial
2. Na sheet "Configuracoes", preencher as localizacoes (linhas 3-12, coluna A)
3. Preencher os pacientes (a partir da linha 16):
   • Nome (primeiro e ultimo junto, ex: "Ana Silva")
   • Localizacao (dropdown aparece automaticamente)
   • Preco (ex: 60 — serve como preco por consulta OU preco mensal SS conforme checkbox SS)
   • Seguranca Social (checkbox, desmarcado por defeito — marcar para pacientes SS)
   • Despesas (ex: 15 — o que paga ao consultorio por consulta; ignorado para SS)
   • A decorrer (checkbox, marcado por defeito — desmarcar para pacientes inativos)

2. Gerar Meses

• Gestao Consultas > Gerar Novo Mes > digitar ano > digitar mes

Cada sheet mensal e criada ja com os pacientes ativos pre-preenchidos.

3. Uso Mensal

Para cada mes, preencher apenas:

• Quantidade Consultas: quantas vezes o paciente veio (ex: 4)
• Pagou: marcar checkbox quando o paciente pagar
• Recibo Enviado: marcar checkbox quando o recibo for enviado

Para pacientes de Seguranca Social (tabela separada abaixo):

• O Preco p/ Mes e preenchido automaticamente a partir das Configuracoes
• Marcar Pagou e Recibo Enviado conforme aplicavel

Os totais calculam-se automaticamente.

4. Resumo Anual

• Gestao Consultas > Atualizar Resumo Anual > digitar ano
• O resumo e recalculado com base em todos os meses preenchidos

Estrutura do Codigo (Code.gs)

Funcoes de Menu (handlers)

• onOpen() - Cria o menu customizado
• menuConfiguracaoInicial() - Handler para criar Configuracoes
• menuGerarNovoMes() - Handler para gerar 1 mes
• menuAtualizarResumoAnual() - Handler para atualizar resumo
• menuAtualizarDropdowns() - Handler para atualizar dropdowns

Funcoes Principais

• criarSheetConfiguracoes(ss) - Cria a sheet com tabelas de localizacoes e pessoas
• criarSheetMes(ss, nomeMes) - Cria uma sheet mensal com template e pacientes ativos pre-preenchidos
• _preencherTabelasMes(ss, sheet, pessoas, pessoasSS) - Constroi as tabelas de dados (so as linhas necessarias)
• criarSheetResumoAnual(ss, ano) - Cria a sheet de resumo anual
• atualizarResumoAnual(ss, sheetResumo, ano) - Agrega dados dos 12 meses, distingue Privado vs SS

Funcoes Auxiliares

• getLocalizacoes(ss) - Le localizacoes da sheet Configuracoes
• getPessoas(ss) - Le pessoas ativas da sheet Configuracoes (6 colunas, exclui SS)
• getPessoasSS(ss) - Le pessoas ativas de Seguranca Social (nome, localizacao, preco SS)
• _getAllPessoas(ss) - Le todas as pessoas numa unica leitura, retorna {normal, ss}
• encontrarTotaisPrincipais(sheetMes) - Localiza a linha TOTAIS da tabela principal
• encontrarTabelaSS(sheetMes) - Localiza a tabela SS (posicao dinamica)
• atualizarDropdownLocalizacoes(ss) - Atualiza dropdowns em todas as sheets (principal + SS); com guards para evitar getRange com 0 linhas quando tabelas estao vazias
• parseMes(input) - Converte input de mes (numero ou nome) para indice
• _getCorMes(nomeMes) - Retorna {bg, fg} da cor do mes a partir do nome da sheet
• _adicionarInfoBox(sheet, row, col, titulo, linhas) - Adiciona caixa de instrucoes formatada numa coluna livre da sheet; linhas com prefixo === sao subtitulos de secao
• formatarHeader(range, corFundo?) - Aplica formatacao de header (cor de fundo parametrizavel)
• ordenarSheets(ss) - Ordena sheets: Configuracoes > Meses > Resumo; usa insercao em ordem inversa para posicao 1 para evitar erros de posicionamento
• onEdit(e) - Trigger para atualizar dropdowns quando localizacoes mudam

Limites

• Maximo 6 localizacoes (configuravel via MAX_LOCALIZACOES)
• Maximo 20 pacientes na configuracao (configuravel via MAX_PESSOAS)
• As tabelas mensais crescem dinamicamente com o numero de pacientes ativos
• A tabela de Pessoas posiciona-se automaticamente abaixo das Localizacoes
• Nomes dos meses sem acentos nas sheets (ex: "Marco" em vez de "Março") para evitar problemas de encoding

Personalizacao

Para alterar limites, editar as constantes no topo do Code.gs:

• MAX_LOCALIZACOES - Numero maximo de localizacoes (default: 6)
• MAX_PESSOAS - Numero maximo de pacientes (default: 20)

Para alterar cores, procurar os codigos hex no codigo ou editar CORES_MESES:

• CORES_MESES - Array de 12 entradas {bg, fg}, uma por mes (Janeiro a Dezembro)
• #c2185b - Rosa escuro (titulos Configuracoes)
• #fdebd0 - Bege (headers Configuracoes)
• #2e7d32 - Verde escuro (titulo tabela Seguranca Social)
• #fbbc04 - Amarelo (titulo Resumo Anual)
• #fff9c4 - Amarelo claro (headers Resumo Anual)
• #ffe082 - Ambar (linha de totais no resumo)
• #d9e2f3 - Azul claro (headers padrao meses)
• #e8f0fe - Azul muito claro (linha de totais nos meses)
• #fde8cd - Laranja claro (linha de totais SS)
• #f8f9fa - Cinza muito claro (linhas alternadas)
• #37474f - Cinzento azulado escuro (titulo das info boxes)
• #546e7a - Cinzento azulado medio (subtitulos das info boxes)
• #eceff1 - Cinzento claro (conteudo das info boxes)

Caixas de Instrucoes nas Sheets

Cada sheet tem uma caixa lateral de instrucoes gerada automaticamente via _adicionarInfoBox:

As caixas nao interferem com os dados (ficam sempre fora da area de tabelas).

Como Adicionar Novos Scripts

Abrir o editor de scripts

1. Na spreadsheet, clicar em Extensoes > Apps Script
2. O ficheiro Code.gs aparece com todo o codigo

Adicionar uma nova funcao

1. No final do ficheiro Code.gs, adicionar a nova funcao:

   function minhaNovaFuncao() {
     var ss = SpreadsheetApp.getActiveSpreadsheet();
     // ... codigo aqui
   }

2. Guardar com Ctrl+S (ou o botao guardar)

Correr uma funcao manualmente

1. No editor Apps Script, selecionar o nome da funcao no dropdown (topo, ao lado do botao ▶)
2. Clicar ▶ Executar
3. Na primeira execucao, o Google pede permissoes — aceitar

Adicionar uma funcao ao menu da spreadsheet

Editar onOpen() em Code.gs:

function onOpen() {
  var ui = SpreadsheetApp.getUi();
  ui.createMenu('Gestao Consultas')
    .addItem('...items existentes...', '...')
    .addSeparator()
    .addItem('Nome visivel no menu', 'minhaNovaFuncao')  // <-- adicionar aqui
    .addToUi();
}

Depois recarregar a spreadsheet (F5) para o menu atualizar.

Criar um trigger automatico (ex: correr diariamente)

1. No editor Apps Script, clicar no icone de relogio (Triggers) na barra lateral
2. Clicar + Adicionar Trigger
3. Selecionar a funcao, tipo de trigger (horario, ao abrir, ao editar, etc.) e confirmar

Depurar erros

• Os logs aparecem em Apps Script > Execucoes (icone de lista na barra lateral)
• Usar console.log('valor:', variavel) para imprimir valores no log
• Erros em runtime mostram a linha exata no log de execucao