# 02 — Arquitetura do Sistema

## Diagrama de Arquitetura Geral

```
┌──────────────────────────────────────────────────────────────────┐
│                      CLIENTES (Devices)                          │
│                                                                  │
│   ┌──────────────────────┐   ┌──────────────────────────────┐   │
│   │   iOS App (Expo Go  │   │  Android App (Expo Go / APK) │   │
│   │   / IPA Build)      │   │                              │   │
│   └──────────┬───────────┘   └──────────────┬───────────────┘   │
└──────────────┼──────────────────────────────┼────────────────────┘
               │ HTTP REST (JSON)              │
               ▼                              ▼
┌──────────────────────────────────────────────────────────────────┐
│              DigitalOcean VPS: 157.245.10.199                    │
│                                                                  │
│  ┌─────────────────────────────────────────────────────────┐     │
│  │                Apache Web Server                        │     │
│  │  /webapp/api/*.php   ←── All REST endpoints             │     │
│  └────────────────────────┬────────────────────────────────┘     │
│                           │                                      │
│    ┌──────────────────────┼──────────────────────────────────┐   │
│    │                  MySQL Server                           │   │
│    │                                                         │   │
│    │  antigravity_master   antigravity_dev   antigravity_X   │   │
│    │  ├ clientes           ├ demanda          ├ demanda       │   │
│    │  ├ usuarios_globais   ├ tarefa           ├ tarefa        │   │
│    │  └ usuario_cliente    └ usuario          └ usuario       │   │
│    └─────────────────────────────────────────────────────────┘   │
└──────────────────────────────────────────────────────────────────┘
                           │
                           │ Cloud APIs
                    ┌──────┴─────────────────┐
                    │ Google Cloud Storage   │  ← Anexos/Attachments
                    │ Expo Push API          │  ← Push Notifications
                    └────────────────────────┘
```

---

## Arquitetura Multi-Tenant

### Conceito
Cada cliente (empresa/organização) tem seu **banco de dados MySQL separado**. O servidor compartilha a mesma instância PHP, mas os dados são completamente isolados.

### Fluxo de Resolução de Tenant

```
Request HTTP
    │
    ├── Parâmetro 'cliente' via GET/POST/JSON body
    │       Ex: ?cliente=dev  ou  { "cliente": "bpoconsig" }
    │
    ▼
init_client.php
    │
    ├── 1. Extrai código do cliente → 'dev'
    ├── 2. Carrega webapp/Parametros/{cliente}/parametros.php
    │       Define: $banco_de_dados, $db_user, $db_pass, $db_host
    ├── 3. Inclui funcoes_comum.php e comunicacaoBD.php
    │       Abre conexão MySQL → armazena em $_SESSION['S_conn']
    └── 4. Endpoint PHP usa $_SESSION['S_conn'] para todas as queries
```

### Arquivo parametros.php
Localizado em `webapp/Parametros/{codigo_cliente}/parametros.php`.

**Conteúdo típico:**
```php
<?php
$banco_de_dados = 'antigravity_dev';
$S_servidor     = 'localhost';
$S_login        = 'root';
$S_senha        = 'senha_do_banco';
```

### Master Database (antigravity_master)
Gerencia usuários globais e a relação entre usuários e clientes.

```
antigravity_master
├── clientes          → Registro de cada tenant (id, codigo, nome, ativo)
├── usuarios_globais  → Usuários únicos por email (login multi-tenant)
└── usuario_cliente   → Relação N:N entre usuário global e tenant
```

---

## Fluxo de Autenticação

```
App → POST /pre_login.php (email + senha)
    │
    ├── Busca em usuarios_globais WHERE email + senha_hash
    ├── Busca clientes associados via usuario_cliente JOIN clientes
    │
    ├── [1 cliente]  → { action: "direct_login", cliente: {...} }
    └── [N clientes] → { action: "select_client", clientes: [...] }

App → POST /login.php (usuario_global_id + cliente_codigo)
    │
    ├── Busca usuario local no BD do cliente (usuario_id local)
    ├── Retorna: user{ usuario_id, nome, cargo, divisao_id, admin, ... }
    └── App armazena em MenuContext + navega para Dashboard
```

