Introdução

Neste documento procuramos apresentar e justificar as escolhas técnicas realizadas durante a implementação da rotina SCANCREF. As escolhas podem ser agrupadas da seguinte maneira:

Paradigma
Arquitetura
Linguagem

Paradigma

A decisão de utilizar a Orientação a Objetos em detrimento da programação estruturada é provavelmente a mudança mais significativa empregada no desenvolvimento desta rotina.

Não chega a ser uma novidade na Squad a existência de rotinas utilizando este modelo, porém o que torna a nossa abordagem um tanto mais inovadora é o uso de padrões de arquitetura e recursos avançados da linguagem que potencializam o poder de abstração da orientação a objetos.

O porquê da escolha

A escolha do paradigma foi orientada pelas vantagens que o mesmo traz para o desenvolvimento:

Reutilização de código: objetos podem ser reutilizados em diferentes partes do programa, o que economiza tempo e esforço de desenvolvimento.
Modularidade: os objetos podem ser criados independentemente e depois integrados em um programa maior. Isso ajuda a separar as diferentes partes do programa em módulos lógicos, tornando o programa mais fácil de entender, manter e modificar.
Abstração: objetos permitem que você abstraia conceitos e ideias em representações mais concretas e fáceis de entender. Isso torna o código mais legível e fácil de manter.
Encapsulamento: a orientação a objetos permite que você esconda a complexidade interna de um objeto. Isso torna o objeto mais fácil de usar, porque o usuário só precisa conhecer as funções públicas disponíveis e não precisa se preocupar com detalhes internos.
Herança: a orientação a objetos permite que você crie hierarquias de objetos, com objetos mais especializados derivados de objetos mais gerais. Isso economiza tempo e esforço de desenvolvimento, uma vez que você pode reutilizar e modificar objetos existentes em vez de criar novos a partir do zero.

Todas estas vantagens foram exploradas com maior ou menor intensidade durante o desenvolvimento. Ao final deste documento deixamos a documentação no padrão Protheus Doc com a descrição das classes e métodos criados.

Arquitetura

Desenvolvemos a rotina SCANCREF utilizando dois modelos arquiteturais:

1. Arquitetura em camadas (Layered Architecture)

O primeiro deles é um modelo em camadas. É importante lembrar que nesta parte da aplicação não há necessidade de persistência de dados, logo não foi necessário se preocupar com uma interface gráfica para entrada de informações por parte do usuário. As camadas criadas são resumidas abaixo:

Model: a camada de modelo é a responsável por representar os objetos que estamos modelando na aplicação, neste caso são os registros ou quadros do arquivo Scanc Refinaria. Foi então criada uma classe para cada registro do arquivo, cada atributo da classe representa um campo do registro;
Service: na camada de serviço, isolamos a lógica de acesso a dados. Aqui são obtidos os dados e instanciados os objetos da camada de modelo;
File: esta camada funciona como uma camada de aplicação, isto é, ela não armazena regras de negócio, mas apenas coordena tarefas e delega trabalho para colaborações de objetos de domínio (camadas Model e Service). Aqui, a camada File é responsável pela montagem e escrita do objeto que representa o arquivo, em meio magnético.

O porquê da escolha

Escolhemos essa abordagem visando os seguintes motivos:

Separação de responsabilidades: cada camada tem uma responsabilidade específica, tornando o código mais fácil de entender, alterar e depurar.
Reutilização de código: as camadas são isoladas e independentes, permitindo que o código seja reutilizado em outros projetos ou partes do mesmo projeto. Isto se aplica, inclusive para os futuros projetos do TAF. Procuramos desenvolver artefatos backend agnósticos, que poderão, a princípio, ser reaproveitados em projetos REST e PO-UI.
Melhor escalabilidade: como as camadas são independentes, é possível escalar apenas aquela que precisa ser escalada, sem afetar as demais camadas.
Facilidade de manutenção: com a separação de responsabilidades, é mais fácil identificar onde estão os erros e realizar manutenções pontuais, sem afetar outras partes do sistema.
Facilidade de testes: a separação de responsabilidades também facilita a criação de testes automatizados para cada camada.

2. Model-View-Controller ou MVC

Aqui foram desenvolvidas as tabelas e as respectivas telas para entrada de informações, utilizando as funções MVC disponibilizadas pelo Framework.

FISA309 - Cadastro dos Quadros - Scanc Refinaria do Anexo VI

FISA310

O porquê da escolha

Escolhemos essa abordagem devido ao domínio do time sobre a tecnologia.

