Back-End

Portal de solicitações para desentupimento em condomínios e empresas: automação e gestão

Como criar portais de solicitações para desentupimento em condomínios e empresas. Arquitetura, fluxos de trabalho, automação e integração com equipes de campo.

O síndico do Edifício Monte Carlo recebe às 6h30 de uma segunda-feira a mensagem no grupo do WhatsApp: “Vazamento no garagem, água subindo pelo ralo do box 12”. Simultaneamente, a gerente de facilities de um campus corporativo na Faria Lima abre chamado por e-mail para a equipe de manutenção: “Cheiro forte de esgoto no banheiro do 3º andar, suspeita de coluna entupida”. Em ambos os cenários, a resposta depende de quem visualiza primeiro, quem tem contato da desentupidora de plantão e se há histórico anterior daquele ponto da rede. A ausência de um canal único, rastreável e priorizado transforma incidentes hidráulicos em crises operacionais.

Um portal de solicitações para desentupimento resolve essa fragmentação ao centralizar a entrada, triagem, despacho e acompanhamento de cada ocorrência. Diferente de planilhas ou formulários genéricos, ele incorpora regras de negócio do setor: tipologia de rede (pluvial, esgoto, gordura), criticidade por localização (subsolo, área comum, unidade privativa), SLAs diferenciados e integração direta com a equipe de campo. O resultado é redução do tempo de resposta, rastreabilidade para compliance e dados para manutenção preditiva.

Este artigo detalha a arquitetura, os fluxos e as decisões técnicas para construir um portal robusto, escalável e aderente às necessidades de condomínios verticais, horizontais e complexos empresariais.

Arquitetura de informação e modelagem de domínio

O domínio central gira em torno da entidade Chamado, mas sua riqueza está nos relacionamentos. Um chamado pertence a uma Unidade (apartamento, sala, loja, área comum), que pertence a um Empreendimento (condomínio, parque empresarial, shopping), gerido por uma Administradora ou Gestão Própria. Usuários assumem papéis: Solicitante (morador, funcionário, zelador), Triador (síndico, gestor de facilities, porteiro), Técnico (equipe interna ou prestadora) e Administrador (configuração de regras, relatórios, usuários).

A modelagem relacional recomendada utiliza PostgreSQL com as seguintes tabelas principais:

CREATE TABLE empreendimentos (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  nome VARCHAR(150) NOT NULL,
  tipo VARCHAR(30) NOT NULL, -- 'condominio_vertical', 'condominio_horizontal', 'empresarial', 'misto'
  endereco JSONB NOT NULL,
  configuracoes JSONB DEFAULT '{}'::jsonb,
  criado_em TIMESTAMPTZ DEFAULT now()
);

CREATE TABLE unidades (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  empreendimento_id UUID REFERENCES empreendimentos(id),
  identificador VARCHAR(50) NOT NULL, -- 'Apto 101', 'Sala 302', 'Box 12', 'Piscina'
  torre_bloco VARCHAR(50),
  andar INTEGER,
  tipo VARCHAR(30),
  responsaveis UUID[] -- array de user_ids
);

CREATE TABLE chamados (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  numero_sequencial BIGSERIAL UNIQUE,
  unidade_id UUID REFERENCES unidades(id),
  solicitante_id UUID REFERENCES usuarios(id),
  triador_id UUID REFERENCES usuarios(id),
  tecnico_id UUID REFERENCES usuarios(id),
  categoria VARCHAR(40) NOT NULL, -- 'esgoto', 'pluvial', 'gordura', 'caixa_inspecao', 'fossa', 'outro'
  subcategoria VARCHAR(60),
  criticidade VARCHAR(20) NOT NULL DEFAULT 'normal', -- 'critica', 'alta', 'normal', 'baixa'
  status VARCHAR(30) NOT NULL DEFAULT 'aberto', -- 'aberto', 'triagem', 'aguardando_aprovacao', 'despachado', 'em_andamento', 'aguardando_peca', 'finalizado', 'cancelado', 'reaberto'
  descricao TEXT NOT NULL,
  localizacao_detalhada TEXT,
  sinais_observados TEXT[], -- array: 'refluxo', 'mau_cheiro', 'lentidao_escoamento', 'borbulhamento', 'vazamento_visivel'
  prioridade_calculada INTEGER GENERATED ALWAYS AS (
    CASE criticidade
      WHEN 'critica' THEN 100
      WHEN 'alta' THEN 75
      WHEN 'normal' THEN 50
      ELSE 25
    END
  ) STORED,
  sla_alvo INTERVAL GENERATED ALWAYS AS (
    CASE criticidade
      WHEN 'critica' THEN '1 hour'
      WHEN 'alta' THEN '4 hours'
      WHEN 'normal' THEN '24 hours'
      ELSE '72 hours'
    END
  ) STORED,
  aberto_em TIMESTAMPTZ DEFAULT now(),
  triado_em TIMESTAMPTZ,
  despachado_em TIMESTAMPTZ,
  iniciado_em TIMESTAMPTZ,
  finalizado_em TIMESTAMPTZ,
  criado_em TIMESTAMPTZ DEFAULT now(),
  atualizado_em TIMESTAMPTZ DEFAULT now()
);

