# 06 — Módulos e Funcionalidades de Negócio

## 1. Módulo de Projetos

### Conceito
Um **Projeto** (`demanda`) é o contêiner principal de trabalho. Agrupa tarefas, equipe, custos, documentos e comentários.

### Ciclo de Vida
```
Planejada → Ativa → (Pausada) → Concluída
                  ↘ Cancelada
                  ↘ Aguarda Registro de Resultados
```

### Quem pode criar projetos?
Qualquer usuário com acesso ao botão "Criar Projeto" no menu — sem restrição de cargo.

### Divisão do Projeto
- Todo projeto tem uma `divisao_id`
- Ao atribuir uma divisão, o sistema auto-adiciona à equipe os usuários da divisão com `cargo` correspondente ao nível estrutural da divisão (via `niveis_estrutura` + sigla da divisão)

### Funcionalidades por Aba (ProjectDetailsScreen)

| Aba | Funcionalidade |
|-----|----------------|
| Visão Geral | Título, resumo, status, progresso, NUP, OS, orçamento, datas, tema, divisão |
| Tarefas | Lista de tarefas com status_color; criar nova tarefa; navegar para TaskDetails |
| Equipe | Lista de membros; adicionar/remover usuários |
| Custos | Lista de custos com status de aprovação; adicionar custo com categoria e centro de custo; aprovar/reprovar por alçada |
| Anexos | Upload de arquivos para GCS; download via URL assinada |
| Links | Adicionar/remover links externos |
| Notas | Comentários colaborativos com autor e data |
| Gantt | Gráfico de barras proporcional por tarefa, exportável como PDF |

### Gantt Chart
- Renderizado com `react-native-svg`
- Capturado com `react-native-view-shot`
- Exportado via `expo-print` (PDF) e `expo-sharing` (compartilhar)
- Barras coloridas por status de tarefa
- Timeline calculada entre menor `data_inicio` e maior `prazo` do projeto

---

## 2. Módulo de Tarefas

### Conceito
Uma **Tarefa** (`tarefa`) é a unidade atômica de trabalho dentro de um projeto. É atribuída a um responsável único e segue um fluxo de revisão por níveis hierárquicos.

### Campo `distribuicao`
- `distribuicao = 0`: Tarefa atribuída diretamente a `usuariodemandado_id`
- `distribuicao = 1`: Tarefa aguarda ser distribuída por alguém na `distribuicao_divisao_id`

Tarefas em distribuição aparecem no card **INBOX** do dashboard, para usuários com `cargo ≥ 1` da divisão alvo.

### Fluxo Completo de Status

```
1 (Não Iniciada) 
    ↓ 
2 (Iniciada) 
    ↓
3 (Em análise - N1) → notifica cargo=1 do projeto
    ↓
4 (Analisada - N1)  → notifica cargo=0 do projeto
    ↓ (se projeto tem N2+)
5 (Em análise - N2) → notifica cargo=2
    ↓
6 (Analisada - N2)  → notifica cargo=1
    ↓ (se projeto tem N3+)
11 (Em análise - N3) → notifica cargo=3
    ↓
13 (Analisada - N3)  → notifica cargo=2
    ↓ (se projeto tem N4)
14 (Em análise - N4) → notifica cargo=4
    ↓
15 (Analisada - N4)  → notifica cargo=3
    ↓
7 (Concluída)

Status paralelos (a qualquer momento):
  9  = Suspensa
  10 = Aguardando Providência Externa
  8  = Cancelada
```

### Afazeres (tarefa_todo)
- Sub-itens de uma tarefa
- Cada afazer tem um responsável (`usuario_id`)
- Status: 1=pendente, 2=concluído (toggle)
- Ordenáveis manualmente (campo `ordem`)
- Têm campo de observação livre
- Criar afazer para outro usuário → push notification para o destinatário

### Providências
Histórico textual de atualizações sobre a tarefa (o que foi feito, observações). Imutáveis: não podem ser editadas, só deletadas.

### Ciência de Conclusão
Quando uma tarefa é concluída, o sistema registra em `tarefa_conclusao` quais usuários precisam tomar ciência. Esta ciência aparece na contagem do card **CONCLUÍDOS** no dashboard.

---

## 3. Módulo de Demandas Rápidas