Linguagem

Embora não seja mandatória em relação às escolhas de paradigma e arquitetura – inclusive, cronologicamente, a escolha da linguagem foi anterior a estas últimas –, optamos pelo uso do TLPP.

O porquê da escolha

As justificativas são:

É uma evolução do ADVPL e, ao contrário desta, continuará recebendo atualizações no futuro, portanto é a escolha mais adequada para a construção de uma rotina durável;
Suporte a namespaces: o que permitiu otimizar a organização conforme arquitetura escolhida;
Suporte a Reflection e Annotations: embora não tenha sido essencial, este recurso permitiu criar uma nova camada de abstração sobre os objetos o que facilitou muito a implementação da rotina (ex.: a criação de metadados sobre os campos de cada registro, tais como a quantidade de casas decimais ou a posição de cada campo).

Anexo I – Artefatos MVC

Anexo II – Classes e métodos TLPP

Namespace backoffice.fiscal.arquivos.estadual.scancref.model

FieldOfScanRef class

Classe genérica com métodos e propriedades comuns à todos os registros do SCANC Refinaria

Definição:

Sintaxe

FieldOfScanRef()

toString of Class FieldOfScanRef method

Retorna o registro no formato Character

Definição:

Sintaxe

FieldOfScanRef():toString()

Retorno

Tipo	Descrição
Character	Retorna o registro no formato Character

RegA6HD class

Classe modelo para o registro de cabeçalho do arquivo SCANC Refinaria

Definição:

Sintaxe

RegA6HD()

RegA6Q3 class

Classe modelo para o registro QUADRO 3 - OPERAÇÕES REALIZADAS PELO EMITENTE DO RELATÓRIO

Definição:

Sintaxe

RegA6Q3()

RegA6Q1 class

QUADRO 1 - Anexo VI Quadro 1 - VALOR DEVIDO POR OPERAÇÕES COM IMPOSTO RETIDO

Definição:

Sintaxe

RegA6Q1()

RegA6Q2 class

QUADRO 2 - APURAÇÃO DO ICMS PROVISIONADO

Definição:

Sintaxe

RegA6Q2()

RegA6Q41 class

QUADRO 4.1 - REPASSE POR OPERAÇÕES REALIZADAS POR DISTRIBUIDORAS/TRR (Transportador Revendedor Retalhista de Combustível)

Definição:

Sintaxe

RegA6Q41()

RegA6Q42 class

QUADRO 4.2 - OPERAÇÕES COM IMPOSTO RETIDO POR OUTROS CONTRIBUINTES

Definição:

Sintaxe

RegA6Q42()

RegA6Q43 class

QUADRO 4.3 - RELATÓRIOS EXTEMPORÂNEOS

Definição:

Sintaxe

RegA6Q43()

RegA6Q5 class

QUADRO 5 - REPASSE POR OPERAÇÕES REALIZADAS POR IMPORTADORES

Definição:

Sintaxe

RegA6Q5()

RegA6Q6 class

QUADRO 6 - REPASSE POR REMESSA DE AEAC (Álcool etílico anidro combustível) OU DE B100 (Biodisel) PARA OUTRAS UF

Definição:

Sintaxe

RegA6Q6()

RegA6Q61 class

QUADRO 6.1 - OPERAÇÕES COM IMPOSTO RETIDO POR ESTABELECIMENTO DO EMITENTE

Definição:

Sintaxe

RegA6Q61()

RegA6Q62 class

QUADRO 6.2 - OPERAÇÕES COM IMPOSTO RETIDO POR OUTROS CONTRIBUINTES

Definição:

Sintaxe

RegA6Q62()

RegA6Q63 class

QUADRO 6.3 - RELATÓRIOS EXTEMPORÂNEOS

Definição:

Sintaxe

RegA6Q63()

RegA6Q71 class

QUADRO 7.1 - OPERAÇÕES COM IMPOSTO RETIDO POR ESTABELECIMENTO DO EMITENTE

Definição:

Sintaxe

RegA6Q71()

RegA6Q72 class

QUADRO 7.2 - OPERAÇÕES COM IMPOSTO RETIDO POR OUTROS CONTRIBUINTES

Definição:

Sintaxe

RegA6Q72()

RegA6Q73 class

QUADRO 7.3 - RELATÓRIOS EXTEMPORÂNEOS

Definição:

Sintaxe

RegA6Q73()

RegA6Q8 class

QUADRO 8 - DEDUÇÃO POR OPERAÇÕES REALIZADAS POR IMPORTADORES

Definição:

