From 542b9d03ca9296faddd8de99b57f051fa9047de3 Mon Sep 17 00:00:00 2001 From: Felipe Araujo Date: Mon, 9 Mar 2026 15:59:08 -0300 Subject: [PATCH] Documenta arquitetura atual e ajustes de perfis/head --- README.md | 176 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 176 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..ecf34e8 --- /dev/null +++ b/README.md @@ -0,0 +1,176 @@ +## SGMP_PROD – Sistema de Gestão de Movimentações de Pessoas + +### Visão geral + +O **SGMP_PROD** é um sistema interno para gestão de processos de pessoas, hoje focado em: + +- Desligamentos +- Admissões (substituição e aumento de quadro) +- Movimentações internas + +Cada processo é representado por uma `Solicitacao` que percorre um fluxo controlado de aprovação, com rastreabilidade completa (status, aprovações, pareceres técnicos e anexos). + +O projeto em produção é um monólito **Django** com renderização server-side e uso de **Tailwind CSS** para o layout das telas principais. + +--- + +### Stack técnica + +- **Linguagem**: Python 3.9 +- **Framework web**: Django 4.2 +- **Banco de dados aplicação**: SQLite (desenvolvimento) / compatível com outros bancos suportados pelo Django +- **Integrações externas**: + - **TOTVS RM (SQL Server)** – dados de colaboradores, cargos, seções, coligadas/filiais. + - **Winthor (Oracle)** – autenticação e dados básicos de usuários. +- **Frontend**: + - Templates Django + - Tailwind CSS via CDN (`base.html` e `dashboard.html`) + - JavaScript vanilla para interações pontuais (modal de aprovação, filtros, expansão de linhas). +- **Empacotamento / Deploy**: + - Docker (`Dockerfile` e `entrypoint.sh`) + - Servidor de aplicação: `gunicorn` + +Principal app Django: + +- `solicitacoes/` – contém: + - `models.py`: modelos de domínio (`UsuarioSistema`, `UsuarioPerfilExtra`, `HeadGestor`, `PessoaRM`, `Solicitacao`, `Desligamento`, `AdmissaoSubstituicao`, `AdmissaoAumentoQuadro`, `Movimentacao`, `Aprovacao`, `Parecer`, enums de status/etapas). + - `services.py`: regras de negócio transacionais (envio de solicitação, aprovação por Head/Diretoria, registro de parecer, etc.). + - `views.py`: orquestração HTTP, dashboard, criação de solicitações, decisão, parecer, gerenciamento de permissões. + - `templates/`: telas do dashboard, detalhe da solicitação e formulários. + +--- + +### Fluxo de aprovação (resumo) + +1. **GESTOR** cria uma `Solicitacao` (desligamento, admissão ou movimentação). +2. Solicitação começa em **`RASCUNHO`**. +3. GESTOR envia → status muda para **`AGUARDANDO_HEAD`** (quando há etapa de Head configurada) ou **`ENVIADA`**, conforme o tipo/regra. +4. **HEAD** (usuário com perfil principal ou extra `HEAD`) aprova/reprova solicitações em `AGUARDANDO_HEAD`, limitado aos gestores aos quais está vinculado (`HeadGestor`). +5. Após a etapa de Head, a solicitação segue para **`ENVIADA`**: + - **GG** e **CONTROLADORIA** registram **pareceres técnicos** (`Parecer`) – não mudam o status diretamente. + - Quando há parecer de GG e de Controladoria, o status avança para **`AGUARDANDO_DIRETORIA`**. +6. **DIRETORIA** aprova ou reprova solicitações em `AGUARDANDO_DIRETORIA`: + - Aprovada → **`FINALIZADA`** + - Reprovada em qualquer etapa → **`REPROVADA`** + +Regras principais: + +- `Solicitacao.etapa_atual()` mapeia o status para a etapa de aprovação. +- `Solicitacao.pode_aprovar(usuario)` centraliza a regra de quem pode aprovar na etapa atual (HEAD ou DIRETORIA, considerando perfis extras). +- `Solicitacao.pode_dar_parecer(usuario)` define se GG / Controladoria podem registrar parecer na etapa `ENVIADA`. + +Mais detalhes de arquitetura estão em [`ARQUITETURA_APROVACAO.md`](./ARQUITETURA_APROVACAO.md). + +--- + +### Perfis, multi-perfis e relação Head–Gestor + +- `UsuarioSistema` possui: + - `perfil` – **perfil principal** (GESTOR, HEAD, GG, CONTROLADORIA, DIRETORIA). + - `UsuarioPerfilExtra` – tabela de **perfis adicionais** (multi-perfis). + - Métodos: + - `tem_perfil(perfil)` – verifica se o usuário possui o perfil principal ou extra. + - `perfis_ativos()` – lista todos os perfis do usuário (principal + extras). + +- `HeadGestor` modela a relação **Head → Gestores**: + - Campos: `head`, `gestor` (FK para `UsuarioSistema`). + - Cada Head só vê/aprova solicitações de gestores vinculados nessa tabela. + - A tela `/permissoes/` permite configurar, manualmente, quais gestores cada Head lidera. + +Documentação detalhada de login, perfis e permissões: [`README_PERMISSOES.md`](./README_PERMISSOES.md). +Histórico e decisões sobre a relação Head–Gestor: [`docs/head_relacao_gestor_investigacao.md`](./docs/head_relacao_gestor_investigacao.md). + +--- + +### Como rodar localmente (sem Docker) + +Pré-requisitos: + +- Python 3.9 +- Acesso opcional aos bancos RM/Winthor (para full integração); sem eles, é possível rodar com dados mínimos locais. + +Passos: + +1. Clonar o repositório: + ```bash + git clone https://git.jurunense.com/felipe.araujo/sgmp.git + cd sgmp/SGMP_PROD + ``` + +2. Criar e ativar o ambiente virtual: + ```bash + python -m venv .venv + source .venv/bin/activate # Windows: .venv\\Scripts\\activate + ``` + +3. Instalar dependências: + ```bash + pip install --upgrade pip + pip install -r requirements.txt + ``` + +4. Aplicar migrações: + ```bash + python manage.py migrate + ``` + +5. Criar usuário admin (opcional, para acesso a `/admin/`): + ```bash + python manage.py createsuperuser + ``` + +6. Rodar o servidor de desenvolvimento: + ```bash + python manage.py runserver + ``` + +7. Acessar: + - Página de login: `http://localhost:8000/login/` + - Dashboard: `http://localhost:8000/` + - Admin Django: `http://localhost:8000/admin/` + +> Observação: em desenvolvimento, integrações com RM/Winthor podem exigir configuração de variáveis de ambiente (host, porta, usuário, senha, etc.) conforme `SQLSERVER_CONFIG` e credenciais Oracle definidas no projeto. + +--- + +### Como rodar com Docker + +O projeto possui um `Dockerfile` voltado para produção (`gunicorn`), incluindo instalação do Oracle Instant Client para integração com Winthor. + +Exemplo simples de build e run: + +```bash +cd SGMP_PROD + +docker build -t sgmp_prod . + +docker run --rm -p 8000:8000 \ + --env-file .env \\ + sgmp_prod +``` + +O `entrypoint.sh` executa migrações e `collectstatic` antes de iniciar o `gunicorn`. + +--- + +### Estrutura de diretórios (resumo) + +```text +SGMP_PROD/ + config/ # settings Django, urls, wsgi + solicitacoes/ # app principal de domínio + models.py # modelos de domínio + services.py # regras de negócio + views.py # views / endpoints + templates/ # templates HTML (base, dashboard, solicitação_detalhe, formulários) + migrations/ # migrations do Django + templates/ # templates globais (base.html, dashboard.html, etc.) + static/ # assets estáticos de desenvolvimento (se houver) + ARQUITETURA_APROVACAO.md + README_PERMISSOES.md + docs/head_relacao_gestor_investigacao.md + Dockerfile + entrypoint.sh + requirements.txt +``` +