# SteelBook - Arquitetura Técnica Completa

## 📋 Índice
1. [Visão Geral](#visão-geral)
2. [Arquitetura do Sistema](#arquitetura-do-sistema)
3. [Banco de Dados](#banco-de-dados)
4. [Fluxo de Dados](#fluxo-de-dados)
5. [Componentes Principais](#componentes-principais)
6. [Autenticação e Segurança](#autenticação-e-segurança)

---

## Visão Geral

**SteelBook** é uma aplicação web moderna para gerenciamento de Databooks técnicos. Permite criar, organizar e gerar documentação completa com suporte a múltiplos formatos, categorização inteligente e integração com IA.

**Stack Tecnológico:**
- **Frontend:** React 18 + TypeScript + Vite
- **Styling:** Tailwind CSS
- **Backend:** Supabase (PostgreSQL + Auth)
- **State Management:** TanStack Query (React Query)
- **UI Components:** Lucide Icons

---

## Arquitetura do Sistema

```
┌─────────────────────────────────────────────────────────────┐
│                     FRONTEND (React)                         │
│  ┌──────────────────────────────────────────────────────┐   │
│  │  Pages: Dashboard, DatabookView, Templates, etc.     │   │
│  │  Components: Modal, Button, Input, LoadingSpinner    │   │
│  │  Hooks: useQuery, useMutation (TanStack Query)       │   │
│  └──────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────┐
│                    SUPABASE (Backend)                        │
│  ┌──────────────────────────────────────────────────────┐   │
│  │  PostgreSQL Database                                 │   │
│  │  - Tabelas de Dados                                  │   │
│  │  - Row Level Security (RLS)                          │   │
│  │  - Triggers e Functions                              │   │
│  └──────────────────────────────────────────────────────┘   │
│  ┌──────────────────────────────────────────────────────┐   │
│  │  Authentication (JWT)                                │   │
│  │  - Email/Password                                    │   │
│  │  - Session Management                                │   │
│  └──────────────────────────────────────────────────────┘   │
│  ┌──────────────────────────────────────────────────────┐   │
│  │  Storage (Bucket)                                    │   │
│  │  - Documentos (PDF, Imagens)                         │   │
│  │  - Logos e Marca d'água                              │   │
│  └──────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘
```

---

## Banco de Dados

### Tabelas Principais

#### 1. **usuarios**
Gerencia usuários do sistema com diferentes perfis.

```sql
CREATE TABLE usuarios (
    id UUID PRIMARY KEY,
    email VARCHAR(255) UNIQUE NOT NULL,
    nome_completo VARCHAR(255) NOT NULL,
    perfil VARCHAR(50) -- 'admin', 'gerente_qualidade', 'engenheiro', 'cliente'
    ativo BOOLEAN DEFAULT TRUE,
    created_at TIMESTAMP DEFAULT NOW()
);
```

**Perfis:**
- `admin`: Acesso total ao sistema
- `gerente_qualidade`: Gerencia qualidade e aprovações
- `engenheiro`: Cria e edita databooks
- `cliente`: Visualiza apenas seus projetos

---

#### 2. **clientes**
Informações dos clientes/empresas.

```sql
CREATE TABLE clientes (
    id UUID PRIMARY KEY,
    nome VARCHAR(255) NOT NULL,
    contato VARCHAR(255),
    email VARCHAR(255),
    telefone VARCHAR(20),
    ativo BOOLEAN DEFAULT TRUE,
    created_at TIMESTAMP DEFAULT NOW()
);
```

---

#### 3. **templates_topicos**
Tópicos padrão que compõem um databook.

```sql
CREATE TABLE templates_topicos (
    id UUID PRIMARY KEY,
    numero_topico VARCHAR(20) NOT NULL,      -- Ex: "1", "1.1", "2.3"
    titulo VARCHAR(255) NOT NULL,
    descricao TEXT,
    obrigatorio BOOLEAN DEFAULT FALSE,
    ordem INTEGER,
    tipo_documentos TEXT[],                  -- ['pdf', 'jpg', 'png']
    tags_padrao TEXT[],
    categoria VARCHAR(100),                  -- Referência à categoria
    created_at TIMESTAMP DEFAULT NOW()
);
```

**Hierarquia de Tópicos:**
- Nível 1: `1`, `2`, `3` (tópicos principais)
- Nível 2: `1.1`, `1.2`, `2.1` (subtópicos)
- Nível 3: `1.1.1`, `1.1.2` (sub-subtópicos)

---

#### 4. **templates_customizados**
Templates personalizados criados a partir dos tópicos padrão.

```sql
CREATE TABLE templates_customizados (
    id UUID PRIMARY KEY,
    nome VARCHAR(255) UNIQUE NOT NULL,
    tipo VARCHAR(50) -- 'novo' ou 'derivado'
    template_pai_id UUID REFERENCES templates_customizados(id),
    topicos_selecionados TEXT[],             -- IDs dos tópicos
    total_topicos INTEGER,
    total_obrigatorios INTEGER,
    descricao TEXT,
    ativo BOOLEAN DEFAULT TRUE,
    criado_por UUID REFERENCES usuarios(id),
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW()
);
```

---

#### 5. **projetos**
Projetos/Databooks em desenvolvimento.

```sql
CREATE TABLE projetos (
    id UUID PRIMARY KEY,
    numero_projeto VARCHAR(100) UNIQUE NOT NULL,
    nome_projeto VARCHAR(255) NOT NULL,
    cliente_id UUID REFERENCES clientes(id),
    template_id UUID REFERENCES templates_customizados(id),
    status VARCHAR(50) -- 'rascunho', 'em_andamento', 'revisao', 'finalizado'
    progresso_percentual INTEGER DEFAULT 0,  -- Calculado automaticamente
    data_inicio DATE,
    data_entrega_prevista DATE,
    responsavel_id UUID REFERENCES usuarios(id),
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW()
);
```

**Status do Projeto:**
- `rascunho`: Criado mas não iniciado
- `em_andamento`: Documentos sendo adicionados
- `revisao`: Aguardando aprovação
- `finalizado`: Databook gerado e entregue

---

#### 6. **databooks_mestres**
Configurações e metadados do databook final.

```sql
CREATE TABLE databooks_mestres (
    id UUID PRIMARY KEY,
    projeto_id UUID NOT NULL REFERENCES projetos(id),
    cliente_nome VARCHAR(255),
    cliente_contato VARCHAR(255),
    cliente_email VARCHAR(255),
    cliente_telefone VARCHAR(20),
    produto_nome VARCHAR(255) NOT NULL,
    produto_tipo VARCHAR(100),
    produto_descricao TEXT,
    produto_normas TEXT[],
    numero_projeto VARCHAR(100),
    ordem_compra VARCHAR(100),
    data_inicio DATE,
    data_entrega_prevista DATE,
    responsavel_id UUID,
    revisao_numero VARCHAR(20) DEFAULT 'Rev. 0',
    revisao_data TIMESTAMP DEFAULT NOW(),
    revisao_autor_id UUID,
    revisao_motivo TEXT,
    logo_empresa_url TEXT,
    logo_cliente_url TEXT,
    marca_agua_url TEXT,
    cor_primaria VARCHAR(7),                 -- Hex color
    cor_secundaria VARCHAR(7),
    titulo_principal VARCHAR(255),
    subtitulo VARCHAR(255),
    texto_rodape_capa TEXT,
    tamanho_pagina VARCHAR(20) -- 'A4' ou 'Letter'
    orientacao VARCHAR(20) -- 'retrato' ou 'paisagem'
    margem_superior_mm NUMERIC(5,2) DEFAULT 20,
    margem_lateral_mm NUMERIC(5,2) DEFAULT 20,
    incluir_marca_agua BOOLEAN DEFAULT TRUE,
    incluir_numero_pagina BOOLEAN DEFAULT TRUE,
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW()
);
```

---

#### 7. **secoes_databook**
Seções do databook (uma por tópico).

```sql
CREATE TABLE secoes_databook (
    id UUID PRIMARY KEY,
    projeto_id UUID NOT NULL REFERENCES projetos(id),
    topico_id UUID REFERENCES templates_topicos(id),
    numero_secao VARCHAR(20) NOT NULL,       -- Ex: "1", "1.1"
    titulo VARCHAR(255) NOT NULL,
    ordem INTEGER,
    status VARCHAR(50) -- 'completo', 'incompleto', 'nao_aplicavel'
    total_documentos INTEGER DEFAULT 0,
    created_at TIMESTAMP DEFAULT NOW()
);
```

---

#### 8. **documentos_auto_indexados**
Documentos carregados em cada seção.

```sql
CREATE TABLE documentos_auto_indexados (
    id UUID PRIMARY KEY,
    databook_id UUID NOT NULL REFERENCES projetos(id),
    secao_id UUID REFERENCES secoes_databook(id),
    secao_numero VARCHAR(20),
    titulo VARCHAR(255) NOT NULL,
    numero_documento VARCHAR(100),
    revisao VARCHAR(20),
    arquivo_url TEXT NOT NULL,               -- URL do Supabase Storage
    arquivo_tipo VARCHAR(50),                -- 'pdf', 'jpg', 'png'
    conteudo_texto TEXT,                     -- Texto extraído (OCR)
    tags_automaticas TEXT[],                 -- Geradas por IA
    tags_usuario TEXT[],                     -- Adicionadas manualmente
    relevancia_score NUMERIC(3,2),           -- 0.00 a 1.00
    confianca_classificacao NUMERIC(3,2),
    ordem_na_secao INTEGER,
    data_documento DATE,
    aprovado BOOLEAN DEFAULT FALSE,
    processado_por_ia VARCHAR(50),           -- 'openai', 'claude', etc
    processado_em TIMESTAMP,
    criado_em TIMESTAMP DEFAULT NOW()
);
```

---

#### 9. **categorias**
Categorias para organizar tópicos e documentos.

```sql
CREATE TABLE categorias (
    id UUID PRIMARY KEY,
    nome VARCHAR(100) UNIQUE NOT NULL,
    descricao TEXT,
    cor VARCHAR(7) DEFAULT '#3B82F6',        -- Hex color
    icone VARCHAR(50),
    ativo BOOLEAN DEFAULT TRUE,
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW()
);
```

**Categorias Padrão:**
- Certificados (#10B981 - Verde)
- Desenhos (#3B82F6 - Azul)
- Relatórios (#F59E0B - Laranja)
- Procedimentos (#8B5CF6 - Roxo)
- Normas (#EF4444 - Vermelho)

---

#### 10. **configuracoes_pastas**
Mapeamento de pastas locais/nuvem para sincronização.

```sql
CREATE TABLE configuracoes_pastas (
    id UUID PRIMARY KEY,
    tipo_documento VARCHAR(100) NOT NULL,
    caminho_local TEXT NOT NULL,
    caminho_subtipo VARCHAR(100),
    caminho_completo TEXT,
    categoria_id UUID REFERENCES categorias(id),
    habilitado BOOLEAN DEFAULT TRUE,
    frequencia_atualizacao VARCHAR(50) -- 'manual', 'ao_criar', 'diario', 'semanal'
    ultima_atualizacao TIMESTAMP,
    incluir_subpastas BOOLEAN DEFAULT TRUE,
    formatos_aceitos TEXT[],
    tamanho_maximo_mb INTEGER DEFAULT 50,
    tags_obrigatorias TEXT[],
    palavras_chave_filtro TEXT[],
    palavras_chave_excluir TEXT[],
    ordem_docs VARCHAR(50) -- 'data', 'nome', 'relevancia'
    criado_por UUID REFERENCES usuarios(id),
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW()
);
```

---

#### 11. **integracao_ia**
Configurações de provedores de IA.

```sql
CREATE TABLE integracao_ia (
    id UUID PRIMARY KEY,
    provider VARCHAR(50) -- 'openai', 'claude', 'gemini'
    api_key_encriptada TEXT NOT NULL,
    modelo_padrao VARCHAR(100),
    maximo_tokens INTEGER DEFAULT 2000,
    ativo BOOLEAN DEFAULT FALSE,
    testado_em TIMESTAMP,
    teste_status VARCHAR(50),
    teste_mensagem TEXT,
    criado_por UUID REFERENCES usuarios(id),
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW()
);
```

---

#### 12. **log_processamento_ia**
Histórico de processamentos com IA.

```sql
CREATE TABLE log_processamento_ia (
    id UUID PRIMARY KEY,
    databook_id UUID NOT NULL REFERENCES projetos(id),
    inicio_processamento TIMESTAMP,
    fim_processamento TIMESTAMP,
    duracao_segundos INTEGER,
    total_documentos_encontrados INTEGER,
    total_documentos_indexados INTEGER,
    total_erros INTEGER,
    pastas_varridas TEXT[],
    provider_ia VARCHAR(50),
    modelo_usado VARCHAR(100),
    tokens_utilizados INTEGER,
    status VARCHAR(50) -- 'sucesso', 'parcial', 'erro'
    mensagem_erro TEXT,
    iniciado_por UUID REFERENCES usuarios(id),
    created_at TIMESTAMP DEFAULT NOW()
);
```

---

#### 13. **permissoes_usuario_detalhadas**
Controle granular de permissões por usuário.

```sql
CREATE TABLE permissoes_usuario_detalhadas (
    id UUID PRIMARY KEY,
    usuario_id UUID NOT NULL REFERENCES usuarios(id),
    pode_criar_template BOOLEAN DEFAULT FALSE,
    pode_editar_template BOOLEAN DEFAULT FALSE,
    pode_deletar_template BOOLEAN DEFAULT FALSE,
    pode_criar_databook BOOLEAN DEFAULT FALSE,
    pode_editar_databook BOOLEAN DEFAULT FALSE,
    pode_deletar_databook BOOLEAN DEFAULT FALSE,
    pode_upload_documentos BOOLEAN DEFAULT FALSE,
    pode_aprovar_documentos BOOLEAN DEFAULT FALSE,
    pode_gerar_pdf BOOLEAN DEFAULT FALSE,
    pode_visualizar_preview BOOLEAN DEFAULT FALSE,
    pode_acessar_logs BOOLEAN DEFAULT FALSE,
    pode_configurar_ia BOOLEAN DEFAULT FALSE,
    pode_configurar_pastas BOOLEAN DEFAULT FALSE,
    pode_gerenciar_usuarios BOOLEAN DEFAULT FALSE,
    acesso_apenas_seus_projetos BOOLEAN DEFAULT TRUE,
    pode_visualizar_precos BOOLEAN DEFAULT FALSE,
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW()
);
```

---

### Relacionamentos Principais

```
usuarios
  ├─ 1:N → projetos (responsavel_id)
  ├─ 1:N → templates_customizados (criado_por)
  ├─ 1:N → configuracoes_pastas (criado_por)
  ├─ 1:N → integracao_ia (criado_por)
  ├─ 1:N → log_processamento_ia (iniciado_por)
  └─ 1:1 → permissoes_usuario_detalhadas

clientes
  └─ 1:N → projetos

templates_topicos
  ├─ 1:N → secoes_databook
  └─ N:M → templates_customizados (via topicos_selecionados)

templates_customizados
  ├─ 1:N → projetos
  └─ 0:1 → templates_customizados (template_pai_id - auto-referência)

projetos
  ├─ 1:1 → databooks_mestres
  ├─ 1:N → secoes_databook
  ├─ 1:N → documentos_auto_indexados
  └─ 1:N → log_processamento_ia

secoes_databook
  ├─ 1:N → documentos_auto_indexados
  └─ 0:1 → templates_topicos

categorias
  ├─ 1:N → templates_topicos
  └─ 1:N → configuracoes_pastas
```

---

## Fluxo de Dados

### 1. Criação de um Novo Databook

```
1. Usuário clica "Novo Databook"
   ↓
2. Seleciona Cliente e Template
   ↓
3. Sistema cria registro em 'projetos'
   ↓
4. Sistema cria 'databooks_mestres' com configurações padrão
   ↓
5. Sistema cria 'secoes_databook' (uma por tópico do template)
   ↓
6. Databook pronto para receber documentos
```

### 2. Upload de Documentos

```
1. Usuário seleciona arquivo (PDF, JPG, PNG)
   ↓
2. Frontend valida tipo e tamanho
   ↓
3. Upload para Supabase Storage
   ↓
4. Sistema cria registro em 'documentos_auto_indexados'
   ↓
5. Se IA ativada: Processa com OCR/Análise
   ↓
6. Atualiza 'secoes_databook.total_documentos'
   ↓
7. Recalcula 'projetos.progresso_percentual'
```

### 3. Cálculo de Progresso

```
Progresso = (Seções com documentos / Total de tópicos) × 100

Exemplo:
- Total de tópicos: 28
- Seções com documentos: 7
- Progresso: (7/28) × 100 = 25%
```

### 4. Geração de PDF

```
1. Usuário clica "Gerar PDF"
   ↓
2. Sistema busca todos os dados do databook
   ↓
3. Renderiza preview com React
   ↓
4. Converte para PDF (html2pdf/jsPDF)
   ↓
5. Aplica marca d'água, numeração, cores
   ↓
6. Download automático
```

---

## Componentes Principais

### Frontend Structure

```
src/
├── pages/
│   ├── Dashboard.tsx              # Visão geral de projetos
│   ├── DatabookView.tsx           # Visualização do databook
│   ├── Templates.tsx              # Gerenciamento de templates
│   ├── TopicosGestao.tsx          # Gerenciamento de tópicos
│   ├── Configuracoes.tsx          # Painel de configurações
│   └── Login.tsx                  # Autenticação
│
├── components/
│   ├── common/
│   │   ├── Button.tsx             # Botão reutilizável
│   │   ├── Input.tsx              # Input reutilizável
│   │   ├── Modal.tsx              # Modal reutilizável
│   │   ├── LoadingSpinner.tsx     # Spinner de carregamento
│   │   └── Navbar.tsx             # Barra de navegação
│   │
│   ├── configuracoes/
│   │   ├── PastasTab.tsx          # Mapeamento de pastas
│   │   ├── CategoriasTab.tsx      # Gerenciamento de categorias
│   │   ├── UsuariosTab.tsx        # Gerenciamento de usuários
│   │   ├── LogsTab.tsx            # Visualização de logs
│   │   └── IATab.tsx              # Configuração de IA
│   │
│   └── databook/
│       ├── DatabookPreview.tsx    # Preview do databook
│       ├── DocumentUpload.tsx     # Upload de documentos
│       └── SectionEditor.tsx      # Editor de seções
│
├── lib/
│   ├── supabase.ts                # Cliente Supabase
│   ├── mutations.ts               # Funções de mutação
│   ├── toast.ts                   # Sistema de notificações
│   └── utils.ts                   # Funções utilitárias
│
└── types/
    └── index.ts                   # Tipos TypeScript
```

---

## Autenticação e Segurança

### Fluxo de Autenticação

```
1. Usuário faz login com email/senha
   ↓
2. Supabase valida credenciais
   ↓
3. Retorna JWT token
   ↓
4. Token armazenado no localStorage
   ↓
5. Incluído em todas as requisições
   ↓
6. Supabase valida token em cada request
```

### Row Level Security (RLS)

Todas as tabelas têm RLS habilitado com políticas:

```sql
-- Exemplo: Usuários veem apenas seus próprios projetos
CREATE POLICY "Usuários veem seus projetos"
ON projetos FOR SELECT
USING (responsavel_id = auth.uid());

-- Exemplo: Apenas admins podem deletar
CREATE POLICY "Apenas admins deletam"
ON projetos FOR DELETE
USING (
  EXISTS (
    SELECT 1 FROM usuarios
    WHERE id = auth.uid() AND perfil = 'admin'
  )
);
```

### Segurança de Dados

- **Senhas:** Hash com bcrypt (Supabase Auth)
- **API Keys:** Encriptadas no banco
- **Tokens:** JWT com expiração
- **HTTPS:** Obrigatório em produção
- **CORS:** Configurado para domínios autorizados

---

## Queries Importantes

### Buscar Progresso de um Projeto

```sql
SELECT 
  p.id,
  p.numero_projeto,
  COUNT(DISTINCT CASE WHEN d.id IS NOT NULL THEN s.id END) as secoes_com_docs,
  COUNT(DISTINCT t.id) as total_topicos,
  ROUND(
    (COUNT(DISTINCT CASE WHEN d.id IS NOT NULL THEN s.id END)::float / 
     COUNT(DISTINCT t.id)) * 100
  ) as progresso_percentual
FROM projetos p
LEFT JOIN secoes_databook s ON p.id = s.projeto_id
LEFT JOIN templates_topicos t ON s.topico_id = t.id
LEFT JOIN documentos_auto_indexados d ON s.id = d.secao_id
WHERE p.id = $1
GROUP BY p.id, p.numero_projeto;
```

### Buscar Documentos de uma Seção

```sql
SELECT 
  d.*,
  c.nome as categoria_nome,
  c.cor as categoria_cor
FROM documentos_auto_indexados d
LEFT JOIN categorias c ON d.secao_numero = c.nome
WHERE d.secao_id = $1
ORDER BY d.ordem_na_secao ASC;
```

### Buscar Tópicos com Cores de Categoria

```sql
SELECT 
  t.*,
  c.cor as categoria_cor
FROM templates_topicos t
LEFT JOIN categorias c ON t.categoria = c.nome
WHERE t.id = ANY($1::uuid[])
ORDER BY t.ordem ASC;
```

---

## Variáveis de Ambiente

```env
VITE_SUPABASE_URL=https://seu-projeto.supabase.co
VITE_SUPABASE_ANON_KEY=sua-chave-anonima
VITE_API_URL=http://localhost:5173
```

---

## Deployment

### Produção

1. Build: `npm run build`
2. Deploy em Vercel/Netlify
3. Configurar variáveis de ambiente
4. Ativar HTTPS
5. Configurar CORS no Supabase

### Banco de Dados

1. Executar migrations em produção
2. Configurar backups automáticos
3. Monitorar performance
4. Manter índices atualizados

---

## Troubleshooting

### Erro 400 ao atualizar

- Verificar se coluna existe na tabela
- Validar tipos de dados
- Checar RLS policies

### Progresso não atualiza

- Verificar se documentos estão sendo salvos
- Checar se secoes_databook.total_documentos está sendo atualizado
- Recarregar página para forçar recálculo

### Upload falha

- Verificar tamanho do arquivo
- Checar permissões do bucket
- Validar tipo de arquivo

---

## Contato e Suporte

Para dúvidas sobre a arquitetura, consulte a documentação do usuário ou entre em contato com o time de desenvolvimento.