Sintaxe

RegA6Q8()

RegA6Q91 class

QUADRO 9.1 - OPERAÇÕES COM IMPOSTO RETIDO POR ESTABELECIMENTO DO EMITENTE

Definição:

Sintaxe

RegA6Q91()

RegA6Q92 class

QUADRO 9.2 - OPERAÇÕES COM IMPOSTO RETIDO POR OUTROS CONTRIBUINTES

Definição:

Sintaxe

RegA6Q92()

RegA6Q93 class

QUADRO 9.3 - RELATÓRIOS EXTEMPORÂNEOS

Definição:

Sintaxe

RegA6Q93()

RegA6Q10 class

QUADRO 10 - DEDUÇÃO POR RESSARCIMENTO EFETUADO A DISTRIBUIDORAS

Definição:

Sintaxe

RegA6Q10()

RegA6Q11 class

QUADRO 11 - DEDUÇÃO POR RESSARCIMENTO EFETUADO A TRR

Definição:

Sintaxe

RegA6Q11()

RegA6Q12 class

QUADRO 12 - DEDUÇÃO POR RESSARCIMENTO EFETUADO A IMPORTADORES

Definição:

Sintaxe

RegA6Q12()

RegA6Q13 class

QUADRO 13 - DEDUÇÃO POR RESSARCIMENTO EFETUADO A OUTROS CONTRIBUINTES

Definição:

Sintaxe

RegA6Q13()

RegA6Q14 class

QUADRO 14 - DEDUÇÃO TRANSFERIDA DE OUTRO ESTABELECIMENTO DO SUJEITO PASSIVO POR SUBSTITUIÇÃO

Definição:

Sintaxe

RegA6Q14()

RegA6Q15 class

QUADRO 15 - DEDUÇÃO TRANSFERIDA PARA OUTRO ESTABELECIMENTO DO SUJEITO PASSIVO POR SUBSTITUIÇÃO

Definição:

Sintaxe

RegA6Q15()

Namespace backoffice.fiscal.arquivos.estadual.scancref.service

ScancRefService class

Classe responsável por obter os dados dos registros do SCANC Refinaria

Definição:

Sintaxe

ScancRefService()

QryCJO of Class ScancRefService method

Método responsável por buscar os registros da tabela CJO com os dados dos quadros preenchidos pelo usuário

Definição:

Sintaxe

ScancRefService():QryCJO()

Retorno

Tipo	Descrição
Character	com o alias da query para uso

DefCliFor of Class ScancRefService method

Método responsável por traduzir o tipo, sendo o cliente, fornecedor ou filial

Definição:

Sintaxe

ScancRefService():DefCliFor()

Retorno

Tipo	Descrição
Array	com os dados da base

getRegA6HD of Class ScancRefService method

Método responsável por fornecer o registro de cabeçalho do SCANC Refinaria

Definição:

Sintaxe

ScancRefService():getRegA6HD()

Retorno

Tipo	Descrição
Object	retorna um objeto do tipo RegA6HD

getRegA6Q1 of Class ScancRefService method

QUADRO 1 - Anexo VI Quadro 1 - VALOR DEVIDO POR OPERAÇÕES COM IMPOSTO RETIDO

Definição:

Sintaxe

ScancRefService():getRegA6Q1()

Retorno

Tipo	Descrição
Object	objeto com dados do registro A6Q1

getRegA6Q2 of Class ScancRefService method

QUADRO 2 - APURAÇÃO DO ICMS PROVISIONADO

Definição:

Sintaxe

ScancRefService():getRegA6Q2()

Retorno

Tipo	Descrição
Object	objeto com dados do registro A6Q2

getRegA6Q3 of Class ScancRefService method

Método responsável por fornecer o QUADRO 3 - OPERAÇÕES REALIZADAS PELO EMITENTE DO RELATÓRIO

Definição:

Sintaxe

ScancRefService():getRegA6Q3()

Retorno

Tipo	Descrição
Array	retorna um array de objetos do tipo RegA6Q3

getRegA6Q41 of Class ScancRefService method

QUADRO 4.1 - OPERAÇÕES COM IMPOSTO RETIDO POR ESTABELECIMENTO DO EMITENTE

Definição:

Sintaxe

ScancRefService():getRegA6Q41()

Retorno

Tipo	Descrição
Object	objeto com dados do registro A6Q41

getRegA6Q42 of Class ScancRefService method

QUADRO 4.2 - OPERAÇÕES COM IMPOSTO RETIDO POR OUTROS CONTRIBUINTES

