← Voltar ao índice

🚀 BB Fast

Ecossistema de ferramentas internas para a rede de conveniência BB Fast Brasil — gestão de compras com matching de fornecedores, Instagram Marketing Studio e API REST de monitoramento de redes sociais.

URL: bbfast.blackcatcorp.com.br
Repo: vituulm/claudinho
Status: ✅ Rodando
FastAPI Python 3.11+ SQLAlchemy (async) SQLite / Aiosqlite React 19 Vite Tailwind CSS v4 Flask instagrapi RapidFuzz pandas / openpyxl ReportLab PySide6 (desktop) Cryptography (Fernet) PostgreSQL / Neon.tech Render.com

Visão Geral do Ecossistema

Central de Compras

Plataforma fullstack (FastAPI + React) para importação de tabelas de preços de fornecedores, matching automático de produtos com RapidFuzz, comparador de preços e geração de listas de compra/relatórios PDF.

Marketing Studio

Aplicação desktop PySide6 para Windows — conecta ao Instagram via Session ID (instagrapi), sincroniza perfil e posts, gera legendas/hashtags com IA, agenda publicações e exibe analytics de engajamento.

API Instagram (bbfast-api)

API REST Flask hospedada no Render.com — expõe dados do Instagram (perfil, feed, stats, analytics) com autenticação por API Key (SHA-256), cache em memória TTL, rate limiting e banco PostgreSQL no Neon.tech.

Central de Compras — central_compras_bbfast

Modelos de dados (SQLAlchemy)

Tabelas

Produto — código interno, nome normalizado, categoria, subcategoria, marca, unidade, qtd_embalagem, código de barras, estoque mínimo/atual.

ProdutoAlias — mapeamento de nomes alternativos por fornecedor com score de confiança e flag de confirmação humana.

Fornecedor — razão social, CNPJ, contato, pedido mínimo, prazo de entrega, frete incluso.

TabelaPreco — referência ao upload de arquivo por fornecedor com data de vigência.

ItemTabela — item extraído da tabela com nome original, normalizado, preço unitário normalizado, status de match (pendente / revisão / aprovado / rejeitado) e JSON de sugestões RapidFuzz.

ListaCompra / ItemListaCompra — lista de compras gerada com itens, quantidades e preços de referência.

Produtos — /api/produtos

GET/api/produtos/
Lista produtos ativos. Query params: ativo, categoria. Ordenado por nome.
POST/api/produtos/
Cria produto. Nome é normalizado automaticamente (remoção de acentos, lowercase). Body: { nome, codigo_interno?, categoria?, marca?, unidade?, ... }
PUT/api/produtos/{produto_id}
Atualiza produto (PATCH semântico — apenas campos enviados). Recalcula nome_normalizado se nome mudar.
DELETE/api/produtos/{produto_id}
Desativação lógica (ativo = false). Não exclui do banco.
POST/api/produtos/upload-csv
Importação em lote de produtos via CSV.

Fornecedores — /api/fornecedores

GET/api/fornecedores/
Lista fornecedores. Filtros: ativo.
POST/api/fornecedores/
Cadastra fornecedor com dados completos (CNPJ, contato, frete, pedido mínimo).
PUT/api/fornecedores/{id}
Atualiza dados do fornecedor.
DELETE/api/fornecedores/{id}
Desativação lógica do fornecedor.

Importação de Tabelas de Preço — /api/importacao

POST/api/importacao/upload
Upload de arquivo XLSX/XLS/CSV do fornecedor. Retorna preview com detecção automática de colunas. Valida extensão, tamanho (configurável via MAX_UPLOAD_MB) e sanitiza nome do arquivo.
POST/api/importacao/confirmar
Confirma mapeamento de colunas e persiste itens no banco. Dispara matching automático via RapidFuzz após importação.
GET/api/importacao/tabelas
Lista tabelas de preço importadas com status e contagem de itens.

Matching Automático — /api/matching

Motor de correspondência fuzzy entre nomes de produtos do fornecedor e cadastro interno, usando RapidFuzz. Status possíveis: pendente → revisao → aprovado / rejeitado.
GET/api/matching/pendentes
Lista itens aguardando revisão humana. Filtros: fornecedor_id, tabela_id. Inclui JSON de sugestões com scores.
POST/api/matching/aprovar
Aprova vínculo item→produto. Cria alias automático para futuras importações.
POST/api/matching/rejeitar
Rejeita sugestão e marca item como rejeitado.
POST/api/matching/executar/{tabela_id}
Força re-execução do matching em toda uma tabela importada.

Comparador de Preços — /api/comparador

GET/api/comparador/
Tabela comparativa de preços de todos os produtos por fornecedor. Filtros: categoria, apenas_com_multiplos_fornecedores.
GET/api/comparador/produto/{produto_id}
Comparação detalhada de preços de um produto específico em todos os fornecedores com preço aprovado.

Lista de Compra — /api/lista-compra

GET/api/lista-compra/
Lista todas as listas de compra criadas.
POST/api/lista-compra/
Cria nova lista de compra com itens e quantidades.

Exportação — /api/exportacao

GET/api/exportacao/pdf/{lista_id}
Gera relatório PDF da lista de compra via ReportLab.
GET/api/exportacao/excel/{lista_id}
Exporta lista de compra em XLSX via openpyxl.

Dashboard — /api/dashboard

GET/api/dashboard/
Métricas consolidadas: total de produtos ativos, fornecedores ativos, tabelas importadas, produtos com preço aprovado e produtos sem match.

