🗺️ Mapa Completo de Regras — FinSight v8.3

Cada etapa do pipeline de dados, da API OMIE até o Dashboard.

1️⃣ SINCRONIZAÇÃO (omie.js → syncAll)

Busca TODOS os registros da API OMIE via paginação (500 por página).

Endpoints chamados:
  financas/contareceber  → ListarContasReceber  (todas as contas a receber)
  financas/contapagar    → ListarContasPagar    (todas as contas a pagar)
  geral/projetos         → ListarProjetos       (projetos ativos)
  geral/categorias       → ListarCategorias     (plano de contas)

Resultado:
  rawCache = { receber: [...], pagar: [...], projetos: [...], categorias: [...] }
  → Salvo em IndexedDB (até 250+ MB)
          

⚠️ Sem filtro de ano aqui — busca TUDO da empresa.

2️⃣ FILTRO POR ANO (_filtrarPorAno — omie.js)

Filtra a lista bruta para o ano selecionado (ex: 2026).

Regra de inclusão: item é incluído SE:
  ✅ data_baixa tem ano = 2026  (data de pagamento/recebimento efetivo)
  ✅ data_vencimento tem ano = 2026
  ✅ data_emissao tem ano = 2026
  ✅ data_registro tem ano = 2026

Itens em aberto:
  ✅ Se NÃO é pago/recebido E data_vencimento entre 2024-2025 → incluído (passivo)

⚠️ PONTO DE PERDA #1:
  Se um item PAGO tem TODAS as datas em 2025 (inclusive data_baixa),
  ele é EXCLUÍDO aqui e nunca chega ao processamento.
          

3️⃣ PROCESSAMENTO (processOmieData — data-engine.js)

Para cada item na lista filtrada, aplica 5 portões (gates):

🚫 Gate A: Cancelado?

_isCancelado(item):
  status_titulo === "CANCELADO" | "CANC" | "DEVOLVIDO" → DESCARTADO

⚠️ PONTO DE PERDA #2:
  Item com status incomum (ex: "CONCLUÍDO", "SUBSTITUÍDO") pode ser
  classificado como cancelado incorretamente.
          

🚫 Gate B: Valor ≤ 0?

_valor(item):
  Tenta: valor_documento → nValorTitulo → nValorPago → nValorLiquido → nValor → valor
  Se TODOS = 0 ou undefined → DESCARTADO

⚠️ PONTO DE PERDA #3:
  Se valor_documento vem como STRING "1.500,00" (com ponto de milhar),
  parseFloat retorna 1.5 (não 1500). Conversão usa replace(',','.').
          

🔀 Gate C: Status — PAGO/RECEBIDO ou EM ABERTO?

Para RECEBER — _isRecebido(item):
  ✅ "RECEBIDO" | "LIQUIDADO" | "PAGO" | "BAIXADO" | "QUITADO" → REGIME CAIXA
  ❓ Qualquer outro status → EM ABERTO (vai para passivo se > 30 dias)

Para PAGAR — _isPago(item):
  ✅ "PAGO" | "LIQUIDADO" | "BAIXADO" | "QUITADO" → REGIME CAIXA
  ❓ Qualquer outro status → EM ABERTO (vai para passivo se > 30 dias)

Fallback por nValorPago:
  Se status está VAZIO e nValorPago > 0 → considera como PAGO/RECEBIDO

⚠️ PONTO DE PERDA #4:
  Se o OMIE usa um status diferente (ex: "BAIXA PARCIAL", "EM PROCESSO"),
  o item é tratado como EM ABERTO — NÃO entra no caixa!
          

📅 Gate D: Data no Ano Correto? (CRITICAL — v8.3)

Para RECEBER (cascade de datas):
  1. data_baixa | dDtCredito | data_credito | dDtRecebimento
  2. data_vencimento  (fallback)
  3. data_emissao | data_registro  (fallback)
  
  Se NENHUMA data cai em 2026 → DESCARTADO (pagSemData++)

Para PAGAR (cascade de datas):
  1. data_baixa | dDtPagamento | data_pagamento
  2. data_vencimento  (fallback)
  3. data_emissao | data_registro  (fallback)
  
  Se NENHUMA data cai em 2026 → DESCARTADO (recSemData++)

⛔ data_previsao NÃO É USADA (v8.3)