Definição:

Sintaxe

ScancRefService():getRegA6Q42()

Retorno

Tipo	Descrição
Object	objeto com dados do registro A6Q42

getRegA6Q43 of Class ScancRefService method

QUADRO 4.3 - RELATÓRIOS EXTEMPORÂNEOS

Definição:

Sintaxe

ScancRefService():getRegA6Q43()

Retorno

Tipo	Descrição
Object	objeto com dados do registro A6Q43

getRegA6Q5 of Class ScancRefService method

QUADRO 5 - REPASSE POR OPERAÇÕES REALIZADAS POR IMPORTADORES

Definição:

Sintaxe

ScancRefService():getRegA6Q5()

Retorno

Tipo	Descrição
Object	objeto com dados do registro A6Q5

getRegA6Q6 of Class ScancRefService method

QUADRO 6 - REPASSE POR REMESSA DE AEAC (Álcool etílico anidro combustível) OU DE B100 (Biodisel) PARA OUTRAS UF

Definição:

Sintaxe

ScancRefService():getRegA6Q6()

Retorno

Tipo	Descrição
Object	objeto com dados do registro A6Q6

getRegA6Q61 of Class ScancRefService method

QUADRO 6.1 - OPERAÇÕES COM IMPOSTO RETIDO POR ESTABELECIMENTO DO EMITENTE

Definição:

Sintaxe

ScancRefService():getRegA6Q61()

Retorno

Tipo	Descrição
Object	objeto com dados do registro A6Q61

getRegA6Q62 of Class ScancRefService method

QUADRO 6.2 - OPERAÇÕES COM IMPOSTO RETIDO POR OUTROS CONTRIBUINTES

Definição:

Sintaxe

ScancRefService():getRegA6Q62()

Retorno

Tipo	Descrição
Object	objeto com dados do registro A6Q62

getRegA6Q63 of Class ScancRefService method

QUADRO 6.3 - RELATÓRIOS EXTEMPORÂNEOS

Definição:

Sintaxe

ScancRefService():getRegA6Q63()

Retorno

Tipo	Descrição
Object	objeto com dados do registro A6Q63

getRegA6Q71 of Class ScancRefService method

QUADRO 7.1 - OPERAÇÕES COM IMPOSTO RETIDO POR ESTABELECIMENTO DO EMITENTE

Definição:

Sintaxe

ScancRefService():getRegA6Q71()

Retorno

Tipo	Descrição
Object	objeto com dados do registro A6Q71

getRegA6Q72 of Class ScancRefService method

QUADRO 7.2 - OPERAÇÕES COM IMPOSTO RETIDO POR OUTROS CONTRIBUINTES

Definição:

Sintaxe

ScancRefService():getRegA6Q72()

Retorno

Tipo	Descrição
Object	objeto com dados do registro A6Q72

getRegA6Q73 of Class ScancRefService method

QUADRO 7.3 - RELATÓRIOS EXTEMPORÂNEOS

Definição:

Sintaxe

ScancRefService():getRegA6Q73()

Retorno

Tipo	Descrição
Object	objeto com dados do registro A6Q73

getRegA6Q8 of Class ScancRefService method

QUADRO 8 - DEDUÇÃO POR OPERAÇÕES REALIZADAS POR IMPORTADORES

Definição:

Sintaxe

ScancRefService():getRegA6Q8()

Retorno

Tipo	Descrição
Object	objeto com dados do registro A6Q8

getRegA6Q91 of Class ScancRefService method

QUADRO 9.1 - OPERAÇÕES COM IMPOSTO RETIDO POR ESTABELECIMENTO DO EMITENTE

Definição:

Sintaxe

ScancRefService():getRegA6Q91()

Retorno

Tipo	Descrição
Object	objeto com dados do registro A6Q91

getRegA6Q92 of Class ScancRefService method

QUADRO 9.2 - OPERAÇÕES COM IMPOSTO RETIDO POR OUTROS CONTRIBUINTES

Definição:

Sintaxe

ScancRefService():getRegA6Q92()

Retorno

Tipo	Descrição
Object	objeto com dados do registro A6Q92

getRegA6Q93 of Class ScancRefService method

QUADRO 9.3 - RELATÓRIOS EXTEMPORÂNEOS

Definição:

Sintaxe

ScancRefService():getRegA6Q93()

Retorno

Tipo	Descrição
Object	objeto com dados do registro A6Q93

getRegA6Q10 of Class ScancRefService method

QUADRO 10 - DEDUÇÃO POR RESSARCIMENTO EFETUADO A DISTRIBUIDORAS

