practice-books-kit

Practice Books Kit — Contabilidade + Folha de Pagamento para uma Clínica de Terapia Privada

Propósito

Fornecer ao proprietário de uma clínica privada um sistema financeiro completo e repetível em duas partes:

• Parte A — Contabilidade mensal. Alimente o agente com os extratos bancários e de cartão do mês. O agente classifica cada transação em um plano de contas fixo e preenche uma coluna mensal de uma planilha de lucros e perdas (P&L), depois comprova que o mês fecha antes de reportá-lo.
• Parte B — O aplicativo Practice Books. Um pequeno aplicativo web somente para administradores que o agente constrói e implanta para o proprietário: folha de pagamento mensal para contratados (1099) e funcionários (W-2) (execução de pagamentos, contracheques, resumos anuais), mais um painel Financeiro somente leitura que visualiza a planilha de P&L da Parte A.

As duas partes se reforçam mutuamente: as Despesas com Contratados do aplicativo podem ser conciliadas com o P&L, e o painel significa que o proprietário sempre vê os números atuais sem precisar abrir a planilha.

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

Entregue ao seu agente de IA esta pasta inteira e, em seguida:

1. Responda à entrevista de configuração abaixo — o agente deve fazer essas perguntas uma vez, antes de qualquer outra ação.
2. Confirme o plano de contas em references/categories.md — mantenha os nomes e a ordem, a menos que uma categoria realmente não se aplique à sua clínica; o agente deve confirmar com você antes do primeiro preenchimento.
3. Entregue um mês de extratos e deixe o agente fazer um primeiro preenchimento. Revise sua reconciliação e a lista de julgamentos; corrija qualquer coisa uma vez, e o agente registra sua decisão como uma regra permanente para os meses seguintes.

Entrevista de configuração (coletar uma vez, anotar, reutilizar todo mês)

O agente deve coletar — e nunca adivinhar — o seguinte antes do primeiro preenchimento ou construção do aplicativo:

• Clínica: nome legal, nome do proprietário, estado(s) de operação, tipo de entidade.
• Contas (os últimos 4 dígitos são suficientes como identificadores):
  • Conta corrente empresarial principal (onde a receita de pagadores cai).
  • Subconta de folha de pagamento, se a clínica usar uma para pagar contratados.
  • Subconta de impostos/poupança, se houver (transferências para ela são internas).
  • Cartão(ões) de crédito empresariais.
  • Contas pessoais/patrimoniais do proprietário que recebem transferências (necessárias para reconhecer retiradas do proprietário).
• Extratos: como o proprietário os fornecerá a cada mês (exportação CSV preferida, PDF se for tudo o que o banco oferece), e qual coluna de data rege o mês (data da transação, não data de postagem, a menos que o proprietário decida de outra forma).
• Convenção de pagamento: o padrão é pago no dia 1º do mês pelo trabalho do mês anterior. Confirme ou registre a convenção real da clínica.
• Pessoas e termos de pagamento (para a Parte B): cada contratado/funcionário, seu tipo (1099 ou W-2), e seus termos de pagamento exatos — percentual dos recebimentos, valor fixo por sessão, por hora ou salário; qualquer divisão separada de pagamento particular/escala móvel; quaisquer deduções recorrentes (por exemplo, uma taxa de assento do EHR). Nunca adivinhe uma taxa de pagamento. Se uma taxa estiver faltando, deixe-a não configurada e sinalize-a.
• Receita fora do extrato: pergunte explicitamente como a clínica recebe dinheiro que nunca chega ao feed bancário — supervisão ou aluguel pagos por Zelle/Venmo/dinheiro/cheque, por exemplo. Esses pagamentos devem ser capturados de e-mails/alertas de pagamento a cada mês ou o P&L subestimará silenciosamente a receita.

Parte A — Fluxo de trabalho mensal de extrato para P&L

Arquivos de referência: references/categories.md (plano de contas + guia de classificação) e references/pl-sheet-spec.md (layout da planilha, fórmulas e o procedimento de preenchimento). Siga-os exatamente.

