Solo Consult Booking Kit — Kit de Agendamento de Consulta Inici…

Kit de Agendamento de Consulta Inicial — Sistema de Consulta Inicial para Consultório Individual (Solo Practice)

⚠️ Leia isto primeiro — o pré-requisito HIPAA (antes de construir qualquer coisa)

Este sistema só é compatível com HIPAA se for executado dentro de uma conta Google Workspace com um Acordo de Associação Comercial (BAA) assinado. Não construa, implante ou coloque dados reais de clientes nele até que todas as seguintes condições sejam verdadeiras:

1. Você tem Google Workspace (Business Starter, Standard, Plus ou uma edição equivalente coberta) no domínio próprio do seu consultório — não uma conta pessoal gratuita do Gmail (@gmail.com). Uma conta pessoal não tem BAA disponível para assinar e nunca deve conter este sistema ou seus dados.
2. O BAA do Google Workspace está assinado. No console de administração do Google (Admin → Conta → Jurídico / "Emenda de Associação Comercial" — o nome exato do menu muda com o tempo), revise e aceite o BAA para Google Workspace / Cloud Identity e mantenha um registro da data. A assinatura é um clique único de aprovação por um administrador do Workspace; se você não conseguir encontrá-lo, pare e resolva isso primeiro — não prossiga presumindo que está coberto.
3. Tudo está nessa conta do Workspace. Os projetos do Apps Script, a planilha de agendamento, o calendário que recebe as consultas e a caixa de correio que envia as confirmações devem pertencer ao mesmo usuário do Workspace (você). Não execute nenhuma parte disso em uma conta pessoal do Google e não aponte agendamentos para um calendário pessoal — uma conta pessoal está fora do BAA.
4. A segurança da conta está ativada: Verificação em Duas Etapas obrigatória para a conta (chaves de acesso / Proteção Avançada são melhores), uma senha forte e única em um gerenciador de senhas e opções de recuperação que você controla.

Software não pode ser "certificado HIPAA", e este kit não torna um consultório compatível com HIPAA por si só. Ele é construído com salvaguardas de suporte à HIPAA (minimização de dados, links de gerenciamento com hash e expiração, eventos de calendário genéricos, varredura de retenção, registro de auditoria — veja references/security-and-hipaa.md), e é executado em um fornecedor (Google) que assinará um BAA. A conformidade também requer sua própria análise de risco, políticas, treinamento e um Aviso de Práticas de Privacidade. Se algum pré-requisito acima estiver faltando, o primeiro trabalho do agente é ajudar o proprietário a corrigir isso — não construir os aplicativos.

Propósito

Fornecer a um clínico individual o sistema de agendamento que um consultório em grupo usa, sem a complexidade de grupo:

• Parte A — Aplicativo Público de Agendamento. Uma página web pública (incorporada no site do consultório) onde um cliente em potencial responde a uma breve verificação de adequação (estado, pagamento, para quem é a consulta, idioma), vê apenas vagas genuinamente abertas — suas horas de consulta declaradas menos os horários ocupados do seu calendário real, folgas e agendamentos existentes — e agenda uma consulta inicial gratuita (15 minutos por padrão; configurável). O cliente recebe um e-mail de confirmação com um arquivo .ics e um link privado de remarcação/cancelamento; você recebe uma notificação mínima. Lembretes (~24h antes) e acompanhamentos pós-consulta são executados em um temporizador.
• Parte B — Console do Proprietário (um aplicativo, três visões). Um aplicativo privado, protegido por PIN, usado apenas por você, que mescla o que um consultório em grupo divide em três aplicativos:
  • Minhas Consultas — consultas futuras / passadas / canceladas, detalhes completos ao clicar, marcar uma consulta passada como não comparecimento.
  • Disponibilidade — definir horas de consulta semanais (dias divididos permitidos), horas específicas por data, folgas, aceitar-novos-clientes ligado/desligado e configurações de agendamento (limite de frequência de consulta, aviso mínimo, buffers, incremento de intervalo); ver sua disponibilidade resolvida e os próximos 7 dias de vagas abertas exatamente como a página de agendamento as calcula.
  • Configurações e Ferramentas — editar cada modelo de e-mail e regra de agendamento sem tocar em código, ver estatísticas de agendamento e a trilha de auditoria, exportar auditoria / CSV de agendamentos (nunca os tokens de gerenciamento).