Definição:

Sintaxe

ScancRefService():getRegA6Q10()

Retorno

Tipo	Descrição
Object	objeto com dados do registro A6Q10

getRegA6Q11 of Class ScancRefService method

QUADRO 11 - DEDUÇÃO POR RESSARCIMENTO EFETUADO A TRR

Definição:

Sintaxe

ScancRefService():getRegA6Q11()

Retorno

Tipo	Descrição
Object	objeto com dados do registro A6Q11

getRegA6Q12 of Class ScancRefService method

QUADRO 12 - DEDUÇÃO POR RESSARCIMENTO EFETUADO A IMPORTADORES

Definição:

Sintaxe

ScancRefService():getRegA6Q12()

Retorno

Tipo	Descrição
Object	objeto com dados do registro A6Q12

getRegA6Q13 of Class ScancRefService method

QUADRO 13 - DEDUÇÃO POR RESSARCIMENTO EFETUADO A OUTROS CONTRIBUINTES

Definição:

Sintaxe

ScancRefService():getRegA6Q13()

Retorno

Tipo	Descrição
Object	objeto com dados do registro A6Q13

getRegA6Q14 of Class ScancRefService method

QUADRO 14 - DEDUÇÃO TRANSFERIDA DE OUTRO ESTABELECIMENTO DO SUJEITO PASSIVO POR SUBSTITUIÇÃO

Definição:

Sintaxe

ScancRefService():getRegA6Q14()

Retorno

Tipo	Descrição
Object	objeto com dados do registro A6Q14

getRegA6Q15 of Class ScancRefService method

QUADRO 15 - DEDUÇÃO TRANSFERIDA PARA OUTRO ESTABELECIMENTO DO SUJEITO PASSIVO POR SUBSTITUIÇÃO

Definição:

Sintaxe

ScancRefService():getRegA6Q15()

Retorno

Tipo	Descrição
Object	objeto com dados do registro A6Q15

Namespace backoffice.fiscal.arquivos.estadual.scancref.file

ScancRef class

Classe modelo para o arquivo SCANC Refinaria

Definição:

Sintaxe

ScancRef()

makeRecords of Class ScancRef method

Método responsável por montar os registros do arquivo

Definição:

Sintaxe

ScancRef():makeRecords(cIdGrupo,cMesAno,cUfDest,_cFilial)

Parâmetros

Nome	Tipo	Uso	Descrição
cIdGrupo	character	Obrigatório	Identificador do grupo
cMesAno	character	Obrigatório	Identificador do período
cUfDest	character	Obrigatório	Unidade federativa do arquivo
_cFilial	character	Obrigatório	Filial para a qual o arquivo será gerado

writeRecords of Class ScancRef method

Método responsável por escrever o arquivo texto

Definição:

Sintaxe

ScancRef():writeRecords(oWriter)

Parâmetros

Nome	Tipo	Uso	Descrição
oWriter	object	Obrigatório	Objeto da classe FWFileWriter responsável pela escrita no arquivo texto

writeCounters of Class ScancRef method

RODAPÉ - gera os totais de linhas de todos os registros do arquvo

Definição:

Sintaxe

ScancRef():writeCounters()

ScancTotais class

RODAPÉ - gera os totais de linhas de todos os registros do arquivo

Definição:

Sintaxe

ScancTotais()

Namespace backoffice.fiscal.arquivos.utils

AnnotationHelper class

Classe no padrão Singleton que fornece um objeto e métodos estáticos para manipulação de annotations

Definição:

Sintaxe

AnnotationHelper()

getDataAnnotation of Class AnnotationHelper method

Organiza as annotations de um objeto em um objeto HashMap de acordo com a chave de pesquisa informada

Definição:

Sintaxe

AnnotationHelper():getDataAnnotation(oObj,cAnnotationName,cKey)

Parâmetros

Nome	Tipo	Uso	Descrição
oObj	Object	Obrigatório	o objeto para o qual se quer obter os dados de annotation
cAnnotationName	Character	Obrigatório	o nome da annotation a ser obtida
cKey	Character	Obrigatório	o índice de pesquisa para o HashMap (deve ser uma propriedade da annotation)

Retorno

Tipo	Descrição
Object	retorna um objeto HashMap

getInstance of Class AnnotationHelper method

Cria uma instância (se não houver) e a fornece

Definição:

Sintaxe

AnnotationHelper():getInstance()

Retorno

Tipo	Descrição
Object	retorna um objeto oAnnotationHelper