1. Reúna TODOS os extratos do mês. Conta corrente principal, subconta de folha de pagamento, cada cartão empresarial, mais a varredura fora do extrato (etapa 2). Se um extrato estiver faltando, diga e preencha apenas o que os extratos fornecidos suportam — nomeie a lacuna no relatório (por exemplo, "Despesas com Contratados pendentes do extrato da conta de folha de pagamento") em vez de preencher ao redor dela silenciosamente.
2. Varra por receita fora do feed. Pesquise os e-mails/alertas de pagamento do proprietário do mês (notificações Zelle/Venmo "você recebeu dinheiro", etc.) e adicione receitas comerciais confirmadas ao livro-razão com sua fonte anotada. Receitas pessoais encontradas na mesma varredura são excluídas e listadas.
3. Analise cada transação de cada extrato em um livro-razão: data, conta de origem, descrição, valor (créditos positivos, débitos negativos).
4. Exclua movimentação interna de dinheiro — não é receita nem despesa:
   • Transferências entre as próprias contas da clínica (conta corrente ↔ subconta de folha de pagamento ↔ subconta de impostos).
   • Transferências para as contas pessoais/patrimoniais do proprietário — estas são retiradas do proprietário, nunca despesas.
   • Pagamentos de cartão de crédito (pagamento automático ou manual) — as compras do cartão são as despesas; o pagamento apenas move dinheiro entre contas.
5. Classifique cada transação restante usando references/categories.md. Pagamentos ACH para contratados feitos a partir da conta de folha de pagamento são Despesas com Contratados. Se uma transação não se encaixar em nenhuma regra, coloque-a na lista de julgamentos para o relatório — nunca a descarte silenciosamente e nunca invente uma nova categoria sem a aprovação do proprietário.
6. Some por categoria nos valores da coluna do mês (despesas negativas).
7. Escreva a coluna do mês conforme references/pl-sheet-spec.md: apenas células de categoria, depois as fórmulas de totais, afirmando o resultado da escrita (contagem de células) antes de confiar nele.
8. Leia de volta e feche. Releia a coluna escrita da planilha e verifique-a em relação ao livro-razão calculado independentemente:
   • Soma da receita categorizada = total de créditos do extrato menos itens excluídos (transferências internas recebidas, reembolsos de cartão tratados conforme a regra do proprietário).
   • Soma das despesas categorizadas = total de débitos do extrato menos itens excluídos.
   • Cada transação no livro-razão é contabilizada exatamente uma vez: categorizada, excluída-com-motivo ou listada como não classificada. Se o fechamento falhar, corrija antes de relatar — não relate um mês que não reconcilia.
9. Reporte o mês ao proprietário: receita, despesas, líquido; totais acumulados no ano; os julgamentos feitos (com valores) e as decisões do proprietário registradas como regras permanentes; qualquer coisa não classificada; quaisquer extratos faltantes. Mantenha o relatório factual e completo — o proprietário audita a partir dele.

Regras rígidas da Parte A

• Apenas valores reais. Use valores reais de transações dos extratos. Nunca estime, faça média, anualize ou insira um número para fazer um mês "parecer completo". Um mês incompleto é relatado como incompleto.
• Nunca sobrescreva uma célula inserida manualmente. Se o proprietário já digitou um valor em uma célula que você está prestes a escrever e ele difere do seu, mantenha o dele, sinalize o conflito no relatório e reconcilie abertamente — uma entrada pré-existente geralmente vem de uma fonte que você não tem.
• Despesas são números negativos na planilha; as fórmulas de totais dependem disso.
• Reembolsos são compensados contra a despesa, nunca registrados como receita. Quando alguém reembolsa a clínica por um custo específico que a clínica adiantou (o caso clássico: um contratado reembolsando sua taxa de assinatura do EHR do grupo), subtraia o reembolso dessa categoria de despesa no mês recebido. Registrar como receita infla ambos os lados.
• Transações pessoais são excluídas e listadas no relatório, não categorizadas "para garantir".
• Aplique as decisões do proprietário consistentemente. Quando o proprietário corrigir uma classificação uma vez, escreva a regra (em sua memória/notas para esta clínica) e aplique-a todo mês depois sem perguntar novamente.

Parte B — O aplicativo Practice Books