⚠️ PONTO DE PERDA #5 (PROVÁVEL CAUSA DOS R$1.5M):
  Se data_baixa está VAZIA ou contém uma data inválida/diferente do campo
  esperado, E data_vencimento/data_emissao são de 2025 →
  O item passa pelo filtro (_filtrarPorAno inclui por vencimento 2025+aberto)
  mas é DESCARTADO aqui porque nenhuma data válida cai em 2026.
  
  OUTRA POSSIBILIDADE:
  O campo real de pagamento pode NÃO ser "data_baixa" mas sim outro campo
  como "dDtBaixa", "dDtPagamento", ou um subcampo aninhado.
          

✅ Gate E: Classificação — Para onde vai o valor?

_catNorm(item) → {codigo, descricao, tipo, raw}
  Extrai categoria de: item.categorias[0].cCodCateg + cDescrCateg
  Fallback: item.distribuicao, item.codigo_categoria, item.operacao

_isCustoDireto(cat):
  Prioridade de classificação:
    1. Mapeamento manual do usuário (localStorage)
    2. Grupo OMIE real (_nomeToGrupos)
    3. Código hierárquico (2.xx = custo)
    4. Keywords na descrição ("custo direto", "CMV", "mão de obra"...)

_mapTipoDespesa(cat):
  Mesma cascata de prioridade. Resultado:
    3.01.xx → pessoal
    3.02.xx → admin
    3.03.xx → comercial
    3.04.xx → financeiro
    3.05.xx → impostos
    4.xx    → investimento
    default → admin (fallback)
          

💰 Gate F: Qual Valor Usar?

REGIME CAIXA (Dashboard, Receitas, Custos, Despesas, Fluxo):
  _valorCaixa(item):
    1. nValorPago   (valor efetivamente movimentado — pode incluir juros/multas)
    2. nValorLiquido (fallback)
    3. valor_documento (face do título — fallback final)

REGIME COMPETÊNCIA (DRE):
  _valor(item):
    1. valor_documento (face do título — valor do serviço)
    2. nValorTitulo (fallback)
    3. nValorPago (fallback final)
          

4️⃣ SEGMENTAÇÃO POR PROJETO

classificarSegmento(nomeProjetoOmie):
  O codigo_projeto do título → busca no projMap → nome do projeto
  
  Nome contém "prospecta tech"     → tecnologia
  Nome contém "cr treinamentos"... → cursos
  Nome contém "cash", "dinamo"...  → estruturação
  Nenhum match                     → projetos (default)
  Sem projeto                      → projetos
          

5️⃣ RESULTADO FINAL → Dashboard

Arrays mensais (12 posições cada):
  receitaTotal[mes]      = soma receita[seg][mes]  (regime CAIXA)
  custosTotal[mes]       = soma custos[seg][mes]    (regime CAIXA)
  despesasTotal[mes]     = soma despesas[tipo][mes] (regime CAIXA)
  resultadoOperacional   = receita - custos - despesas
  resultadoLiquido       = resOp × (1 - SIMPLES 6.5%)
  
  dre.receita/custos/despesas = regime COMPETÊNCIA (data_emissao)
  
  caixaCategorizado.entradas = receita por segmento (projetos/cursos/tecn/estr)
  caixaCategorizado.saidas   = custos + 6 tipos de despesas
  
  passivo = itens em aberto vencidos > 30 dias
          

🚨 Resumo: 5 Pontos de Perda de Dados

⚠️ #1 — Filtro por Ano

Onde:omie.js _filtrarPorAno

Causa:Todas datas em ano anterior

Impacto:ALTO — exclui antes de processar

⚠️ #2 — Status Cancelado

Onde:_isCancelado

Causa:Status inesperado

Impacto:BAIXO geralmente

⚠️ #3 — Valor Zero/Inválido

Onde:_valor parseFloat

Causa:Formato "1.500,00"

Impacto:MÉDIO se muitos itens

⛔ #4 — Status Não Reconhecido

Onde:_isPago / _isRecebido

Causa:"BAIXA PARCIAL" etc

Impacto:ALTO — valor vai para passivo

⛔ #5 — Data Fora do Ano

Onde:_mesDoAno retorna -1

Causa:data_baixa vazia/2025

Impacto:CRÍTICO — ~R$1.5M perdido