🏗️ Arquitetura - ecosif-compliance

📋 Visão Geral

ecosif-compliance é um microserviço Python/Flask especializado em validação de conformidade contábil. Utiliza um sistema de regras configuráveis com DSL (Domain-Specific Language) customizada para validar documentos contábeis e identificar possíveis inconsistências.

🎯 Objetivo do Serviço

• ✅ Validação de conformidade contábil através de regras configuráveis
• ✅ Sistema de regras flexível com DSL customizada
• ✅ Identificação de indícios de problemas contábeis
• ✅ Histórico de execuções para auditoria
• ✅ Integração com dados contábeis do eCosif

🏛️ Arquitetura em Camadas

┌─────────────────────────────────────────────────────────┐
│              Camada de Apresentação (REST)               │
│                                                          │
│  Flask + Flask-RESTX                                    │
│  • starter.py (app principal)                           │
│  • Endpoints REST                                       │
│  • Swagger UI automático                                │
│                                                          │
│  Responsabilidades:                                     │
│  • Receber requisições HTTP                             │
│  • Validação básica de entrada                          │
│  • Chamar services de validação                         │
│  • Retornar resultados em JSON                          │
└────────────────────┬────────────────────────────────────┘
                     │
                     │ usa
                     ▼
┌─────────────────────────────────────────────────────────┐
│            Camada de Aplicação (Services)               │
│                                                          │
│  Services                                              │
│  • compliance.py - Validação principal                 │
│  • rule.py - Gerenciamento de regras                   │
│  • account.py - Operações com contas                   │
│                                                          │
│  Responsabilidades:                                     │
│  • Lógica de validação                                 │
│  • Execução de regras DSL                              │
│  • Processamento de dados                              │
└────────────────────┬────────────────────────────────────┘
                     │
                     │ usa
                     ▼
┌─────────────────────────────────────────────────────────┐
│           Camada de Persistência (DAOs)                 │
│                                                          │
│  Data Access Objects                                   │
│  • RuleDao                                             │
│  • DocumentDao                                         │
│  • ProcessDao                                          │
│  • ClueTypeDao                                         │
│                                                          │
│  Responsabilidades:                                     │
│  • Acesso a dados                                      │
│  • Queries otimizadas                                  │
└────────────────────┬────────────────────────────────────┘
                     │
                     │ persiste
                     ▼
┌─────────────────────────────────────────────────────────┐
│              Camada de Dados (Entities)                 │
│                                                          │
│  SQLAlchemy Entities                                   │
│  • RuleEntity                                          │
│  • DocumentEntity                                      │
│  • ProcessEntity                                       │
│  • ClueTypeEntity                                      │
│  • BusinessSystemEntity                                │
│                                                          │
│  Responsabilidades:                                     │
│  • Mapeamento ORM                                      │
│  • Validações de modelo                                │
└────────────────────┬────────────────────────────────────┘
                     │
                     │ persiste
                     ▼
┌─────────────────────────────────────────────────────────┐
│                 PostgreSQL Database                      │
│  • Tabelas de regras                                   │
│  • Tabelas de processos                                │
│  • Dados contábeis (via ecosif-database)              │
└─────────────────────────────────────────────────────────┘

📦 Estrutura de Pacotes

app/
├── starter.py              # Aplicação Flask principal
├── config/                 # Configurações
│   ├── config.py          # Classe de configuração
│   └── config*.json       # Arquivos de configuração
├── service/                # Services de negócio
│   ├── compliance.py      # Validação de conformidade
│   ├── rule.py            # Gerenciamento de regras
│   ├── account.py         # Operações com contas
│   ├── parsetab.py        # Tabela de parsing DSL
│   └── parser.out         # Output do parser
├── db/                     # Camada de dados
│   ├── dao/               # Data Access Objects
│   │   ├── rule.py
│   │   ├── document.py
│   │   ├── process.py
│   │   ├── clue_type.py
│   │   └── business_system.py
│   ├── entity/            # Entidades SQLAlchemy
│   │   ├── rule.py
│   │   ├── document.py
│   │   ├── process.py
│   │   └── ...
│   ├── session_manager.py
│   └── session.py
├── custom_exception/       # Exceções customizadas
│   ├── custom_http_exception.py
│   └── custom_runtime_exceptions.py
├── logger/                 # Sistema de logging
│   └── logger.py
└── error_handler.py        # Tratamento de erros global

🔧 Tecnologias e Dependências

Core

• Python 3.12+ - Linguagem base
• Flask 2.3+ - Framework web
• Flask-RESTX 1.1+ - API REST com Swagger
• Flask-CORS - CORS support

Persistência

• SQLAlchemy - ORM
• psycopg2-binary - Driver PostgreSQL
• PostgreSQL 15+ - Banco de dados

DSL e Parsing

• PLY (Python Lex-Yacc) - Parser para DSL customizada

Utilitários

• Pandas - Manipulação de dados
• pandas-ods-reader - Leitura de arquivos ODS
• Gunicorn - WSGI server (produção)

Logging

• concurrent-log-handler - Logging assíncrono

📊 Componentes Principais

Flask Application (starter.py)

Arquivo principal que inicializa: - Flask app - Flask-RESTX API - Flask-CORS - Error handlers globais - Endpoints REST

Services

compliance.py

• Execução de validações
• Processamento de regras
• Integração com dados contábeis

rule.py

• Gerenciamento de regras (CRUD)
• Listagem de tipos de indício
• Listagem de sistemas de negócio

account.py

• Operações com contas contábeis
• Cálculos de saldos
• Agregações

DAOs (Data Access Objects)

• RuleDao - Acesso a regras
• DocumentDao - Acesso a documentos
• ProcessDao - Acesso a processos
• ClueTypeDao - Acesso a tipos de indício
• BusinessSystemDao - Acesso a sistemas de negócio

Entities (SQLAlchemy)

• RuleEntity - Entidade de regra
• DocumentEntity - Entidade de documento
• ProcessEntity - Entidade de processo
• ProcessRuleEntity - Relação processo x regra

🔄 DSL - Domain-Specific Language

O serviço utiliza uma DSL customizada para definir regras de validação:

Funções Disponíveis

• SALDO_CONTA(conta, data) - Retorna saldo de uma conta
• SOMA_SALDO_CONTAS([contas], data) - Soma saldos de múltiplas contas
• VARIACAO_SALDO(conta, data1, data2) - Variação de saldo
• DIFERENCA_PERCENTUAL_SALDOS(saldo1, saldo2) - Diferença percentual

Estruturas de Controle

• IF condição THEN expressão ELSE expressão
• RETORNA valor - Retorna sucesso
• ERRO "mensagem" - Retorna erro com mensagem

Exemplo

IF SALDO_CONTA("1.1.01", "2025-11") > 1000000 THEN
  ERRO "Saldo da conta 1.1.01 muito alto"
ELSE
  RETORNA "OK"

🔄 Fluxo de Validação

1. Cliente solicita validação via POST /api/compliance/run
2. Flask recebe requisição
3. Service busca regras aplicáveis
4. Parser compila scripts DSL
5. Service executa regras sobre dados contábeis
6. Service persiste resultados no banco
7. Flask retorna resultados

🔐 Configuração

Arquivos de Configuração

O serviço utiliza arquivos JSON para configuração: - config.json (padrão) - config-{environment}.json (baseado em ecosif.runtime.environment)

Variáveis de Ambiente

• ecosif.runtime.environment - Define qual arquivo de config usar

Última Atualização: 2025-12-01