Módulo 6 - Folha de Pagamento & Acertos (payroll)
Módulo 6: Folha de Pagamento & Acertos (payroll)
Section titled “Módulo 6: Folha de Pagamento & Acertos (payroll)”Estado actual — extratos da equipe. O botão Ver no aviso A devolver abre Pagamentos na página do extrato correspondente, expande o holerite e rola até ele. A lista usa A receber para valores pendentes a favor do funcionário. No PDF, o valor recebido por visita aparece como Conta própria ou Dinheiro.
Estado actual — rastreabilidade da remuneração. Alocação de equipe, finalização, recálculo de horas e correção financeira declaram a origem de cada valor: calculado pela tarifa do cadastro, informado no campo de remuneração, preservado ou comissão. O servidor registra, no histórico da tarefa, ação e endpoint, autor autenticado, data, horas, valor anterior/novo, tarifa padrão ou específica e versão do funcionário consultada. Valores declarados como cálculo automático que não reproduzem horas × tarifa são recusados; valor digitado continua identificado assim mesmo quando coincide com a tarifa. Na correção financeira, “preservado” é conferido contra o mesmo valor de partida que o formulário mostra (recordedStaffPay: o que o holerite pagou, senão o custo registrado, senão a regra da folha) — antes era só contra manualLaborCosts, e uma visita sem custo registrado recusava qualquer correção, até só um item cobrado do cliente, com “Preserved staff pay cannot change”. Uma mudança de tarifa que atualiza visitas futuras registra sua origem própria. A prova é produzida pelo servidor, protegida de substituição pelo payload e visível apenas à gestão; snapshots e diferenças de folhas fechadas permanecem preservados. Registros anteriores ou clientes que não informam a ação ficam explicitamente sem origem identificada: o campo de custo por si só não prova edição manual.
Estado actual — coordenação. Preparação/geração, recálculo do período, transição e cancelamento passam por application/generatePayrollCycle, recalculatePayrollPeriod, transitionPayrollEntry e cancelPayrollEntry, com contratos públicos de folha e efeitos de rede/estado nos hooks. Mantêm Londres, seleção manual, autor e lotes do servidor, linhas manuais, descontos, saldo transportado e deduplicação. Recusa não anuncia sucesso; conclusão de outra sessão não publica registros nem avisos.
Estado actual — equipe e gerentes. Payroll calcula apenas trabalho, gorjetas, extras, ajustes manuais, adiantamentos e dinheiro recebido pela equipe. Não há reserva nem distribuição percentual de lucro. Banking → Drawings (Retiradas) registra valores mensais fixos e retiradas extras, independentes das visitas e da folha. Somente managers ativos podem ser selecionados para novos valores mensais e extras, com a mesma validação na API. Admin configura e registra; manager consulta. Preparar um mês cria uma única obrigação por sócio/mês; alterar ou pausar o valor mensal não muda obrigações já registradas. Pagamentos parciais confirmados têm entidade, conta de saída, data, referência e descrição opcional próprias; a descrição aparece no histórico e no extrato. A descrição da retirada extra também é opcional; somente transferências pagas entram no extrato bancário, dinheiro fica no histórico da retirada. Retry preserva a instrução e não duplica pagamentos; exceder o saldo é recusado. A migração 0208 limpa a reserva e os percentuais de teste, mantendo as bases salariais e proteções das correções.
Estado actual — transferências. Banking → Payroll abre o registro com funcionário, holerite aprovado, valor e método do botão (banco ou dinheiro); a conta filtrada é pré-selecionada. O ícone no Payroll abre o holerite específico da linha, somente após aprovação. No perfil da equipe, Registrar adiantamento abre essa mesma janela, já na pessoa e no tipo adiantamento. Valores negativos abrem uma entrada de dinheiro (IN, devolução de pendência pelo funcionário); positivos, pagamento da folha (OUT). Cada abertura reinicia o formulário. Havendo vários holerites, o seletor identifica qual está sendo pago/devolvido e o valor corresponde somente a ele. A quitação da transferência vincula o payroll_id do holerite.
Estado actual — ajustes após recálculo. O recálculo devolve as linhas manuais junto com os totais, mantendo bônus, reembolsos e descontos na prévia e no PDF sem precisar recarregar. Repetir o recálculo preserva as linhas e não duplica seus valores.
Estado actual — pagar e desfazer (13/10). Marcar um holerite aprovado como pago/quitado ocorre em duas etapas: primeiro registra-se a transferência bancária/em espécie de quitação ([PAYOUT:...] ou [COLLECTION_RETURN:...]) vinculada ao holerite, o que habilita o botão de dar baixa na linha; em seguida confirma-se a baixa no holerite. Sem transferência de quitação, a linha oferece a opção de transferir ou de forçar o fechamento (forceClose: true, marcando carried_forward_to = 'PENDING_CARRY'), transportando a dívida ou crédito para o próximo holerite (balancesToCarry), sem afetar holerites positivos históricos. Quando o funcionário tem valor a devolver à empresa (totalNet < 0), a confirmação e o aviso confirmam explicitamente que o dinheiro foi recebido (“Confirmar recebimento”, “Dinheiro recebido”) e não pago. Um admin ou gerente pode desfazer o pagamento (PAID → APPROVED, botão Desfazer pagamento na linha, também com confirmação), mesmo quando há transferência de quitação vinculada; é recusado (409) apenas se o pagamento quitou um adiantamento deduzido no holerite (employee_advances.payroll_id fora de [PAYOUT:...]/[COLLECTION_RETURN:...]) ou já transportou saldo para uma folha seguinte (carried_forward_to). A History registra o motivo “Payment undone” ou “Force-closed to carry forward”.
Estado actual — recálculo com tarefas tardias. O recálculo agora abre uma modal dedicada com acompanhamento em tempo real (PayrollRecalculateModal): exibe progresso percentual, log de atividades passo a passo, valores antes e depois de cada funcionário, motivo exato em caso de erro individual e botão de tentar novamente nos que falharam. Cada holerite em rascunho (DRAFT) possui seu próprio botão “Recalcular” na linha (PayrollTableRow), permitindo ao gestor recalcular exclusivamente um profissional sem disparar o processo desnecessariamente para todo o período. O recálculo no cabeçalho do período permite selecionar todos ou filtrar quais colaboradores recalcular. Na geração manual (PayrollPeriodPreviewModal), a seleção de funcionários é preservada contra atualizações em segundo plano, conta com atalhos de “Selecionar todos / Desmarcar todos” e discrimina com precisão na confirmação os profissionais incluídos na emissão. O endpoint /api/atomic/payrollEntries?recalculate=true aceita entryId único ou período completo, com tratamento seguro por item e sem travar a interface. O recálculo espera até 180 s no app (PERIOD_RECALCULATION_TIMEOUT_MS). Regenerate/Recalculate registra no histórico do holerite a regeneração manual, autor e horário após salvar, mesmo se os totais não mudarem; uma recusa não gera esse registro. Recalculate inclui no holerite DRAFT tarefas concluídas após a geração e tarefas antigas pendentes com data até o fim do período, além de cancelamentos com compensação. Visitas já incluídas em outro holerite da mesma pessoa não se repetem. Repetir o recálculo conserva as inclusões e descontos sem duplicação; tarefas de período posterior, holerites Approved/Settled ficam fora. A base salarial original e suas correções continuam preservadas, somando as novas tarefas. O salvamento verifica novamente as fontes para recusar concorrência com outra geração, recálculo ou alteração de tarefa.
Estado actual — sequência automática. A folha automática só gera o próximo período quando todos os holerites anteriores estão PAID/Settled. Holerite Draft/Approved bloqueia a geração sem consumir a tentativa da semana; nas próximas execuções elegíveis do cron, a regra é reavaliada. O batch repete a guarda para impedir uma geração concorrente. A geração manual continua explícita.
Estado actual — sem fechamento (13/10). A folha não tem mais o passo “Fechar período”: o fluxo é Aprovar → Pagar. Aprovar mostra o holerite à pessoa (o boot da funcionária devolve tudo que não é DRAFT) e envia o push “Your payslip is ready”; o cron de liberação de domingo e PUT /atomic/payrollRuns foram removidos, junto com a janela de fechamento. Cada período da lista mostra o próximo passo (N para aprovar → N para pagar → Período quitado) e é nomeado só pelas datas (sem “Auto:”/“Custom:”; o histórico de execuções diz qual foi automática ou manual). O link do período gerado no calendário abre esse período na tabela abaixo (rola até ele) em vez da prévia, e abrir o calendário sempre começa no próximo período ainda não gerado até hoje (verde = início, azul = fim; âmbar = já está numa folha). A folha automática espera só que todos os holerites anteriores estejam PAID (automaticPayrollReadySql, cópia na tela unpaidPayslipCount), fica devida do dia/hora configurados até o fim da semana para o mesmo período de segunda a domingo, e avisa admins e gerentes uma vez por semana (PAYROLL_AUTO_WAITING, push ao reference_id). Visitas de dias anteriores que ninguém concluiu nem cancelou aparecem em Visitas não concluídas na página, sem travar nada; concluídas, entram na próxima folha. Desfazer pagamento não depende mais de período fechado. Opções da linha e estágios: a linha de resumo da pessoa exibe exclusivamente o ícone de abrir o holerite e a seta de expandir. Ao abrir o holerite, o documento e a modal identificam explicitamente se é Rascunho (provisório) ou Final (Emitido/Quitado). Ao expandir a linha, são exibidas apenas as opções do estágio corrente nos 3 estados padronizados (Draft, Issued e Paid): em Draft, Emitir holerite, Excluir rascunho e Quitar dívida (exclusiva para rascunho com saldo anterior trazido, dando baixa na dívida e recalculando o rascunho de imediato); em Issued, Voltar para rascunho e Pagar/Confirmar recebimento (ou Transferir/Forçar quitação); em Paid, selo de quitado e Desfazer pagamento. Os filtros da tabela contam com All, Drafts, Issued e Paid.
Estado actual. Cancelar substitui os custos planejados (horas ou comissão) pela compensação informada para o cancelamento; sem compensação, limpa o pagamento da equipe. O Worker também limpa custos antigos quando um cliente anterior omite esse campo na transição. A geração e o recálculo de rascunho contam no Worker (POST /api/atomic/payrollGenerate e POST /api/atomic/payrollEntries?recalculate=true): o cliente manda só o ciclo ou o period; totais, visitas e IDs não são autorados no aparelho. Adiantamento descontado uma vez. Gorjetas 100% à funcionária. Uma despesa da visita (financials.staffExtras) sai da empresa e soma no holerite de quem foi nomeado, por baixo do valor da visita, sem entrar na fatura. closedBy/closedAt vêm da sessão e do D1, não do aparelho. O PDF usa o mesmo PayslipDocument na prévia administrativa e no acesso do funcionário: resumo de horas, recebido em cash, recebido por bank transfer na conta do funcionário e saldo; a taxa horária fica somente em cada tarefa. A tabela do PDF não tem a coluna Saldo por tarefa (desde 2026-11-07): Data, Cliente, Horas, Valor/hora e Recebido; uma linha manual ou uma correção traz o próprio valor abaixo da descrição; o saldo fica só no resumo e no rodapé. Recebimentos por meio vêm das visitas, enquanto o rodapé mantém o total recebido gravado no holerite. Taxas diferentes são mostradas por tarefa; quem só recolhe dinheiro não ganha horas. O total recebido do rodapé e o saldo preservam os valores gravados do holerite, com saldo negativo a devolver; em aprovado/pago, horas e detalhes atuais das visitas são identificados como referência. Tabela administrativa padronizada com densidade compacta (px-4 sm:px-6 py-3.5), UserAvatar, componentes Button canônicos e modal de pré-visualização/exportação em PDF do holerite (PayslipPreviewModal), com discriminação completa dos serviços incluídos e suporte visual a gerentes com valores de caixa a compensar. A tabela conta com barra operacional (TabToolbar) contendo busca por nome/função/período (CFInput) e pílulas de status (StateFilterPills: All, Drafts, Approved, Settled, Owing Company com contagens reativas). Os botões Recalculate e Approve ficam alinhados à direita na coluna Options do período. O recálculo atualiza todos os holerites DRAFT desse período pelo Worker, preservando aprovados e pagos. O lote informa quantos foram atualizados e quantos falharam; uma falha individual não anuncia sucesso completo. Quando o recálculo traz dado novo (valor ou visita mudou em pelo menos um holerite), o Worker grava uma linha em payroll_recalculations (migration 0205), listada no histórico de execuções (PayrollRunHistory) como execução Manual com status Recalculated, autor, horário, holerites alterados e o líquido deles; sem mudança, nada é listado (a auditoria do holerite continua). Não é um payroll_runs: não abre nem fecha período e não bloqueia a folha automática. Holerites pagos (Settled) mostram o cadeado e não oferecem ações de edição (status, adiantamento/transferência), mas com as cores normais, sem aparência de desativado. A seção Folhas geradas agrupa os holerites pelo período gerado, apresentando para cada grupo um cabeçalho com contagem, status e botão de aprovação em lote para rascunhos pendentes (onBatchApprove), além de um banner com o somatório exato de 5 métricas financeiras (horas a receber brutas, valores recebidos em dinheiro, recebidos em conta própria, a devolver/descontados e total líquido). A lista de folhas é uma tabela de períodos, sem os filtros Active Cycle/All Periods; abrir um período colapsa o anterior. Apenas o primeiro período da página começa aberto. A lista e o histórico de execuções usam o Pager padrão, com dez registros por página. Os profissionais permanecem em ordem alfabética (staffName) na tabela e nas prévias de folha. A linha principal de cada funcionário no ciclo ativo resume quantidade de horas trabalhadas, recebimentos em dinheiro e conta própria somados e saldo líquido, negativo quando há devolução; valores financeiros completos ficam no detalhe. A lista de tarefas termina sem aviso de regra de acerto nem rodapé de quantidade de serviços ou Self-Employed. Ao expandir um funcionário, as mesmas cinco métricas aparecem imediatamente abaixo do nome, antes das tarefas, incluindo valores zerados e sinal negativo no líquido a devolver. Cada tarefa identifica os recebimentos em dinheiro (CASH) ou em conta própria (EMPLOYEE_ACCOUNT). A tabela de tarefas usa Plus Jakarta Sans, valores em peso bold e referências na mesma família, e mantém horas, taxas, valores, sinais e ícones, sem os rótulos custom/negociado/Direct Collection/No direct collection nem os textos explicativos abaixo de Task Settlement. O calendário ocupa a largura inteira da página, abrindo colapsado com o intervalo do período no cabeçalho, folha automática e botão de prévia da folha. Finalizar conferência fica dentro da prévia, apenas para um ciclo gerado e aberto cujas datas coincidam com o período mostrado; o ciclo anterior nunca é escolhido automaticamente. Clicar no período gerado mostrado ao lado da semana abre a prévia com as datas desse ciclo. A prévia mostra também os holerites já gerados nesse período e permanece aberta após gerar, para conferir e finalizar. Ao expandir o calendário manual, o corte Até Hoje (Agora) é aplicado automaticamente; fechar o calendário não altera o período. O calendário inicia a semana na segunda-feira, exibe o número da semana ISO (Sem {num} / W{num}) em cada linha e destaca as semanas e períodos já gerados em tom âmbar legível e contrastante (amber-100 / amber-950) em vez de cinza desbotado, além de exibir na coluna lateral de cada semana os períodos de folha gerados com o total pago. A prévia manual é calculada no Worker sem gravar e oferece checkbox por funcionário e seleção de todos. Totais e confirmação consideram somente os marcados; a geração valida os IDs e calcula os valores no servidor. Funcionários desmarcados podem ser gerados depois no mesmo período, sem repetir salários ou descontos. O resumo da prévia manual apresenta somente funcionários, tarefas, deduções e líquido, sem KPI de Profit Share. A prévia manual e os holerites já gerados dentro dela reutilizam a mesma linha da folha: Pessoa → Horas → Recebido → Saldo → Opções. A seleção fica junto ao nome apenas na prévia; aprovação e pagamento permanecem na folha gerada. Expandir mostra a mesma tabela de tarefas e os mesmos ajustes adicionais; horas e recebimentos respeitam os snapshots quando disponíveis. Horas próprias prevalecem, senão divide-se o esforço entre a equipe; quem apenas recolhe dinheiro não ganha horas. Líquido a devolver é exibido com sinal negativo. Nos detalhes, Staff Rate mostra o custo manual dividido pelas horas quando disponível, preservando a indicação de comissão. O botão de prévia da folha abre a modal PayrollPeriodPreviewModal na janela inteira ao lado do sidebar (desktopPresentation="page"), utilizando PayrollTaskBreakdownTable com paridade completa com a tabela de fechamento: exibe quantidade de horas trabalhadas da funcionária, taxa horária cobrada do cliente (Rate Cliente), taxa horária recebida pela funcionária (Rate Funcionário), discriminação de gorjetas e pagamentos recolhidos, e tarefas clicáveis que abrem os detalhes da visita (ServiceDetailsModal via TaskActionRegistry) em camada sobreposta sem fechar a prévia. Ao clicar em gerar folha, uma janela de confirmação alerta sobre as consequências da geração manual (selamento imediato das tarefas e antecipação do ciclo) com aviso reforçado caso a folha automática semanal esteja ativada (autoPayrollEnabled); a geração só persiste com essa confirmação explícita, e fechar a prévia não salva nada. Logo abaixo do calendário, a tabela de falhas na folha (PayrollGapsTable) lista exclusivamente atendimentos concluídos que pertençam a períodos de folha já fechados e que não tenham sido pagos, sem listar tarefas a faturar de ciclos abertos ou futuros. A grade preenche a primeira e a última semana com os dias do mês anterior e do seguinte, em tom mais claro. Semanas passadas que já possuem folha gerada e integralmente concluída (sem tarefas pendentes e com todos os colaboradores apurados) ficam permanentemente fechadas (CLOSED) no calendário (em tom âmbar), bloqueando sua seleção e impedindo a geração retroativa de semanas passadas; porém, quando uma semana foi apenas parcialmente gerada (ex.: folha emitida para um ou alguns colaboradores enquanto outros ainda estão pendentes, ou com tarefas por apurar), essa semana permanece aberta para prévia (Preview Payroll) e emissão para os demais colaboradores, sem bloquear o botão nem as datas. Semanas futuras além da semana corrente também permanecem bloqueadas. Tarefas atrasadas ou pendentes pertencentes a períodos já fechados aparecem na tabela de falhas na folha (PayrollGapsTable) com o aviso explícito de que serão apuradas e pagas automaticamente na folha da semana atual, sem necessidade nem permissão de regerar a folha da semana passada. A seleção de período no calendário é estritamente semanal (segunda a domingo): tocar em qualquer dia da grade ou no crachá da semana (W{num}) seleciona a semana inteira correspondente (segunda a domingo), sem seleção fragmentada ou períodos aleatórios de dias avulsos. Ao fechar ou gerar a folha no meio da semana (ex.: quarta ou quinta-feira), o fechamento cobre a semana inteira de segunda a domingo (com teto no domingo da semana atual endOfWeek(today, { weekStartsOn: 1 })), sem erro de data futura: as tarefas já concluídas (DONE) são apuradas e quitadas, enquanto as visitas ainda abertas ou futuras permanecem pendentes e entram normalmente quando finalizadas ou na folha automática seguinte. Ao gerar ou pré-visualizar a folha para a semana atual que já foi previamente gerada, o sistema apura exclusivamente a diferença: colaboradores que já estavam com a folha fechada e paga (PAID) e possuem novas tarefas concluídas no período recebem um holerite aditivo com novo identificador (-diff), contendo unicamente os novos trabalhos; colaboradores com holerite em rascunho (DRAFT) têm o rascunho existente atualizado no local (UPDATE), recalculando seus totais com as novas tarefas sem duplicar o holerite; e colaboradores que já estavam com a folha fechada e paga (PAID) sem novas tarefas a receber não são repetidos na prévia (previewEntries) nem na geração. O seletor de período tem layout compacto com sugestão automática de data de início baseada no término da última folha registrada (lastRun.periodEnd + 1 dia, com teto na semana atual para não pular para semanas futuras e manter a semana corrente sempre aberta a prévias e emissões para os demais colaboradores) e botões de atalho de corte rápido (“Até Ontem” cobrindo a semana anterior e “Até Hoje (Agora)” cobrindo a semana corrente de segunda a domingo). Suporta inclusão retroativa de atendimentos finalizados posteriormente, geração automática semanal em segundo plano (AutoPayrollModal / payrollConfig) na madrugada de segunda-feira (03:00) cobrindo a semana de segunda a domingo (23:59:59), com conferência da gerência na segunda-feira e liberação de holerites para a equipe assim que o ciclo for conferido e fechado (CLOSED). Mudar a hora da funcionária, ou a hora dela para um tipo de serviço, regrava o custo dela nas visitas em que está escalada, que ainda não começaram e cujo dia em Londres é o da alteração ou um dia seguinte (horas × a hora nova); uma visita de um dia anterior fica com o custo que já tinha, e o preço do cliente não muda. A aba Transferências e Acertos (TransfersTab) gerencia a quitação física de holerites aprovados, saídas de adiantamentos e entradas de devoluções de dinheiro de clientes e cobranças manuais por transferência ou em espécie, consolidando saldos credores e devedores por funcionária e repassando créditos compensatórios para a folha subsequente.
Falhas inesperadas ao gravar lançamentos ou criar/fechar uma execução de folha passam por atomicServerError. O painel administrativo conserva o diagnóstico sanitizado por ação; nenhuma das quatro experiências recebe stack, SQL ou mensagem interna do D1. Regras de fechamento e validações de negócio permanecem respostas específicas.
O módulo Payroll automatiza o fechamento financeiro quinzenal ou mensal das funcionárias de limpeza, considerando remuneração por trabalho, ajustes manuais e acertos da equipe.
A geração prepara o período em lote: serviços, IDs já pagos e cancelamentos posteriores são indexados uma única vez antes dos lançamentos individuais. Assim, aumentar a equipe não repete a leitura integral dos mesmos atendimentos para cada profissional. As regras de elegibilidade e os valores permanecem idênticos — incluindo custo manual de cancelamento, divisão por equipe, Cash in Hand, adiantamentos e proteção contra pagamento duplicado — em navegador, PWA e shells nativos.
A persistência da geração é indivisível. POST /api/atomic/payrollGenerate calcula no Worker e grava ciclo, holerites e bases salariais em um único batch D1. Retry equivalente é idempotente; colisões divergentes recebem 409. Stores e avisos só avançam após a confirmação integral.
A janela Close Period lista as tarefas em aberto do período por data, com referência, cliente, status e equipe; clicar abre a visita por cima da janela. A verificação acompanha alterações nas tarefas enquanto a janela está aberta.
O fechamento usa uma trava síncrona antes do primeiro await, compartilhada por confirmação, geração suplementar e saída do diálogo. O Worker repete a regra decisiva no UPDATE: somente um ciclo OPEN sem tarefas abertas dentro de periodStart/periodEnd pode ser fechado. A primeira decisão concorrente vence; as demais recebem 409 sem reescrever assinatura ou horário. closedBy é resolvido pela sessão/registro da profissional e closedAt pelo relógio do D1, portanto o aparelho não pode forjar a auditoria. Datas autoritativas retornadas diretamente à interface usam ISO 8601 UTC com sufixo Z, evitando interpretações diferentes entre Safari/iOS e Chromium/Android/desktop. A resposta autoritativa alimenta store e log. Falha retorna false, mantém a folha aberta com os dados de verificação e permite retry. Loading e trava são liberados em finally, portanto uma exceção não congela a interface e dois toques no mesmo frame não duplicam o fechamento. A criação individual de ciclo é somente insert: colisão de ID não pode alterar rótulo, totais ou um período já fechado; autor e horário também são derivados no servidor.
A aprovação e a liquidação também são confirmações autoritativas. POST /api/atomic/payrollEntries cria somente DRAFT e recusa colisão de ID sem sobrescrever valores (exceto quando chamado explicitamente com ?recalculate=true e { period } para recalcular, um após o outro, os holerites rascunho desse período com base nos dados mais recentes sem resetar o ciclo inteiro); PUT aceita exclusivamente DRAFT → APPROVED → PAID e a volta APPROVED → DRAFT (botão Back to draft na linha, auditado; aprovar não quita nada, os adiantamentos só na liquidação), exigindo o estado esperado no próprio UPDATE; PAID é final. Regressão, salto ou uma segunda decisão concorrente retorna 409 com o status e o valor de adiantamentos persistidos para a tela se reconciliar. Cada holerite possui ownership síncrono contra toque duplo, mantém o botão desabilitado e ocupado enquanto salva e só altera o estado local ou anuncia Fiscal Period Sealed depois da aceitação do Worker. Ao marcar PAID, um token criptográfico limita o mesmo batch transacional do D1 à decisão vencedora: ele grava o status, liquida todos os adiantamentos pendentes daquela profissional e reconcilia advances_amount; uma falha ou disputa não pode deixar apenas parte desses dados confirmada. O cache de profissionais é revalidado ao terminar, mantendo desktop, PWA, Android e iOS na mesma fonte de verdade. Os serviços incluídos já ficam selados por includedRequestIds; não recebem mais a versão artificial 9999. Gorjetas concedidas pelos clientes (financials.tips) são repassadas 100% líquidas para a funcionária (tipsAmount, gravado em payroll_entries.tips_amount), sem dedução de VAT ou margem da empresa.
💵 1. Componentes do Pagamento da Funcionária
Section titled “💵 1. Componentes do Pagamento da Funcionária”O valor líquido de cada holerite (PayrollSettlementLogic.buildEmployeeSettlement) é:
$$\text{Líquido} = \text{Base} + \text{Participação no lucro} - \text{Dinheiro recebido por ela} - \text{Adiantamentos pendentes}$$
- Base: para cada serviço
DONEdo período ainda não incluído em holerite algum,horas faturadas ÷ tamanho da equipe × taxa/hora, ou o custo manual (manualLaborCosts) quando registrado. Cancelamento só paga com custo manual. - Taxa/hora por serviço: o cadastro da funcionária tem a taxa padrão (
hourlyWage) e, opcionalmente, uma taxa por tipo de serviço (serviceWages, colunaservice_wages_json, migração 0145 — ex.: £14 standard, £15 deep clean, £16 end of tenancy).wageForService(src/shared/employeeWage.ts) é a regra única: a taxa do serviço do job vence; serviço sem taxa própria (ou zero) paga a padrão. Folha, custo de alocação, margem do orçamento e custo editável do job leem por ela. Um save semserviceWagesmantém as taxas gravadas. - Dinheiro recebido por ela (Cash in Hand): serviços pagos em
CASH/EMPLOYEE_ACCOUNTdescontam de quem recebeu (financials.staffCollectedBy, gravado na baixa; sem registro, quem está configurada na tarefa —crewCollectorId; com equipe de uma pessoa, ela; com duas ou mais sem ninguém configurado, ninguém, nunca a primeira da equipe) o valor efetivamente recebido (financials.staffCollectedCash), ou, se ainda não registrado,totalWithVat/price; as outras pessoas da visita recebem suas horas sem desconto. Quem recebeu pode estar fora da equipe — um gerente que pegou o dinheiro (2026-09-29) ou uma funcionária com dados bancários em cuja conta o cliente pagou (2026-10-06): a visita entra no holerite dele só para o desconto (sem horas nem gorjeta), e o gerente passa a ter holerite; negativo, o saldo segue para o próximo (debtsToCarry). - Não existem bônus de avaliação 5 estrelas ou de pontualidade no código; versões anteriores deste documento os descreviam.
Correções de 2026-09-11:
- As datas do período (
YYYY-MM-DD) passam porparseDate(dia local).new Date()as lia como meia-noite UTC — no Brasil (UTC-3) a semana de segunda a domingo virava domingo a sábado. - O desconto do dinheiro recebido usa
staffCollectedCash:totalWithVatdescontava 20% a mais quando o cliente absorve o VAT. - Adiantamentos descontados uma vez só. Ao marcar
PAID, o Worker quita apenas os adiantamentos criados até a geração do holerite (employee_advances.created_at <= payroll_entries.created_at) — antes quitava todos os pendentes, inclusive um dado depois e nunca descontado. E enquanto a profissional tiver um holeriteDRAFT/APPROVED, um novo holerite não desconta adiantamentos: eles são daquele holerite aberto. Antes os dois descontavam o mesmo adiantamento.
Os quatro KPIs do ciclo ativo consideram somente holerites DRAFT e APPROVED; lançamentos PAID permanecem no histórico e na tabela, mas não inflam novamente Total Earnings, Cash with Crew, Company to Pay ou To Collect. O cálculo percorre as entradas uma vez e arredonda o agregado a centavos. Novos holerites confirmados são inseridos no topo, preservando a mesma ordenação decrescente recebida no boot, e a formatação monetária mantém exatamente duas casas em todos os runtimes.
- Compensação Automática de Cash in Hand: Faturas recebidas em dinheiro ou transferências diretas para a conta da funcionária (
EMPLOYEE_ACCOUNT) excluídas da contabilidade (Xero/QuickBooks) são tratadas como recebimentos antecipados e deduzidas automaticamente do valor líquido a transferir no fechamento da folha. - Holerite negativo (
totalNet < 0): o saldo a devolver fica no próprio holerite, como valor a receber (companyReceivable), e é quitado nele. Fechar o período não o transforma em adiantamento: isso descontava a mesma dívida duas vezes quando o holerite também era quitado.
🛠️ 2. Arquivos Principais do Módulo
Section titled “🛠️ 2. Arquivos Principais do Módulo”- Serviço de Períodos:
src/features/payroll/services/PayrollPeriodService.ts - Liquidação da Folha:
src/features/payroll/services/PayrollSettlementLogic.ts - Geração de Holerite (Payslip):
src/components/financials/employee/PayslipDocument.tsx - Zustand Store:
src/stores/payrollStore.ts - Painel de Pagamentos:
src/pages/Payroll.tsx
Holerite (PayslipDocument) — revisão 2026-09-12
Section titled “Holerite (PayslipDocument) — revisão 2026-09-12”- Cada holerite lista as próprias visitas (
includedRequestIds), indexadas pelo id do holerite (EmployeeFinancialSnapshotService.tasksByPayslip). Antes o índice era pelo rótulo do período e guardava um holerite por rótulo: rodar o período de novo para pagar uma visita atrasada gera um segundo holerite com o mesmo rótulo, e ele mostrava — e exportava em PDF — as visitas do primeiro. - O valor de cada visita usa
PayrollSettlementLogic.calculateEmployeeEarnings, a mesma regra do cálculo da folha (custo registrado, senão horas × valor-hora). Lendo só o custo registrado, a visita aparecia com £0 embora estivesse no total. - O resumo começa pelo ganho dos serviços (
baseAmount); gorjetas e ajustes manuais são discriminados antes dos descontos e do saldo líquido. - Holerite com saldo a devolver à empresa: quando as deduções de pagamentos diretos/dinheiro retido (
deductionsDirectPayment) e adiantamentos superam os ganhos do período (totalNet < 0), o documento e o cartão exibem explicitamente “Amount Due to Company / A devolver” em destaque positivo com aviso de compensação, em vez de “Balance to Transfer -£X”. - As datas do período são lidas em horário de Londres (
parseDate). - As prévias administrativa e da equipe buscam as visitas históricas do próprio período apenas quando a janela operacional não contém todos os
includedRequestIds. Enquanto algum serviço não puder ser conferido, avisam que a lista está incompleta e não permitem exportar PDF; falha da busca oferece nova tentativa. A consulta arquivada fica separada do cache operacional e é limpa na troca de sessão.
Financials do funcionário — semana a semana (2026-10-15)
Section titled “Financials do funcionário — semana a semana (2026-10-15)”O dinheiro da equipe é semanal (a folha roda de segunda a domingo), então a tela Financials do funcionário (EmployeeFinancialsView) não tem seletor de período (Semana/Mês/Ano/Personalizado) nem somas de vários períodos: saíram os cartões “Money Received” e “Scheduled Work” e os campos employeeEarnings/employeeProjected/employeeHours de FinancialStats, que não tinham outro leitor. A tela abre na semana atual (segunda a domingo em Londres): as visitas concluídas da semana com horas e ganho da semana no cabeçalho. Cada visita é uma linha VisitPayRow (a mesma nos holerites e na lista de espera): dia, cliente, T-<ano>-<seq>, horas próprias (staffDurationHours; carpet mostra Comissão) e como o cliente pagou: à empresa, a outra pessoa da equipe, ou a ela em dinheiro/conta. Neste caso, mostra recebido (recibos aplicados, senão staffCollectedCash, senão o bruto de splitVat) ou a receber (collectionDue) com Confirmar recebimento (o formulário da visita, CrewCollectionCard → /api/field/collect, com as mesmas regras de baixa: valor real, referência estável, parcial deixa a fatura em aberto, excedente vai para revisão) e Lembrar cliente (/api/field/payment-reminder: trava de 24 h no servidor, agrupa todas as cobranças em aberto do cliente somando e detalhando tarefa a tarefa, entregue na hora na conversa da última tarefa em aberto ao cliente com o app — sem app, retida para liberação do gerente com push ao escritório; hook useCrewPaymentReminder, um envio por vez). Abaixo ficam: as visitas anteriores ainda sem baixa (PaymentsToRecord com before = início da semana), as visitas concluídas antes desta semana que ainda não estão em nenhum holerite e a lista dos holerites, um por semana, mais recente primeiro (createdAt), com o Pager padrão (8 por página). Desde 2026-11-07 a linha não mostra o ganho da visita nem “Sai do seu extrato”: por visita só aparece o que a funcionária recebe na conta ou recolhe em dinheiro, para não parecer que devolve dinheiro à empresa; o valor fica só no total da semana (cabeçalho e holerite). Baixar holerite (a funcionária no PayslipCard e o escritório no PayslipPreviewModal) baixa o PDF direto no navegador e no app instalado pela tela inicial (download: true), sem abrir a janela de compartilhar; só o app nativo, que não tem download, ainda compartilha. O escritório continua vendo tudo (ganho, recebimentos e saldo) na folha e no perfil da funcionária. Os cartões Próximo pagamento/Dinheiro comigo e a tabela Serviços a receber saíram. A tela lê a cópia mais nova de cada visita (store ou consulta do período), para que uma baixa ou um lembrete apareçam na hora.
No Home do funcionário, os recebimentos a confirmar são uma linha de Needs your attention (useReceiptsLine, AttentionCard — o mesmo cartão do Home do cliente): a contagem e os valores em dinheiro e em conta; See abre por baixo as tarefas em aberto (cliente, data, referência T-<ano>-<seq>, método e valor), e tocar numa delas ou em View in Financials abre Payments na aba de confirmação. A mesma lista do cartão traz as mensagens não lidas e um holerite aprovado a ver (o pago fica em Payments).
Em Financials do funcionário (EmployeeFinancialsView), a navegação é organizada em abas (CFTabs):
- Semanal e Holerites: visitas concluídas na semana atual, visitas concluídas anteriores aguardando holerite e a lista dos holerites semanais.
- Aguardando confirmação: aba dedicada (com badge da quantidade em aberto em destaque) reunindo todas as tarefas aguardando confirmação de recebimento (
useAwaitingReceipts), com as ações de Confirmar recebimento (CrewCollectionCard→/api/field/collect), Lembrar cliente e visualização da tarefa, ou estado vazio quando tudo estiver confirmado. Ao dar baixa no recebimento, se o cliente tiver outras tarefas concluídas em aberto (pagamento mensal ou final de semana), o formulário permite selecionar tarefas adicionais com checkbox e “Selecionar todas”, recalculando o total e distribuindo o valor pago cronologicamente entre elas. A regra continua única (useAwaitingReceipts). Cada holerite busca a própria semana ao abrir (PayslipCard). As visitas lidas pela tela são as das últimas 8 semanas até hoje (EMPLOYEE_WEEKS_BACK,useFinancialsController). A visão do cliente e o Reports do gestor mantêm o filtro de período.
🔒 Fechamento da folha no horário de Londres
Section titled “🔒 Fechamento da folha no horário de Londres”Fechar uma rodada confere se ainda há visitas abertas entre as meias-noites de Londres que delimitam o período (londonPeriodBounds, em payrollRuns.ts). O app grava o período como o instante da meia-noite de Londres, que no verão é 23:00 UTC do dia anterior, e o date(period_end, '+1 day') cortava esse valor para a data em UTC. Com isso, o último dia do período ficava fora da verificação, e uma folha de agosto podia ser fechada com visitas de 31/08 ainda abertas.
🧾 Aviso de pagamento
Section titled “🧾 Aviso de pagamento”- Ao pagar um holerite, o aviso mostra os trabalhos que ele trava e o valor de adiantamentos que ele descontou. Antes, contava todos os adiantamentos em aberto da funcionária, mas o servidor só quita os que o holerite descontou.
🧽 Carpet: comissão, paga pela folha
Section titled “🧽 Carpet: comissão, paga pela folha”Carpet é um negócio por comissão, qualquer que seja a pessoa que executa (Pedro, Priscila…). isCommissionJob (src/shared/carpetService.ts) reconhece a tarefa pela marca financials.outsourcedCommission ou pelo serviço de carpet. Nunca é horas × salário: não há labor-hrs na tarefa nem divisão de horas no Team selection.
Payout. Quem executa recebe o valor da tarefa sem VAT menos a comissão de Settings → Profit sharing → Carpet settlement (carpetSettlementConfig.commissionPercent), dividido igualmente pela equipe (carpetPayoutPerPerson). Ele é gravado em manualLaborCosts quando a equipe é definida (confirmação da quote e Team selection, via carpetLabourCosts), com a comissão vigente naquele momento; o custo da tarefa é a soma dos payouts e o lucro é a comissão. As visitas de uma série repetem preço, marca e payouts (RecurrenceService, recurrence-auto-extend).
Payslip. A tarefa concluída entra na folha como qualquer outra, com o payout como linha. Se o cliente pagou direto a quem executou (CASH / EMPLOYEE_ACCOUNT), o valor recebido é descontado (staffCollectedCash, ou o preço sem VAT quando não registrado): o saldo daquela tarefa é −comissão, abatido das outras linhas do mesmo payslip; se o total ficar negativo, é valor a receber da pessoa. Carpet fica fora do P&L residencial e da divisão de lucro. calculateCarpetSettlement continua descrevendo a mesma regra, com VAT e Flat Rate.
↪️ Saldo negativo passa para o próximo payslip
Section titled “↪️ Saldo negativo passa para o próximo payslip”Um payslip que fecha abaixo de zero (a pessoa deve à empresa: dinheiro de limpeza ou pagamento de carpet que recebeu direto, adiantamentos acima do que ganhou) leva esse saldo para o próximo payslip dela, que o desconta como Balance brought forward (payroll_entries.balance_brought_forward, migration 0151). Só é levado depois de fechado (PAID) — um payslip ainda aberto não pode ser quitado duas vezes —, e uma vez só: o fechado grava em carried_forward_to o payslip que o levou (debtsToCarry em src/shared/payrollSettlement.ts; a geração no Worker marca na mesma transação). Recalcular um rascunho relê exatamente o que ele já levou. Se o próximo também fechar negativo, o saldo segue para o seguinte. Vale para limpeza e carpet igualmente.
⏱️ 3. Folha Automática Semanal & Inclusão Retroativa de Tarefas Fechadas Posteriormente
Section titled “⏱️ 3. Folha Automática Semanal & Inclusão Retroativa de Tarefas Fechadas Posteriormente”A. Sugestão Inteligente de Período e Presets de Corte (Cutoff)
Section titled “A. Sugestão Inteligente de Período e Presets de Corte (Cutoff)”- Data Inicial Automática: Na geração manual (
usePayrollController), a data de início é sugerida como a segunda-feira da pendência mais antiga ou a segunda-feira seguinte ao término da última folha registrada (lastRun.periodEnd + 1 dia), assegurando continuidade temporal sem lacunas. - Seleção Estritamente Semanal (Segunda a Domingo): Não há seleção fragmentada de dias avulsos. Tocar em qualquer dia do calendário ou no badge de número da semana (
W{num}) seleciona a semana inteira correspondente, de segunda-feira a domingo. - Fechamento no Meio da Semana: O fechamento manual no meio da semana (ex.: quarta ou quinta-feira) fecha a semana inteira de segunda a domingo. A validação de negócio do backend e frontend (
payrollGenerateCore.tsePayrollPeriodService.ts) permite períodos comendDateaté o domingo da semana corrente (endOfWeek(new Date(), { weekStartsOn: 1 })), sem disparar erro de data futura. Visitas concluídas (DONE) são computadas e quitadas; visitas futuras ou ainda em andamento permanecem em aberto e serão contempladas na próxima execução. - Presets de Atalho Semanal:
- Semana Anterior (
PREVIOUS_WEEK): Seleciona com um toque a semana inteira anterior (segunda a domingo). - Semana Atual (
CURRENT_WEEK): Seleciona com um toque a semana inteira em curso (segunda a domingo). - Semana Específica: Clicar em qualquer dia do mês seleciona a respectiva semana completa de segunda a domingo. O conceito obsoleto de corte fragmentado/personalizado (“Custom Period”) foi removido.
- Semana Anterior (
- Desbloqueio de Período Parcial: Enquanto houver funcionários pendentes de pagamento no período selecionado, as datas e a semana não são travadas (
dayValues/isPeriodFullyClosed). A folha automática em segundo plano contempla os colaboradores pendentes e os dias restantes da semana, sem duplicar tarefas já faturadas.
B. Inclusão Automática de Tarefas Concluídas com Atraso (“Retro Tasks”)
Section titled “B. Inclusão Automática de Tarefas Concluídas com Atraso (“Retro Tasks”)”- Problema resolvido: Se uma visita agendada semanas atrás foi marcada como
DONE(ou cancelada com custo de mão de obra) somente depois que a folha daquela data já havia sido fechada, anteriormente ela ficava fora dos filtros estritos de data (startDateTime >= startIso) e nunca era paga. - Regra atual: Qualquer tarefa elegível com
scheduledStartTime <= endIsoque ainda não conste em nenhum holerite (!alreadyInPayroll.has(req.id)) é automaticamente incorporada no cálculo do ciclo vigente. A profissional recebe seu ganho base integral (baseAmount), tem eventual valor em dinheiro retido debitado (deductionsDirectPayment), e a visita entra no cálculo de lucro não compartilhado (unsharedPeriodProfit). - Idempotência e Segurança: Quando o ciclo é gravado em
POST /api/atomic/payrollGenerateou via cron, os IDs dessas tarefas são selados emincludedRequestIdsno D1. Elas nunca serão computadas novamente em folhas futuras.
C. Execução Semanal Automática em Segundo Plano (Auto-Payroll Cron)
Section titled “C. Execução Semanal Automática em Segundo Plano (Auto-Payroll Cron)”- Configuração e Padrão Operacional: Gerenciada pela modal
AutoPayrollModalna interface ou emSettings, armazenada empayrollConfig(systemSettings):autoPayrollEnabled: Ativo por padrão (true).runDayOfWeek: Segunda-feira (1), executando na madrugada antes do início do expediente.runHourLondon: Madrugada às03:00(horário de Londres).cutoffStrategy:YESTERDAY(Até Ontem / Domingo 23:59:59).- Delimitação de Ciclo (Segunda a Domingo 23:59:59): O ciclo compreende 7 dias completos, iniciando na Segunda-feira e fechando no final de Domingo (
Auto: YYYY-MM-DD to YYYY-MM-DD). A gerência tem a segunda-feira para conferir e aprovar os holerites antes de efetuar o pagamento.
- Processamento: Acionado periodicamente no tick do
dispatch-scheduledviamaybeRunAutoPayroll(db, env). - Proteção contra Duplicidade (Claim Semanal): Uma chave de claim idempotente no formato
AUTO-PAYROLL-<YYYY-MM-DD>ancorada na segunda-feira é registrada de forma transacional emsystem_logsantes do processamento. Duas instâncias ou retries concorrentes na mesma semana são rejeitados de imediato. - Interação entre Geração Manual e Folha Automática Semanal:
- Holerite Pago (
PAID/ Imutável): Sempre que um holerite é pago, ele torna-se estritamente imutável. Caso o colaborador execute novas tarefas no restante do período, a folha automática semanal (ou uma nova geração manual) gera um holerite extra/suplementar para aquele colaborador no mesmo período (englobando exclusivamente as tarefas novas). O colaborador fica com dois holerites no período: o primeiro quitado (PAID) e o segundo em rascunho (DRAFT). - Holerite em Rascunho Não Pago (
DRAFT): Se uma folha manual foi gerada no meio da semana e ainda não foi paga (permanece emDRAFT), a folha automática no encerramento da semana atualiza o holerite manual em rascunho (recalculateDraftEntry), incorporando todas as tarefas concluídas da semana inteira sem criar holerites duplicados.
- Holerite Pago (
- Notificação e Log: Se gerada com sucesso, um evento
PAYROLL_AUTO_COMPLETEDé gravado no log do sistema e uma notificação push administrativa é enviada com o rótulo do ciclo, número de holerites rascunho gerados e valor total da rodada. Se não houver atendimentos a pagar, o ciclo é ignorado com o logPAYROLL_AUTO_SKIPPED.
D. Tratamento de Pagamentos Diretos em Conta do Funcionário (EMPLOYEE_ACCOUNT) vs Dinheiro (CASH)
Section titled “D. Tratamento de Pagamentos Diretos em Conta do Funcionário (EMPLOYEE_ACCOUNT) vs Dinheiro (CASH)”- Desconto Antecipado no Holerite Semanal: Quando um serviço está indicado para pagamento direto na conta do funcionário (
plannedPaymentMethod: 'EMPLOYEE_ACCOUNT'ouactualPaymentMethod: 'EMPLOYEE_ACCOUNT'), o valor bruto previsto da tarefa é debitado integralmente do holerite semanal da cobradora da equipe (crewCollectorId), independente de baixa na invoice e de qualquer saldo devedor em aberto (staffCollectionExpectedGross). Eventual saldo devedor caso o cliente não pague tudo é ajustado nos recebimentos posteriores do cliente, mantendo o desconto no holerite integral. Caso a empresa identifique e reconcilie o pagamento por outra via da empresa (ex.:TRANSFERouSTRIPE), o recálculo do rascunho ou a folha seguinte remove o débito da funcionária. - Cash planejado só desconta depois da baixa (2026-10-12): uma visita em
CASHpara a equipe sem baixa não desconta nada (o cliente pode não pagar, ou pagar na visita seguinte). Na tabela de tarefas ela aparece como Cash a receber · nome (payroll.taskTable.cashToCollect), nunca como Pago à Empresa. Quando a baixa chega com o holerite da semana já aprovado ou pago, o desconto entra no holerite seguinte como ajuste (payroll_adjustments). Enquanto isso, a visita seguinte do mesmo cliente mostra um aviso com o valor em aberto (EarlierCashOwedBanner, regraearlierCashOwed): quem estava na equipe daquela visita dá baixa ali mesmo (CrewCollectionCard); quem não estava é orientado a avisar o escritório; o escritório vê o valor e acerta em Billing. - Controle das visitas sem baixa (2026-10-12): uma regra só (
awaitingCrewRecord,crewCollection.ts) define a visita finalizada paga à equipe — cash ou conta do funcionário — que ninguém deu baixa: qualquer status não liquidado, inclusive em invoice de rascunho (DRAFT); visita ainda por acontecer não conta. O método vem do registrado, senão do planejado pela empresa, senão do gravado na visita (crewMethodFor), para nada sair do controle se a empresa mudar a configuração. Ela alimenta o Cash check (aguardando, mais antigas primeiro, com dias em aberto, em vermelho depois de 7), a pendência no perfil do funcionário (cash e conta), a lista Pagamentos para dar baixa do próprio funcionário em Financials (linhas da semana ePaymentsToRecordpara as anteriores; a baixa é responsabilidade dele) com o resumo no Dashboard (AwaitingReceiptsSummary) e o aviso da visita seguinte (só cash). - Cliente com várias visitas em aberto (2026-11-05): a funcionária recebe tudo de uma vez na última visita do cliente (
groupAwaitingReceipts,useAwaitingReceipts.ts). A aba de confirmações (PaymentsToRecord) e a lista da Home (useReceiptsLine) mostram uma linha por cliente com a última visita, o total e as visitas incluídas; Lembrar cliente e Confirmar recebimento existem só nela (o lembrete do servidor já soma todas). Na semana (VisitPayRow) a última mostra o total, e as anteriores dizem “Recebida junto com a última visita” sem ações; dentro de uma visita anterior o cartão de recebimento (CrewCollectionCard) só aponta para a última. No cartão verde da última as visitas anteriores são uma linha só, Saldo das visitas anteriores (CollectionBalanceSummary): a lista delas fica no box amarelo acima, sem repetir. Se o valor digitado não cobre tudo, o cartão mostra Fica em aberto: cada visita com o que falta, quitando das mais antigas para a mais nova (distributePaymentAcrossVisits), como no Finalizar. O badge da aba conta clientes. - Recebimento a menor aguardando o escritório (2026-11-09): quando a funcionária confirma um valor diferente do devido, a baixa vira proposta (
crewReceiptReview) que o escritório aprova; antes a visita continuava em Pagamentos para dar baixa como se nada tivesse sido registrado. AgoraawaitingCrewRecorddeixa de fora a visita com proposta, ereceiptAwaitingApproval(crewCollection.ts) estende isso às visitas anteriores que entraram no mesmo recebimento (earlierRequestIds): saem da aba de confirmações, da linha da Home e do lembrete ao cliente (/api/field/payment-reminder), e na semana a linha da visita (VisitPayRow) diz em azul “Você registrou £X de £Y · aguardando aprovação do escritório”. No cartão de revisão do escritório (CrewCompletionReviewCard) o botão diz a consequência também numa visita só: “Confirmar recebimento e deixar £Z em aberto”. Aprovado, o resto fica devido na própria visita (AWAITING): volta para Pagamentos para dar baixa da funcionária só com a diferença, entra no lembrete e, se for dinheiro, aparece na visita seguinte do cliente (EarlierCashOwedBanner). O “manter como crédito” só aparece no recebimento de várias visitas: numa visita só, o valor a mais é registrado e não vira crédito. - Quem responde pela diferença (2026-11-09): um recebimento a menor tem um padrão por método em
/api/field/collect. Dinheiro (a menor, ou nada —NONE): o cliente fica devendo o resto e paga na próxima visita, seja qual for a funcionária; a visita guardashortfallNextVisit,staffCollectionExpectedGrossfica 0 e a folha desconta só o dinheiro em mãos (crewCollectedAmountdevolve 0 quando nada foi recebido e o resto ficou para a próxima visita). A próxima visita já mostra e cobra visitas anteriores em aberto (earlierUnpaidVisits: aviso, Finalizar e o cartão de recebimento); quem receber lá dá baixa, é descontado do que recebeu, e a marca some. Conta da funcionária (e “não sei”,UNCONFIRMED): desconta a visita inteira; o escritório cobra o cliente e só ela confirma o resto quando cair na conta (volta para Pagamentos para dar baixa com a diferença; a baixa posterior não desconta de novo). Ao aprovar, o escritório pode escolher o outro (shortfallTo, só escritório;CrewCompletionReviewCardmostra as duas opções com o padrão marcado e a frase da consequência pelo nome). Os valores sempre fecham: devido + pago do cliente = valor das visitas, e o desconto de cada funcionária = o que ela tem em mãos + o que o escritório deixou com ela (teste: cliente paga £0, outra funcionária recebe £120 na visita seguinte → £0 e £120). Na semana da funcionária a linha diz “Você recebeu £X · £Z fica para a próxima visita do cliente”, com £Z = o que o cliente ainda deve agora (collectionDue), não o valor guardado na marca. - O escritório fecha o resto por qualquer caminho (2026-11-09): com a fatura em aberto, Billing → pagar à mão (
/billing/manual-settle) registra o resto em qualquer meio — transferência, cartão, dinheiro ou conta de uma funcionária (nomeando quem recebeu), conta da empresa — e a folha desconta de quem recebeu; sem nada recebido, Change billing na fatura (/billing/invoice-reissue) troca a rota: a fatura em dinheiro fica VOID com o número e a visita volta para ser cobrada pela nova rota. Cada pagamento é uma linha da fatura com o meio, e o rastro fecha:functions/api/field/shortCashTrace.test.tscobre £50 em dinheiro + £10 por transferência (£50 descontados), £50 + £10 na conta da funcionária (£60), nada no dia e £60 por transferência (£0), £50 na conta da funcionária e os £10 por transferência à empresa (£60 provisórios, depois £50), o mesmo com os £60 já num holerite rascunho (corrigido para £50) ou pago (fica pago; ajuste de −£10 de desconto no próximo,payroll_adjustments), e nada no dia com a rota trocada para transferência (fatura VOID, nada com a funcionária). - Status da Tarefa e Baixa Posterior: Mesmo com o valor debitado no holerite da semana, a tarefa permanece pendente de pagamento (
paymentStatus: 'AWAITING'). Ela fica destacada no perfil e extrato da funcionária (StaffProfileePendingPayoutsTable), permitindo que a própria profissional acione a baixa de pagamento (“Dar baixa no pagamento” viaCrewCollectionCard//api/field/collect, definindoactualPaymentMethod = 'EMPLOYEE_ACCOUNT') assim que constatar a entrada dos fundos em sua conta bancária. - Cobranças e Lembretes (Reminders) Restritos à Gerência: Neste primeiro momento, qualquer lembrete de cobrança (WhatsApp, e-mail ou reenvio de fatura) é de responsabilidade e competência exclusiva da gerência (
MANAGERouADMIN). A interface não disponibiliza botões de cobrança para os funcionários até que o fluxo esteja consolidado e homologado pela operação. - Diferença para Pagamentos em Dinheiro (
CASH): Ao concluir uma tarefa em dinheiro (FinishVisitModal), se o funcionário confirma o recebimento em mãos, o serviço é marcado comoPAIDe descontado do holerite. Se indicar que o dinheiro não foi recebido, a tarefa permanece emAWAITINGsem desconto antecipado no holerite, permitindo que a baixa seja dada posteriormente quando o dinheiro for efetivamente entregue, ou que o gerente altere a forma de pagamento.
E. Tabela Didática de Detalhamento por Tarefa e Navegação de Períodos Anteriores
Section titled “E. Tabela Didática de Detalhamento por Tarefa e Navegação de Períodos Anteriores”-
Visualização e Auditoria de Períodos Fechados: A seção de folhas de pagamento permite alternar de forma intuitiva entre Ciclo Ativo (padrão com contagem de rodadas abertas), Períodos Anteriores (seletor drop-down listando períodos fechados com a respectiva quantidade de holerites) e Todos os Períodos (visão consolidada de todos os registros históricos). Na tabela de histórico de execuções (
PayrollRunHistory), o botão Inspect Run abre o resumo da execução (PayrollRunSummaryModal): quem entrou, tarefas, horas (a mesma regra da linha,payslipWorkedHours), bruto, recebido e líquido, com totais — valores como os holerites estão agora. Os holerites vêm deGET /api/atomic/payrollRuns?id=: de uma geração, pelopayroll_financial_basis(só os dela, mesmo com duas execuções no mesmo período); de um recálculo, pelos IDs que ele alterou (entry_ids_json); de uma execução anterior ao basis, pelo período. Tarefas de períodos antigos chegam pela consulta de período, como no holerite. Abaixo da tabela, Fora da folha neste período lista as visitas do período que nenhum holerite levou — ainda abertas (nem DONE nem CANCELLED) e concluídas fora de qualquer holerite, com o valor da equipe —, pela mesma regra do fechamento (tasksLeftOutOfPayroll, também usada porverifyClose, e a mesma listaPayrollTaskList); tocar numa abre a visita por cima. -
Tabela Didática de Tarefas por Holerite (
PayrollTaskBreakdownTable): Ao expandir qualquer linha de holerite no painel (ocupando 100% da largura no topo da área expandida, sem duplicar o botão de holerite), as tarefas incluídas são apresentadas em formato tabular didático e transparente:- Data / Cliente: Data do atendimento com link direto para o cliente.
- Qtd Horas: Duração do atendimento ou cota de horas do funcionário (ou indicação de não escalado caso apenas tenha recebido o pagamento).
- Rate Cliente & Rate Funcionário: Valor cobrado por hora do cliente e a taxa horária aplicada para o funcionário (padrão, por tipo de serviço ou custo manual).
- Ganho do Trabalho: Valor bruto conquistado pelo atendimento, somado a eventuais despesas ou itens extras adicionais da funcionária (
staffExtras). - Forma de Pgto & Coleta Direta: Identifica se o cliente pagou à empresa, se foi recebido por colega, ou se houve coleta direta pela funcionária em dinheiro (
CASH) ou em sua conta bancária (EMPLOYEE_ACCOUNT). - Balanço da Tarefa & Didática de Compensação: Informa com clareza o cálculo financeiro de cada atendimento:
- Coleta excedente / Apenas Coleta: Exibe o valor total a deduzir quando a funcionária recebeu o pagamento do cliente (inclusive quando não executou a tarefa, deduzindo integralmente o valor retido enquanto as horas são pagas à equipe executora).
- Coleta parcial: Exibe a diferença restante que a empresa transferirá no fechamento semanal.
- Coleta exata: Confirma o recebimento direto do valor integral.
- Pago à empresa ou por colega: Confirma que o ganho do serviço será pago na íntegra via transferência bancária da empresa.
-
Detalhamento de Saldos de Períodos Anteriores (Brought Forward): Quando um holerite herda saldo de períodos anteriores (
balanceBroughtForward, seja débito transportado ou crédito a compensar), esse valor não fica oculto ou restrito ao rodapé:- No documento do holerite (
PayslipDocument): Ganha um cartão de destaque próprio no cabeçalho junto aos indicadores principais (Horas, Dinheiro em Mãos, Transferência Bancária e Saldo Líquido), além de figurar explicitamente como uma linha destacada na tabela analítica antes do cômputo final. - Na listagem do escritório (
PayrollTableRow): A linha mostra ao lado do nome só o ícone de histórico com o valor (−£.../+£...; o texto completo fica para leitor de tela). As colunas separam Balance (o saldo do período:totalNet − balanceBroughtForward) de Amount to pay (o valor final do PDF, que inclui o saldo anterior). Expandida, a barra de opções do estágio fica dentro do banner do saldo anterior (título curto + valor à esquerda, botões à direita; a explicação vira tooltip) e o cartão repetido no rodapé saiu. - Quitar o saldo anterior à parte: em Draft, e também na prévia de geração (antes de gerar a folha), Settle debt now / Transfer now transfere só o saldo anterior contra o holerite que o deixou (
getPayrollEntryTransferTarget); o rascunho é recalculado e fica sem valores anteriores — e uma folha gerada depois não o leva, porque a transferência quita o antigo (balancesToCarry). Num holerite já aprovado o total já inclui o saldo anterior, então Transfer / Payout paga o valor inteiro contra ele mesmo.
- No documento do holerite (
-
Correções de 20/10 (análise do módulo):
- Adiantamentos: o holerite grava quais adiantamentos descontou (
deducted_advance_ids_json, migration 0222) e o pagamento quita exatamente esses. Antes, quitava só os criados antes do rascunho: um adiantamento dado depois e descontado num recálculo ficava em aberto e era descontado de novo no holerite seguinte. Se um deles já foi quitado por outro holerite, o pagamento é recusado (voltar a rascunho e recalcular). Holerites anteriores à coluna (NULL) seguem a regra antiga. O salvar da funcionária não muda mais valor, data nem descrição de um adiantamento quitado. - Pagamento parcial: só a soma das transferências igual ao líquido libera o “Confirm paid” e o PAID automático; o Worker recusa menos (409 com
remaining), a não ser com force close, que leva só o restante. O saldo anterior transportado também é só o que as transferências deixaram (payslipRemainingAmount). O “Transfer / Payout” de um holerite emitido já sugere o que falta pagar. - Uma regra de recálculo: gerar de novo um período que já tem o rascunho usa
recalculatedDraft, a mesma do Recalculate — mantém as linhas manuais, a base congelada com correções e os ajustes. Uma visita congelada que sai do rascunho (cancelada sem pagamento, levada por outro holerite) leva junto o salário que a geração congelou para ela (jobs_json); só a paga fora do sistema fica, porque a linha de desconto dela já tira o valor. - Exclusão: só rascunho, num único batch guardado pelo status. Não existe mais o POST que criava holerite com totais vindos do navegador.
- Recalcular o período: recalcula só os rascunhos; o ícone do PDF de cada rascunho mostra que está atualizando, e os holerites emitidos e pagos continuam livres.
- Transferência que falhou: se o adiantamento não foi salvo, nada mais acontece (antes o holerite ainda era marcado PAID).
- Crédito transportado: “Transfer now” funciona para um crédito fechado à espera de carry (force close ou já levado por um rascunho).
- Adiantamentos: o holerite grava quais adiantamentos descontou (
-
Banking e Payroll batendo (20/10): um cruzamento em produção achou payslips com transferências repetidas (4 × £170 num payslip de £170; 3 devoluções de −£36 num saldo de −£36) — a baixa não acontecia e a transferência era registrada de novo. Agora:
- o Worker recusa, no salvar da funcionária, uma transferência de quitação que passe do líquido do payslip ou vá no sentido contrário (
PAYSLIP_OVERPAID, 409, nada é gravado) e o app mostra o motivo; - pagar pelo Payroll e conciliar pelo extrato do Banking quitam o payslip pela mesma regra (
functions/api/common/payslipSettlement.ts: os adiantamentos que ele descontou; recusa se um deles foi quitado por outro); - o saldo por pessoa do Banking (
computeEmployeeBalances) usa o que falta de cada payslip emitido, não conta de novo um adiantamento já descontado nele e inclui os saldos antigos ainda à espera de um payslip emitido; - um Manual Charge é o que a pessoa deve (positivo, descontado no próximo payslip) e nunca vira movimento de banco — antes era gravado negativo, somando ao pagamento.
- o Worker recusa, no salvar da funcionária, uma transferência de quitação que passe do líquido do payslip ou vá no sentido contrário (
-
Correções de visitas antigas na lista e no PDF: uma correção (
adjustments, p. ex. “Manual payment recorded by the office” — o dinheiro de uma visita de um payslip já fechado, descontado no próximo) aparece na lista expandida do payslip e no PDF com a data, o cliente e o códigoT-…da visita, que abre ao clicar (no PDF, o link/task/…). A visita vem da lista do app, senão do dia dela buscado no servidor, senão da cópia guardada no payslip que a pagou (usePayslipCorrections). -
Reverter um pagamento registrado depois do payslip fechado: o registro cria uma correção (
payroll_adjustments) que a geração seguinte leva ao rascunho. Se a visita volta a Awaiting enquanto esse rascunho está aberto, a correção inversa entra no mesmo rascunho na hora e os totais acompanham — antes ela ficava pendente para um payslip gerado depois e o rascunho continuava descontando o dinheiro.
F. Controle de Transferências e Acertos (Aba Transfers)
Section titled “F. Controle de Transferências e Acertos (Aba Transfers)”- Separação entre Intenção e Quitação: O holerite aprovado expressa a intenção de pagamento, enquanto a transferência bancária ou acerto em dinheiro representa a quitação física. A aba dedicada Transferências e Acertos (
TransfersTab) consolida esses fluxos sem depender de planilhas externas. - Tipos de Movimentação Suportados:
- Saídas (
OUT): Pagamento de holerite (PAYSLIP_PAYOUT) e Adiantamento (ADVANCE). - Entradas (
IN): Devolução de dinheiro de cliente retido em mãos (CUSTOMER_CASH_RETURN) e Cobrança/Ajuste manual (MANUAL_CHARGE).
- Saídas (
- Meios de Pagamento e Conta Bancária da Empresa: Transferência Bancária (
BANK_TRANSFER) e Dinheiro (CASH). Quando o meio é transferência bancária, a interface permite selecionar a conta bancária da empresa utilizada para a operação (contas cadastradas nas entidades fiscais, principais e secundárias). - Persistência Sem Alteração de Schema: Armazena metadados estruturados no campo
descriptionda tabelaemployee_advancesno padrão[TYPE:METHOD:ACCOUNT_ID] Notes(ou[TYPE:METHOD] Notespara registros sem conta bancária específica), preservando compatibilidade com o schema D1 existente. - Quitação de Holerites Aprovados: A modal
NewTransferModalpermite selecionar holerites aprovados pendentes; ao salvar a transferência de pagamento, o holerite é automaticamente marcado como liquidado (PAID). - Crédito Compensatório em Próximos Holerites: Devoluções e cobranças manuais negativas (
amount < 0) geram saldo credor para a funcionária, sendo abatidas como crédito nas deduções da próxima folha gerada (advancesCreditede nota explicativa no PDFPayslipDocument). - Monitoramento e Auditoria: Três cartões de KPI (A Pagar Aprovado, Adiantamentos em Aberto e Créditos/Devoluções Pendentes), grade de saldos por funcionária com atalhos de liquidação rápida e tabela filtrável com histórico completo de transferências.
G. Controle Bancário & Tesouraria Operacional (Banking)
Section titled “G. Controle Bancário & Tesouraria Operacional (Banking)”Accounts centraliza saldo inicial, despesas, pagamentos parciais, recorrências, transferências entre contas e conciliação. O contrato está em Banking e Accounts. Payroll e Drawings alimentam seus movimentos a partir dos registros originais, sem um segundo lançamento manual.
Ajustes do holerite (2026-10-13). No holerite em rascunho (prévia do Payroll), Ajustes neste holerite (PayslipAdjustments) adiciona linhas sem visita: extra (antes “bônus”) e reembolso somam ao bruto e ao líquido, desconto (ex.: item quebrado) só tira do líquido. A lista vai inteira, com motivo, por POST /atomic/payrollEntries?manualItems=true (só DRAFT, guarda por last_actor_json, auditada); o servidor move os totais pela diferença e grava manual_items_json (migração 0207, regra em src/shared/payslipManualItems.ts). O recálculo do rascunho (recalculateDraftEntry) soma as linhas de novo; as outras escritas (correções de visita, quem recebeu) já ajustam por diferença. Aprovado, volta a rascunho para ajustar. O documento/PDF mostra cada linha (Bonus, Reimbursement, Deduction). Extras de uma visita continuam na visita (staffExtras).
Pago fora do sistema (2026-11-09). Uma visita cujo pagamento a alguém foi feito à mão ou antes de o sistema existir sai do payroll pelo botão Paid outside the system da linha dela no holerite em rascunho (SettleOutsideButton, ADMIN/MANAGER, com motivo) → POST /atomic/payrollEntries?settleOutside=true (payrollOutsideSettle.ts). A visita ganha financials.payrollSettledOutside[pessoa] (quem, quando, motivo e o valor), um campo de dinheiro de visita fechada como os outros, e a regra settledOutsidePayroll (src/shared/payrollOutside.ts) a conta como já paga para essa pessoa: nenhuma geração ou recálculo a pega, e ela não aparece como devida (Payments da diarista, visitas fora do payroll). O rascunho é recalculado na hora sem ela; se a base congelada da geração já contava o salário dela, entra uma linha de desconto T26-xxxx paid outside the system desse valor, que fica em todo recálculo (descartar o rascunho e gerar de novo já sai sem a visita e sem a linha). Recusado com a visita num holerite aprovado ou pago, ou já baixada.
Payments da funcionária (2026-10-22). A tela segue o padrão do Home: abas This week & payslips e To record; This week é uma linha (período · N visits · horas · pagamento, ou “No finished visits this week yet”) com as visitas abaixo; Waiting for a payslip e Weekly payslips com o título de seção do Home; sem estado vazio grande.
Folha em palavras simples (2026-10-27). Semana em vez de “período fiscal/alvo”, “Folhas anteriores” em vez de “registo de geração”, o período legível (“26 out – 1 nov”) em vez do código guardado. Cada linha mostra o próximo passo à vista — “Emitir holerite” no rascunho, “Pagar” ou “Receber” no emitido — e um saldo negativo aparece como “A receber £33.00”.
- Conta da funcionária: o escritório cobra, ela só confirma (2026-11-09): quando parte já caiu na conta dela e o resto continua devido (
officeChargesRest,crewCollection.ts), a folha já descontou a visita inteira e quem cobra o cliente é o escritório. Em Pagamentos para dar baixa a linha diz “O escritório está cobrando o resto do cliente. Confirme aqui quando cair na sua conta.” e só oferece Confirmar recebimento; o lembrete dela (/api/field/payment-reminder) recusa essa visita e a deixa fora do agrupamento.