Implementação de referência: dois aplicativos web do Google Apps Script apoiados por uma planilha e seu próprio Google Calendar. Nenhum serviço de agendamento de terceiros, sem análise, sem rastreadores.

O que a edição solo deliberadamente remove (grupo → solo)

• Sem aplicativo "Conecte Seu Calendário". Em um consultório em grupo, esse aplicativo existe por um motivo: cada profissional, conectado como ele mesmo, compartilha seu calendário com a conta central do consultório com permissão "Fazer alterações em eventos" e registra o ID do calendário de volta no sistema de agendamento. Um proprietário individual é o proprietário do script e o proprietário do calendário — o aplicativo de agendamento já é executado como você, com acesso de proprietário ao seu calendário. Não há nada para compartilhar e nada para registrar. A configuração é apenas: coloque o ID do seu calendário na guia Config (o ID do seu calendário principal é simplesmente seu endereço de e-mail; ou crie um calendário dedicado "Consultas Iniciais" na mesma conta do Workspace e use seu ID), então execute o checkSetup() embutido e confirme que ele relata accessRole=owner e freebusy=OK.
• Sem pasta de trabalho de registro de profissionais e sem sincronização de registro. Um clínico = uma linha Config contendo nome, credenciais, estados licenciados, painéis, idiomas, idades atendidas, sinalizador de escala móvel, link de biografia, fuso horário, ID do calendário. Nenhum trabalho de sincronização, nenhum ID de profissional entregue a mais ninguém.
• Sem mecanismo de correspondência/roteamento de profissionais. O assistente de grupo roteia um cliente para o clínico certo. O assistente individual apenas verifica a adequação em relação a você: estado errado, um painel que você não aceita, uma faixa etária que você não atende ou sem escala móvel quando isso é necessário → uma mensagem clara de não adequação com seu e-mail de contato, nunca um beco sem saída.
• Sem nada de vários profissionais: sem PINs por profissional em um registro compartilhado (um PIN do proprietário, com hash, na guia Config), sem "editar em nome de", sem filtro de profissional, sem folga de todo o consultório (sua folga é apenas sua folga).

Entregando isso ao seu agente (para o colega recebendo este kit)

Este kit é neutro em relação à plataforma: é Markdown simples (o formato aberto de Skills de Agente) e funciona com qualquer agente de IA capaz — um agente que carrega skills, um agente de codificação com um espaço de trabalho ou um agente apenas de chat com os arquivos carregados. README.md nesta pasta tem as instruções específicas da plataforma e PROMPT.md tem um prompt inicial copiável; qualquer caminho termina no mesmo lugar:

1. Confirme que o pré-requisito HIPAA no topo foi atendido (Workspace + BAA assinado + segurança). Se não estiver, faça isso primeiro.
2. Responda à entrevista de configuração abaixo — o agente deve perguntar uma vez, antes de construir.
3. Deixe o agente construir e testar ambos os aplicativos, execute a lista de verificação de teste em references/test-checklist.md com agendamentos de teste e só então troque seus links públicos para a nova página de agendamento.

Mantenha seu link de agendamento antigo (se houver) ativo como fallback até que a lista de verificação de teste passe de ponta a ponta.

Instruções para o agente construindo isso (qualquer plataforma)