---

## Hierarquia Organizacional

O sistema implementa uma estrutura de 4 níveis hierárquicos, configuráveis por cliente via tabela `constantes`:

```
estrutura_gerencial_4 (cargo=4)
    └── diretoria (cargo=3)
          └── coordenacao (cargo=2)
                └── divisao (cargo=1 ou cargo=0)
                      └── usuario (cargo=0 = executor)
```

### Campo `cargo` na tabela `usuario`

| Valor | Papel | Responsabilidades |
|-------|-------|-------------------|
| `0` | Executor / Colaborador | Executa tarefas; vê revisões do N1 sobre suas tarefas |
| `1` | Gestor Nível 1 | Revisa em NIVEL_ESTRUTURA1; pode distribuir tarefas na divisão |
| `2` | Gestor Nível 2 | Revisa em NIVEL_ESTRUTURA2 |
| `3` | Gestor Nível 3 | Revisa em NIVEL_ESTRUTURA3 |
| `4` | Gestor Nível 4 | Revisa em NIVEL_ESTRUTURA4 |

### Nomes de Nível (Configurável)
Na tabela `constantes`, o campo `niveis_estrutura` armazena os nomes separados por vírgula:
```
Ex: "Divisão,Coordenação,Diretoria,Presidência"
          ↑N1        ↑N2       ↑N3        ↑N4
```

Os placeholders `#NIVEL_ESTRUTURA1#` a `#NIVEL_ESTRUTURA4#` nos status de tarefa são substituídos em tempo real pelos nomes configurados.

---

## Fluxo de Dados — Ciclo de Vida de uma Tarefa

```
1. Criação
   CreateTaskScreen → POST task_actions.php (create_task)
   → INSERT tarefa (status=1 "Não Iniciada")
   → INSERT tarefa_historico
   → sendPushNotification to usuariodemandado_id OR divisao

2. Execução
   TaskDetailsScreen → POST task_actions.php (update_task_status)
   → UPDATE tarefa SET tarefa_status_id = 2 ("Iniciada")
   → INSERT tarefa_historico

3. Submissão para Revisão (cargo 0 → cargo 1)
   → UPDATE tarefa_status_id = 3 ("Em análise - N1")
   → INSERT tarefa_historico
   → Push notification para cargo=1 que é recurso do projeto

4. Aprovação (cargo 1)
   → UPDATE tarefa_status_id = 4 ("Analisada - N1")
   → Push notification para cargo=0 (executor original)

5. Escalada para N2 (se necessário)
   → UPDATE tarefa_status_id = 5 ("Em análise - N2")
   → Push notification para cargo=2

...e assim por diante até Concluída (status_id=7)
```

---

## Fluxo de Arquivos (GCS)

```
App seleciona arquivo
    │
    ├── POST multipart/form-data → upload_attachment.php
    │       (ou upload_project_attachment.php / upload_cost_attachment.php)
    │
    ├── PHP faz upload para GCS
    │       Bucket: webgruppo-attachments
    │       Path: {cliente}/tarefas/{tarefa_id}/{timestamp}_{filename}
    │
    ├── Grava path no BD (tarefa_anexo.gcs_path)
    │
    └── Download via download_attachment.php
            → Gera URL Signed (válida 15 min) via GCS SDK
            → Redireciona app para download seguro
```

---

## Comunicação App ↔ Backend

### Padrão de Request
- **GET**: Queries de leitura (parâmetros via query string)
- **POST**: Mutações (parâmetros via `application/json` body ou `multipart/form-data` para uploads)
- **Autenticação**: Sem JWT. Usa `user_id` + `cliente` em cada request (stateless)
- **CORS**: `Access-Control-Allow-Origin: *` em todos os endpoints

### Padrão de Response
```json
{
  "success": true | false,
  "message": "Descrição opcional do resultado",
  "data": { ... } // Payload específico do endpoint
}
```

### Parâmetro Obrigatório Universal
Todos os endpoints requerem `cliente` (código do tenant). Enviado como:
- Query string: `?cliente=dev&user_id=5`
- JSON body: `{ "cliente": "dev", "action": "create_task", ... }`