@fayz-ai/plugin-workforce

Escala, ponto e fechamento de competência — o RH operacional de qualquer app Fayz.

Status: beta — pre-1.0. A camada de dados está escrita e validada; a superfície de UI pode mudar antes do 1.0.

Toda casa que tem gente na escala precisa responder três perguntas: quem está escalado, quem de fato veio, e o mês está fechado. plugin-workforce é o módulo que responde as três sem inventar um segundo cadastro de pessoa e sem uma segunda tabela de horário.

Três decisões sustentam o modelo, e estão no SQL antes de estarem na tela:

• A batida é um EVENTO, append-only. kind ∈ (clock_in, break_start, break_end, clock_out), N por dia, agrupados por (person_id, work_date). Intervalo de almoço e turno partido saem de graça, e "quais pontos estão em aberto?" tem resposta sem coluna derivada.
• O ajuste é uma LINHA, com autor e motivo obrigatório. Nunca um UPDATE na batida — o horário real fica intocado, que é o que torna o ponto prova.
• O previsto mora em public.schedules, com kind = 'work_shift'. A escala publicada materializa a linha e guarda o id; o cruzamento previsto × realizado vira uma chave, e não um casamento por nome e hora.

O que tem dentro

• Um módulo /workforce com seis telas: Escalas, Templates, Registros de Ponto, Fechamento, Pessoas & Documentos, Encargos e Honorários
• Escala do dia a partir de um molde, com SNAPSHOT do turno — mudar o molde não reescreve o passado
• Folha de ponto agrupada por dia, com o crachá previsto × realizado lendo v_workforce_day (absent = falta, outside_schedule = fora da escala)
• Fechamento de competência por RPC (workforce_period_close / workforce_period_reopen), com motivo obrigatório para reabrir
• A ficha do colaborador vem do arquétipo de pessoa do @fayz-ai/admin — documentos, endereços, unidades e horário inclusos
• Custo de pessoal LIDO do razão do Financeiro (plg_financial_rep_dre, a mesma view do relatório de DRE), desenhado como DEMONSTRATIVO — árvore do plano de contas, uma coluna por mês de competência; este plugin não escreve nenhuma despesa
• Qual ramo do plano é pessoal é uma DECLARAÇÃO da casa, em workforce.payroll_account_codes (tenants.settings, migration 006). Sem escolha a tela mostra todas as despesas classificadas e avisa que é o que está fazendo — deduzir o ramo pelo nome da conta erraria no primeiro plano que numera diferente
• Provider plugável: memória por padrão, Supabase quando há cliente registrado

Install

npm install @fayz-ai/plugin-workforce

Peer deps: @fayz-ai/core, @fayz-ai/ui, @fayz-ai/admin, mais react / react-dom.

Usage

import { defineSaas } from '@fayz-ai/admin'
import { createWorkforcePlugin } from '@fayz-ai/plugin-workforce'

export const app = defineSaas({
  // ...
  plugins: [
    createWorkforcePlugin({
      currency: { code: 'BRL', locale: 'pt-BR', symbol: 'R$' },
      labels: { pageTitle: 'RH', pageSubtitle: 'Escala, ponto e fechamento da equipe' },
      // O SQL da jornada não guarda remuneração. Sem isto a folha mostra horas e
      // um traço no lugar do valor, em vez de inventar um número.
      hourlyRate: 22.5,
    }),
  ],
})

Permissões

O baseline semeia oito chaves, e duas delas são segregação de função de propósito: workforce.adjust_time (corrigir a batida de outra pessoa é prova, não edição) e workforce.close_period (quem aponta não é quem fecha o mês).