• Trabalhe a partir destes arquivos, não da memória de sistemas semelhantes. Leia este arquivo e cada referência antes de escrever código. Onde uma referência e a instrução ao vivo do proprietário entrarem em conflito, a instrução do proprietário vence e a mudança é registrada.
• Sua entrega são arquivos + etapas verificadas, quaisquer que sejam suas ferramentas. Produza cada projeto como arquivos prontos para colar (Code.gs, Index.html, Manage.html quando aplicável, appsscript.json). Se você tiver acesso direto à conta Google do proprietário ou a um caminho de API/implantação do Apps Script, você pode implantar — mas apenas com a autorização do proprietário, e você ainda verifica a partir do resultado servido. Se você não tiver esse acesso (a maioria dos agentes de chat não tem), entregue os arquivos e guie o proprietário por references/setup-and-deploy.md clique a clique: as ações de login no Google, autorização de escopo e implantação são do proprietário, e um agente que não pode fazê-las deve dizer isso claramente, em vez de sugerir que implantou algo.
• Teste nas formas que a produção usará. Construa uma estrutura de teste local que simule a camada de planilha/calendário e chame cada função do servidor exatamente nas formas de argumento que o cliente enviado envia. Execute após cada mudança de código, não apenas no final.
• Nunca exija um recurso específico de fornecedor. Tudo aqui é Google Apps Script + Planilhas + Calendário + Gmail mais Markdown. Se sua plataforma oferecer uma conveniência (uma integração de implantação, uma ferramenta de arquivo), use-a, mas a construção não deve depender dela — o mesmo kit deve funcionar para o próximo proprietário em um agente diferente.

Entrevista de configuração (coletar uma vez, escrever, nunca adivinhar)

• Pré-requisito: domínio do Workspace, a conta que será proprietária de tudo (por exemplo, [email protected]), BAA assinado (data), Verificação em Duas Etapas ativada.
• Consultório: nome do consultório, seu nome + credenciais como os clientes devem ver, e-mail de contato do consultório, e-mail de notificação (pode ser o mesmo), URL do site, URL da política de privacidade.
• Calendário: calendário principal ou um calendário de consultas dedicado na mesma conta? Seu ID vai na Config. (Recomendado: calendário dedicado — eventos de consulta ficam visualmente separados e você pode compartilhar o livre/ocupado desse calendário sem expor o conteúdo do seu calendário principal. De qualquer forma, o aplicativo só lê livre/ocupado e escreve eventos de consulta genéricos.)
• Perfil de adequação (orienta as opções de pagamento/elegibilidade do assistente — gerado a partir da Config, nunca codificado na página): estados onde você é licenciado; painéis de seguros, EAPs e fundos que você aceita (nomes exatos para o cliente); pagamento particular e escala móvel (sim/não e qualquer redação de piso que você use publicamente); idiomas em que você oferece terapia; quem você atende (adultos / adolescentes / crianças / casais / famílias); se você atende clientes localizados fora dos EUA (se sim: as consultas ainda são gratuitas, mas a terapia contínua é particular/escala móvel — o assistente restringe as opções de pagamento de acordo).
• Regras de agendamento (padrões do sistema de referência — confirme ou altere): duração da consulta 15 min; janela de agendamento 14 dias; aviso mínimo 12 horas; grade de intervalos a cada 30 minutos; buffer de 10 minutos em torno de eventos ocupados; limite de remarcação/cancelamento 4 horas; lembrete 24h antes; acompanhamento pós-consulta 5 minutos após o término da consulta; uma consulta ativa por e-mail/telefone do cliente (proteção contra duplicidade ativada).
• Disponibilidade inicial: suas horas de consulta semanais iniciais + fuso horário, para que a página tenha vagas reais no primeiro dia. (Você as manterá no Console depois.)
• Redação do e-mail: modelos de confirmação, lembrete e acompanhamento (tokens como {ClientFirstName}, {EventDateTime}, {ProviderName}); o link de pesquisa / próximos passos para o qual o e-mail de acompanhamento aponta; o nome/endereço do remetente (seu endereço ou um alias de envio em sua conta como [email protected] — aliases precisam de um escopo OAuth extra, veja a referência de implantação).
• Marca: a aparência do seu site para a página pública (fontes, cor do texto, cor de destaque para botões/links, estilo de canto). A página pública usa um estilo de site plano — sem vidro/aurora de portal, sem marca do Google, sem diálogos nativos do navegador.
• Idioma(s): apenas inglês ou bilíngue? O sistema de referência suporta um segundo idioma completo (um conjunto de perguntas traduzido, e-mails no idioma em que o cliente agendou). Adicione apenas se você realmente atende clientes nesse idioma.
• Aviso de privacidade: a redação curta de privacidade do formulário de agendamento que os clientes devem reconhecer (o que é coletado, que o e-mail não é monitorado para emergências, linha de crise 988 / 911 nos EUA). Cada agendamento armazena o carimbo de data/hora do reconhecimento + versão do aviso. Atualize a string de versão sempre que a redação mudar.