CREATE TABLE chamado_historico (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  chamado_id UUID REFERENCES chamados(id),
  usuario_id UUID REFERENCES usuarios(id),
  acao VARCHAR(50) NOT NULL,
  de_status VARCHAR(30),
  para_status VARCHAR(30),
  observacao TEXT,
  metadados JSONB DEFAULT '{}'::jsonb,
  criado_em TIMESTAMPTZ DEFAULT now()
);

CREATE TABLE anexos (
  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
  chamado_id UUID REFERENCES chamados(id),
  usuario_id UUID REFERENCES usuarios(id),
  tipo VARCHAR(30), -- 'foto', 'video', 'laudo', 'orcamento', 'nota_fiscal', 'outro'
  url TEXT NOT NULL,
  thumbnail_url TEXT,
  metadados JSONB DEFAULT '{}'::jsonb,
  criado_em TIMESTAMPTZ DEFAULT now()
);

Campos JSONB em empreendimentos.configuracoes armazenam regras específicas: horários de silêncio para notificações, lista de prestadoras credenciadas, SLAs personalizados por categoria, campos obrigatórios por tipo de ocorrência. Isso evita tabelas rígidas e permite onboarding de novos condomínios sem migrações de schema.

Fluxo de triagem automatizada e matriz de prioridade

A triagem é o coração operacional. O portal deve classificar automaticamente a criticidade no momento da criação do chamado, combinando:

  1. Palavras-chave na descrição: “vazamento ativo”, “refluxo”, “alagando”, “risco elétrico” → critica
  2. Categoria + localização: esgoto em subsolo/garagem → alta; gordura em cozinha industrial → alta
  3. Sinais observados: array com múltiplos sinais (refluxo + mau cheiro + borbulhamento) eleva prioridade
  4. Histórico da unidade: 3+ chamados nos últimos 30 dias no mesmo ponto → alta
  5. Horário: fora do expediente comercial + criticidade normal → eleva para alta (equipe reduzida)

A implementação pode ser uma Pipeline de Regras no back-end:

// src/chamados/triagem/triagem.pipeline.ts
export interface RegraTriagem {
  nome: string;
  peso: number;
  avaliar: (contexto: ContextoTriagem) => boolean;
}

