README

Este repositório contém as regras de negócio para o Sistema de Gestão Municipal da Prefeitura de Itabuna, implementado em PHP com Eloquent ORM.

📋 Índice

• Visão Geral
• Estrutura do Projeto
• Models
• Repositories
• Services
• Instalação
• Uso
• Exemplos de Código

🎯 Visão Geral

Este projeto implementa a camada de regras de negócio para um sistema de gestão municipal, utilizando os padrões Repository e Service para organizar a lógica de acesso a dados e regras de negócio.

Tecnologias Utilizadas

• PHP 8+
• Illuminate/Database (Eloquent ORM)
• Padrão Repository
• Padrão Service Layer
• PSR-4 Autoloading

📁 Estrutura do Projeto

src/
├── Models/
│   ├── Estrutural/          # Models da estrutura organizacional
│   │   ├── Secretaria.php
│   │   └── Departamento.php
│   └── Intranet/           # Models da intranet municipal
│       ├── Avisos.php
│       ├── Calendario.php
│       ├── Aniversariantes.php
│       ├── Noticias.php
│       ├── Links.php
│       ├── Telefones.php
│       ├── Emails.php
│       ├── Menu.php
│       ├── Submenu.php
│       ├── SubmenuSimples.php
│       ├── Cidade.php
│       └── Estado.php
├── Repositories/
│   ├── RepositoryInterface.php
│   ├── BaseRepository.php
│   ├── Estrutural/
│   │   ├── SecretariaRepository.php
│   │   └── DepartamentoRepository.php
│   └── Intranet/
│       ├── AvisosRepository.php
│       ├── CalendarioRepository.php
│       ├── AniversariantesRepository.php
│       ├── NoticiasRepository.php
│       ├── LinksRepository.php
│       ├── TelefonesRepository.php
│       ├── EmailsRepository.php
│       ├── MenuRepository.php
│       ├── SubmenuRepository.php
│       └── SubmenuSimplesRepository.php
└── Services/
    ├── ServiceInterface.php
    ├── BaseService.php
    ├── Estrutural/
    │   ├── SecretariaService.php
    │   └── DepartamentoService.php
    └── Intranet/
        ├── AvisosService.php
        ├── CalendarioService.php
        ├── AniversariantesService.php
        ├── NoticiasService.php
        ├── LinksService.php
        ├── TelefonesService.php
        ├── EmailsService.php
        ├── MenuService.php
        ├── SubmenuService.php
        └── SubmenuSimplesService.php

🗄️ Models

Estrutural

Secretaria

Campos:

• nome (string, 200 chars) - Nome da secretaria

Relacionamentos:

• departamentos() - hasMany com Departamento
• telefones() - hasMany com Telefones
• emails() - hasMany com Emails

Departamento

Campos:

• nome (string, 200 chars) - Nome do departamento
• secretaria_id (int) - ID da secretaria

Relacionamentos:

• secretaria() - belongsTo com Secretaria
• telefones() - hasMany com Telefones
• emails() - hasMany com Emails

Intranet

Avisos

Campos:

• tipo (string, 1 char) - Tipo do aviso (I=Informativo, A=Alerta, E=Erro, S=Sucesso)
• titulo (string, 200 chars) - Título do aviso
• mensagem (string, 200 chars) - Mensagem do aviso

Calendario

Campos:

• data_evento (date) - Data do evento
• titulo (string, 100 chars) - Título do evento
• subtitulo (string, 200 chars) - Subtítulo do evento

Aniversariantes

Campos:

• data_aniversario (date) - Data de aniversário
• user_id (int) - ID do usuário
• cpf (string, 14 chars) - CPF do aniversariante

Noticias

Campos:

• titulo (string, 200 chars) - Título da notícia
• data_noticia (date) - Data da notícia
• caminho_imagem (string, 200 chars) - Caminho da imagem
• subtitulo (string, 200 chars) - Subtítulo da notícia
• conteudo (text) - Conteúdo da notícia

