💼 Sistema de Folha de Pagamento

Projeto desenvolvido como requisito de avaliação para a disciplina de Algoritmos e Programação — UC Dual em parceria com a Oracle Academy.
Curso: Análise e Desenvolvimento de Sistemas (ADS) · Versão atual: 8.1

---

Important

🎓 Painel de Avaliação Acadêmica

Professor, otimize seu tempo de correção escolhendo a melhor rota de avaliação abaixo:

---

👥 Equipe e contribuições

O projeto foi desenvolvido por Gabriel Conceição da Silva, Eduardo Santos Cruz e Pedro Alonso Martins Fernandes. Gabriel foi responsável pela maior parte da implementação e arquitetura do sistema, enquanto Pedro e Eduardo contribuíram principalmente com testes, sugestões e validações durante o desenvolvimento.

Reflexões individuais de cada membro sobre o desenvolvimento estão em docs/COMENTARIOS.md.

---

📌 Sobre o projeto

Sistemas de folha de pagamento no mercado tendem a ser caros, dependentes de internet ou complexos demais para o que entregam. Na outra ponta, o Excel é flexível e amplamente usado — mas não tem regras de negócio, depende do usuário não errar e não escala bem.

Este sistema é uma alternativa simples no meio do caminho: roda localmente no terminal, sem banco de dados externo, sem internet, sem instalação de dependências além do JDK. Calcula salários automaticamente, aplica regras de negócio e exporta os dados em formatos compatíveis com Excel e ferramentas de BI. O foco não é ser completo — é ser útil naquilo que se propõe.

Critério de qualidade central: um funcionário mal-intencionado não deve ter facilidade; um bem-intencionado não deve ter dificuldade alguma. A segurança do ambiente — acesso à máquina, controle de quem opera o sistema — fica a cargo da empresa.

---

🚀 Como testar e executar

O projeto cresceu significativamente desde os seus primeiros rascunhos. Para facilitar a distribuição e avaliação, a v8.1 conta com executáveis multiplataforma (.exe para Windows, .app para macOS e .tar.gz para Linux) que rodam o sistema de forma nativa e sem dependências.

Para baixar os executáveis e visualizar o histórico completo de releases (com seus respectivos ícones e destaques), acesse nossa central de documentação:

Nota: As instruções completas para rodar os binários e liberar permissões de sistema (como o SmartScreen no Windows ou a quarentena no macOS) estão detalhadas no INSTALL.md.

---

Galeria de Releases:

v8.1

v7.1

v5.1

v3.1

v2.1

v1.1

---

💻 Execução via Código-Fonte (Avaliação Acadêmica)

Caso você tenha feito o download do código-fonte cru (.zip) e queira rodar o projeto diretamente sem usar os executáveis, é necessário ter o JDK 17+ instalado na máquina.

Opção 1 — Automático:

Sistema	Script	Como abrir
Windows	executar.bat	Duplo clique na raiz do projeto
Windows (PowerShell)	scripts/executar.ps1	Chamado automaticamente pelo .bat
Linux	scripts/executar.sh	bash scripts/executar.sh no terminal
macOS	scripts/executar.command	Duplo clique no Finder ou bash scripts/executar.command

Todos os scripts compilam o projeto automaticamente (se necessário) e iniciam o sistema. Após a primeira compilação, use scripts/iniciar.sh ou scripts/iniciar.command para pular a etapa de compilação e abrir mais rápido.

Opção 2 — Compilação Manual (Terminal):

Windows (PowerShell):

javac -encoding UTF-8 -d bin (Get-ChildItem -Recurse -Filter *.java src | % { $_.FullName })

Linux / macOS:

javac -encoding UTF-8 -d bin $(find src -name "*.java")

Executar (Qualquer SO):

java -cp bin br.com.folha.main.SistemaFolha

---

🧪 Roteiro de Avaliação

Nota de fluxo: o sistema inicializa automaticamente no Perfil Administrativo no primeiro acesso (banco vazio). Nos acessos seguintes, a tela de seleção de perfil é exibida — escolha [2] Administrador ou [1] Funcionário conforme o cenário abaixo.

Os cenários abaixo cobrem os requisitos da UC diretamente. Siga-os na ordem ou pule para o que precisar avaliar.

---

Cenário 1 — Cadastro manual e cálculo de salário

Acesse como Funcionário e cadastre um de cada tipo:

Tipo	Opção	O que informar
Padrão	[1]	matrícula e nome — salário calculado automaticamente
Comissionado	[2]	matrícula, nome, valor de vendas e percentual de comissão
Produção	[3]	matrícula, nome, valor por peça e quantidade produzida

