🏗️ 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 regrasDocumentDao- Acesso a documentosProcessDao- Acesso a processosClueTypeDao- Acesso a tipos de indícioBusinessSystemDao- Acesso a sistemas de negócio
Entities (SQLAlchemy)¶
RuleEntity- Entidade de regraDocumentEntity- Entidade de documentoProcessEntity- Entidade de processoProcessRuleEntity- 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 contaSOMA_SALDO_CONTAS([contas], data)- Soma saldos de múltiplas contasVARIACAO_SALDO(conta, data1, data2)- Variação de saldoDIFERENCA_PERCENTUAL_SALDOS(saldo1, saldo2)- Diferença percentual
Estruturas de Controle¶
IF condição THEN expressão ELSE expressãoRETORNA valor- Retorna sucessoERRO "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¶
- Cliente solicita validação via
POST /api/compliance/run - Flask recebe requisição
- Service busca regras aplicáveis
- Parser compila scripts DSL
- Service executa regras sobre dados contábeis
- Service persiste resultados no banco
- 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