Importrust · Documentação Técnica · v1.0

Infraestrutura
Importrust.

Mapa operacional dos quatro servidores que sustentam o negócio: o que cada um faz, como se ligam, e onde vive cada coisa.

Versão: 1.0 · Abril 2026
Audiência: Developers · Operações
Servidores: 4 (VPS · Queue · BO · Apps)

Índice

Cada capítulo segue o mesmo formato — identificação, módulos, integrações, crons, conexões, alertas — para que possas comparar servidores rapidamente.

00Visão geralMapa do sistema · fluxos cross-server04
01VPSvps.importrust.com · pipelines, scrapers, Amélia06
1.1Identificação & infra06
1.2Aplicações & serviços07
1.3Cars Pipeline · arquitectura08
1.4Crons & integrações09
02Queuequeue.importrust.com · webhooks, propostas, MCP10
2.1Identificação & estrutura10
2.2Módulos11
2.3MCP — sub-sistema12
03Backofficebackoffice.importrust.com · WordPress + Router PHP13
3.1Identificação & arquitectura13
3.2Módulos /api14
3.3Crons, webhooks & integrações16
04Apps/apps · plataforma multi-tenant17
4.1Modelo & isolamento17
4.2Apps activas18
05Cross-cuttinglogin, deploy, base de dados19
06Dados & modelo de negóciotabelas principais, propostas, deals22
6.1Top tabelas por volume22
6.2Propostas — o objecto central23
6.3Deals · Contacts · sync HubSpot24
6.4WordPress como config store (CPTs)25
07HubSpot CRMschema, pipelines, forms, commerce25
7.1Schema (custom properties)25
7.2Pipelines, stages, owners26
7.3Forms27
7.4Commerce & activity28
08Documentos & fluxoso que chega, o que sai, assinatura29
8.1Docs que o cliente envia29
8.2Docs que a Importrust gera30
8.3Assinatura digital31
8.4Infra já pronta para área cliente32
09Backlog Asanafeatures pendentes, relação com área cliente33
10ApêndicesURLs · alertas · glossário34

SECÇÃO 00

Visão geral.

Quem é quem, quem fala com quem, e quem é dono do quê.

Mapa do sistema

As setas mostram quem inicia a comunicação. Cada cor é o servidor de origem. Cinzentos são sistemas externos.

VPS inicia

Queue inicia

Backoffice inicia

Apps iniciam

Externo → interno

Hosting (mesma máquina)

Fluxos cross-server

Os 7 fluxos que cruzam servidores. Lê estes antes de mergulhares num servidor — quase tudo o que aparece em mais que um sítio começa aqui.

Fluxo	Caminho	Descrição
Cars Pipeline VPS BO	`mobile.de` → `VPS /opt/queue-jobs/cars` → `MySQL queue_importrust` → `MeiliSearch cars_mobilede`	Cron `/3 min` no VPS faz sync incremental, calcula CO2/ISV/IUC e indexa em MeiliSearch. ~2M anúncios. Source of truth: VPS*.
HubSpot Sync BO	`HubSpot` ↔ `BO /api/crons/hubspot_sync.php` ↔ `tabelas contacts_hubspot · deals_hubspot`	Polling 1/min em processos separados (contacts, deals) com Search API. Webhooks reais em `/webhooks/hubspot`.
Amélia VPS Queue	`VPS amelia-v5 :3099` ↔ `queue.importrust.com/api/amelia`	Session manager corre no VPS. Endpoints HTTP do lado do Queue: `/amelia/mcp.php`, `/amelia/mcp-tools/*` (hubspot, email, signatures, contracts, docs).
Tradutor PDF App VPS	`/apps/tradutor-pdfs (BO)` ↔ `VPS tradutor-worker.service` + `/opt/inpaint`	App recebe upload → fila → worker no VPS faz OCR (AWS Textract) + tradução (OpenRouter) + inpaint + rebuild PDF.
WhatsApp BO Queue	`Meta Cloud API` → `Queue /webhooks/whatsapp/webhook.php` → `workers/message_worker.php`	Webhook recebido no Queue. Worker processa e chama BO para resposta. Templates pelo `template_hub` no BO.
Propostas (frontend) BO Queue	`React SPA` → `BO /api/propostas/*` · cálculos em `Queue /isv · /iuc · /propostas`	Frontend faz CRUD via BO; cálculos pesados (ISV, IUC) chamam Queue. Source of truth ISV/IUC: Queue — versões no BO são duplicado obsoleto.
StandVirtual VPS	`scraper Python` → `SQLite standvirtual.db (~600MB)` → `MySQL + MeiliSearch cars_standvirtual`	Scraper full quinzenal + incremental dias pares. Sync MeiliSearch `*/5 min`. Usado para "comparação de preços" nas listagens.

Quem é dono do quê

Base de dados principal

importrustadm_backofficeprod

Vive no servidor BO. Acedida directamente pelo BO (full) e pelo Queue (full) com mesmas credenciais. Apps vêem só read-only.

Base de dados Cars

queue_importrust @ VPS

29.6 GB, 15 tabelas. ÚNICO MySQL no VPS. Usado só pelo Cars Pipeline. Não confundir com o nome da BD do Backoffice.

MeiliSearch

VPS :7700

Índices: cars_mobilede (~2M), cars_standvirtual (~42K). Usado pelo Cars Pipeline e por queries do BO.

DBs por App

importrustadm_*

Cada app no BO tem MySQL próprio + user MySQL próprio (criados via cPanel API). Isolamento ao nível do server, não do código.

SECÇÃO 01

VPS.

O servidor que nunca dorme. Pipelines, scrapers, Amélia e tudo o que precisa de processos persistentes.

Servidor 01 · VPS

vps.importrust.com

also: retomas.importrust.com

Host: Hostinger VPS (KVM)
OS: Ubuntu 24.04.4 LTS
CPU: AMD EPYC 9354P · 2 vCPU
RAM: 7.8 GB · swap 4 GB
Disco: 96 GB · 96 % cheio
Uptime: 37 dias
Acesso: SFTP · root
Env ID: 8f3d8028-…

Camadas activas

Web

Apache 2

2 vhosts SSL: vps.importrust.com e retomas.importrust.com. Proxy reverso para serviços Node.

Process manager

PM2

3 apps Node persistentes (amelia-v5, pdf-service, retomas) + systemd para tradutor-worker.

Bases de dados

MySQL · Meili

MySQL local (cars), MeiliSearch (índices ~2M docs), SQLite (StandVirtual cache).

Mapa de pastas

/root/ ├── amelia/ # PM2 amelia-v5 (Node ESM session-manager) │ ├── .env, package.json, session-manager.js │ ├── .session_ids.json # estado runtime das sessões │ └── logs/, .claw/ ├── api/cars/ # model_aliases.json (asset, não app) └── not_used/ # amelia-old, amelia-dev, claude-0 (legacy) /opt/ ├── queue-jobs/ # SOURCE OF TRUTH do Cars Pipeline │ ├── cars/ # jobs, api, configs, meilisearch, transformadores │ ├── isv/, iuc/ # cálculos (não confundir com Queue) │ ├── _configs.php, db_pdo.php, funcoes.php │ └── trusted_stands.json ├── scraping_standvirtual_v2/ # Python scraper, SQLite ~600MB ├── scraping_ultimatespecs/ # scraper CO2 reference ├── pdf-service/ # PM2 :3100 — Express + Puppeteer + Paged.js ├── pdf-generator/ # PHP puro (legacy, ainda usado) ├── retomas/ # PM2 :3000 — Next.js 16 + Supabase + Anthropic SDK ├── retomas-deploy/ # scripts de deploy do retomas ├── cars-transformadores/ ├── inpaint/ # usado pelo tradutor (apaga texto em imagens) ├── backups/ # backups automáticos a cada 6h ├── phpmyadmin/, adminer/ └── ⚠ not_used/, OLD_NOT_USED/ /var/www/html/ ├── index.html, pdf/, pdfs/ └── tradutor/ # PHP worker.php (systemd tradutor-worker)

Aplicações & serviços

Tudo o que está vivo a correr neste servidor — processos, portas, e quem chama cada um.

Processos PM2

Nome	Porta	Stack	Caminho	Função
PM2amelia-v5	`3099`	Node ESM	`/root/amelia`	Session manager da Amélia. Expõe SSE em `/amelia-stream`, upload em `/amelia-upload`, notify em `/amelia-notify` (proxied pelo Apache via vps.importrust.com).
PM2pdf-service	`3100`	Express + Puppeteer + Paged.js	`/opt/pdf-service`	Renderiza HTML em PDF A4 paginado (Paged.js). Usado para artefactos do orchestrator e pelos contratos do BO.
PM2retomas	`3000`	Next.js 16 + Supabase + Anthropic SDK	`/opt/retomas`	App pública de retomas (avaliação de viaturas). Domain próprio: `retomas.importrust.com`.

Serviços systemd custom

Unit	WorkingDirectory	Comando	Função
systemdtradutor-worker	`/var/www/html/tradutor`	`php worker.php`	Worker permanente para a app `tradutor-pdfs`. Restart=always. Logs em `tmp/worker_stdout.log`.

Portas abertas

Porta	Serviço	Bind	Exposto?
`22`	SSH (sshd)	0.0.0.0	Sim
`80 / 443`	Apache (vps + retomas)	0.0.0.0	Sim
`3000`	retomas (Next.js)	0.0.0.0	Apache proxy
`3099`	amelia-v5	0.0.0.0	Apache proxy
`3100`	pdf-service	0.0.0.0	Local + interno
`3306`	MySQL	0.0.0.0	Sim · cuidado
`7700`	MeiliSearch	0.0.0.0	Sim · key-protected
`8080`	phpMyAdmin (PHP built-in)	127.0.0.1	Não

Apache vhosts

ServerName	DocumentRoot / Proxy	SSL
vps.importrust.com	`/var/www/html` + proxies `/amelia-stream` · `/amelia-upload` · `/amelia-notify` → :3099	Let's Encrypt
retomas.importrust.com	Proxy `/` → `127.0.0.1:3000` (excepção: `/deploy`)	Let's Encrypt

Detalhe operacional O domain vps.importrust.com serve apenas os endpoints da Amélia (proxied) — não há aplicação web na raiz. O retomas.importrust.com é uma app Next.js pública, completa.

Cars Pipeline

O motor que mantém ~2M anúncios indexados em MeiliSearch com CO2/ISV/IUC calculados em tempo real. Vive em /opt/queue-jobs/cars. Source of truth absoluto: este servidor.