Links

Campos:

• titulo (string, 200 chars) - Título do link
• link (string, 200 chars) - URL do link
• icone (string, 100 chars) - Ícone do link

Telefones

Campos:

• numero (string, 15 chars) - Número do telefone
• titulo (string, 100 chars) - Título/Descrição
• secretaria_id (int) - ID da secretaria
• departamento_id (int) - ID do departamento

Relacionamentos:

• secretaria() - belongsTo com Secretaria
• departamento() - belongsTo com Departamento

Emails

Campos:

• email (string, 200 chars) - Endereço de email
• titulo (string, 100 chars) - Título/Descrição
• secretaria_id (int) - ID da secretaria
• departamento_id (int) - ID do departamento

Relacionamentos:

• secretaria() - belongsTo com Secretaria
• departamento() - belongsTo com Departamento

Menu

Campos:

• titulo (string, 100 chars) - Título do menu
• icone (string, 100 chars) - Ícone do menu

Relacionamentos:

• submenus() - hasMany com Submenu

Submenu

Campos:

• titulo (string, 100 chars) - Título do submenu
• link (string, 200 chars) - Link do submenu
• menu_id (int) - ID do menu pai

Relacionamentos:

• menu() - belongsTo com Menu

SubmenuSimples

Campos:

• titulo (string, 100 chars) - Título do submenu
• icone (string, 100 chars) - Ícone do submenu
• link (string, 200 chars) - Link do submenu

🗃️ Repositories

Todos os repositories estendem BaseRepository e implementam RepositoryInterface, fornecendo:

Métodos Base

• all() - Buscar todos os registros
• find($id) - Buscar por ID
• create(array $data) - Criar novo registro
• update($id, array $data) - Atualizar registro
• delete($id) - Deletar registro
• paginate($perPage = 15) - Paginação
• findWhere(array $criteria) - Buscar com critérios
• findWhereFirst(array $criteria) - Buscar primeiro com critérios
• count() - Contar total de registros

Métodos Específicos

Cada repository possui métodos específicos para suas necessidades:

SecretariaRepository:

• allWithDepartamentos() - Buscar com departamentos
• findWithDepartamentos($id) - Buscar por ID com departamentos
• findByNome($nome) - Buscar por nome
• countComDepartamentos() - Contar secretarias com departamentos
• countSemDepartamentos() - Contar secretarias sem departamentos

AvisosRepository:

• findByTipo($tipo) - Buscar por tipo
• findByTitulo($titulo) - Buscar por título
• findRecent($limit) - Buscar avisos recentes
• countByTipo($tipo) - Contar por tipo

CalendarioRepository:

• findByData($data) - Buscar eventos por data
• findBetweenDates($inicio, $fim) - Buscar entre datas
• findProximosEventos($limit) - Buscar próximos eventos
• findByMes($ano, $mes) - Buscar por mês

(E muitos outros métodos específicos para cada repository)

🎯 Services

Todos os services estendem BaseService e implementam ServiceInterface, fornecendo:

Métodos Base

• all() - Listar todos
• find($id) - Buscar por ID
• create(array $data) - Criar (com validação)
• update($id, array $data) - Atualizar (com validação)
• delete($id) - Deletar (com validação)
• paginate($perPage = 15) - Paginação
• count() - Contar registros

Validações Implementadas

Cada service possui validações específicas:

• Tamanhos de campos conforme especificação
• Formatos de email e URL
• Validação de CPF (11 dígitos)
• Verificação de relacionamentos
• Prevenção de duplicatas
• Validação de datas e períodos
• Caracteres mínimos/máximos

🚀 Instalação

1. Clone o repositório:

git clone https://github.com/prefeituradeitabuna/pmi_regras_de_negocio.git
cd pmi_regras_de_negocio

1. Instale as dependências:

composer install

1. Configure o autoloader:

{
    "autoload": {
        "psr-4": {
            "Pmi\\RegrasDeNegocio\\": "src/"
        }
    }
}