Saúde — Central de Compras

GET/health
Healthcheck. Retorna {"status":"ok","service":"Central de Compras BB Fast"}.

Marketing Studio — bbfast_marketing

Sobre

Aplicação desktop para Windows empacotada com PyInstaller. Interface PySide6 com splash screen. Conecta ao Instagram via instagrapi usando Session ID (cookie sessionid do navegador). Dados armazenados localmente em SQLite.

Módulos principais
  • app/services/instagram_client.py — wrapper instagrapi
  • app/analytics/analyzer.py — engagement rate, best posting times, snapshots, campanhas
  • app/ai/content_generator.py — geração de legendas, hashtags e planos de campanha
  • app/services/sync_worker.py — sincronização de perfil/posts (QThread)
  • app/database/db.py — SQLite com tabelas: accounts, posts, profile_snapshots, sync_log, scheduled_posts
  • mobile/server.py — servidor Flask local (bridge para mobile/web)
Identidade Visual BB Fast
#FFD600 Amarelo primário
#E42313 Vermelho acento
#0f0f0f Fundo escuro

API Flask local (mobile server) — http://localhost:PORT

GET/api/status
Estado da conexão Instagram: {"connected": bool, "username": str}
POST/api/login
Autenticação via Session ID do Instagram. Body: {"session_id": "..."}
POST/api/logout
Encerra sessão Instagram.
GET/api/sync
Sincroniza perfil e posts do Instagram. Salva snapshot de métricas no SQLite.

API REST Instagram — bbfast-api (Render.com)

Autenticação

Todas as rotas (exceto /health) requerem header X-API-Key: <chave>. Chaves armazenadas como SHA-256 no PostgreSQL. Dois escopos: read (consultas) e admin (atualizar session, agendar posts).

Modelos PostgreSQL (Neon.tech)

api_keys — key_hash (SHA-256), scope (read/admin), label
profiles — username, followers, following, posts_count, bio, profile_pic_url
profile_snapshots — histórico diário de métricas de perfil
posts — shortcode, caption, likes, comments, timestamp, media_type
session_config — session_id criptografado com Fernet
scheduled_posts — image_url, caption, scheduled_at, status
sync_log — histórico de sincronizações com timestamps e erros

Instagram — /api/instagram

GET/api/instagram/profile X-API-Key read
Perfil do Instagram: username, followers, following, posts, bio, profile_pic_url.
GET/api/instagram/feed X-API-Key read
Feed de posts recentes. Query param: limit (padrão 6). Dados em cache com TTL.
GET/api/instagram/stats X-API-Key read
Estatísticas consolidadas: engagement rate, melhores horários de publicação, crescimento. Dispara run_sync() quando cache expirado.

Analytics — /api/analytics

GET/api/analytics/dashboard X-API-Key read
Dashboard completo: métricas de crescimento, posts com maior engajamento, melhores horários (calculados por calculate_best_posting_times()), stats de campanhas agendadas.
GET/api/analytics/snapshots X-API-Key read
Histórico de snapshots de métricas. Query param: days (padrão 30).

Posts Agendados — /api/posts

GET/api/posts/scheduled X-API-Key read
Lista posts agendados com status (pendente/publicado/erro).
POST/api/posts/schedule X-API-Key admin
Agenda publicação. Body: {"image_url": "...", "caption": "...", "scheduled_at": "2025-05-28T19:00:00"}. Imagem referenciada por URL pública (sem upload local — filesystem efêmero no Render).

Autenticação Instagram — /api/auth

POST/api/auth/session-id X-API-Key admin
Atualiza o Session ID do Instagram (criptografado com Fernet antes de persistir). Body: {"session_id": "..."}. Renovar quando o Instagram expirar a sessão.

Saúde — API Instagram

GET/health Público
Healthcheck sem autenticação. Monitorado pelo UptimeRobot a cada 14 min para evitar hibernação no Render gratuito.

Variáveis de Ambiente

Central de Compras

DATABASE_URLCaminho SQLite (ex: sqlite+aiosqlite:///./bbfast.db) MAX_UPLOAD_MBTamanho máximo de upload de tabela (padrão 20) CORS_ORIGINSOrigens permitidas para o frontend React

API Instagram (Render.com)

DATABASE_URLConnection string PostgreSQL Neon.tech (?sslmode=require) SECRET_KEYChave Fernet para criptografar Session ID (base64url 32 bytes) API_KEY_READChave de acesso read (armazenada como SHA-256) API_KEY_ADMINChave de acesso admin (armazenada como SHA-256) INSTAGRAM_SESSION_IDSession ID inicial para seed (cookie sessionid do instagram.com)

Arquitetura de Deploy

Central de Compras (local / VPS)
  ├─ FastAPI + Uvicorn (porta 8000) — SQLite async
  └─ React 19 + Vite (servido como static em produção)

Marketing Studio (Windows)
  └─ PySide6 desktop app
       └─ Flask local server (mobile/server.py) → instagrapi → Instagram

API Instagram (cloud)
  └─ Flask + Gunicorn (1 worker) — Render.com Starter
       ├─ PostgreSQL Neon.tech (0.5 GB)
       ├─ Cache em memória (cachetools TTL)
       ├─ Rate limiting por rota (Flask-Limiter)
       └─ UptimeRobot → GET /health (14 min) — evita hibernação

Gerado automaticamente — BlackCat Corp • Voltar ao índice