mobile.de Auto API
  └─ pipeline_cars.sh (cron */3 min) ── SEQUENCIAL
       │
       ├─ Fase 1 · sync_changes.php
       │    └→ cars_offers_raw      (MySQL, ~1.85M activos)
       │       └ INSERT cars_emissions (status='pending')
       │
       ├─ Fase 2 · processor_emissions.php (batch=500)
       │    ├→ co_emission do anúncio (auto API)        → confidence 'high'
       │    ├→ Eléctrico → CO2=0                         → confidence 'high'
       │    ├→ BDs ref: VCA → US → EEA → ADEME → EPA    → confidence 'medium'
       │    ├→ AI (OpenRouter Gemini)                    → confidence 'low'
       │    └→ cars_emissions (status='ready')
       │
       └─ Fase 3 · processor_sync_meilisearch.php
            ├ Calcula: ISV, IUC, chave-na-mão, financiamento, prestações
            ├ Junta: CO2 (JOIN cars_emissions WHERE status='ready')
            ├ Junta: comparação SV (modo incremental)
            └→ cars_mobilede (MeiliSearch, ~2M docs)

StandVirtual scraper (Python, independente)
  └─ standvirtual_cache.db (SQLite, ~600 MB)
       ├ sync_mysql.py        → standvirtual_listings (MySQL, ~35K)
       └ sync_sv_meilisearch  → cars_standvirtual (MeiliSearch, ~42K)

API pública (Apache → /opt/queue-jobs/cars/api/get.php)
  └→ MeiliSearch search + cálculos em runtime

Porquê sequencial?

Antes os 3 scripts corriam como crons independentes */2. Resultado: o MeiliSearch indexava carros antes do CO2 estar resolvido — ficavam sem ISV/poupança durante 2-4 minutos. O pipeline_cars.sh garante a ordem: sync → emissions → meili. Um cron em vez de três.

Tabelas chave (MySQL `queue_importrust`)

Tabela	Linhas	Função
`cars_offers_raw`	~1.85 M	Anúncios activos da mobile.de (raw payload + delta)
`cars_emissions`	~1.85 M	Status do CO2 por anúncio (pending → ready) com confidence + fonte
`standvirtual_listings`	~35 K	Anúncios SV sincronizados do SQLite local
`co2_*`	—	5 BDs de referência: VCA, US (EPA), EEA, ADEME, EPA

Índices MeiliSearch

Índice	Docs	Função
`cars_mobilede`	~2 M	Listing principal de viaturas — todas as queries do frontend de propostas
`cars_standvirtual`	~42 K	Listings SV — usado para comparação de preços

Crons activos

29 entradas no crontab do root. Os mais críticos primeiro.

Frequência	Comando	Função
`*/3 min`	`pipeline_cars.sh`	Pipeline completo Cars (sync → emissions → meili)
`*/5 min`	`cron_watchdog.php`	Watchdog do pipeline
`*/5 min`	`sync_sv_meilisearch.py`	SQLite SV → MeiliSearch
`* * * * *`	`amelia-scheduler.sh`	Verifica scheduled reports da Amélia
`0 */3 h`	`processor_emissions_ai.php`	CO2 fallback por AI (OpenRouter Gemini)
`0 9 * * *`	`cron_daily_report.php` + `run_daily_csv.sh`	Relatórios diários do pipeline
`0 5 * * 0`	`reconcile_stale_offers.php --max-age=14`	Domingo 5h: reconciliação 50K batch
`0 3 * * 0`	`cleanup_ghost_docs.php`	Domingo 3h: ghost docs do MeiliSearch
`0 2 * * 0`	`cleanup_removed_offers.sh`	Domingo 2h: anúncios removidos
`0 4 */2`	`run_daily.sh (StandVirtual)`	Dias pares 4h: scrape SV incremental + HEAD stale
`0 3 1 * *`	`run_full.sh (StandVirtual)`	Dia 1 do mês 3h: scrape SV completo
`0 23 15 * *`	`meilisearch_compact.sh`	Dia 15 23h: compaction MeiliSearch (~2-5 min downtime)
`0 */6 h`	`backup_files.sh`	Backups a cada 6h (max 2 backups)
`0 4 * * 0`	`update-claude.sh`	Domingo 4h: actualiza CLI Claude na Amélia
`0 * * * *`	`amelia/cleanup-files.sh`	Cleanup horário da Amélia

Integrações externas

Sistema	Quem usa	Função
mobile.de Auto API	Cars Pipeline	Source raw dos anúncios (PT + ES)
StandVirtual (scraping)	scraping_standvirtual_v2	Scrape directo HTML, comparação de preços
UltimateSpecs (scraping)	scraping_ultimatespecs	Dados técnicos + emissões CO2 reference
OpenRouter	processor_emissions_ai · Amélia · retomas	Modelos AI (Gemini, Claude). Key dedicada CO2.
Anthropic SDK	retomas (Next.js)	Avaliação de retomas via Claude
Supabase	retomas (Next.js)	Auth + storage da app retomas
Resend	retomas	Envio de emails da app retomas

Quem chama o VPS

Queue → VPS

amelia /amelia-stream

A Amélia (no Queue) abre SSE para o VPS para receber respostas em streaming.

App tradutor-pdfs → VPS

tradutor-worker

A app de tradução envia PDFs para a fila local do VPS (worker systemd).

Backoffice → VPS (BD)

queue_importrust

Frontend de propostas faz queries directas à API /opt/queue-jobs/cars/api/get.php via Apache.

Público → retomas

retomas.importrust.com

App pública para clientes avaliarem viaturas para retoma.

Alertas operacionais Disco a 96% (92/96 GB). Swap a 95% (3.8/4 GB). Pasta /root/not_used e /opt/not_used têm versões antigas (amelia-old, amelia-dev, claude-0). Logs do MeiliSearch + crons avolumam o disco.

SECÇÃO 02

Queue.

Endpoints PHP só executados a pedido. Recebe webhooks, calcula propostas e expõe a inteligência consumida pelo BO e pela Amélia.

Servidor 02 · Queue

queue.importrust.com

/api (prod) · /apidev (staging)

Host: Hostinger shared (de-fra-h5g-node23)
OS: Debian 6.1
Stack: PHP 8 + Composer (Guzzle/Symfony)
User shell: u748143581_1j3IMTxXD
Tamanho prod: 199 MB
Acesso: SFTP
Persistência: Nenhuma só on-request
BD: Remota (BO) — não tem MySQL local

Mapa de pastas (prod `/api`)

api/ ├── _configs.php, .env, env_loader.php, funcoes.php (49KB), db_pdo.php ├── composer.json, composer.lock, vendor/ │ ├── amelia/ # endpoints HTTP usados pela Amélia (VPS) │ ├── mcp.php (12KB), unclaim.php │ ├── docs/ # hubspot, email-ops, template-hub, documents │ └── mcp-tools/ # hubspot, email_force_send, signatures, contracts │ ├── workers/ # scripts CLI chamados por outros servidores │ ├── message_worker.php (17KB) │ ├── hubspot_sync_worker.php (8KB) │ ├── reprocess_empty_responses.php (9KB) │ └── ⚠ worker_debug.log (115 MB) │ ├── webhooks/whatsapp/ │ ├── webhook.php (9KB) │ └── ⚠ webhook_log.txt (12.5 MB) │ ├── mcp/ # sub-sistema MCP (admin panel + tools + workers) │ ├── mcp.php, lib/ (16 ficheiros, ~390KB total) │ ├── tools/ # architect (206KB), sandbox (110KB), scratchpad... │ ├── custom_tools/dpn/ │ ├── workers/, src/Services/ │ ├── v1/public/ # widget.js (70KB), chat_entry, auth, orchestrate │ ├── v1/admin/ # 19 sub-áreas (chat, sandbox, pipeline, dashboard...) │ └── migrations/ │ ├── propostas/ │ ├── get.php (21KB) │ └── funcoes/funcoes.php (139KB), requests.php (325KB) │ ├── isv/{pt,es}, iuc/{pt,es} # SOURCE OF TRUTH dos cálculos │ └── debug/ # sql.php, sql_helper, sql_credentials, SQL_DEBUG_TOOL.md

Diferenças staging vs prod O /apidev tem cars/ (que prod não tem — source of truth do cars é o VPS), sandboxes_storage/, voice_phonetics_ptpt, cron_jobs_dpn_outro_server/, e várias pastas com prefixo _ (legado: _propostas, __cars, _mcp, __meilisearch).

Módulos da Queue

Cada pasta debaixo de /api é um conjunto de endpoints PHP servido directamente pelo path. Não há router — a URL mapeia para o ficheiro.

Módulo	Endpoints / Ficheiros	Função
amelia/ VPS chama	`mcp.php` `mcp-tools/*`	Endpoints chamados pela Amélia (VPS) para acesso a HubSpot, email forçado, view image, get docs, signature list, contract list, hubspot file. `unclaim.php` liberta sessão. `docs/` tem markdown lido pelas tools.
workers/	`message_worker.php` `hubspot_sync_worker.php` `reprocess_empty_responses.php`	Workers PHP CLI chamados via cron noutros servidores. message_worker processa mensagens de chat (WhatsApp, Amélia). hubspot_sync_worker sincroniza dados.
webhooks/whatsapp/	`webhook.php`	Endpoint público que recebe webhooks da Meta Cloud API. Valida signature, enfileira mensagem para processamento.
propostas/	`get.php` (21KB) `funcoes/*` (464KB)	API de propostas comerciais — listing, detalhe, cálculos. `requests.php` (325KB) é o monstro com todas as requests externas.
isv/ SOT	`pt/calcular.php` `pt/calcular_pesados.php` `es/...`	Source of truth do cálculo ISV (Imposto Sobre Veículos). PT e ES separados. Versões duplicadas no BO devem ser apagadas.
iuc/ SOT	`pt/calcular.php` `pt/calcular_pesados.class` (40KB) `es/...`	Source of truth do cálculo IUC (Imposto Único de Circulação). Idem.
mcp/	67 MB · 9 sub-pastas	Sub-sistema completo (página seguinte).
debug/	`sql.php`	Tool de debug SQL (read-only). Auth por API key. Documentado em `SQL_DEBUG_TOOL.md`.

Conexões externas (do `.env`)

Sistema	Variável	Uso
MySQL Backoffice	`DB_HOST=94.46.135.155`	BD `importrustadm_backofficeprod` — partilhada com BO
Zyte	`ZYTE_API_KEY`	Scraping com proxies
Decodo	`DECODO_USERNAME/PASSWORD`	Pool de proxies residenciais
OpenRouter	`OPENROUTER_KEY_CO2`	Cálculo CO2 via Gemini (key dedicada)
Importrust API	`IMPORTRUST_API_KEY`	Auth interna entre serviços

Quem chama a Queue

VPS (Amélia)