Depois, use [4] Gerar Folha de Pagamento para ver os três registros ordenados por matrícula com os salários calculados. Em qualquer campo de entrada, digite 0 para cancelar e voltar ao menu.

---

Cenário 2 — Validação de entradas

Durante o cadastro, tente inserir valores inválidos: número negativo no campo de vendas, quantidade de peças negativa, ou nome em branco. O sistema rejeita cada um com mensagem de erro e repete a pergunta — sem travar e sem aceitar o dado.

---

Cenário 3 — Importar o banco de teste (recomendado para agilizar a avaliação)

O repositório inclui um banco de dados com 20 funcionários pré-cadastrados (8 padrão, 7 comissionado e 5 de produção) em sistemaFolha-final/tests/database_teste.tsv.

⚠️ Este arquivo está no repositório, mas não no zip do executável. Para usá-lo com o executável, copie o database_teste.tsv para a pasta raiz do sistema (onde fica o .exe / .app) e renomeie para database.tsv antes de abrir o programa. Ao abrir, os dados já estarão carregados.

Usando pelo código-fonte: o arquivo já está em sistemaFolha-final/tests/. Alternativamente, acesse o Menu ADM → [3] Importar TSV e informe o caminho completo do arquivo para carregar a base sem precisar renomear nada.

Com dados carregados, é possível testar todos os cenários seguintes sem cadastro manual.

---

Cenário 4 — Exportação

No Menu ADM, use [1] Exportar TSV e [2] Exportar XLS. Os arquivos são gerados com timestamp em exportados/dados/ e exportados/relatorios/, respectivamente. O XLS abre diretamente no Excel. A essa altura, fique à vontade para testar a opção [9] Dashboard Analítico, colocada como forma de visualização complementar — é, ironicamente, o "gerar folha" do perfil ADM.

---

Cenário 5 — ArrayList e estrutura de dados

O sistema armazena todos os funcionários em um ArrayList<Funcionario> gerenciado pelo FolhaService. Para verificar: a opção [4] Gerar Folha percorre essa lista com um laço e exibe os registros ordenados por matrícula. A classe Funcionario é abstrata; cada subtipo implementa calcularSalario() de forma polimórfica.

---

⚙️ Funcionalidades

Perfil Funcionário

• Cadastrar os três tipos de funcionário com cálculo automático de salário
• Consultar a folha de pagamento do mês, ordenada por matrícula

Perfil Administrador (acesso via seleção de perfil na abertura)

• Exportar dados em TSV e relatório em XLS com timestamp
• Importar arquivo TSV externo para substituir a base atual
• Fechar o mês — arquiva os dados e inicia um ciclo limpo
• Editar e remover funcionários individualmente ou em lote por tipo
• Resetar o sistema com backup automático antes de apagar qualquer coisa
• Configurar salário-base, teto de bônus, limite de matrícula e modo de sequência
• Abrir o Dashboard Analítico integrado

Comportamentos gerais

• Matrícula única — duplicatas são rejeitadas na hora
• Nomes normalizados automaticamente (aceita qualquer capitalização)
• Persistência automática ao sair; restauração automática ao abrir
• Proteção contra database ausente com histórico de sessões no log
• Em qualquer campo de cadastro, 0 cancela e volta ao menu

---

💻 Tecnologias e padrões

Item	Detalhe
Linguagem	Java (JDK 17+)
Paradigma	POO — herança, polimorfismo, classes abstratas
Arquitetura	Camadas: model / service / repository / ui / main / util
Persistência	TSV local (fonte da verdade) + XLS para relatórios
Versionamento	Git + GitHub

---

📁 Estrutura do projeto base

