sgmp/README.md

## 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
```