/amelia/mcp-tools/*

A cada turn da Amélia, são chamadas várias tools (HubSpot, email, signatures, contracts).

Backoffice (frontend)

/isv · /iuc · /propostas

Cálculos pesados são delegados ao Queue — o BO tem versões obsoletas que devem ser removidas.

WhatsApp Meta

/webhooks/whatsapp

Cada mensagem inbound chega aqui primeiro; o worker faz processing assíncrono.

MCP widget público

/mcp/v1/public/widget.js

Embebido nos sites Importrust como widget de chat.

MCP — sub-sistema

Plataforma própria de tools para agentes IA. Combina lib partilhada, tools compostas, painel admin e widget público.

mcp/ ├── mcp.php (12 KB) # entrypoint principal │ ├── lib/ # 16 ficheiros, ~390 KB │ ├── mcp_lib.php (148 KB) │ ├── mcp_lib_others.php (243 KB) │ ├── pipeline_lib.php (39 KB) │ ├── hubspot_lib.php (30 KB) │ ├── bridge_lib.php (22 KB) │ ├── chat_core.php (18 KB) │ ├── entity_resolver.php (17 KB) │ ├── whatsapp_worker_lib.php (10 KB) │ ├── meta_router.php (6 KB) │ ├── DockerManager.php (4 KB) │ ├── whatsapp_lib.php, mcp_tools_whatsapp.php │ ├── healthcheck.php, admin_auth.php, mcp_client.php │ └── backup/ │ ├── tools/ # MCP tool definitions │ ├── architect_tools.php (206 KB) # maior │ ├── sandbox_tools.php (110 KB) │ ├── scratchpad.php (34 KB) │ ├── calculators_tools.php (19 KB) │ ├── memory_tools.php, manage_entity.php │ ├── state_management_tools.php, onboarding_tools.php │ ├── custom_tools/dpn/ # tools cliente DPN │ ├── criar_nota_cliente.php │ └── registar_cliente_com_contexto.php │ ├── workers/ │ └── pipeline_hook_worker.php │ ├── v1/public/ # exposto à web │ ├── widget.js (70 KB) │ ├── chat_entry.php (20 KB), chat_history, chat_stop │ ├── auth.php, orchestrate_trigger.php │ ├── run_migration.php, test_widget.html │ ├── v1/admin/ # painel de operação (auth) │ ├── chat/, sandbox/, pipeline/, debug/, dashboard/ │ ├── clients/, agents/, traces/, ai/ │ ├── crm/, entities/, origins/, types/, config/ │ ├── tools/, phases/, staging/, internal/ │ ├── whatsapp_simulator/ │ ├── bridges.php, db-proxy.php │ ├── src/Services/ │ └── PlannerService.php │ └── migrations/ └── 20260103_external_bridges.sql

O que isto faz

Widget público

v1/public/widget.js

Chat embed para sites externos. Tem auth, history, stop, e orchestration trigger. Conversa por trás é gerida pelas tools/.

Tools (catálogo)

tools/*.php

Funções expostas como MCP — calculators, memory, sandbox, scratchpad, architect (planning), entity management, onboarding flows.

Painel admin

v1/admin/*

19 sub-áreas para operar o sistema — ver chats, debug pipelines, gerir agentes/clientes/CRM, simular WhatsApp, configurar bridges externos.

Bridges externos

migrations + bridges.php

Conectores para sistemas terceiros (CRM, WhatsApp, Docker). Definidos em SQL migration de 2026-01-03.

Onde o MCP encaixa O MCP da Queue é um sistema interno, separado do MCP que o orchestrator usa. É o que serve o widget público e o painel admin de chat/operação. As tools são chamadas por agentes IA (Claude, OpenRouter) durante conversas.

SECÇÃO 03

Backoffice.

O coração do sistema. Onde a equipa trabalha todos os dias e onde vive a base de dados principal do negócio.

Servidor 03 · Backoffice

backoffice.importrust.com

/api · /apidev · /apps · /webhooks

Host: Hostinger cPanel
Stack: WordPress + PHP 8 + Router custom
Frontend: React + Vite (build deployado)
BD principal: importrustadm_backofficeprod
Acesso: FTP (não SFTP)
Documentação: STACK.md (462 linhas)
Login: WordPress + plugin custom
Apps isoladas: /apps/* (isolamento MySQL)

Arquitectura de routing

Browser → .htaccess (rewrite) → index.php → router.php → ficheiro.php

router.php valida que o path começa com:
  - api/        → core backend prod (carrega WordPress + _configs)
  - apidev/     → core backend staging
  - webhooks/   → endpoints públicos
  - apps/       → multi-app platform (NÃO carrega bootstrap principal!)

URL                                         FICHEIRO
/api/propostas/get?id=123              →    api/propostas/get.php
/apps/global-trading/v1/api/hello      →    apps/global-trading/v1/api/hello.php
/wp-json/importrust-login/login         →    wp-content/plugins/importrust-login/...
/webhooks/hubspot                       →    webhooks/hubspot.php

Dois mundos isolados

Mundo 1 · Core

/api · /apidev · /webhooks

Carrega _configs.php + WordPress ($wpdb) + acesso total à main DB. Frontend React fala com /api.

Mundo 2 · Apps

/apps/{slug}/...

NÃO carrega bootstrap principal. Apenas _bootstrap.php próprio: PDO isolado, sandbox de filesystem, validação CORS.

Mapa de pastas (root)

/ ├── wp-admin/, wp-content/, wp-includes/, wp-*.php # WordPress completo ├── router.php, router_old.php ├── index.php, .htaccess ├── STACK.md (14 KB) # DOCUMENTAÇÃO oficial │ ├── api/ # 41 sub-pastas — core PROD ├── apidev/ # 47 sub-pastas — core STAGING │ ├── apps/ # multi-app platform (capítulo 04) │ ├── backups/, downloads/, files/, Users/ ├── importadores/ # vazia │ ├── ____funcoes.php (573 KB) # LEGACY órfão (4 underscores) ├── header_site.js (73 KB) ├── error_log (278 KB) ├── favicon.ico (251 KB), logo512.png └── wp-config.php, .user.ini, php.ini

Módulos /api

41 pastas. Agrupadas por domínio funcional para ler — não há separação física entre elas.

Negócio core

Módulo	Conteúdo chave	Função
propostas/	`media_nacional/` · `verificacoes/` · `transportes/` · `funcoes/` · `links/`	Endpoint de propostas: criação, edição, links públicos, transportes nacionais, verificação de disponibilidade
viaturas/	`marcas/` · `modelos/` · `cidades_es/` · `municipios_es/`	Catálogo de viaturas e geografia ES
hubspot/	`forms/` · `deals/` · `contacts/` · `orcamentos/` · `propostas/` · `funcoes/` · `stages_dictionary.php` · `properties_dictionary.php`	Integração com HubSpot CRM — leitura/escrita
contratos/	`create.php` (28 K) · `aws_translate.php` (24 K) · `aws_translate_async_functions.php` (60 K) · `funcoes.php` (92 K) · `templates/` · `html2pdf/` · `pdfs_gerados/` · `deepl_translate.php`	Geração de contratos PDF + tradução AWS Translate / DeepL. Inclui assinatura visual do Pedro.
assinatura/	`criar.php` · `assinar.php` · `certificado.php` (19 K) · `cron_reminders.php` · `funcoes_assinatura_slack.php` (28 K) · `funcoes_assinatura_pdf.php`	Assinatura digital de contratos — fluxo, certificado, lembretes, integração Slack
sng/	`README.md` (11 K) · `get_form_data.php` (16 K) · `submit.php` · `encrypt.php`	Integração SNG (matrículas / portal automóvel)
garantias/	`get.php` · `get_es.php`	Garantias PT/ES

Comunicação

Módulo	Conteúdo	Função
email/	`send.php` (18 K) · `preview.php` · `history.php` · `funcoes_email.php` (37 K) · `funcoes_documentos_email.php`	Envio de emails transaccionais (Brevo)
brevo/	`sendMail.php` · `log.php` · `logs.php` · `templates_preview.php` · `reviews_manager.php`	Wrapper Brevo + revisões + logs
template_hub/	`ai_tools.php` (141 K!) · `bulk_operations.php` (21 K) · `templates_v2.php` · `rascunhos.php` · `comentarios.php` · `assignments.php` · `wp_write_helpers.php`	Hub de templates (emails, contratos) com tooling IA, comentários, atribuições, rascunhos
webhooks/	`brevo/` · `whatsapp/` · `propostas/` · `sheets/` · `translations/` · `hubspot/` · `bulkgate/`	Endpoints públicos para webhooks de cada integração

Automação & dados

Módulo	Conteúdo	Função
automacoes/	`trigger.php` · `get_propriedades.php` · `salome_hub.php` (30 K, root)	Triggers de automação — workflows internos
loops/	15 ficheiros: `sync_iuc` · `sync_marcas` · `sync_marcas_by_ano` · `stand_virtual` · `automatic_emails_*` (5) · `migrar_para_s3` · `novo_sync_emails` (16 K) · `comunidades_es` · `carros_es/`	Scripts long-running (chamados manualmente ou por cron) para sincronizações em batch
filtros/	`get.php` (12 K)	Filtros unificados (marca, modelo, ano, preço…) usados pelo frontend
metricas/	`get.php`	Métricas de negócio
validadores/	`validadores.php` (16 K)	Validações partilhadas (NIF, IBAN, matrícula…) PT + ES
configs/	`tabela_juros.php` · `custos_financiamento.php` · `taxas_servico.php` · `simulador_financiamento_es.php` · `prazos_financiamento_disponiveis_es.php`	Configuração de financiamento (PT + ES)
user/	`get` · `edit` · `create` · `dashboard.php` (15 K) · `analytics.php` (82 K) · `analytics_v2.php` (149 K) · `pedidos/` · `propostas/` · `responsaveis_financiamento/` · `notificacoes` · `logs`	Gestão de utilizadores internos + dashboards + analytics pesados
tools/	28 items · CSVs grandes (`codigos_postais.csv` 25.6 MB, `export_leads_pt.csv` 4.5 MB) · `seed_hubspot_snapshots` (28 K) · `extract/` · `spain/` · `testes/`	Scripts one-off + dados estáticos. Não é app — é pasta de utilitários.

Visualização & ficheiros

Módulo	Conteúdo
view/	`docs/` · `propostas/` · `area_cliente/` — viewers HTML server-side
pdf/	`view/` — viewer de PDFs
downloads/	Storage de ficheiros para download
emails/	`simulador_isv/` · `funcoes.php`

Duplicação confirmada isv/{pt,es} e iuc/{pt,es} existem aqui mas são versões obsoletas — o source of truth está no Queue. Devem ser apagadas (~80 KB de código duplicado).

Crons

Activados via cPanel cron jobs. Os mais importantes:

Cron / Trigger	Ficheiro	Função
`1/min × 2 procs`	`crons/hubspot_sync.php` (121 K)	Polling HubSpot Search API. Processos separados para contacts e deals. log_file_enabled=false (recém-desactivado)
diário	`crons/cron_sync_owners.php`	Sync owners HubSpot
periódico	`crons/hubspot_verify_dealstages.php` (50 K)	Verificação de transições de stage
periódico	`crons/update_propostas_expiradas.php`	Marca propostas como expiradas
periódico	`crons/cron_reminders_assinatura.php` (14 K)	Lembretes de assinatura pendente
diário	`crons/brevo_logs.php`	Aggregation de logs Brevo
periódico	`crons/reset_tokens.php`	Reset de tokens expirados
—	`crons/deal_flow_notify.php` (apidev)	Notificações de fluxo de deals

Webhooks recebidos

Path	De	Função
`/webhooks/hubspot`	HubSpot	Eventos real-time (criação/edição de contacts/deals)
`/webhooks/whatsapp`	Meta Cloud API	Mensagens recebidas via WhatsApp Business
`/webhooks/brevo`	Brevo	Tracking de email (open, click, bounce)
`/webhooks/bulkgate`	BulkGate	SMS delivery reports
`/webhooks/sheets`	Google Sheets (Apps Script)	Sync bidireccional com sheets internos
`/webhooks/translations`	Tradutor pipeline	Notificação de tradução completa
`/webhooks/propostas`	Frontend / externo	Triggers de eventos de proposta

Integrações externas

Sistema	Variável .env	Função
HubSpot	`HUBSPOT_BEARER_TOKEN`	CRM principal — contacts, deals, owners
WhatsApp Meta	`WHATSAPP_META_API_KEY` + `PHONE_NUMBER_ID` + `BUSINESS_ACCOUNT_ID`	WhatsApp Business — mensagens, templates
BulkGate	`BULKGATE_API_KEY` + `APP_ID`	Envio de SMS (PT/ES)
Brevo	`BREVO_API_KEY`	Envio de emails transaccionais
OpenAI	3 keys: `CHATGPT_API_KEY` · `_TRADUTOR_DOCS` · `_TRADUTOR_RESUMO`	GPT para análise / sumários / tradução
OpenRouter	5 keys: `DOC_TRANSLATOR` · `CO2` · `TECHNICAL_DATA` · `WHATSAPP` · `CHUNKING_INDEXER`	Modelos AI especializados por uso
AWS	`AWS_KEY/SECRET` · 2 buckets em eu-west-1	S3 storage (imagens propostas + bucket geral) + Translate/Textract
Pinecone	`PINECONE_API_KEY` + `INDEX_HOST`	Vector DB para knowledge base
DeepL	(em `contratos/deepl_translate.php`)	Tradução de contratos
Microlink	`MICROLINK_API_KEY`	Screenshots / metadata de URLs
REON	`REON_API_KEY`	Validações automotive
Zyte / Decodo	`ZYTE_API_KEY` · `DECODO_*`	Scraping com proxies
Google reCAPTCHA	`GOOGLE_RECAPTCHA_SECRET`	Anti-bot em formulários públicos

Alertas operacionais Logs do hubspot_sync ocupavam 1.2 GB + 988 MB em /api/crons/ (já desactivados, ficheiros existentes ainda no disco). Ficheiro ____funcoes.php de 573 KB órfão na root. isv/ e iuc/ duplicam o Queue. Logs do Brevo + de assinatura também crescem sem rotação.

SECÇÃO 04

Apps.

Plataforma multi-tenant dentro do Backoffice. Apps com base de dados, FTP e código completamente isolados.

Servidor 03 · Apps · /apps

Plataforma multi-app

backoffice.importrust.com/apps/{slug}/...

Localização: Pasta /apps no Backoffice
Bootstrap: _bootstrap.php próprio
Isolamento DB: MySQL user por app
Isolamento FTP: FTP user por app (root v1/)
Provisionamento: cPanel API (auto)
Promote: apidev → api (com backup)
Auth: WordPress users + per-app perms
Apps activas: 5 (ignorando privadas)

Como funciona o isolamento

/apps/ request                            /api/ request
     │                                          │
     ▼                                          ▼
  index.php                                 index.php
     │                                          │
     │ $pasta = 'apps'                          │ $pasta = 'apidev'
     │ NÃO carrega bootstrap principal          │ carrega bootstrap.php
     │ NÃO carrega _configs.php                 │ carrega _configs.php
     │ NÃO existe $wpdb                         │ $wpdb disponível
     │                                          │
     ▼                                          ▼
  router.php → apps/{slug}/api/file.php     router.php → api/{module}/file.php
                  │
                  ▼
            _bootstrap.php (apps/)
            • PDO isolado (user MySQL próprio)
            • Sandbox filesystem (só pasta da app)
            • CORS validation (*.importrust.com + localhost)
            • Auth WordPress opcional

Estrutura de uma app

apps/{slug}/ ├── config.php # DB credentials + admin api key + permissions ├── start.php # entry para agentes/onboarding ├── promote.php # apidev → api + backup ├── credentials.php # recover credentials ├── docs.php # docs endpoint ├── feedback.php # feedback endpoint ├── APP_REFERENCE.md # quick reference (URLs, keys) ├── welcome_kit.json # gerado pelo provisionamento ├── debug/ │ ├── sql.php # SQL debug (read-only) com Api-Key + IP whitelist │ ├── logs.php # request/error logs │ └── migrate.php # runner de migrations ├── v1/ │ ├── api/ # endpoints PROD │ ├── apidev/ # endpoints STAGING │ ├── _migrations/ # SQL migrations │ └── backups/ # backups automáticos do promote └── (lib/ · worker/ · tmp/ · uploads/ — opcional, depende da app)

Plataforma — ficheiros admin

Ficheiro	Função
`apps/_bootstrap.php` (19 K)	Detecta app por URL, abre PDO isolado, valida CORS + auth WP, sandboxes file access
`apps/_rest_router.php` (5 K)	REST routing opcional (`GET /items/:id`) — apps sem `routes.php` usam file-based
`apps/_shared/_wp_db.php`	Ligação à BD WordPress (login unificado)
`apps/_shared/_helpers_rest.php`	Helpers REST partilhados
`apps/admin/create.php` (19 K)	Cria app (DB + user MySQL + FTP + APP_REFERENCE.md) via cPanel API
`apps/admin/sync.php` (6 K)	Sincroniza ficheiros do `_TEMPLATE` para apps existentes
`apps/_TEMPLATE/`	Esqueleto copiado para cada nova app
`apps/DEPLOY.md` (5 K)	Documentação operacional
`apps/ImportrustOS.postman_collection.json`	Colecção Postman da plataforma

Apps activas

Cada app tem URL base backoffice.importrust.com/apps/{slug}, FTP user próprio (root v1/), DB própria importrustadm_{slug} e API key dedicada.

global-trading core

API key: b1c20d37… DB: importrustadm_global_trading FTP: global-trading@backoffice… Estado: prod vazio

Path	Conteúdo
`v1/api/`	Apenas `hello.php` + `example.php` — não promovido ainda
`v1/apidev/`	23 módulos prontos: offers, stock, imports, entities, entity_groups, equipment, currencies, vat_rates, favorites, files, history, search, notifications, notes, settings, dashboard, ai, temp, debug, _lib + health.php + migrations 004→009
`v1/_migrations/`	`001_initial_schema.sql` (24 K) — schema completo
`debug/`	`migrate.php` · `sql.php` · `logs.php`

Plataforma de stock/offers de trading internacional. Toda a app está em apidev — falta promote para prod.

tradutor-pdfs activa

API key: 46be204e… DB: importrustadm_tradutor_pdfs VPS link: tradutor-worker.service

Path	Conteúdo
`v1/api/`	`translate/` · `uploads/`
`v1/worker/`	`run.php` + `config.php`
`v1/lib/`	`ocr_textract.php` (35 K, AWS Textract) · `translate_openrouter.php` (24 K) · `build_pdf.php` (29 K) · `pdf_to_images.php` · `paint_rects.php` · `inpaint_remote.php` · `deskew.php` · `font_detector.php` · `cost_tracker.php` · `summary.php` · `cron_worker.php` · `process_job.php` · `process_job_cli.php`

Pipeline completo de tradução de PDFs: OCR (Textract) → tradução (OpenRouter) → inpaint (VPS) → rebuild PDF.

interno interna

API key: a0f137e9… DB: importrustadm_interno Estado: em desenvolvimento

Path	Conteúdo
`v1/api/`	`health.php` · `env_check.php` · `log.php` · `davs/`

Ferramentas internas Importrust. Pequena, criada 2026-02-18.

admin platform

Control plane da plataforma — não é uma app de negócio. Cria apps via cPanel + sincroniza ficheiros do template.

_TEMPLATE platform

Esqueleto copiado para novas apps. Não correr — é template.

SECÇÃO 05

Cross-cutting.

Login, deploy e ownership da base de dados — coisas que tocam todos os servidores.

Fluxo de login

O login é WordPress + plugin custom — chamado pelo frontend React e validado pelas apps via _wp_db.php.

Frontend React
   │  POST /wp-json/importrust-login/login
   │  { username, password }
   ▼
WordPress Backoffice
   ├─ wp-content/plugins/importrust-login/importrust-login.php
   │   • register_rest_route('importrust-login', '/login', POST)
   │   • custom_authenticate_user()
   │     ├─ wp_authenticate(user, pass)
   │     ├─ INSERT INTO login_logs (user, ip, status)
   │     └─ retorna user_id, capabilities, meta
   │
   └─ wp-content/plugins/wps-hide-login
       • esconde /wp-login.php (segurança)

Apps (request a /apps/{slug}/...)
   └─ _bootstrap.php
       ├─ se $login_obrigatorio = true:
       │   ├─ lê cookie/header de sessão WP
       │   ├─ _wp_db.php → wp_users · wp_usermeta
       │   └─ valida permissão da app (config.php → permissions)
       └─ expõe $user, $user_role à app

Gotcha O ficheiro do plugin tem $hubspot_bearer_token hardcoded no topo. Devia vir do .env do BO. Não é blocker, mas é dívida.

Fluxo de deploy

Servidor	Método	Notas
VPS	SFTP (root)	Edição directa de ficheiros · scripts em /opt/retomas-deploy/ para a app retomas
Queue	SFTP (Hostinger user)	Sem promote — alterações directas em `/api` ou `/apidev`
Backoffice core	FTP (cPanel)	Sem promote — alterações directas em `/api` ou `/apidev`
Apps	FTP (per-app user)	Upload para `v1/apidev/` → `POST /apps/{slug}/promote` → copia para `v1/api/` com backup automático

Workflow operacional do Sérgio Tudo é editado localmente em ~/claude-command-center/projects/ e sincronizado via FTP/SFTP usando as tools do orchestrator (deploy_compare · deploy_preview · deploy_confirm). Os projectos locais são source of truth.

Bases de dados — quem é dono do quê

importrustadm_backofficeprod PRINCIPAL

Vive em: Hostinger MySQL (acessível via 94.46.135.155) Tabelas: 111+

A base de dados onde vive todo o negócio diário. Acedida directamente por:

Backoffice core — full access via _configs.php
Queue — full access via .env (mesmas credenciais)
Apps — só read-only, exposto como {$main_db} em queries
VPS Cars Pipeline — escreve em cars_* tables

Tabelas chave (do STACK.md do BO)

Tabela	Conteúdo
`propostas`	Propostas de viaturas (id_proposta, url_acesso, pais, ativo)
`propostas_info`	153 colunas — ISV, IUC, preço final
`propostas_caracteristicas`	85 colunas — marca, modelo, combustível
`contacts_hubspot`	Contactos HubSpot (synced)
`deals_hubspot`	47 colunas — deals HubSpot
`configs`	Configuração single-row do sistema
`wp_users · wp_usermeta`	Users WordPress (login)
`login_logs`	Logs de tentativas de login (do plugin)
`hubspot_webhook_requests`	Pedidos webhook (lifecycle)
`hubspot_webhooks_queue`	Fila de processamento webhook
`hubspot_owners`	Membros da equipa HubSpot
`deal_stages`	Histórico de mudanças de stage
`cars_offers_raw · cars_emissions`	Cars Pipeline (escrito pelo VPS)
`pt_distritos · pt_concelhos · pt_codigos_postais`	Geografia PT
`comunidades_es · cidades_es · municipios_es`	Geografia ES

queue_importrust CARS PIPELINE

Vive em: VPS MySQL local (porta 3306) Tamanho: 29.6 GB Tabelas: 15

⚠️ Não confundir com o Queue server — o nome é histórico. É a BD usada apenas pelo Cars Pipeline no VPS. O Queue server NÃO usa esta BD.

importrustadm_{app_slug} PER APP

Uma BD MySQL por cada app: importrustadm_global_trading, importrustadm_tradutor_pdfs, importrustadm_interno, etc. Cada uma com user MySQL próprio. Criadas automaticamente via cPanel API quando se cria nova app.

SQLite — StandVirtual cache

/opt/scraping_standvirtual_v2/standvirtual_cache.db — ~600 MB. Cache local do scraper Python. Sincroniza para MySQL e MeiliSearch periodicamente.

MeiliSearch

Índice	Tamanho	Função
`cars_mobilede`	~2 M docs	Search principal de viaturas (frontend de propostas)
`cars_standvirtual`	~42 K docs	Comparação de preços

SECÇÃO 06

Dados & modelo
de negócio.

O que vive na base de dados principal — e o que isso revela sobre como a Importrust trabalha com cada cliente.

Top tabelas por volume

Das 80+ tabelas da BD principal, estas são as que importam para entender o negócio. Ignoradas: caches, logs, WordPress core.

Volumes de produção

Tabela	Linhas	MB	Função
`propostas`	203 174	177	Proposta raiz (url_acesso, país, ativo)
`propostas_info`	216 251	90	153 colunas — ISV, IUC, preços, cálculos
`propostas_caracteristicas`	120 408	4 583	85 colunas — marca, modelo, combustível… 4.5 GB! investigar
`propostas_info_2`	114 722	40	Versão 2 — migração incompleta?
`deals_hubspot`	126 751	23	Mirror dos deals HubSpot (47 colunas)
`contacts_hubspot`	118 519	21	Mirror dos contacts HubSpot (22 colunas)
`deal_stages`	50 801	7	Histórico de mudanças de stage
`modelos`	126 855	20	Catálogo de modelos de viaturas
`marcas`	180	<1	Catálogo de marcas
`caracteristicas_traducoes`	336 418	35	Traduções de características

Infraestrutura & pipes

Tabela	Linhas	MB	Função
`brevo_messageIds_contents`	688 430	1 794	Conteúdo de emails Brevo — 1.8 GB
`pedidos_url_iframe`	663 615	8 074	8 GB — iframes de pedidos (cache de renderização?)
`hubspot_property_history`	309 810	37	Histórico de mudanças de props (sync)
`hubspot_polling_snapshots`	254 762	154	Snapshots do polling 1/min
`hubspot_objects_state`	254 099	167	Estado actual dos objectos
`automatic_emails_logs`	241 018	41	Logs de emails automáticos
`contact_form_submits`	52 729	270	Submissões de forms (inclui Brevo payloads)
`hubspot_webhook_requests`	25 350	23	Requests recebidos via webhook
`pedidos_url`	42 166	565	Pedidos de URL partilhados

Documentos, assinatura, tradução

Tabela	Linhas	MB	Função
`gerador_documentos`	12 805	3	Catálogo de documentos a gerar (tipos)
`gerador_documentos_valores`	422 190	34	Valores/placeholders usados na geração
`propostas_aceites_documentacao`	1 791	<1	Pedidos de docs ao cliente (status: pending/validation/completed/rejected)
`propostas_aceites_documentacao_valores`	5 328	<1	Valores submetidos pelo cliente (slug + valor)
`deals_ficheiros`	—	—	Ficheiros uploaded por deal (`visivel_cliente`)
`deals_documentos_acessos`	42	<1	Log de acessos a docs (enum `origem`: sign/backoffice/area_cliente)
`assinaturas_documentos`	—	—	Envelopes de assinatura digital
`assinaturas_documentos_items`	—	—	Ficheiros dentro do envelope
`assinaturas_eventos`	1 135	<1	Eventos da assinatura
`traducao_documentos`	1 484	243	Pedidos de tradução (app tradutor-pdfs)
`traducao_documentos_paginas`	15 857	357	Páginas traduzidas

Propostas — o objecto central

A proposta é a unidade de negócio. Cada proposta pode tornar-se deal no HubSpot, gerar documentos, pedir documentação ao cliente, ser assinada. Está espalhada por 3 tabelas principais.

propostas (203K · 177 MB)          ← raiz
  id_proposta · url_acesso · pais · ativo

propostas_info (216K · 90 MB · 153 cols)  ← dados de cálculo
  id_proposta → propostas
  novo · tipo_de_combustivel · cilindrada · emissoes_numerico · hibrido · wltp
  data_registo · preco_base_carro · preco_final_carro · tipo_de_veiculo
  isv · iuc · isv_2025 · iuc_2025 · iuc_cilindrada · iuc_co2 · iuc_adicional_co2
  iuc_coeficiente_ano_matriculo · iuc_adicional_gasoleo
  valor_chavenamao_particular · valor_chavenamao_empresa
  tipo_de_isencoes · outros_servicos · taxadeservico · beneficio
  media_mercado_nacional
  (+ ~130 colunas adicionais)

propostas_caracteristicas (120K · 4.5 GB · 85 cols) ← specs da viatura
  id_proposta → propostas
  marca · modelo · combustivel · transmissao · cilindrada
  (85 cols — maior tabela em disco do sistema)

propostas_info_2 (114K · 40 MB) ← versão 2 (migração?)

propostas_bg_queue (168K · 18 MB)       ← fila de background
propostas_aceites_documentacao (1.8K)    ← pedidos de docs
propostas_downloads_extras (15K)         ← ficheiros extra
formularios_enviados_isv_pt (5K)         ← submissões do simulador ISV

O que cada proposta contém

Identificação

id_proposta · url_acesso

url_acesso é o link público que o cliente recebe (ex: backoffice.../view/propostas/{hash})

Cálculo fiscal

ISV + IUC 2024 + 2025

Guardam-se 2 versões (antes/depois de mudança legal), com parcelas (cilindrada, CO2, adicional gasóleo)

Preço

chave-na-mão

Duas variantes: valor_chavenamao_particular vs _empresa

Serviços

tipo_de_isencoes

outros_servicos + taxadeservico + beneficio — margem, extras, promoções aplicadas

Comparação mercado

media_mercado_nacional

Referência de preço em PT (usado para mostrar "poupança vs. nacional")

Características

marca · modelo · ano

Em tabela separada (propostas_caracteristicas) porque são ~85 campos técnicos

Dívida técnica visível propostas_info_2 existe em paralelo com propostas_info (migração incompleta). propostas_caracteristicas tem 4.5 GB para 120K linhas — ~38 KB/linha, anormal. Provável acumulação de JSON/texto em colunas — vale investigar antes de replicar.

Deals · Contacts · sync HubSpot

O mirror local do HubSpot (deals_hubspot + contacts_hubspot) vive na BD principal. Alimentado pelo cron 1/min + webhooks. O código já prevê área do cliente (codigo_acesso_area_cliente).

deals_hubspot · 47 colunas · 126K linhas

deal_id · dealname · dealstage · pipeline · hubspot_owner_id contact_id · id_deal · uuid_deal preco_carro · preco_final · fee_importrust · valor_do_negocio chassi · chassis (x2 — typo) marca · modelo servico_express codigo_acesso_area_cliente ← JÁ EXISTE na DB url_acesso_proposta_aceite ← URL da aceitação de proposta status_documentacao_proposta ← status global da docs document_status ← idem last_dealstage entered_qualificacao · entered_negocio_fechado · entered_pedido_fatura entered_49283185 · entered_979206269 · entered_8545815 · entered_1239757 entered_168415362 · entered_49229880 # timestamps de entrada em stages last_email_sent_date · nr_vezes_falhado data_pronto_para_carregar_ · update_data_previsao_de_carga · update__data_carregamento invalid · invalid_by_automation · invalid_by_automation_reason atualizado · active · association_changed_at formularios_triggers created_at · updated_at · deleted_at · restored_at

contacts_hubspot · 22 colunas · 118K linhas

contact_id · firstname · lastname · email · phone · mobilephone date_of_birth · gender · country hs_lead_status · hubspot_owner_id forma_do_1_contacto · como_conheceu_a_importrust submissao_formulario_count · submissao_do_formulario # contador + origem url_acesso_proposta # URL público com a proposta do cliente isv_simulation_hash_pt # hash do simulador ISV formularios_feedback_triggers_final ref created_at · updated_at · active

Sinais importantes

Código área cliente

codigo_acesso_area_cliente

Coluna já existe em deals_hubspot. A área do cliente foi antecipada na modelação — só falta construir o UI.

URL pública de proposta

url_acesso_proposta

Existe em contacts_hubspot. Cada cliente já tem link directo para a sua proposta — ponto natural de entrada para a área do cliente.

ISV simulation hash

isv_simulation_hash_pt

Cada lead que usa o simulador ISV ganha um hash único. Permite mostrar ao cliente "a minha simulação" vs "a proposta real".

Status documentação

status_documentacao_proposta

Já existe um campo global de estado da documentação no deal — candidato a virar widget no dashboard do cliente.

WordPress como config store

O /wp-admin não é só para login — está a ser usado como editor visual de configuração. 38 post types, 22 deles custom (via CPT UI). Não geram páginas públicas — são linhas de config que a equipa edita como "posts".

Motor HubSpot automation (construído dentro do WP)

Post type	Posts	Função
`hs-trigger-logica`	109	Regras de trigger — condições (campo, condição, valor), passagem de stage, propriedade alterada, envia email para stand/transportadora
`hs-trigger-conteudo`	103	Conteúdos enviados — assunto, body, brevo_template_id, FAQs, CTA, anexos, whatsapp feedback stage, banner
`hs_trigger_conteudo`	7	duplicação com `-` — migração incompleta
`hs-brevo-feedbacks`	5	Feedbacks Brevo
`hs-noreply-sales`	9	Templates no-reply sales
`pontos_de_contacto`	2	Pontos de contacto (override por país)

A automação "real" não está no HubSpot — está no WP hs-trigger-logica (109) + hs-trigger-conteudo (103) = motor de automação completo construído em cima do WP. É ESTE motor que os crons do backoffice (hubspot_sync, verify_dealstages) consultam. Explica porque os workflows do próprio HubSpot parecem ter pouco uso — a lógica está aqui.

Gerador de documentos (templates)

Post type	Posts	Função
`gerador_documentos`	34	Templates de contratos/procurações/modelo_9/etc com placeholders + condições de visibilidade + tipo_sociedade + país
`campos_gerador_docs`	69	Campos disponíveis (slug, tipo, opções) — cada campo pode ter repetidores com até 5 opções + campos que aparecem condicionalmente
`submissao_doc_fields`	19	Definição de campos que o cliente submete — label, slug, tipo, required, opções de select, condições, rejeição automática
`submissao_documentos`	2	Configuração global da submissão

Importante para a área do cliente O submissao_doc_fields é exactamente a meta-config dos documentos que o cliente envia — incluindo rejeicao_automatica. É o lugar certo para acrescentar novos tipos de docs (recibo de vencimento, comprovativo IBAN, etc.) sem mexer em código.

Visualização de stages & fluxo

Post type	Posts	Função
`etapas_visuais`	20	Mapeamento stage HubSpot → etapa visual — is_anchor_point, etapa_anterior/seguinte, dias_min/max, anchor_property_slug, país, tipo_negocio. candidato a timeline do cliente

Automações & notificações

Post type	Posts	Função
`automacoes`	17	Automação: trigger → (email + whatsapp + sms) com template Brevo, CC/BCC, notifica via dashboard/hubspot, pais
`automacoes_notifica`	10	Notificações (presumível: quem recebe cada automação)

Configurações de cálculo

garantia / garantias_es

16 + 8

Escalões de garantia: kms max, idade max, opções de duração (até 5 × duração + preço)

zona_transporte

10

CP prefixes + preços CEVA/FAMA (normal + SUV)

tabela_juros

4

Taxas para financiamento

coeficientes_es · dicionario_taxas · configuracao_taxas

2 + 2 + 2

Tabelas fiscais ES + dicionário de taxas PT

custo_abertura · comissao_servico

1 + 1

Valores single-row de config de preço

responsaveis-credito · team-leaders-grupos

2 + 1

Responsabilidades internas

Agentes IA

Post type	Posts	Função
`agentes-ia`	7	Perfis de agentes: prompt principal, tipo, ferramentas associadas, formato de resposta, ativo
`tools-ia`	6	Tools JSON expostas aos LLMs

Standard / infra WP

Post type	Posts	Função
`acf-field`	344	Definições de campos ACF — o esqueleto da maioria dos CPTs acima
`acf-field-group`	29	Grupos de campos ACF
`revision`	360	Histórico de revisões WP
`attachment`	164	Media library
`seedprod`	1	Plugin SeedProd (landing pages)
`brevo_blocks · custom-css-js · wp_global_styles · wp_navigation · wp_template`	5 total	Infra (editor Gutenberg, CSS injection, Brevo blocks)
`post`	1 auto-draft	Posts WP standard — não usados

Leitura sumária O WordPress é o painel de configuração da operação — não um site de conteúdo. A equipa edita triggers, documentos, etapas, automações e tarifas como "posts" com ACF. Isto explica porque o BO tem 17 plugins WP instalados. Qualquer feature nova deve perguntar: "Isto devia ser uma config editável via CPT, ou código?"

SECÇÃO 07

HubSpot CRM.

Portal 6644558 · EUR · 57 users. Schema rico, 8 pipelines, facturação activa desde Jan 2026.

Schema HubSpot

505 properties em contacts, 889 em deals. A customização é feita a direito no objecto — não há custom objects.

Objecto	Total	Custom	Groups	Notas
Contacts	505	124	16	62 em `contactinformation`, 22 no `formulário_isv_-_pt`
Deals	889	324	11	`dealinformation` tem 281 campos — é o coração
Companies	258	1	—	Quase vazio. Stands tratados como atributo do deal
Invoices	—	5	—	`nif · nif_cliente · proforma_nr · fatura_custo_extra · otros`
Line items / Quotes / Notes / Tasks	—	0	—	Sem customização
Tickets	—	—	4	Sem scope para ler props — mas 4 groups existem
Custom objects	0	—	—	Nenhum criado. Não há objecto "Viatura" nem "Contrato"

Top grupos de properties custom

Grupo	Objecto	Campos	O que revela
dealinformation	deals	281	Ciclo completo de importação — legal, logística, financeiro
contactinformation	contacts	62	Perfil de lead + qualificação
formulário_isv_-_pt	contacts	22	Simulador ISV dedicado
dealstages	deals	17	Checklist de passagens de fase
deal_activity	deals	13	Tracking operacional
order_information	contacts	11	Tracking operacional do cliente

Convenções e dívida

Nomenclatura

snake_case PT

Sem prefixo global. Sufixos: _fin (financiamento), _es/__es_ (Espanha), __gal_ (Galícia), _leg (legacy)

Duplicados confirmados

3 × nome_garantia

homlogacao_individual + homologacao_individual · tipo_pagamento + tipo_de_pagamento · 5 variantes de "previsão de carga"

Legacy auto-declarado

_leg suffix

carro_com_a_importrust_leg e outros com sufixo _leg — devem ser arquivados

Obs. pessoais na schema

obs_fabi

Campo com nome de pessoa (Fabi) em grupo errado — cheira a nota temporária que ficou

Domínios principais do negócio (inferidos da schema) Legalização/aduaneiro (DAV, DUA, IMT, FAMA, COC, FINE, Gelangen, SOH, Mod9) · Financiamento (sub-sistema autónomo, ~30 campos) · ISV/IUC (simulador + 25+ campos entre contacts e deals) · Multi-mercado (PT/ES/Galícia)

Pipelines & equipa

8 deal pipelines · 0 tickets (não usam)

Pipeline	Stages	Função
Sales Portugal (`default`)	12	Funil comercial principal PT
Ops Portugal	25	State machine pós-venda (transporte, IPO/IMT/ISV, entrega)
Sales Spain	—	Espelho ES do Sales PT
Ops Spain	17	Espelho ES do Ops PT
B2B	4	Ciclo curto empresarial
Financiamentos	—	Ciclo de crédito
Retomas	—	Viaturas entregues como contrapartida
Mercado Nacional	—	Stock local sem importação

Sales Portugal — fluxo (12 stages)

RECICLAGEM (20%) → QUALIFICAÇÃO (20%) → PROPOSTAS (30%) → NEGOCIAÇÃO (40%)
    ↓
CONTRATO (90%)
    ↓
Deal Desk (100%, closed) → Validação (100%) → Docs Carro (100%) → Negócio Fechado (100%)

Side stages: On hold (20%), Falhado (0%), Para Recuperar Falhados (10%)

Gotcha crítico O stage com id=closedwon em Sales PT tem label "NEGOCIAÇÃO" com probabilidade 0.4. Qualquer query que filtre por stageId=closedwon está errada. Closed-won está distribuído por 4 stages (Deal Desk, Validação, Docs Carro, Negócio Fechado) — todos com isClosed=true. isClosed=true não equivale a "processo terminado" — há 4 estados pós-fecho antes do deal passar para Ops.

Equipa — 60 owners · 8 teams

Team	Nº	Notas
Sales Portugal	22	Maior equipa
Ops Portugal	10	Pós-venda PT
Sales Spain	5	—
Finance	5	—
CS (Customer Success)	2	—
Ops Spain	1	—
BI	1	—
Fyre	1	—
Sem team	13	Inclui bot "Mauro" (AI chatbot)

Modelo dual PT/ES — não unificado Os pipelines estão espelhados por geografia (Sales PT / Sales ES, Ops PT / Ops ES) em vez de pipeline global com country-field. Qualquer cliente (PT ou ES) atravessa primeiro Sales → Operations. Isto implica que a área do cliente tem de saber desenhar-se em PT e ES mantendo paridade — não é "feature PT" e depois "portar para ES".

Forms · 18 activos

Todos os forms trazem UTMs + gclid hidden + dropdown submissao_do_formulario que identifica a origem para workflows. Zero forms arquivados — muito lixo vivo.

Forms principais (com submissões recentes)

Form	País	Função
Formulário Contacto (Portugal)	PT	Principal do site, redirect `/obrigado/`
Formulário de Contacto c/ Financiamento (PT)	PT	Variante com dados de simulação anexados
Formulário de PopUp (Portugal)	PT	Popup no site
Formulario Contacto V2 (Spain)	ES	Espelho ES do principal
Simulador de Propostas (PT)	PT	Pedido de proposta
Formulário de ISV	PT	Simulador ISV dedicado
Formulário de Crédito	PT	Pedido de crédito
Retomas	PT	Avaliação de retoma (com fotos)
Retomas - Link [Email]	PT	Entry-point que envia link por email para completar

Anomalias confirmadas

Duplicação / lixo

3 suporte PT

3 forms de suporte PT simultâneos, um com typo "Suporte From", outro com nome default nunca renomeado

Ainda "activos" mas antigos

2 forms "Antigo"

Contact PT de 2019 e Spain de 2024 ainda activos com reCAPTCHA — deveriam estar arquivados

Abandonados

Pedidos Pagamento Stands

Criado Nov/2025, 3 campos, zero submissões alguma vez

Falta confirmado

Form Newsletter

Não existe. A task Asana é legítima — não há duplicação a temer.

Commerce Hub · activo desde Jan 2026

Invoices a sério desde Janeiro. Quotes abandonadas. Sem custom objects.

Objecto	Volume	Status
Invoices	173	Numeração `2026-15` → `2026-210`. 31 só em Abril. Valores 247 € a 292.600 €. Quase todas `paid`. `nif_cliente` preenchido. activo
Line items	511	~3 por invoice — custos extra, serviços adicionais
Commerce payments	151	Fluxo de pagamento tracked
Quotes	3	Todas `DRAFT` com `amount=0`. Propostas a clientes NÃO estão aqui — estão no backoffice PHP. abandonado
Products	—	Sem scope para listar (mas o objecto existe)
Subscriptions	0	não usado
Custom objects	0	`/crm/v3/schemas` devolve vazio

Invoices começam em 2026-15, não 2026-1 Indica sincronização automática do backoffice PHP → HubSpot desde Jan 2026 (backoffice é fonte autoritativa, HubSpot recebe para relatórios e ligar ao deal). Quotes ficaram no caminho — estão em PHP.

Activity objects · volumes impressionantes

Objecto	Volume	Notas
Emails	866 955	Qualquer sync completo tem de ser incremental
Notes	417 702	0 custom props. Body em `hs_note_body` — usadas activamente (682 chars médios)
Tasks (HubSpot)	328 143	24k abertas · 304k completadas · 134 props · 0 custom
Calls	210 872	Central telefónica tracked
Meetings	126	Equipa não usa este objecto

Associations · todas standard

Zero labels custom. Tudo HUBSPOT_DEFINED. Labels non-trivial: Primary, Billing Contact (typeId=930/931), Contact with Primary Company, Deal with Primary Company. O backoffice pode usar typeIds standard (1, 4, 5, 6, 19, 20) sem descoberta dinâmica.

Workflows · bloqueados (falta scope)

MISSING_SCOPES em /automation/* A Private App (HUBSPOT_BEARER_TOKEN) não tem o scope automation activado. Sem isto, não conseguimos listar quantos workflows activos existem, nem os seus triggers/actions. Risco: workflows HubSpot podem estar a duplicar ou conflituar com os crons do backoffice (sync_owners, verify_dealstages, hubspot_sync). Para destravar: Settings → Integrations → Private Apps → editar app → ligar scope automation.

SECÇÃO 08

Documentos
& fluxos.

O que o cliente envia, o que a Importrust gera, como é assinado — e a infraestrutura que já está pronta para ser usada pelo cliente.

O que o cliente envia hoje

Dados vividos em propostas_aceites_documentacao (1 791 pedidos) e propostas_aceites_documentacao_valores (5 328 respostas). Hoje captura-se via BD + upload — mas o canal real é email/WhatsApp. Este é o ponto central da futura área do cliente.

Status actual — 1 791 pedidos

Pending

861

Cliente ainda não enviou tudo

Completed

473

Tudo enviado e aceite

Validation

415

A aguardar revisão interna

Rejected

3

Qualidade insuficiente

Tipo contrato

1377 : 375

Particular vs Empresa

País

pt / es

Colecções separadas por país

Slugs de documentos submetidos

Slug	Submetidos	Descrição	Sociedade
`documento_conducao_pt`	894	Carta de condução	particular
`documento_identificacao_pt`	882	CC / Passaporte	particular
`tipo_identificacao_pt`	879	Tipo do doc (CC vs Passaporte)	particular
`morada_pt`	719	Morada completa	particular
`codigo_postal_pt`	693	Código postal	particular
`cidade_pt`	692	Cidade	particular
`codigo_certidao_permanente_pt`	167	Certidão permanente	empresa
`provincia_es`	57	Província	particular ES
`localidad_es`	55	Localidade	particular ES
`telefono_es`	54	Telefone	particular ES
`documento_identificacion_es`	51	DNI/NIE	particular ES
`tipo_identificacion_es`	50	Tipo do doc ES	particular ES
`direccion_es`	50	Morada ES	particular ES
`padron_factura_es`	49	Padrão para facturação	particular ES
`dni_representante_es`	5	DNI do representante	empresa ES
`cif_definitivo_es`	5	CIF definitivo	empresa ES
`certificado_vies_es`	5	Certificado VIES	empresa ES
`escrituras_empresa_es`	5	Escrituras	empresa ES

Dados críticos ainda não capturados como "doc" Recibos de vencimento (para financiamento), comprovativos IBAN, comprovativos morada recentes, fotos da viatura de retoma, fotos pós-acidente — andam por WhatsApp/email e não têm slug no sistema actual. Sinal: os foto_1..foto_6 nos deals HubSpot são uma workaround desesperada que devia ser substituída por storage real.

O que a Importrust gera para o cliente

Vivido em gerador_documentos (12 805 configurações × variantes). Cada linha é uma combinação única de tipo_documento × tipo_contrato × tipo_sociedade. Um volume enorme que tem de ficar todo acessível no portal.

Matriz de documentos (top)

tipo_documento	tipo_contrato	tipo_sociedade	Cnt
contrato	importacao	particular	1 360
procuracao	importacao	particular	1 205
autorizacao_levantamento	importacao	particular	1 142
modelo_9	importacao	particular	1 113
seguro	importacao	particular	1 088
checklist_chegada	importacao	particular	997
autorizacao_levantamento	importacao	empresa	500
contrato	importacao	empresa	497
modelo_9	importacao	empresa	497
procuracao	importacao	empresa	459
seguro	importacao	empresa	430
checklist_chegada	importacao	empresa	397
credito	importacao	particular	141
contrato	importacao_express	particular	70
contrato	legalizacao	particular	57

Tipos × variantes

Tipos de documento

8 tipos

contrato · procuracao · autorizacao_levantamento · modelo_9 · seguro · checklist_chegada · credito · financiamento

Tipos de contrato

3 tipos

importacao · importacao_express · legalizacao

Tipo de sociedade

2 tipos

particular · empresa — ~79% particular, 21% empresa

Valores/placeholders

422 190

gerador_documentos_valores — variáveis preenchidas por doc (templates com substituição)

Faturação — já no HubSpot Commerce Além destes 8 tipos, existem 173 invoices a circular no HubSpot desde Jan 2026 (também entregues ao cliente por email hoje). Devem integrar no portal junto com os docs do gerador_documentos.

Sistema de assinatura

Fluxo completo: envelope → email ao cliente → cliente assina (draw/type/upload) → PDF assinado. Tem event log, reminders, expiry — está pronto a ligar à área do cliente.

assinaturas_documentos

Campo	Função
`id_deal`	Deal associado
`token`	Token público para o signatário
`tipo_sociedade`	`particular` / `empresa`
`status`	`pending` → `partial` → `completed` / `expired`
`nome_signatario · email_signatario`	Identificação do cliente
`email_enviado_em · reminder_1_em · reminder_2_em · ultimo_email_diario`	Cadência de lembretes (até diário)
`hash_envelope`	Hash do conjunto de documentos
`completed_at · expires_at`	Timestamps finais
`ip_ultimo_acesso · user_agent`	Audit trail

assinaturas_documentos_items

Campo	Função
`id_assinatura`	Envelope pai
`id_ficheiro_deal`	→ `deals_ficheiros` (o ficheiro físico)
`tipo_documento · nome_documento`	Identificação
`status`	`pending` / `signed`
`metodo_assinatura`	`draw` · `type` · `upload`
`modo_assinatura`	`digital` · `manual`
`assinatura_base64 · assinatura_path`	Imagem da assinatura
`pdf_assinado_path`	PDF final assinado
`upload_path · upload_original_name`	Caso upload (não digital)
`data_assinatura · ip_assinatura`	Audit legal

Está mais avançado do que parece Reminders automáticos, 3 métodos de assinatura (desenhada/texto/upload), IP + user-agent para prova legal, hash de envelope para integridade. Falta o "hub" onde o cliente vê tudo junto — hoje o fluxo é um email por envelope.

A área do cliente está metade construída

Durante a exploração da DB descobrimos sinais claros de que o modelo já foi pensado. Vários campos existem à espera que o UI seja construído.

Campos que já existem

Tabela	Campo	O que revela
`deals_hubspot`	`codigo_acesso_area_cliente`	O token de acesso à área do cliente já tem coluna reservada em cada deal. Só falta gerar e usar.
`deals_hubspot`	`url_acesso_proposta_aceite`	URL já gerado para o cliente aceder à proposta — antecessor natural da "minha proposta" na área cliente
`deals_hubspot`	`status_documentacao_proposta` + `document_status`	Status global da docs no deal — candidato a widget de progresso no dashboard do cliente
`contacts_hubspot`	`url_acesso_proposta`	Cada cliente já tem link directo para a sua proposta
`deals_ficheiros`	`visivel_cliente` (tinyint)	Flag de visibilidade ao cliente já existe por ficheiro. Permite à equipa marcar explicitamente o que o cliente vê.
`deals_ficheiros`	`requer_assinatura` (`nao · digital · manual`)	Cada ficheiro já sabe se precisa de assinatura — entrada natural para a UI do cliente
`deals_documentos_acessos`	`origem` enum: `sign · backoffice · area_cliente`	O enum JÁ inclui "area_cliente". O log está preparado para registar acessos feitos via área cliente (actualmente sem uso — 0 linhas com essa origem).
`assinaturas_documentos`	`token` + `email_signatario`	Cada assinatura já tem token de acesso público — integrável no portal como "assinaturas pendentes"

Peças que já funcionam isoladas

Upload de ficheiros

deals_ficheiros + S3

Sistema de upload existe. Só falta expor ao cliente uma UI para submeter (não só à equipa).

Pedido de docs

propostas_aceites_documentacao

BD preparada com status, rejeição, motivo. Hoje usado por agente interno — precisa de UI cliente.

Assinatura

assinaturas_documentos(_items)

Fluxo completo com email, reminders, 3 métodos. Integra-se facilmente.

Propostas

url_acesso público

Cada proposta já tem link único. Pode ser a "entrada" da área do cliente.

Faturação

HubSpot Invoices

173 invoices fluindo desde Jan 2026. API HubSpot permite listá-las por contact_id.

Comunicação

Emails · WhatsApp · SMS

3 canais já integrados. Podem virar notificações do portal (em vez de estar a caçar docs por WhatsApp).

Leitura Construir a área do cliente é sobretudo juntar peças que já existem debaixo de uma UI unificada, com auth (via codigo_acesso_area_cliente ou WP login do cliente), notificações, e os dois fluxos novos que o Sérgio chamou: upload de docs pelo cliente (recibos vencimento, etc) e download organizado (facturas, contratos, certidões).

SECÇÃO 09

Backlog Asana.

28 tasks pendentes. Categorizadas por relevância para a área do cliente.

Backlog categorizado

Fonte: tasks table do command-center (sincronizada de Asana). Total: 28 tasks pending + 1 ready.

Ligadas à área do cliente

Task	Secção	Resumo
Agent Hub	Área Cliente	Único task com tag explícita "Área Cliente". Sem descrição — placeholder do conceito novo.
Assinatura da proposta pelo cliente	Dash Interno	2 páginas: print do view + confirmação com código SMS. Ref manie.pt. Lançamento previsto 31/03/2026.
Bot: dizer se compensa importar	—	Feature do bot (cliente)
Bot: botão/link clicável	—	Remove fricção — não copiar URL
Bot: ir buscar carros sem links	—	Cliente descreve o que quer, bot propõe

Tocam no cliente, UI interno

Task	Secção	Resumo
[Documentação] Novo Flow para a dashboard	Dash Interno	BD aceita/rejeita docs submetidos pelo cliente, batch ou individual, com motivo
Form newsletter	Website	Nome+email → Brevo (tag) + HubSpot (propriedade + observação)
[Leads Simuladores] - Abrir em blank	Infraestrutura	UX fix nos simuladores públicos
API Garantias	—	Endpoint para expor garantias ao cliente

Subtasks órfãs — motor de templates

Sem descrição mas nomes sugerem engine de geração de documentos com placeholders (relevante porque toca no doc que o cliente recebe):

Criar lógica para substituição de inputs por placeholders - Backend
Integrar lógica e enviar post para API que faz substituição dos dados (×2)
Backend / Back-End / Pedido (×2)

Puramente interno (11 tasks)

Task	Secção / Contexto
Mapa Km's - Mapeamento automático	Dayoff ↔ Sheets
Correção novo Analytics	Dash Interno
Métricas e automação de dados Hubspot	Infraestrutura (GSheets)
Automatização de Expirar Lista	Global Trading (app interna)
[Sheets + Dashboard] Ligar 2 sheets	Infraestrutura
Fwd: Análise IVR	Análise central de chamadas
[Coches.net] Melhorar precisão de pesquisa	Search interno
[Dashboard] Tasks Soltas	Dashboard admin
[Automações] Gerais	Placeholder
Seleciona um Filtro	Helper do backlog Asana
Subtask de teste	Ignorar

Prioridades implícitas Lançamento já previsto: Assinatura da proposta pelo cliente (31/03/2026). Features do bot (3 tasks) estão todas na mesma área de fricção. A task "Agent Hub" é o placeholder do conceito grande — candidato a virar a "casa" onde tudo encaixa.

URLs por servidor

Referência rápida. Asteriscos marcam endpoints expostos publicamente sem auth.

VPS

URL	Função
`https://vps.importrust.com/amelia-stream`	SSE stream da Amélia (proxy → :3099)
`https://vps.importrust.com/amelia-upload`	Upload da Amélia
`https://vps.importrust.com/amelia-notify`	Notify da Amélia
`https://retomas.importrust.com` *	App pública de retomas (Next.js)

Queue

URL	Função
`queue.importrust.com/api/propostas/get`	API propostas
`queue.importrust.com/api/isv/{pt,es}/calcular`	Cálculo ISV
`queue.importrust.com/api/iuc/{pt,es}/calcular`	Cálculo IUC
`queue.importrust.com/api/amelia/mcp.php`	MCP entry da Amélia
`queue.importrust.com/api/webhooks/whatsapp/webhook` *	Webhook WhatsApp Meta
`queue.importrust.com/api/mcp/v1/public/widget.js` *	Widget de chat embedável
`queue.importrust.com/api/mcp/v1/public/chat_entry.php` *	Entry do widget

Backoffice (core)

URL	Função
`backoffice.importrust.com/wp-json/importrust-login/login` *	Login (plugin custom)
`backoffice.importrust.com/api/propostas/*`	API propostas
`backoffice.importrust.com/api/contratos/*`	API contratos
`backoffice.importrust.com/api/hubspot/*`	API HubSpot
`backoffice.importrust.com/api/email/send`	Envio email
`backoffice.importrust.com/api/template_hub/*`	Template hub
`backoffice.importrust.com/webhooks/{hubspot,whatsapp,brevo,bulkgate,sheets,translations,propostas}` *	Webhooks recebidos

Backoffice Apps

URL pattern	Função
`/apps/admin/create`	Criar nova app (admin only)
`/apps/admin/sync`	Sync ficheiros do template
`/apps/{slug}/v1/api/{endpoint}`	Endpoints prod da app
`/apps/{slug}/v1/apidev/{endpoint}`	Endpoints staging
`/apps/{slug}/promote`	Promote apidev → api
`/apps/{slug}/debug/{sql,logs,migrate}`	Debug tools (Api-Key)
`/apps/{slug}/credentials`	Recuperar credenciais
`/apps/{slug}/docs?topic=onboarding`	Docs da app

Alertas operacionais activos

Servidor	Item	Detalhe / acção
VPS	Disco a 96% (92/96 GB)	Risco real. Pasta `not_used` + logs avolumam. Ver para libertar.
VPS	Swap a 95% (3.8/4 GB)	Memória sob pressão
VPS	`/root/not_used` + `/opt/not_used`	amelia-old, amelia-dev, claude-0 — limpar quando confirmado
Queue	`workers/worker_debug.log` = 115 MB	Sem rotação. Truncar.
Queue	`webhooks/whatsapp/webhook_log.txt` = 12.5 MB	Sem rotação. Truncar ou rotar.
BO	`crons/hubspot_sync_runtime_log_contacts.txt` = 1.2 GB	Logging desactivado em `log_file_enabled=false` · ficheiro ainda no disco
BO	`crons/hubspot_sync_runtime_log_deals.txt` = 988 MB	Idem
BO	`____funcoes.php` 573 KB órfão na root	Legacy (4 underscores) — mover para revisão
BO	`isv/` + `iuc/` duplicados do Queue	Source of truth está no Queue — apagar do BO
BO	`tools/codigos_postais.csv` 25.6 MB	Asset estático grande — considerar mover para storage
BO	HubSpot bearer hardcoded em `importrust-login.php`	Mover para `.env`
Apps	`global-trading` com prod vazio	23 módulos prontos em apidev — falta promote
BO	`propostas_caracteristicas` 4.5 GB / 120K linhas	~38 KB/linha — investigar acumulação de texto/JSON
BO	`pedidos_url_iframe` 8 GB / 663K linhas	Cache de iframes? Precisa de rotação/expiry
BO	`brevo_messageIds_contents` 1.8 GB	Conteúdo bruto de emails — considerar mover para S3
BO	`propostas_info_2` em paralelo com `propostas_info`	Sinal de migração incompleta — decidir qual é source of truth
BO	`foto_1..foto_6` em deal properties HubSpot	Workaround para guardar fotos — devia ser storage real (S3)
BO	HubSpot `stageId=closedwon` tem label "NEGOCIAÇÃO"	Qualquer query que filtre por `closedwon` está errada
BO	HubSpot Private App sem scope `automation`	Não vemos workflows — risco de duplicação com crons. Ligar scope.
BO	HubSpot Forms: 3 suporte + 2 "Antigo" + 1 nunca submetido	Limpeza: arquivar forms antigos, renomear "Suporte From"
BO	WP CPTs `hs-trigger-conteudo` vs `hs_trigger_conteudo`	103 posts em um, 7 no outro (com underscore) — migração incompleta
BO	Motor de automação HubSpot vive no WP (212 posts)	Não documentado fora do WP — source of truth das automações é o CPT, não o HubSpot

Glossário

Termo	Significado
apidev	Versão staging dos endpoints. Existe em paralelo com `api` (prod). Em apps usa-se `v1/apidev`.
promote	Acção que copia `v1/apidev/` para `v1/api/` com backup automático. Só existe na plataforma de Apps.
bootstrap	Ficheiro PHP que prepara o ambiente da request — abre PDO, valida CORS, opcionalmente exige login.
source of truth	Onde a versão correcta de algo vive. Cars Pipeline = VPS. ISV/IUC = Queue. Frontend propostas = BO.
MCP	Model Context Protocol. No Queue refere-se ao sub-sistema próprio de tools para agentes IA + widget de chat.
Amélia	Agente IA persistente. Vive como processo PM2 no VPS, mas chama endpoints do Queue.
cron-runner	Wrapper bash usado no VPS (`/opt/cron-runner.sh`) que dá nome + locking a um cron.
Welcome Kit	JSON gerado quando se cria uma nova app — contém credentials DB, FTP, API key, URLs.
Hostinger shared	Hosting partilhado — sem processos persistentes, sem SSH root. Apenas execução por request HTTP.
codigo_acesso_area_cliente	Coluna em `deals_hubspot` reservada para o token de acesso do cliente à sua área — ainda não preenchida/usada.
visivel_cliente	Flag (0/1) em `deals_ficheiros` que marca que ficheiros a equipa quer expor ao cliente. Já implementada, falta UI cliente.
url_acesso_proposta	URL público único de cada proposta (hash). Porta de entrada natural para a futura área do cliente.
propostas_aceites_documentacao	Sistema de pedido de docs ao cliente (status pending/validation/completed/rejected). 1 791 registos. Tabela pai.
gerador_documentos	Catálogo de documentos que a Importrust gera (contrato, procuração, modelo_9, seguro, checklist_chegada, autorização_levantamento, crédito, financiamento) por tipo_contrato × tipo_sociedade.
assinaturas_documentos / _items	Sistema de envelope de assinatura digital. Token por envelope, 3 métodos (draw/type/upload), reminders automáticos.
Commerce Hub (HubSpot)	Feature do HubSpot para facturação: invoices, line items, payments. Activa desde Jan 2026, alimentada pelo backoffice.
closed-won distribuído	No Sales PT, o estado "ganho" está espalhado por 4 stages (Deal Desk, Validação, Docs Carro, Negócio Fechado), todos com `isClosed=true, probability=1.0`.
CPT (Custom Post Type)	Tipo de post do WordPress declarado via plugin CPT UI. No BO a maioria dos CPTs não servem páginas públicas — são "linhas de configuração" editáveis no `/wp-admin`.
ACF	Advanced Custom Fields — plugin que adiciona campos customizados aos CPTs. Explica os 344 `acf-field` no WP.
hs-trigger-logica / hs-trigger-conteudo	Dois CPTs que juntos formam o motor de automação HubSpot da Importrust (regras + conteúdos). 212 posts no total.
etapas_visuais	CPT que mapeia stages HubSpot → etapas visíveis. Base natural da timeline do cliente no portal.
gerador_documentos / submissao_doc_fields	CPTs que configuram respectivamente o que a Importrust gera (templates) e o que o cliente submete (campos). Editáveis pela equipa sem código.

Como ler este documento Cada capítulo de servidor tem o mesmo formato — identificação, módulos, integrações, crons, conexões, alertas. Para tarefas operacionais começa pelo capítulo do servidor afectado. Para entender um fluxo cross-server (ex: tradutor) usa a tabela "Fluxos cross-server" (página 5).

InfraestruturaImportrust.

Índice

Visão geral.

Mapa do sistema

Fluxos cross-server

Quem é dono do quê

VPS.

vps.importrust.com

Camadas activas

Mapa de pastas

Aplicações & serviços

Processos PM2

Serviços systemd custom

Portas abertas

Apache vhosts

Cars Pipeline

Porquê sequencial?

Tabelas chave (MySQL queue_importrust)

Índices MeiliSearch

Crons activos

Integrações externas

Quem chama o VPS

Queue.

queue.importrust.com

Mapa de pastas (prod /api)

Módulos da Queue

Conexões externas (do .env)

Quem chama a Queue

MCP — sub-sistema

O que isto faz

Backoffice.

backoffice.importrust.com

Arquitectura de routing

Dois mundos isolados

Mapa de pastas (root)

Módulos /api

Negócio core

Comunicação

Automação & dados

Visualização & ficheiros

Crons

Webhooks recebidos

Integrações externas

Apps.

Plataforma multi-app

Como funciona o isolamento

Estrutura de uma app

Plataforma — ficheiros admin

Apps activas

global-trading core

tradutor-pdfs activa

interno interna

admin platform

_TEMPLATE platform

Cross-cutting.

Fluxo de login

Fluxo de deploy

Bases de dados — quem é dono do quê

importrustadm_backofficeprod PRINCIPAL

Tabelas chave (do STACK.md do BO)

queue_importrust CARS PIPELINE

importrustadm_{app_slug} PER APP

SQLite — StandVirtual cache

MeiliSearch

Dados & modelode negócio.

Top tabelas por volume

Volumes de produção

Infraestrutura & pipes

Documentos, assinatura, tradução

Propostas — o objecto central

O que cada proposta contém

Deals · Contacts · sync HubSpot

deals_hubspot · 47 colunas · 126K linhas

contacts_hubspot · 22 colunas · 118K linhas

Sinais importantes

WordPress como config store

Motor HubSpot automation (construído dentro do WP)

Gerador de documentos (templates)

Visualização de stages & fluxo

Automações & notificações

Infraestrutura
Importrust.

Tabelas chave (MySQL `queue_importrust`)

Mapa de pastas (prod `/api`)

Conexões externas (do `.env`)

Dados & modelo
de negócio.

Documentos
& fluxos.