Arquivo de referência: references/app-spec.md — modelo de dados, regras de pagamento, ciclo de vida de execução, contrato do leitor de finanças, lista de gráficos e portões de implantação. Construa de acordo com essa especificação.

Formato do trabalho:

1. Confirme os dados da entrevista de configuração (especialmente pessoas + termos de pagamento). Não construa nada financeiro com base em uma taxa adivinhada.
2. Construa localmente primeiro. Escreva o código do servidor + cliente e um ambiente de teste local que simule a camada de planilha e chame cada função do servidor nas mesmas formas de argumento que o cliente envia. Cubra no mínimo: matemática de base de pagamento (percentual / fixo / divisão privada), guardas de ciclo de vida de execução (uma execução deve passar por Aprovado antes de Pago), a gravação Pago → Histórico de Pagamentos, o sinalizador do limite de $600 do 1099, o limite da base salarial do FICA do W-2 e o analisador financeiro contra strings de formato contábil.
3. Implante com portões. Envie o código, depois leia o conteúdo do projeto implantado de volta e exija uma correspondência byte por byte com os arquivos locais testados antes de criar uma versão — uma implantação com conteúdo desatualizado parece idêntica a uma boa até que alguém abra o aplicativo. Atualize as implantações existentes para a nova versão; nunca crie uma nova URL de implantação (cada nova URL é um link que alguém precisa atualizar, e URLs antigas continuam servindo código antigo). Após a atualização, liste novamente as implantações para confirmar que a versão realmente foi movida (as listas de implantação podem levar alguns segundos para refletir a mudança).
4. Autorização do proprietário é uma etapa manual única. O proprietário abre o projeto uma vez e aprova os escopos (spreadsheet + send-mail). Até lá, a URL do aplicativo mostrará um erro de acesso — isso é esperado, não é um bug.
5. Checklist de primeira execução para o proprietário: desbloqueie, confirme que a planilha de dados foi criada automaticamente, sincronize/adicione pessoas, defina a base de pagamento e a taxa de cada pessoa e, em seguida, crie a primeira execução de pagamento (mês anterior) como uma execução de teste em Rascunho e revise as linhas antes de aprovar qualquer coisa.

Limites do aplicativo (informe ao proprietário antecipadamente)

• O aplicativo apenas calcula e registra. Ele não arquiva impostos eletronicamente (1099/W-2/941), não movimenta dinheiro nem faz pagamentos, e não envia nada para nenhuma agência. O proprietário paga as pessoas pelo banco como de costume; o aplicativo registra que isso aconteceu.
• Os valores de retenção do W-2 são estimativas (método de percentual anualizado a partir de uma guia de tabelas de impostos editável) para o contador do proprietário verificar — nunca os apresente como prontos para arquivamento.
• Sem números completos de SSN/EIN ou contas bancárias na planilha do aplicativo. Armazene apenas sinalizadores "formulário fiscal registrado" / "ACH registrado"; identificadores completos permanecem nos sistemas seguros existentes da clínica.
• O aplicativo é somente para administradores: uma porta de entrada de login do proprietário (por exemplo, um PIN verificado no servidor contra uma lista de funcionários), e cada função do servidor verifica novamente a autorização do chamador. Os prestadores nunca veem o aplicativo; sua própria visualização de pagamento, se houver, é uma superfície separada somente leitura.
• O painel Financeiro é somente leitura — o aplicativo nunca escreve na planilha de P&L. O preenchimento mensal (Parte A) continua sendo a única maneira de inserir números no P&L.

Regras operacionais para o agente

• Siga os arquivos de referência em vez de improvisar; onde uma referência e uma instrução ao vivo conflitam, a instrução atual do proprietário vence e a alteração é anotada.
• Verifique a partir do artefato, não por conta própria: leia de volta as planilhas após as gravações, leia de volta o código implantado após as implantações e execute o ambiente de teste após as alterações de código.
• Quando uma etapa falhar, relate o que falhou, em que estado as coisas realmente estão e o que acontece a seguir. Nunca relate um preenchimento, uma implantação ou uma execução de pagamento como concluída com base no fato de tê-la iniciado.