admtracksteel/dbmaker
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
dbmaker/docs/ARQUITETURA_TECNICA.md

22 KiB
Raw Permalink Blame History

SteelBook - Arquitetura Técnica Completa

📋 Índice

  1. Visão Geral
  2. Arquitetura do Sistema
  3. Banco de Dados
  4. Fluxo de Dados
  5. Componentes Principais
  6. 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.

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.

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.

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.

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.

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.

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).

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.

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.

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.

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.

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.

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.

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:

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

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

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

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

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.

Reference in New Issue View Git Blame Copy Permalink