💡 Uso

Básico

use Pmi\RegrasDeNegocio\Models\Estrutural\Secretaria;
use Pmi\RegrasDeNegocio\Repositories\Estrutural\SecretariaRepository;
use Pmi\RegrasDeNegocio\Services\Estrutural\SecretariaService;

// Instanciar
$model = new Secretaria();
$repository = new SecretariaRepository($model);
$service = new SecretariaService($repository);

// Usar
$secretarias = $service->all();
$secretaria = $service->find(1);
$total = $service->count();

Com Validação

try {
    $novaSecretaria = $service->create([
        'nome' => 'Secretaria de Educação'
    ]);
} catch (\InvalidArgumentException $e) {
    echo "Erro de validação: " . $e->getMessage();
}

📝 Exemplos de Código

Exemplo 1: Gerenciar Secretarias

$secretariaService = new SecretariaService($secretariaRepository);

// Criar nova secretaria
$secretaria = $secretariaService->create([
    'nome' => 'Secretaria de Saúde'
]);

// Buscar secretarias com departamentos
$secretariasCompletas = $secretariaService->allWithDepartamentos();

// Contar secretarias que possuem departamentos
$totalComDepartamentos = $secretariaService->countComDepartamentos();

Exemplo 2: Gerenciar Avisos

$avisosService = new AvisosService($avisosRepository);

// Criar aviso de alerta
$aviso = $avisosService->create([
    'tipo' => 'A',
    'titulo' => 'Manutenção do Sistema',
    'mensagem' => 'O sistema ficará indisponível entre 22h e 02h'
]);

// Buscar avisos por tipo
$alertas = $avisosService->findByTipo('A');

// Contar avisos de cada tipo
$totalAlertas = $avisosService->countByTipo('A');

Exemplo 3: Gerenciar Eventos

$calendarioService = new CalendarioService($calendarioRepository);

// Criar evento
$evento = $calendarioService->create([
    'data_evento' => '2025-09-15',
    'titulo' => 'Reunião Geral',
    'subtitulo' => 'Reunião mensal com todos os secretários'
]);

// Buscar próximos eventos
$proximosEventos = $calendarioService->getProximosEventos(5);

// Buscar eventos do mês atual
$eventosDoMes = $calendarioService->findByMes(2025, 9);

Exemplo 4: Gerenciar Aniversariantes

$aniversariantesService = new AniversariantesService($aniversariantesRepository);

// Buscar aniversariantes de hoje
$aniversariantesHoje = $aniversariantesService->getAniversariantesDoDia();

// Buscar aniversariantes do mês
$aniversariantesDoMes = $aniversariantesService->getAniversariantesDoMes();

// Contar aniversariantes de hoje
$totalHoje = $aniversariantesService->countAniversariantesDoDia();

🔧 Funcionalidades Implementadas

✅ Repositories

• CRUD completo para todos os models
• Paginação automática
• Busca com critérios personalizados
• Relacionamentos Eloquent
• Métodos específicos para cada entidade
• Contagem de registros

✅ Services

• Validações robustas de dados
• Regras de negócio específicas
• Verificação de relacionamentos
• Tratamento de exceções
• Métodos de busca avançada
• Contagem com validações

✅ Validações

• Tamanhos de campos
• Formatos de email e URL
• Validação de CPF
• Verificação de existência
• Prevenção de duplicatas
• Validação de datas

🤝 Contribuição

1. Fork o projeto
2. Crie uma branch para sua feature (git checkout -b feature/AmazingFeature)
3. Commit suas mudanças (git commit -m 'Add some AmazingFeature')
4. Push para a branch (git push origin feature/AmazingFeature)
5. Abra um Pull Request

📄 Licença

Este projeto é propriedade da Prefeitura Municipal de Itabuna.

📞 Contato

Prefeitura Municipal de Itabuna - Site Oficial

Link do Projeto: https://github.com/prefeituradeitabuna/pmi_regras_de_negocio