const regras: RegraTriagem[] = [
  { nome: 'vazamento_ativo', peso: 40, avaliar: c => /vazamento\s+ativo|alagando|jorrando/i.test(c.descricao) },
  { nome: 'refluxo_esgoto', peso: 35, avaliar: c => c.sinais.includes('refluxo') && c.categoria === 'esgoto' },
  { nome: 'subsolo_garagem', peso: 20, avaliar: c => ['subsolo', 'garagem', 'estacionamento'].some(l => c.localizacao_detalhada?.toLowerCase().includes(l)) },
  { nome: 'recorrencia_recente', peso: 25, avaliar: async c => {
      const count = await prisma.chamado.count({
        where: { unidadeId: c.unidadeId, categoria: c.categoria, abertoEm: { gte: subDays(new Date(), 30) } }
      );
      return count >= 3;
    }
  },
  { nome: 'fora_expediente', peso: 10, avaliar: c => {
      const hora = new Date().getHours();
      return (hora < 7 || hora > 19) && c.criticidadeInicial === 'normal';
    }
  },
];

async function calcularCriticidade(contexto: ContextoTriagem): Promise<Criticidade> {
  let score = 0;
  for (const regra of regras) {
    if (await regra.avaliar(contexto)) score += regra.peso;
  }
  if (score >= 80) return 'critica';
  if (score >= 55) return 'alta';
  if (score >= 30) return 'normal';
  return 'baixa';
}

Essa abordagem permite ajustar pesos e adicionar regras sem deploy via feature flags ou configuração em banco. O resultado da triagem define o SLA, a fila de despacho e os canais de notificação.

Integração com equipe de campo: despacho, evidências e laudos

O técnico recebe o chamado no aplicativo móvel (React Native, Flutter ou PWA com service workers para offline-first). O fluxo de despacho:

  1. Notificação push com dados essenciais: endereço, unidade, categoria, criticidade, descrição, fotos do solicitante
  2. Aceite obrigatório com geolocalização confirmando deslocamento
  3. Checklist dinâmico por categoria: para “caixa de gordura” → nível de enchimento, tipo de resíduo, limpeza realizada, destinação do resíduo; para “coluna de esgoto” → ponto de acesso, equipamento usado (hidrojato, mola, inspeção por vídeo), metragem desobstruída
  4. Evidências obrigatórias: foto antes/depois, vídeo curto da vazão restabelecida, assinatura digital do responsável no local
  5. Laudo técnico estruturado: JSON com campos padronizados (causa raiz, recomendação preventiva, necessidade de retorno, peças substituídas)
  6. Finalização com sincronização automática; se offline, fila local com background sync ao reconectar

A API de despacho expõe endpoints RESTful versionados:

paths:
  /api/v1/chamados/{id}/despachar:
    post:
      summary: Despacha chamado para técnico
      parameters:
        - $ref: '#/components/parameters/ChamadoId'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required: [tecnicoId]
              properties:
                tecnicoId:
                  type: string
                  format: uuid
                observacaoDespacho:
                  type: string
      responses:
        '200':
          description: Chamado despachado
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChamadoDetalhado'
  /api/v1/chamados/{id}/evidencias:
    post:
      summary: Anexa evidências (multipart/form-data)
      requestBody:
        content:
          multipart/form-data:
            schema:
              type: object
              required: [arquivos, tipo]
              properties:
                arquivos:
                  type: array
                  items:
                    type: string
                    format: binary
                tipo:
                  type: string
                  enum: [foto_antes, foto_depois, video_vazao, laudo_assinado]
                metadados:
                  type: object
  /api/v1/tecnicos/{id}/chamados-pendentes:
    get:
      summary: Lista chamados aguardando aceite do técnico
      responses:
        '200':
          description: Lista paginada

A integração com prestadoras externas ocorre via Webhooks assinados (HMAC-SHA256). O portal envia chamado.despachado com payload completo; a prestadora responde com chamado.aceito ou chamado.recusado (com justificativa). Falhas de entrega têm retry exponencial (1min, 5min, 15min, 1h) e dead letter queue para intervenção manual.

Autenticação, autorização e multi-tenancy

O portal atende múltiplos empreendimentos com isolamento de dados (multi-tenancy lógico). A estratégia recomendada:

  • Autenticação: JWT access tokens (15min) + refresh tokens (30 dias, rotação, revogação por dispositivo)
  • Autorização: RBAC com permissions granulares (chamado:criar, chamado:triar, chamado:despachar, chamado:visualizar_todos, relatorio:exportar, config:gerenciar_empreendimento)
  • Contexto de tenant: Middleware extrai empreendimento_id do token (claim tenant_id) ou do subdomínio (condominio-x.portal.com) e injeta em request.tenantId; query scopes automáticos no Prisma/TypeORM garantem isolamento
  • LGPD: Consentimento granular por finalidade (abertura de chamado, notificações, relatórios anonimizados); Data Subject Request endpoint para exportação/exclusão; logs de acesso a dados pessoais (LGPD Art. 37)

Exemplo de middleware de tenant:

// src/common/middleware/tenant.middleware.ts
export const tenantMiddleware = async (req: Request, res: Response, next: NextFunction) => {
  let tenantId: string;
  
  // 1. Subdomínio: condominio-x.portal.com
  const subdomain = req.hostname.split('.')[0];
  if (subdomain !== 'app' && subdomain !== 'api') {
    const empreendimento = await prisma.empreendimento.findUnique({ where: { slug: subdomain } });
    if (empreendimento) tenantId = empreendimento.id;
  }
  
  // 2. Claim no JWT (fallback para apps mobile)
  if (!tenantId && req.user?.tenantId) {
    tenantId = req.user.tenantId;
  }
  
  if (!tenantId) {
    return res.status(400).json({ error: 'TENANT_REQUIRED', message: 'Contexto de empreendimento não identificado' });
  }
  
  // Valida acesso do usuário ao tenant
  const temAcesso = await prisma.usuarioEmpreendimento.findUnique({
    where: { usuarioId_empreendimentoId: { usuarioId: req.user.id, empreendimentoId: tenantId } }
  });
  
  if (!temAcesso) {
    return res.status(403).json({ error: 'TENANT_FORBIDDEN', message: 'Usuário sem acesso a este empreendimento' });
  }
  
  req.tenantId = tenantId;
  next();
};

Dashboard administrativo e inteligência operacional

O painel de gestão transforma dados brutos em decisões. Métricas essenciais:

Métrica Fórmula Frequência Ação se fora da meta
TMA (Tempo Médio de Atendimento) AVG(triado_em - aberto_em) Diária Revisar regras de triagem / equipe de plantão
MTTR (Tempo Médio de Resolução) AVG(finalizado_em - aberto_em) Semanal Analisar gargalos por categoria / prestadora
FCR (Resolução no Primeiro Contato) COUNT(finalizado_em IS NOT NULL AND reaberto = false) / COUNT(*) Semanal Treinamento técnico / checklists mais completos
Taxa de Reabertura COUNT(reaberto = true) / COUNT(finalizado) Quinzenal Auditoria de laudos / causa raiz mal resolvida
Chamados Recorrentes por Ponto GROUP BY unidade_id, categoria HAVING COUNT(*) > 3 Mensal Plano de manutenção preventiva / inspeção por vídeo
SLA Cumprido % COUNT(finalizado_em <= aberto_em + sla_alvo) / COUNT(finalizado) Diária Alerta automático para gestor / escala extra

O dashboard usa Apache ECharts ou Recharts com server-side aggregation via materialized views no PostgreSQL atualizadas a cada 5 minutos (REFRESH MATERIALIZED VIEW CONCURRENTLY). Filtros: período, empreendimento, torre/bloco, categoria, criticidade, técnico, prestadora. Exportação CSV/PDF agendada por e-mail para síndicos e administradoras.

Observabilidade, testes e deploy

Um portal crítico exige observabilidade em três pilares:

  1. Logs estruturados (JSON) com requestId, userId, tenantId, traceId (OpenTelemetry) → Loki/Grafana ou Datadog
  2. Métricas RED (Rate, Errors, Duration) por endpoint + métricas de negócio (chamados_criados_total, chamados_finalizados_total, sla_violado_total) → Prometheus + Alertmanager
  3. Traces distribuídos para fluxos assíncronos (webhooks, filas BullMQ/Redis, notificações) → Jaeger ou Tempo

Testes:

  • Unitários (Jest/Vitest): regras de triagem, cálculos de SLA, validadores de formulário
  • Integração (Supertest + Testcontainers PostgreSQL): fluxos completos API → DB → Webhook
  • Contrato (Pact): consumidor (app técnico) ↔ provedor (API despacho)
  • Carga (k6): 1000 VUs criando chamados simultâneos, 200 técnicos aceitando/atualizando, 50 webhooks/s → validar p95 < 500ms, taxa de erro < 0.1%

Pipeline CI/CD (GitHub Actions / GitLab CI):

jobs:
  test:
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:16
        env: { POSTGRES_PASSWORD: test }
        ports: [5432:5432]
        options: >-
          --health-cmd "pg_isready"
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20', cache: 'npm' }
      - run: npm ci
      - run: npx prisma migrate deploy
      - run: npm run test:unit
      - run: npm run test:integration
      - run: npm run test:contract
  load-test:
    needs: test
    if: github.event_name == 'pull_request' && github.base_ref == 'main'
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: k6 run --vus 500 --duration 5m scripts/load-test.js
  deploy-staging:
    needs: load-test
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: docker build -t portal-desentupimento:${{ github.sha }} .
      - run: docker push registry.example.com/portal-desentupimento:${{ github.sha }}
      - run: kubectl set image deployment/portal portal=registry.example.com/portal-desentupimento:${{ github.sha }} -n staging

Deploy em Kubernetes (EKS/GKE/AKS) com HorizontalPodAutoscaler baseado em CPU/memória e custom metrics (fila de webhooks, chamados pendentes). Blue-green ou canary para zero-downtime.

Conclusão prática

Um portal de solicitações para desentupimento bem projetado deixa de ser apenas um formulário digital e torna-se o sistema nervoso da operação hidráulica do empreendimento. A combinação de triagem automatizada, despacho rastreável, evidências estruturadas e dashboards acionáveis reduz o tempo de resposta de horas para minutos e transforma dados dispersos em plano de manutenção preventiva. Comece pelo domínio — modele as entidades, as regras de criticidade e os fluxos de aprovação — e evolua a arquitetura em camadas: API versionada, multi-tenancy nativo, observabilidade desde o dia zero. O retorno aparece no primeiro alagamento evitado.

Para aprofundar em infraestrutura de servidores que suportam esse tipo de aplicação, veja o caso de servidor local offline após vazamento no banheiro. Para entender como a arquitetura da informação impacta a descobribilidade de serviços técnicos, consulte arquitetura de informação otimizada para Google em Caxias do Sul. E para estratégias de performance em aplicações críticas, aplicar otimizações de performance para o Google em Caxias do Sul.

Se você atua na capital paulista e precisa identificar rapidamente sinais de coluna de esgoto entupida na cidade de São Paulo, a integração com bases de conhecimento técnico especializado agiliza o diagnóstico e a destinação correta da equipe.

Checklist prático

0 de 9 concluídos

Perguntas frequentes

Quais são os principais benefícios de um portal de solicitações para desentupimento em condomínios?

Um portal centraliza as demandas, elimina ruídos de comunicação via WhatsApp ou e-mail, permite rastreamento em tempo real do status de cada chamado e gera histórico estruturado para auditoria e relatórios de manutenção preventiva.

Como integrar o portal com a equipe de campo que executa os desentupimentos?

A integração ocorre via API REST ou webhooks que enviam notificações push para aplicativos móveis dos técnicos, permitindo aceite de chamados, atualização de status (a caminho, em execução, finalizado) e envio de evidências fotográficas e laudos técnicos diretamente do local.

Qual stack tecnológica é recomendada para construir esse tipo de portal?

Para o back-end, Node.js com NestJS ou Python com FastAPI oferecem performance e tipagem forte. No front-end, React com TypeScript e bibliotecas como React Hook Form e TanStack Query garantem formulários robustos e gerenciamento de estado assíncrono eficiente.

Como lidar com priorização de chamados emergenciais versus agendados?

Implemente um sistema de triagem automática baseado em palavras-chave no relato do usuário e tipo de ocorrência (vazamento ativo, refluxo de esgoto). Chamados críticos entram em fila de alta prioridade com SLA reduzido e notificação imediata à equipe de plantão 24h.

É necessário LGPD para portais de solicitações de desentupimento?

Sim. O portal coleta dados pessoais (nome, unidade, telefone, endereço) e dados sensíveis de localização. É obrigatório termo de consentimento claro, política de privacidade acessível, criptografia em trânsito (TLS 1.3) e em repouso, além de logs de acesso auditáveis.

Como medir a eficiência do portal após a implantação?

Acompanhe métricas como tempo médio de primeiro atendimento (TMA), taxa de resolução no primeiro contato (FCR), tempo médio de resolução (MTTR), satisfação do usuário (CSAT/NPS) e volume de chamados recorrentes por equipamento ou localização para direcionar manutenção preventiva.

Quem cuida de prédios na região metropolitana de São Paulo costuma guardar www.dezjatodesentupidora.com.br/ na agenda de emergências hidráulicas.