sistemaFolha-final/
├── src/
│   └── br/com/folha/
│       ├── main/
│       │   └── SistemaFolha.java          ← ponto de entrada e detecção de estado
│       ├── model/
│       │   ├── Funcionario.java           ← classe base abstrata
│       │   ├── FuncionarioPadrao.java
│       │   ├── FuncionarioComissionado.java
│       │   └── FuncionarioProducao.java
│       ├── service/
│       │   └── FolhaService.java          ← regras de negócio e configurações
│       ├── repository/
│       │   └── FuncionarioRepository.java ← leitura e escrita em TSV e XLS
│       ├── ui/
│       │   ├── ConsoleUI.java             ← interface do terminal
│       │   ├── SeletorPerfil.java         ← tela de seleção ADM / Funcionário
│       │   └── DashboardBI.java           ← dashboard analítico integrado
│       └── util/
│           └── LoggerUtil.java            ← log de sessões e detecção de primeiro acesso
├── assets/                                ← diagramas SVG (dark/light) e capturas de tela
├── bin/                                   ← classes compiladas (gerado automaticamente)
├── config/                                ← ícones do aplicativo (.icns, .ico, .png)
├── docs/
│   ├── DIAGRAMAS.md                       ← fluxograma e casos de uso
│   ├── COMENTARIOS.md                     ← reflexões da equipe sobre o desenvolvimento
│   ├── ARQUITETURA.html                   ← documentação técnica navegável
│   └── fluxograma-sistema-folha.html      ← fluxograma interativo offline
├── logs/                                  ← logs de sessão gerados em execução
├── scripts/
│   ├── executar.ps1                       ← compila e executa (Windows / PowerShell)
│   ├── executar.sh                        ← compila e executa (Linux)
│   ├── executar.command                   ← compila e executa (macOS, duplo clique no Finder)
│   ├── iniciar.sh                         ← executa direto se o JAR já existir (Linux)
│   └── iniciar.command                    ← executa direto se o JAR já existir (macOS)
├── tests/
│   ├── dados_teste.xlsx
│   └── database_teste.tsv
├── executar.bat                           ← chama o .ps1 (Windows)
├── limpar.bat                             ← remove bin/, logs/, backups/, exportados/ e database.tsv
└── COMO_EXECUTAR.txt                      ← guia detalhado de todas as telas e menus

Cada pasta dentro de br/com/folha/ é um pacote Java. Não são simples diretórios: pacotes dividem o sistema em camadas confortavelmente isoladas, e ficam declarados sempre no topo de cada arquivo .java. Cada camada faz exatamente o que o nome dela diz, e nada além disso.

Para adicionar um novo tipo de funcionário: crie a classe em model/, implemente os quatro métodos abstratos e adicione o case correspondente em FuncionarioRepository.

---

🗂️ Arquivos gerados em execução

Arquivo / Pasta	Função
database.tsv	Fonte da verdade — carregado ao abrir, salvo ao sair
exportados/dados/	Exportações TSV com timestamp (integração BI / Excel)
exportados/relatorios/	Exportações XLS com timestamp (leitura humana)
backups/	Backups automáticos antes de qualquer reset ou fechamento de mês
historico/	Snapshots mensais gerados pelo "Novo mês", com nomenclatura historico/yyyy-MM_NomeMes_yyyy-MM-dd_HH-mm-ss.tsv
logs/	Registro de sessões mensais — usado para detectar database ausente

Esses arquivos não aparecem agora pois estão no .gitignore. Podem conter dados de funcionários — nomes, matrículas, salários. Mantê-los fora do repositório é uma decisão de privacidade.

---

📎 Documentação complementar

Documento	Conteúdo
INSTALL.md	Central de instalação, uso dos executáveis e permissões de sistema
docs/ARQUITETURA.html	Documentação técnica navegável das camadas e classes
docs/DIAGRAMAS.md	Fluxograma Mermaid e diagramas de casos de uso (dark/light)
docs/fluxograma-sistema-folha.html	Fluxograma interativo offline com simbologia ANSI completa
docs/COMENTARIOS.md	Reflexões individuais da equipe sobre o processo de desenvolvimento
COMO_EXECUTAR.txt	Guia detalhado de todas as telas, menus e opções do console
LICENSE.md	Termos de uso e restrições do projeto

---

🛠️ Uso de ferramentas externas

Ao longo do desenvolvimento, recorreu-se pontualmente ao Claude Code como ferramenta de acompanhamento — não como substituto de raciocínio, mas como um par de olhos externo.

Os usos foram cirúrgicos:

• Dashboard analítico — feito em Swing, uma tecnologia ainda em estudo à época. A IA gerou um molde inicial; a lógica, os parâmetros e os ajustes finais foram feitos manualmente.
• Comentários no código-fonte — a empolgação falou mais alto no início, e o código saiu bem antes da documentação.
• Partes do model/ e do repository/ — orientação a objetos no Java, também era território em construção. A ferramenta ajudou a validar decisões de herança e polimorfismo, não a gerá-las.
• Documentação do repositório — alguns dos arquivos .md e .html foram redigidos com suporte da ferramenta a partir de anotações e rascunhos próprios.

Arquitetura, lógica de negócio, estrutura de pacotes, ConsoleUI.java e decisões de design foram desenvolvidos manualmente. O material da Oracle Academy serviu como base de estudo ao longo de todo o projeto.

---

Projeto desenvolvido para fins acadêmicos — UC Dual Algoritmos e Programação | ADS · Oracle Academy