Como tudo se encaixa (um parágrafo)

Ambos os aplicativos são executados como você (USER_DEPLOYING) dentro da sua conta do Workspace. O aplicativo de Agendamento é público e anônimo: os visitantes nunca veem a planilha ou qualquer detalhe do calendário — a disponibilidade é calculada apenas a partir de livre/ocupado. Um agendamento, feito sob um bloqueio de script para que dois visitantes não possam pegar o mesmo intervalo, escreve uma linha na guia Compromissos, cria um evento de título genérico ("Consulta Inicial — ", descrição mínima, sem participante cliente) no seu calendário e envia um e-mail para o cliente (confirmação + .ics + link de gerenciamento privado, token armazenado apenas como um hash SHA-256) e para você (mínimo de triagem, sem nome do cliente no assunto). Um temporizador de 5 minutos envia lembretes e acompanhamentos e executa a varredura de retenção. O Console é protegido por PIN, lê/escreve a mesma pasta de trabalho e é o único lugar onde os detalhes completos do agendamento são visualizados. Modelo de dados completo e regras de precedência: references/architecture.md.

Ordem de construção (não reordenar)

1. Pasta de trabalho + Aplicativo de Agendamento conforme references/booking-app-spec.md e references/setup-and-deploy.md (criar a planilha, executar setupSheet(), checkSetup(), setupTriggers(), implantar).
2. Aplicativo Console conforme references/console-app-spec.md (proteção PIN, Minhas Consultas, Disponibilidade, Configurações e Ferramentas) contra a mesma pasta de trabalho.
3. Testar com references/test-checklist.md — agendamento de teste real de ponta a ponta, tentativa de duplo agendamento, remarcação/cancelamento através do link enviado por e-mail, caminho de não adequação, lembrete/acompanhamento manual.
4. Entrar em produção: incorporar o aplicativo de Agendamento na página de agendamento do seu site, trocar links públicos, manter o link antigo como fallback até que você tenha recebido um agendamento real de forma limpa.

Regras rígidas para o agente (estas são as lições caras)

• Escopos: declare o escopo completo https://www.googleapis.com/auth/spreadsheets sempre que o código chamar SpreadsheetApp.openById — o escopo somente leitura faz com que toda chamada desse tipo lance uma exceção. Se o aplicativo enviar e-mail com ambos GmailApp e MailApp, declare ambos gmail.send e script.send_mail (gmail.send sozinho não cobre MailApp, e as falhas são engolidas por try/catch — o e-mail silenciosamente nunca é enviado). O envio de um alias de envio via GmailApp também precisa de gmail.settings.basic. Os recursos do Calendário precisam do Serviço Avançado do Calendário (v3) ativado no manifesto.
• Implantações: após a primeira implantação, sempre aumente a implantação existente para uma Nova versão. Nunca crie uma nova implantação — uma nova URL quebra cada incorporação e link, e a URL antiga continua servindo código antigo. Leia o conteúdo implantado de volta / verifique a marcação servida…