sigrhapf/Documents/sigfip/sigefp/MANUAL_COMPLETO_USO_SIGEFP.md

📖 Manual Completo de Uso - SIGEFP

Sistema Integrado de Gestão de Folha de Pagamento
Versão: 1.0
Data: 2025-01-XX

---

📋 Índice

1. Introdução
2. Acesso ao Sistema
3. Dashboard
4. Módulo Administração
5. Módulo Organização
6. Módulo RH & Folha
7. Módulo Orçamento
8. Módulo Tesouraria
9. Módulo Dados Comuns
10. Fluxos Integrados
11. Cenários de Teste

---

1. Introdução

1.1 Sobre o Sistema

O SIGEFP é um sistema integrado para gestão de folha de pagamento do setor público, desenvolvido especificamente para Guiné-Bissau. O sistema gerencia todo o ciclo de vida dos funcionários públicos, desde a admissão até o pagamento, incluindo integração com orçamento e tesouraria.

1.2 Estrutura do Manual

Este manual está organizado por módulos, cada um com:

• Descrição do módulo
• Funcionalidades principais
• Passo a passo de uso
• Validações e regras de negócio
• Cenários de teste

1.3 Credenciais de Teste

Usuário Administrador:

• Username: admin
• Password: admin (ou conforme configurado)

---

2. Acesso ao Sistema

2.1 Login