### Conceito
Uma **Demanda Rápida** (`tarefarapida`) é uma tarefa simples e direta entre dois usuários, sem necessidade de um projeto. Funciona como uma "mensagem com prazo".

### Características
- Sem projeto pai
- Um criador (`usuario_id`) e um destinatário (`usuariodemandado_id`)
- Prioridades: 1=Baixa, 2=Média, 3=Alta
- `visibilidade = 0` para demandas próprias; `1` para delegadas
- Tem providências, links e anexos, mas sem fluxo de revisão hierárquica

### Ciclo de Vida
```
Ativa (1) → Concluída (2)
           ↘ Cancelada (3)  →  Reativada → Ativa (1)
```

### Cards no DemandListScreen
1. **A Fazer** — demandas onde sou `usuariodemandado_id` e status=Ativa
2. **Por Mim** — demandas onde sou `usuario_id` (criador) e deleguei
3. **Concluídas** — demandas fechadas relacionadas a mim

---

## 4. Módulo de Custos

### Conceito
Permite registrar e aprovar custos dentro de um projeto, com controle por alçada (cargo mínimo para aprovar, com limite de valor).

### Campos de um Custo
- `categoria_custo_id` → Categoria do custo
- `centro_custo_id` → Centro de custo contábil
- `valor` → Valor monetário (DECIMAL)
- `observacao` → Justificativa
- `beneficiario_id` → Usuário beneficiado
- `necessita_aprovacao` = 1 → Requer aprovação manual

### Fluxo de Aprovação
```
Custo registrado
    │
    ├── necessita_aprovacao = 0 → Aprovado automaticamente
    │
    └── necessita_aprovacao = 1
            │
            → INSERT autoriza_custo (status=0 pendente)
            → Aparece no card CUSTOS do dashboard para gestores com alçada
            │
            ├── Aprovado (status=1) → custo aprovado
            └── Reprovado (status=2) → custo reprovado com observação
```

### Alçada (alcada_custo)
Define qual `cargo` pode aprovar qual `categoria_custo_id`, com `limite` de valor.

---

## 5. Módulo de Busca Global

### Comportamento
- Busca simultânea em projetos, tarefas e demandas
- Suporta busca parcial (`%termo%`) e busca exata (`"entre aspas"`)
- Limita a 20 resultados por tipo
- Resultados divididos em 3 abas na `SearchResultsScreen`

### Campos pesquisados
| Tipo | Campos |
|------|--------|
| Projetos | `demanda.descricao`, `demanda.resumo` |
| Tarefas | `tarefa.descricao` |
| Demandas | `tarefarapida.descricao` |

---

## 6. Módulo de Aprovação de Ciência

### Conceito
Quando um projeto ou tarefa é concluído, os usuários relacionados precisam **tomar ciência** do resultado. Isso é registrado em `tarefa_conclusao` / `demanda_conclusao`.

### No Dashboard
Card **CONCLUÍDOS** exibe a contagem de itens pendentes de ciência para o usuário logado.

### Na `CostApprovalScreen`
- Exibe custos aguardando aprovação para o cargo do usuário
- Permite aprovar/reprovar com observação

---

## 7. Módulo de Configurações (Admin Only)

Acessível apenas por usuários com `admin = 1`.

### Constantes do Sistema
Controla o comportamento global via tabela `constantes`:
- **Nomenclaturas de cargo** (ex: "Executor", "Supervisor", "Coordenador")
- **Nomes dos níveis estruturais** (ex: "Divisão", "Coordenação", "Diretoria", "Presidência")
- **a_vencer**: dias antes do prazo para alertar em amarelo
- **habilita_sgf**: ativa/desativa módulo de SGF

### Estruturas Organizacionais
CRUD completo para todos os 4 níveis: divisão → coordenação → diretoria → estrutura_gerencial_4.

### Usuários
- Cria/edita usuários locais
- Sincroniza automaticamente com `antigravity_master`
- Ao criar: INSERT em `usuarios_globais` + INSERT em `usuario_cliente`
- Ao editar senha: UPDATE em `usuarios_globais.senha_hash`

### Temas de Projeto
Categorização de projetos (ex: "TI", "RH", "Financeiro").

### Categorias de Custo + Alçadas
CRUD de categorias + definição de quais cargos podem aprovar e até qual valor.

### Centros de Custo
CRUD de centros de custo contábeis.