1. Acesse a URL do sistema (ex: http://localhost:5173)
2. Você será redirecionado para a página de login
3. Informe seu username e password
4. Clique em "Entrar"

2.2 Primeiro Acesso

Após o login, você verá:

• Dashboard com visão geral do sistema
• Menu lateral com todos os módulos
• Barra superior com informações do usuário

2.3 Navegação

• Use o menu lateral para navegar entre módulos
• Clique no logo ou em "Dashboard" para voltar à página inicial
• Use o botão de recolher no menu para expandir/colapsar

---

3. Dashboard

3.1 Descrição

O Dashboard fornece uma visão geral do sistema com estatísticas e informações recentes.

3.2 Funcionalidades

• ✅ Estatísticas de agentes (total, ativos, inativos, desligados)
• ✅ Contagem de ministérios e unidades orgânicas
• ✅ Folhas de pagamento recentes
• ✅ Lotes de pagamento recentes
• ✅ Execução orçamentária

3.3 Como Usar

1. Visualizar Estatísticas

   • As estatísticas são exibidas automaticamente em cards
   • Atualizam em tempo real conforme os dados do sistema

2. Acessar Módulos Rápidos

   • Clique nos cards para navegar diretamente para o módulo relacionado
   • Ex: Clique em "Total de Agentes" para ir à lista de agentes

3. Ver Atividades Recentes

   • Role a página para ver folhas e pagamentos recentes
   • Clique em qualquer item para ver detalhes

3.4 Cenários de Teste

Teste 1: Verificação de Estatísticas

1. Acesse o Dashboard
2. Verifique se os números estão corretos
3. Compare com os dados reais do sistema

Teste 2: Navegação Rápida

1. Clique em um card de estatística
2. Verifique se navega para a página correta
3. Volte ao Dashboard

---

4. Módulo Administração

4.1 Descrição

Gerencia utilizadores, perfis, permissões e auditoria do sistema.

4.2 Submódulos

4.2.1 Utilizadores (/admin/users)

Funcionalidades:

• ✅ Listar utilizadores
• ✅ Criar novo utilizador
• ✅ Editar utilizador existente
• ✅ Atribuir perfis a utilizadores
• ✅ Desativar/ativar utilizadores

Passo a Passo:

Criar Novo Utilizador:

1. Acesse Administração → Utilizadores
2. Clique em "Novo Utilizador"
3. Preencha os campos:
   • Username (obrigatório, único)
   • Email (obrigatório, único)
   • Nome Completo (obrigatório)
   • Password (obrigatório, mínimo 8 caracteres)
   • Ativo (checkbox)
4. Clique em "Salvar"

Editar Utilizador:

1. Na lista de utilizadores, clique no menu ⋮ ao lado do utilizador
2. Selecione "Editar"
3. Modifique os campos desejados
4. Clique em "Salvar"

Atribuir Perfis:

1. Clique no menu ⋮ ao lado do utilizador
2. Selecione "Atribuir Perfis"
3. Marque/desmarque os perfis desejados
4. Clique em "Salvar"

Validações:

• Username deve ser único
• Email deve ser único e válido
• Password deve ter no mínimo 8 caracteres
• Nome completo é obrigatório

Cenários de Teste:

1. Criar utilizador com dados válidos
2. Tentar criar utilizador com username duplicado (deve dar erro)
3. Tentar criar utilizador com email inválido (deve dar erro)
4. Editar utilizador existente
5. Atribuir múltiplos perfis a um utilizador

---

4.2.2 Perfis e Permissões (/admin/roles)

Funcionalidades:

• ✅ Listar perfis
• ✅ Criar novo perfil
• ✅ Editar perfil existente
• ✅ Gerenciar permissões do perfil

Passo a Passo:

Criar Novo Perfil:

1. Acesse Administração → Perfis e Permissões
2. Clique em "Novo Perfil"
3. Preencha:
   • Código (obrigatório, único, ex: RH_MANAGER)
   • Nome (obrigatório, ex: Gestor de RH)
   • Descrição (opcional)
4. Clique em "Salvar"

Gerenciar Permissões:

1. Clique no menu ⋮ ao lado do perfil
2. Selecione "Gerenciar Permissões"
3. Marque/desmarque as permissões desejadas
4. Clique em "Salvar"

Validações:

• Código deve ser único
• Código deve estar em UPPERCASE
• Nome é obrigatório

Cenários de Teste:

1. Criar perfil com código único
2. Tentar criar perfil com código duplicado (deve dar erro)
3. Atribuir permissões a um perfil
4. Editar perfil existente

---

4.2.3 Auditoria (/admin/audit)

Funcionalidades:

• ✅ Consultar logs de auditoria
• ✅ Filtrar por utilizador, módulo, data
• ✅ Exportar logs

Passo a Passo:

Consultar Logs:

1. Acesse Administração → Auditoria
2. Use os filtros:
   • Utilizador (opcional)
   • Módulo (opcional: RH, Budget, Treasury, etc.)
   • Data Inicial (opcional)
   • Data Final (opcional)
3. Clique em "Filtrar"
4. Os logs serão exibidos na tabela

Exportar Logs:

1. Após aplicar filtros, clique em "Exportar"
2. Escolha o formato (Excel ou PDF)
3. O arquivo será baixado

Cenários de Teste:

1. Consultar todos os logs
2. Filtrar por utilizador específico
3. Filtrar por módulo
4. Filtrar por período
5. Exportar logs filtrados

---

5. Módulo Organização

5.1 Descrição

Gerencia a estrutura organizacional do Estado: Ministérios, Unidades Orgânicas e Cargos.

5.2 Submódulos

5.2.1 Ministérios (/org/ministries)

Funcionalidades:

• ✅ Listar ministérios
• ✅ Criar novo ministério
• ✅ Editar ministério existente
• ✅ Filtrar e buscar

Passo a Passo:

Criar Novo Ministério:

1. Acesse Organização → Ministérios
2. Clique em "Novo Ministério"
3. Preencha:
   • Código (obrigatório, único, ex: MIN-001)
   • Nome (obrigatório, ex: Ministério das Finanças)
   • Sigla (opcional, ex: MINFIN)
   • Descrição (opcional)
4. Clique em "Salvar"

Validações:

• Código deve ser único
• Nome é obrigatório

Cenários de Teste:

1. Criar ministério com dados válidos
2. Tentar criar ministério com código duplicado
3. Editar ministério existente
4. Buscar ministério por nome

---

5.2.2 Unidades Orgânicas (/org/units)

Funcionalidades:

• ✅ Listar unidades orgânicas
• ✅ Criar nova unidade
• ✅ Editar unidade existente
• ✅ Hierarquia (unidades podem ter unidades pai)

Passo a Passo:

Criar Nova Unidade Orgânica:

1. Acesse Organização → Unidades Orgânicas
2. Clique em "Nova Unidade"
3. Preencha:
   • Código (obrigatório, único, ex: UO-001)
   • Nome (obrigatório)
   • Ministério (obrigatório, selecione da lista)
   • Unidade Pai (opcional, para hierarquia)
   • Tipo (opcional)
   • Descrição (opcional)
4. Clique em "Salvar"

Validações:

• Código deve ser único
• Nome é obrigatório
• Ministério é obrigatório
• Unidade pai deve pertencer ao mesmo ministério

Cenários de Teste:

1. Criar unidade orgânica de nível 1 (sem pai)
2. Criar unidade orgânica de nível 2 (com pai)
3. Tentar criar unidade com código duplicado
4. Editar unidade existente
5. Filtrar unidades por ministério

---

5.2.3 Cargos e Posições (/org/positions)

Funcionalidades:

• ✅ Listar cargos
• ✅ Criar novo cargo
• ✅ Editar cargo existente

Passo a Passo:

Criar Novo Cargo:

1. Acesse Organização → Cargos e Posições
2. Clique em "Novo Cargo"
3. Preencha:
   • Código (obrigatório, único, ex: POS-001)
   • Título (obrigatório, ex: Diretor)
   • Descrição (opcional)
   • Categoria (opcional)
4. Clique em "Salvar"

Validações:

• Código deve ser único
• Título é obrigatório

Cenários de Teste:

1. Criar cargo com dados válidos
2. Tentar criar cargo com código duplicado
3. Editar cargo existente
4. Buscar cargo por título

---

6. Módulo RH & Folha

6.1 Descrição

Módulo principal para gestão de recursos humanos e processamento de folha de pagamento.

6.2 Submódulos

6.2.1 Agentes (/rh/agents)

Funcionalidades:

• ✅ Listar agentes/funcionários
• ✅ Criar novo agente
• ✅ Editar agente existente
• ✅ Visualizar detalhes completos
• ✅ Filtros avançados
• ✅ Exportação (PDF, Excel)

Passo a Passo:

Criar Novo Agente:

1. Acesse RH & Folha → Agentes

2. Clique em "Novo Funcionário"

3. Preencha os dados:

   Identificação:

   • Matrícula (obrigatório, único, ex: 2024/001)
   • NIF (obrigatório, único)
   • BI Número (obrigatório, único)
   • Nome Completo (obrigatório)
   • Data de Nascimento (obrigatório)
   • Gênero (obrigatório)
   • Nacionalidade (opcional)

   Contato:

   • Email (opcional)
   • Telefone (opcional)
   • Endereço (opcional)

   Status:

   • Status (obrigatório: REGISTERED, ACTIVE, INACTIVE, SUSPENDED, TERMINATED)
   • Data de Admissão (obrigatório)
   • Tipo de Nomeação (obrigatório)

4. Clique em "Salvar"

Visualizar Detalhes:

1. Na lista, clique no menu ⋮ ao lado do agente
2. Selecione "Ver Detalhes"
3. Ou clique diretamente no nome do agente
4. Uma modal abrirá com:
   • Informações pessoais
   • Contrato ativo
   • Conta bancária primária
   • Histórico de status
   • Eventos de carreira
   • Avaliações

Filtros Avançados:

1. Clique em "Filtros" (ícone de funil)
2. Selecione os filtros:
   • Status
   • Ministério
   • Unidade Orgânica
   • Cargo
   • Situação Funcional
   • Tipo de Nomeação
3. Clique em "Aplicar Filtros"

Exportar Dados:

1. Aplique filtros se necessário
2. Clique em "Exportar"
3. Escolha o formato (Excel ou PDF)
4. O arquivo será baixado

Validações:

• Matrícula deve ser única
• NIF deve ser único
• BI Número deve ser único
• Data de nascimento não pode ser futura
• Data de admissão não pode ser futura

Cenários de Teste:

1. Criar agente com todos os dados obrigatórios
2. Tentar criar agente com matrícula duplicada
3. Editar agente existente
4. Visualizar detalhes completos
5. Filtrar agentes por status
6. Filtrar agentes por ministério
7. Exportar lista de agentes
8. Buscar agente por nome ou matrícula

---

6.2.2 Contratos (/rh/contracts)

Funcionalidades:

• ✅ Listar contratos
• ✅ Criar novo contrato
• ✅ Editar contrato existente
• ✅ Filtrar por agente

Passo a Passo:

Criar Novo Contrato:

1. Acesse RH & Folha → Contratos
2. Clique em "Novo Contrato"
3. Preencha:
   • Agente (obrigatório, selecione da lista)
   • Tipo de Contrato (obrigatório: PERMANENT, TEMPORARY, INTERIM)
   • Data de Início (obrigatório)
   • Data de Término (opcional, para contratos temporários)
   • Unidade Orgânica (obrigatório)
   • Cargo (obrigatório)
   • Categoria Salarial (obrigatório)
   • Grau Salarial (obrigatório)
   • Escalão (obrigatório)
   • Salário Base de Referência (obrigatório)
   • Horas Semanais (opcional, padrão: 40)
   • Ativo (checkbox)
4. Clique em "Salvar"

Validações:

• Agente é obrigatório
• Data de início não pode ser futura
• Data de término deve ser posterior à data de início
• Apenas um contrato ativo por agente

Cenários de Teste:

1. Criar contrato permanente para agente
2. Criar contrato temporário com data de término
3. Tentar criar dois contratos ativos para o mesmo agente (deve dar erro)
4. Editar contrato existente
5. Filtrar contratos por agente

---

6.2.3 Contas Bancárias (/rh/bank-accounts)

Funcionalidades:

• ✅ Listar contas bancárias
• ✅ Criar nova conta
• ✅ Editar conta existente
• ✅ Definir conta primária

Passo a Passo:

Criar Nova Conta Bancária:

1. Acesse RH & Folha → Contas Bancárias
2. Clique em "Nova Conta"
3. Preencha:
   • Agente (obrigatório)
   • Banco (obrigatório, selecione da lista)
   • Número da Conta (obrigatório)
   • Código da Agência (opcional)
   • Conta Primária (checkbox - apenas uma por agente)
4. Clique em "Salvar"

Validações:

• Agente é obrigatório
• Banco é obrigatório
• Número da conta é obrigatório
• Apenas uma conta primária por agente

Cenários de Teste:

1. Criar conta bancária para agente
2. Marcar conta como primária
3. Tentar criar segunda conta primária (deve desmarcar a anterior)
4. Editar conta existente
5. Filtrar contas por agente

---

6.2.4 Grelha Salarial (/rh/salary-grid)

Funcionalidades:

• ✅ Visualizar estrutura salarial
• ✅ Gerenciar categorias, graus e escalões
• ✅ Visualizar valores da grelha

Passo a Passo:

Visualizar Estrutura:

1. Acesse RH & Folha → Grelha Salarial
2. A estrutura é exibida hierarquicamente:
   • Categorias (ex: Técnico Superior, Assistente)
   • Graus (dentro de cada categoria)
   • Escalões (dentro de cada grau)
   • Valores (para cada escalão)

Gerenciar Categorias:

1. Clique em "Nova Categoria"
2. Preencha:
   • Código (obrigatório, único)
   • Nome (obrigatório)
3. Clique em "Salvar"

Gerenciar Graus:

1. Selecione uma categoria
2. Clique em "Novo Grau"
3. Preencha:
   • Código (obrigatório)
   • Nome (obrigatório)
   • Categoria (já selecionada)
4. Clique em "Salvar"

Gerenciar Escalões:

1. Selecione um grau
2. Clique em "Novo Escalão"
3. Preencha:
   • Número do Escalão (obrigatório, único no grau)
   • Grau (já selecionado)
4. Clique em "Salvar"

Gerenciar Valores:

1. Selecione um escalão
2. Clique em "Novo Valor" ou "Editar"
3. Preencha:
   • Valor Base (obrigatório, em XOF)
   • Data de Vigência (obrigatório)
4. Clique em "Salvar"

Cenários de Teste:

1. Visualizar estrutura salarial completa
2. Criar nova categoria
3. Criar grau dentro de categoria
4. Criar escalão dentro de grau
5. Definir valor para escalão
6. Verificar valores atuais vs históricos

---

6.2.5 Períodos de Folha (/rh/payroll-periods)

Funcionalidades:

• ✅ Listar períodos de folha
• ✅ Criar novo período
• ✅ Abrir/fechar período
• ✅ Filtrar por ano fiscal

Passo a Passo:

Criar Novo Período:

1. Acesse RH & Folha → Períodos de Folha
2. Clique em "Novo Período"
3. Preencha:
   • Ano Fiscal (obrigatório, ex: 2025)
   • Mês (obrigatório, 1-12)
   • Data de Início (obrigatório)
   • Data de Término (obrigatório)
   • Status (obrigatório: DRAFT, OPEN, CLOSED)
4. Clique em "Salvar"

Abrir Período:

1. Selecione um período com status DRAFT
2. Clique no menu ⋮
3. Selecione "Abrir Período"
4. Confirme a ação

Fechar Período:

1. Selecione um período com status OPEN
2. Clique no menu ⋮
3. Selecione "Fechar Período"
4. Confirme a ação

Validações:

• Não pode haver dois períodos abertos para o mesmo mês/ano
• Data de término deve ser posterior à data de início
• Período fechado não pode ser reaberto

Cenários de Teste:

1. Criar período para mês futuro
2. Abrir período (mudar de DRAFT para OPEN)
3. Tentar criar dois períodos abertos para o mesmo mês (deve dar erro)
4. Fechar período (mudar de OPEN para CLOSED)
5. Filtrar períodos por ano fiscal

---

6.2.6 Processamento (/rh/payroll-runs)

Funcionalidades:

• ✅ Listar processamentos de folha
• ✅ Criar novo processamento
• ✅ Processar folha (calcular itens)
• ✅ Gerar ordens de pagamento
• ✅ Exportar folha

Passo a Passo:

Criar Novo Processamento:

1. Acesse RH & Folha → Processamento
2. Clique em "Novo Processamento"
3. Preencha:
   • Período (obrigatório, selecione período aberto)
   • Ministério (obrigatório)
   • Unidade Orgânica (obrigatório)
   • Tipo (obrigatório: REGULAR, BONUS, ADJUSTMENT)
4. Clique em "Salvar"

Processar Folha:

1. Selecione um processamento com status DRAFT ou PENDING
2. Clique no menu ⋮
3. Selecione "Processar Folha"
4. O sistema irá:
   • Calcular vencimentos base
   • Calcular proventos (abono de família, etc.)
   • Calcular descontos (INPS, IRPS, Selo)
   • Gerar itens de folha
5. Aguarde a conclusão

Visualizar Itens:

1. Após processar, clique em "Ver Itens"
2. Você verá:
   • Itens de proventos (vencimento, abono)
   • Itens de descontos (INPS, IRPS, Selo)
   • Valores brutos e líquidos

Gerar Ordens de Pagamento:

1. Processamento deve estar com status COMPLETED
2. Clique no menu ⋮
3. Selecione "Gerar Ordens de Pagamento"
4. As ordens serão criadas no módulo Tesouraria

Exportar Folha:

1. Selecione um processamento
2. Clique em "Exportar"
3. Escolha o formato (PDF ou Excel)
4. O arquivo será baixado

Validações:

• Período deve estar aberto (status OPEN)
• Apenas um processamento por período/ministério/unidade
• Processamento deve estar COMPLETED para gerar ordens

Cenários de Teste:

1. Criar processamento para período aberto
2. Processar folha (calcular itens)
3. Verificar cálculos (vencimento, descontos)
4. Verificar integração com orçamento (commitment)
5. Gerar ordens de pagamento
6. Exportar folha em PDF
7. Exportar folha em Excel

---

6.2.7 Regras de Imposto (/rh/tax-settings)

Funcionalidades:

• ✅ Visualizar regras globais de descontos
• ✅ Criar/editar regras
• ✅ Ativar/desativar regras

Passo a Passo:

Visualizar Regras:

1. Acesse RH & Folha → Regras de Imposto
2. As regras são exibidas por tipo de desconto:
   • INPS (percentual sobre vencimento)
   • Selo (percentual sobre vencimento)

Criar Nova Regra:

1. Clique em "Nova Regra"
2. Preencha:
   • Tipo de Desconto (obrigatório: INPS, SELO)
   • Percentual (obrigatório, ex: 7.00 para 7%)
   • Data de Vigência (obrigatório)
   • Ativo (checkbox)
3. Clique em "Salvar"

Validações:

• Percentual deve ser entre 0 e 100
• Data de vigência não pode ser futura
• Apenas uma regra ativa por tipo de desconto

Cenários de Teste:

1. Visualizar regras ativas
2. Criar nova regra de INPS
3. Criar nova regra de Selo
4. Desativar regra antiga
5. Ativar nova regra

---

6.2.8 Escalões de IRPS (/rh/tax-brackets)

Funcionalidades:

• ✅ Visualizar escalões de IRPS
• ✅ Criar/editar escalões
• ✅ Gerenciar faixas de rendimento

Passo a Passo:

Visualizar Escalões:

1. Acesse RH & Folha → Escalões de IRPS
2. Os escalões são exibidos em tabela com:
   • Limite Inferior
   • Limite Superior
   • Taxa Percentual
   • Dedução em Excesso

Criar Novo Escalão:

1. Clique em "Novo Escalão"
2. Preencha:
   • Limite Inferior (obrigatório, em XOF)
   • Limite Superior (opcional, NULL para último escalão)
   • Taxa Percentual (obrigatório, ex: 10.00 para 10%)
   • Dedução em Excesso (obrigatório, em XOF)
   • Data de Vigência (obrigatório)
3. Clique em "Salvar"

Validações:

• Limite superior deve ser maior que limite inferior
• Taxa deve ser entre 0 e 100
• Não pode haver sobreposição de faixas
• Último escalão deve ter limite superior NULL

Cenários de Teste:

1. Visualizar escalões atuais
2. Criar novo escalão
3. Verificar cálculo de IRPS com diferentes rendimentos
4. Editar escalão existente
5. Verificar que não há sobreposição de faixas

---

6.2.9 Avaliações (/rh/evaluations)

Funcionalidades:

• ✅ Listar avaliações de desempenho
• ✅ Finalizar avaliação
• ✅ Filtrar por agente e ano

Passo a Passo:

Visualizar Avaliações:

1. Acesse RH & Folha → Avaliações
2. As avaliações são exibidas com:
   • Agente
   • Ano de Referência
   • Pontuação
   • Menção (MAU, MEDIOCRE, REGULAR, BOM, MUITO_BOM)
   • Status (DRAFT, FINAL)

Finalizar Avaliação:

1. Selecione uma avaliação com status DRAFT
2. Clique no menu ⋮
3. Selecione "Finalizar"
4. Confirme a ação
5. O sistema irá:
   • Atualizar status para FINAL
   • Calcular menção baseada na pontuação
   • Verificar elegibilidade para promoção (3 anos BOM ou MUITO_BOM)

Validações:

• Apenas avaliações DRAFT podem ser finalizadas
• Pontuação deve estar entre 0 e 20
• Menção é calculada automaticamente

Cenários de Teste:

1. Visualizar avaliações
2. Finalizar avaliação DRAFT
3. Verificar cálculo de menção
4. Verificar elegibilidade para promoção
5. Filtrar avaliações por agente
6. Filtrar avaliações por ano

---

7. Módulo Orçamento

7.1 Descrição

Gerencia exercícios fiscais, linhas orçamentais e execução orçamentária.

7.2 Submódulos

7.2.1 Exercícios Fiscais (/budget/fiscal-years)

Funcionalidades:

• ✅ Listar exercícios fiscais
• ✅ Criar novo exercício
• ✅ Abrir/fechar exercício
• ✅ Visualizar status

Passo a Passo:

Criar Novo Exercício:

1. Acesse Orçamento → Exercícios Fiscais
2. Clique em "Novo Exercício"
3. Preencha:
   • Ano (obrigatório, único, ex: 2025)
   • Data de Início (obrigatório, ex: 2025-01-01)
   • Data de Término (obrigatório, ex: 2025-12-31)
   • Status (obrigatório: DRAFT, OPEN, CLOSED)
4. Clique em "Salvar"

Abrir Exercício:

1. Selecione um exercício com status DRAFT
2. Clique no menu ⋮
3. Selecione "Abrir Exercício"
4. Confirme a ação
5. Status mudará para OPEN

Fechar Exercício:

1. Selecione um exercício com status OPEN
2. Clique no menu ⋮
3. Selecione "Fechar Exercício"
4. Confirme a ação
5. Status mudará para CLOSED

Validações:

• Ano deve ser único
• Data de término deve ser posterior à data de início
• Apenas um exercício pode estar aberto por vez
• Exercício fechado não pode ser reaberto

Cenários de Teste:

1. Criar exercício fiscal para 2025
2. Abrir exercício (mudar para OPEN)
3. Tentar abrir dois exercícios (deve dar erro)
4. Fechar exercício (mudar para CLOSED)
5. Verificar que exercício fechado não pode ser reaberto

---

7.2.2 Linhas Orçamentais (/budget/lines)

Funcionalidades:

• ✅ Listar linhas orçamentais
• ✅ Criar nova linha
• ✅ Editar linha existente
• ✅ Visualizar saldos (alocado, comprometido, liquidado, pago, disponível)

Passo a Passo:

Criar Nova Linha Orçamentária:

1. Acesse Orçamento → Linhas Orçamentais
2. Clique em "Nova Linha"
3. Preencha:
   • Exercício Fiscal (obrigatório, selecione exercício aberto)
   • Código (obrigatório, único, ex: 2025-MINFIN-311100)
   • Descrição (obrigatório)
   • Ministério (obrigatório)
   • Unidade Orgânica (obrigatório)
   • Classe Econômica (obrigatório, ex: 311100 para vencimentos)
4. Clique em "Salvar"

Visualizar Saldos:

1. Na lista, você verá colunas:
   • Total Alocado (valor inicial)
   • Total Comprometido (compromissos)
   • Total Liquidado (liquidações)
   • Total Pago (pagamentos)
   • Saldo Disponível (calculado: Alocado - Comprometido)

Validações:

• Código deve ser único
• Exercício fiscal deve estar aberto
• Classe econômica deve ser válida

Cenários de Teste:

1. Criar linha orçamentária para exercício aberto
2. Verificar saldos iniciais (alocado = valor inicial)
3. Após processar folha, verificar comprometimento
4. Após liquidação, verificar saldo liquidado
5. Após pagamento, verificar saldo pago
6. Verificar cálculo de saldo disponível

---

7.2.3 Execução (/budget/execution)

Funcionalidades:

• ✅ Visualizar execução orçamentária
• ✅ Filtrar por período e linha
• ✅ Ver movimentos (COMMITMENT, LIQUIDATION, PAYMENT)

Passo a Passo:

Visualizar Execução:

1. Acesse Orçamento → Execução
2. Use os filtros:
   • Linha Orçamentária (opcional)
   • Período (opcional, formato: YYYYMM)
   • Tipo de Movimento (opcional: COMMITMENT, LIQUIDATION, PAYMENT)
3. Clique em "Filtrar"
4. Os movimentos serão exibidos na tabela

Entender os Movimentos:

• COMMITMENT (Compromisso): Quando a folha é gerada, compromete o orçamento
• LIQUIDATION (Liquidação): Quando a folha é processada, liquida o compromisso
• PAYMENT (Pagamento): Quando o tesouro confirma o pagamento

Fluxo Completo:

1. Folha Gerada → COMMITMENT criado
2. Folha Processada → LIQUIDATION criado
3. Pagamento Confirmado → PAYMENT criado

Cenários de Teste:

1. Visualizar todos os movimentos
2. Filtrar por linha orçamentária
3. Filtrar por período
4. Filtrar por tipo de movimento
5. Verificar sequência: COMMITMENT → LIQUIDATION → PAYMENT
6. Verificar valores corretos em cada etapa

---

8. Módulo Tesouraria

8.1 Descrição

Gerencia lotes de pagamento, ordens de pagamento e confirmações do tesouro.

8.2 Submódulos

8.2.1 Lotes de Pagamento (/treasury/batches)

Funcionalidades:

• ✅ Listar lotes de pagamento
• ✅ Criar novo lote
• ✅ Atualizar status do lote
• ✅ Filtrar por período e ministério

Passo a Passo:

Criar Novo Lote:

1. Acesse Tesouraria → Lotes de Pagamento
2. Clique em "Novo Lote"
3. Preencha:
   • Período (obrigatório, formato: YYYYMM, ex: 202501)
   • Ministério (obrigatório)
4. Clique em "Salvar"
5. Status inicial será CREATED

Atualizar Status:

1. Selecione um lote
2. Clique no menu ⋮
3. Selecione "Atualizar Status"
4. Escolha o novo status:
   • SENT_TO_BANK (enviado ao banco)
   • CONFIRMED (confirmado)
   • REJECTED (rejeitado)
5. Opcionalmente, adicione uma mensagem
6. Clique em "Salvar"

Validações:

• Período é obrigatório
• Ministério é obrigatório
• Status só pode avançar (CREATED → SENT_TO_BANK → CONFIRMED)

Cenários de Teste:

1. Criar lote de pagamento
2. Atualizar status para SENT_TO_BANK
3. Atualizar status para CONFIRMED
4. Filtrar lotes por período
5. Filtrar lotes por ministério
6. Verificar ordens de pagamento no lote

---

8.2.2 Ordens de Pagamento (/treasury/orders)

Funcionalidades:

• ✅ Listar ordens de pagamento
• ✅ Visualizar detalhes
• ✅ Filtrar por lote e status

Passo a Passo:

Visualizar Ordens:

1. Acesse Tesouraria → Ordens de Pagamento
2. As ordens são exibidas com:
   • Lote
   • Agente
   • Valor Bruto
   • Valor Líquido
   • Status

Filtrar Ordens:

1. Use os filtros:
   • Lote (opcional)
   • Status (opcional: CREATED, SENT_TO_BANK, PAID, REJECTED)
2. Clique em "Filtrar"

Visualizar Detalhes:

1. Clique em uma ordem
2. Você verá:
   • Dados do agente
   • Conta bancária
   • Valores (bruto, descontos, líquido)
   • Linha orçamentária
   • Status e histórico

Validações:

• Ordens são geradas automaticamente a partir de folhas processadas
• Status só pode avançar

Cenários de Teste:

1. Visualizar ordens geradas a partir de folha
2. Filtrar ordens por lote
3. Filtrar ordens por status
4. Verificar valores corretos (bruto vs líquido)
5. Verificar conta bancária do agente

---

8.2.3 Confirmações (/treasury/confirmations)

Funcionalidades:

• ✅ Listar confirmações de pagamento
• ✅ Registrar confirmação do tesouro
• ✅ Atualizar status de pagamento

Passo a Passo:

Registrar Confirmação:

1. Acesse Tesouraria → Confirmações
2. Clique em "Nova Confirmação"
3. Preencha:
   • Ordem de Pagamento (obrigatório, selecione da lista)
   • Data de Pagamento (obrigatório)
   • Referência da Transação (opcional, ex: TXN-2025-001-001)
   • Status (obrigatório: PENDING, PAID, REJECTED, CANCELLED)
   • Mensagem (opcional)
4. Clique em "Salvar"

Atualizar Status:

1. Selecione uma confirmação
2. Clique no menu ⋮
3. Selecione "Atualizar Status"
4. Escolha o novo status
5. Clique em "Salvar"

Impacto no Orçamento:

• Quando status muda para PAID, um movimento PAYMENT é criado no orçamento
• O saldo disponível da linha orçamentária é atualizado

Validações:

• Ordem de pagamento é obrigatória
• Data de pagamento não pode ser futura
• Status PAID requer referência de transação

Cenários de Teste:

1. Registrar confirmação de pagamento
2. Marcar como PAID
3. Verificar criação de movimento PAYMENT no orçamento
4. Verificar atualização de saldo disponível
5. Filtrar confirmações por status
6. Filtrar confirmações por período

---

9. Módulo Dados Comuns

9.1 Descrição

Gerencia dados compartilhados entre módulos.

9.2 Submódulos

9.2.1 Bancos (/common/banks)

Funcionalidades:

• ✅ Listar bancos
• ✅ Criar novo banco
• ✅ Editar banco existente

Passo a Passo:

Criar Novo Banco:

1. Acesse Dados Comuns → Bancos
2. Clique em "Novo Banco"
3. Preencha:
   • Código (obrigatório, único, ex: 001)
   • Nome (obrigatório, ex: Banco Central dos Estados da África Ocidental)
   • Sigla (opcional, ex: BCEAO)
   • Código SWIFT (opcional)
4. Clique em "Salvar"

Validações:

• Código deve ser único
• Nome é obrigatório

Cenários de Teste:

1. Criar banco com dados válidos
2. Tentar criar banco com código duplicado
3. Editar banco existente
4. Verificar uso do banco em contas bancárias de agentes

---

10. Fluxos Integrados

10.1 Fluxo Completo: RH → Orçamento → Tesouraria

Este é o fluxo principal do sistema, desde a criação de um agente até o pagamento.

Passo 1: Configuração Inicial

1. Criar Exercício Fiscal (/budget/fiscal-years)

   • Criar exercício 2025
   • Abrir exercício (status OPEN)

2. Criar Linha Orçamentária (/budget/lines)

   • Criar linha para vencimentos
   • Definir valor alocado

3. Criar Período de Folha (/rh/payroll-periods)

   • Criar período para Janeiro 2025
   • Abrir período (status OPEN)

Passo 2: Cadastro de Agente

1. Criar Agente (/rh/agents)

   • Preencher dados pessoais
   • Status: ACTIVE

2. Criar Contrato (/rh/contracts)

   • Vincular agente
   • Definir cargo, categoria, grau, escalão
   • Definir salário base

3. Criar Conta Bancária (/rh/bank-accounts)

   • Vincular agente
   • Definir banco e número da conta
   • Marcar como primária

Passo 3: Processamento de Folha

1. Criar Processamento (/rh/payroll-runs)

   • Selecionar período
   • Selecionar ministério e unidade
   • Status inicial: DRAFT

2. Processar Folha (/rh/payroll-runs)

   • Clicar em "Processar Folha"
   • Sistema calcula:
     • Vencimento base
     • Proventos (abono de família)
     • Descontos (INPS, IRPS, Selo)
   • Status muda para COMPLETED

3. Verificar Execução Orçamentária (/budget/execution)

   • Deve aparecer COMMITMENT
   • Valor = total bruto da folha

Passo 4: Geração de Ordens de Pagamento

1. Gerar Ordens (/rh/payroll-runs)

   • A partir de folha COMPLETED
   • Clicar em "Gerar Ordens de Pagamento"
   • Ordens são criadas automaticamente

2. Verificar Ordens (/treasury/orders)

   • Ordens devem aparecer com status CREATED
   • Valores devem estar corretos (bruto e líquido)

Passo 5: Lote de Pagamento

1. Criar Lote (/treasury/batches)

   • Selecionar período
   • Selecionar ministério
   • Status: CREATED

2. Adicionar Ordens ao Lote (automático ou manual)

   • Ordens são vinculadas ao lote

3. Enviar ao Banco (/treasury/batches)

   • Atualizar status para SENT_TO_BANK

Passo 6: Confirmação de Pagamento

1. Registrar Confirmação (/treasury/confirmations)

   • Selecionar ordem de pagamento
   • Informar data de pagamento
   • Informar referência da transação
   • Status: PAID

2. Verificar Execução Orçamentária (/budget/execution)

   • Deve aparecer PAYMENT
   • Valor = valor líquido pago

3. Verificar Saldo (/budget/lines)

   • Saldo disponível deve ser atualizado
   • Fórmula: Alocado - Comprometido

10.2 Validações do Fluxo

Verificações Importantes:

1. ✅ Período deve estar aberto para processar folha
2. ✅ Exercício fiscal deve estar aberto para criar linhas
3. ✅ Agente deve ter contrato ativo
4. ✅ Agente deve ter conta bancária primária
5. ✅ Linha orçamentária deve ter saldo disponível
6. ✅ Folha deve estar COMPLETED para gerar ordens
7. ✅ Ordem deve estar em lote para enviar ao banco

---

11. Cenários de Teste

11.1 Teste End-to-End Completo

Objetivo: Testar todo o fluxo desde cadastro até pagamento.

Passos:

1. Criar exercício fiscal 2025 e abrir
2. Criar linha orçamentária com valor de 10.000.000 XOF
3. Criar período de folha para Janeiro 2025 e abrir
4. Criar agente com dados completos
5. Criar contrato para o agente (salário: 600.000 XOF)
6. Criar conta bancária primária
7. Criar processamento de folha
8. Processar folha
9. Verificar:
   • Itens de folha calculados corretamente
   • COMMITMENT criado no orçamento
   • Saldo disponível atualizado
10. Gerar ordens de pagamento
11. Criar lote de pagamento
12. Enviar lote ao banco
13. Registrar confirmação de pagamento (PAID)
14. Verificar:

• PAYMENT criado no orçamento
• Saldo disponível atualizado corretamente

Resultado Esperado:

• Todos os passos executados sem erros
• Valores calculados corretamente
• Integração entre módulos funcionando
• Saldos atualizados corretamente

---

11.2 Teste de Cálculos de Folha

Objetivo: Verificar cálculos de proventos e descontos.

Cenário:

• Agente com salário base: 600.000 XOF
• 2 dependentes (abono de família: 2.000 XOF cada)
• INPS: 7%
• Selo: 0.3%
• IRPS: conforme escalões

Cálculos Esperados:

1. Vencimento Base: 600.000 XOF
2. Abono de Família: 4.000 XOF (2 × 2.000)
3. Total Bruto: 604.000 XOF
4. INPS: 42.280 XOF (604.000 × 7%)
5. Selo: 1.812 XOF (604.000 × 0.3%)
6. Base IRPS: 561.720 XOF (604.000 - 42.280)
7. IRPS: Conforme escalão (exemplo: 46.172 XOF)
8. Total Descontos: 90.264 XOF
9. Valor Líquido: 513.736 XOF

Passos:

1. Criar agente e contrato
2. Processar folha
3. Verificar cada item calculado
4. Comparar com cálculos manuais

---

11.3 Teste de Validações

Objetivo: Verificar que validações estão funcionando.

Cenários de Erro Esperados:

1. ❌ Criar agente com matrícula duplicada
2. ❌ Criar contrato sem agente
3. ❌ Processar folha com período fechado
4. ❌ Criar linha orçamentária com exercício fechado
5. ❌ Gerar ordens sem folha processada
6. ❌ Registrar pagamento sem ordem de pagamento

Passos:

1. Tentar cada ação inválida
2. Verificar mensagem de erro apropriada
3. Verificar que dados não foram salvos

---

11.4 Teste de Integração Orçamentária

Objetivo: Verificar integração RH → Orçamento.

Passos:

1. Criar linha orçamentária com saldo de 1.000.000 XOF
2. Processar folha com total bruto de 800.000 XOF
3. Verificar:
   • COMMITMENT criado: 800.000 XOF
   • Saldo disponível: 200.000 XOF (1.000.000 - 800.000)
4. Processar liquidação
5. Verificar:
   • LIQUIDATION criado: 800.000 XOF
6. Confirmar pagamento
7. Verificar:
   • PAYMENT criado: valor líquido (ex: 700.000 XOF)
   • Saldo disponível atualizado

---

12. Dicas e Boas Práticas

12.1 Ordem Recomendada de Cadastro

1. Dados Comuns (bancos)
2. Organização (ministérios, unidades, cargos)
3. Orçamento (exercícios fiscais, linhas)
4. RH (agentes, contratos, contas)
5. Folha (períodos, processamentos)
6. Tesouraria (lotes, ordens, confirmações)

12.2 Verificações Antes de Processar Folha

• ✅ Período está aberto
• ✅ Agentes têm contratos ativos
• ✅ Agentes têm contas bancárias primárias
• ✅ Linhas orçamentárias têm saldo disponível
• ✅ Regras de imposto estão configuradas
• ✅ Escalões de IRPS estão configurados

12.3 Troubleshooting

Problema: Folha não processa

• Verificar se período está aberto
• Verificar se agentes têm contratos
• Verificar logs de erro

Problema: Ordens não são geradas

• Verificar se folha está COMPLETED
• Verificar se agentes têm contas bancárias

Problema: Saldo orçamentário incorreto

• Verificar movimentos de execução
• Verificar sequência: COMMITMENT → LIQUIDATION → PAYMENT

---

13. Conclusão

Este manual cobre todas as funcionalidades principais do SIGEFP. Use-o como guia para:

• ✅ Entender cada módulo
• ✅ Executar operações corretamente
• ✅ Testar funcionalidades
• ✅ Verificar coerência e lógica
• ✅ Resolver problemas comuns

Para suporte adicional, consulte:

• Documentação técnica (ANALISE_TECNICA_FRONTEND.md)
• Documentação da API (ENDPOINTS_API.md)
• Logs do sistema

---

Manual gerado em: 2025-01-XX
Versão: 1.0
Sistema: SIGEFP v1.0