Money

Este documento descreve o padrão Money, a forma como pode ser utilizado nos produtos e as propriedades da sua implementação interna.

Conceitos

Money

Tipo de domínio da Framework que representa um valor monetário numa determinada moeda.

Currency

Representa uma moeda.

Exchange Rate A taxa de câmbio, de forma simplificada, é um fator de conversão entre duas moedas. As tabelas de câmbio são definidas pelos bancos centrais. Numa transação, dentro de determinadas regras, o câmbio pode ser acordado entre as partes, não sendo obrigatório a utilização do câmbio oficial.

Transação

Documento que representa uma operação transacional.

Transação Monetária

Transação que envolve valores monetários (transferência de dinheiro).

Moeda da Transação

Moeda em que todos os valores monetários de uma transação estão representados. Também designada por moeda original. Por exemplo, quando uma empresa portuguesa compra um produto a uma empresa inglesa, a moeda da transação é a Libra Esterlina (GBP).

Moeda Base

Moeda principal de gestão da empresa, tipicamente a moeda oficial do país onde esta está localizada. Moeda em que os movimentos são analisados e em que a empresa presta contas. Todas as transações realizadas no sistema devem ser convertidas para a moeda base. Na versão atual da Framework a moeda base é definida na entidade CorePatterns.Company, ou seja, existirá uma por cada empresa existente no sistema.

Moeda de Reporting

Também designada por moeda alternativa, é uma segunda moeda de gestão. Esta moeda é particularmente importante nos países em que a moeda local não tem estabilidade e também muito útil para filiais de multinacionais que precisam de reportar à casa mãe numa moeda distinta da moeda do país em que operam (moeda base). Todas as transações devem ser convertidas para esta moeda. Na versão atual da Framework a moeda de reporting é definida na entidade CorePatterns.Organization, ou seja, existirá apenas uma por organização, partilhada entre todas as empresas. Quando uma determinada entidade não for company-dependent, ou seja, for “partilhada” entre todas as empresas, a respetiva moeda base será a mesma que a moeda de reporting definida na organização.

Requisitos Principais

Moedas - A cada moeda deve ser associado o número de casas decimais para efeitos de arredondamento aquando da conversão para essa moeda a partir de uma outra, o número de casas decimais é obtido na entidade currency e nos campos FractionDigits ou PriceFractionDigits, dependendo da modelação. - Quando se trate de uma “sub moeda”, deve ser indicada a moeda de referência (moeda “mãe”)

Tabelas Cambiais - As tabelas cambiais têm que ser representadas no sistema com a mesma lógica que o respetivo banco central determina. Ou seja, sempre que uma taxa de câmbio esteja visível ao utilizador (para introdução ou consulta) deve respeitar a forma como são definidas. - Cada câmbio deve estar associado a um par moeda origem e moeda destino.

Transações (ex. Documento) - Associado à transação deve ficar registado: a moeda em que foi realizada, os valores na moeda da transação (ex. preços unitários, valores totais), os câmbios para a moeda base e moeda de reporting (opcional) e os valores calculados nas duas moedas de gestão (base e reporting). - Nota: só precisam de ser convertidos para as moedas de gestão os valores passíveis de serem utilizados para efeitos de reporting (ex. os preços unitários de um documento não precisam de ser convertidos). - Os câmbios associados à transação devem ser sugeridos pela data de emissão do documento, podendo estes serem alterados pelo utilizador.

Conversão de Valores - Para ser possível efetuar a conversão entre duas moedas, tem que estar definido o câmbio para o par moeda origem/moeda destino. - O resultado da conversão de um valor numa determinada moeda para outra deve ser arredondado ao número de casas decimais definidos na ficha da moeda destino.

Reporting - Com exceção da impressão de documentos (tem requisitos próprios), todo o reporting deve ser obtido com base em valores já convertidos e não podem depender de qualquer conversão a realizar no momento.

Desenho

Currency

A moeda é representada por uma entidade definida no módulo CorePatterns. Todos os módulos em que seja necessário representar moedas, deverão fazê-lo através de uma associação para essa entidade, e devem implementar a interface IMonetaryData ou a interface IMonetaryTransaction.

Currency na Base de Dados

A currency é representada na base de dados por: - Uma coluna para a currency - Uma coluna para a currency base - Uma coluna para a currency de reporting

A persistência na base de dados das três moedas facilita a consulta dos valores do Money na currency correta e facilita a leitura dos dados.

Exchange Rates

As taxas de câmbios entre moedas são registadas no sistema através de um documento que facilita o registo de câmbios entre várias moedas em simultâneo: ExchangeRatesDocument.

Quando um documento deste tipo é registado, são produzidos também registos nas entidades ExchangeRates e CurrencyRate. A primeira é utilizada por um application service que permite obter o câmbio entre duas moedas. A segunda é utilizada pela implementação do tipo Money para fazer a conversão entre moedas.

Todas estas entidades estão também disponíveis no módulo Business Patterns e são internas a esse módulo.

Money

O Money na Framework Elevation é: - Um tipo de domínio que facilita a modelação de entidades que têm valores monetários. - Um tipo C#, definido no módulo Core Patterns, que encapsula toda a lógica de manipulação de valores monetários de acordo com os requisitos anteriores.

Tipo de Domínio Money

Todos os valores monetários devem ser representados no modelo de entidades por atributos do tipo Money.

Tipo C# Money

Este tipo C# está definido na assembly Primavera.Business.Patterns.Api e inclui:

• Todos os construtores do tipo usados nas mais variadas situações.
• Operadores (+, -, *, etc.).
• Toda a lógica de conversão do valor entre a moeda da transação e as moedas base e de reporting.
• As seguintes propriedades:
• Amount – valor monetário.
• DataAmount – valor do Amount como armazenado na base de dados.
• Currency – moeda do valor monetário.
• BindAmount – valor usado no binding.
• BaseAmount – valor na moeda base.
• ReportingAmount – valor na moeda de reporting.
• ExchRateBase – taxa de câmbio para a moeda base.
• ExchRateReporting – taxa de câmbio para a moeda de reporting.
• ExchangeRate – taxa de câmbio para a moeda base que pode ser manipulada pelo programador.
• Rounding – forma de arredondamento.
• FractionDigits – número de casas decimais (proveniente do campo fraction digits ou prices fraction digits).
• Métodos para tratamento de arredondamento, inicialização de valores, etc.

Money no POCO

Para cada atributo (exemplo: Total) de uma entidade modelado como Money, existirá no respetivo POCO:

• Uma propriedade para o Money (exemplo: Total).

Tipo C# MoneyResource

Este tipo C# está definido na assembly Primavera.Core.Patterns.Api e inclui:

• As seguintes propriedades:
• Amount – valor monetário.
• BaseAmount – valor na moeda base.
• ReportingAmount – valor na moeda de reporting.
• Symbol – símbolo da currency .
• FractionDigits – número de casas decimais (proveniente do campo fraction digits ou prices fraction digits).
• Métodos para tratamento de arredondamento, inicialização de valores, etc.

MoneyResource nas Resources

Para cada atributo (exemplo: Total) de uma entidade modelado como Money, existirá no respetiva resource:

• Uma propriedade para o MoneyResource (exemplo: Total), esta resource representa um money do lado do cliente.

Money na Base de Dados

Para cada atributo (exemplo: Total) de uma entidade modelado como Money, existirá na respetiva tabela:

• Uma coluna para o valor monetário (exemplo: TotalAmount).
• Uma coluna para o valor na moeda base (exemplo: TotalAmountBase).
• Uma coluna para o valor na moeda de reporting (exemplo: TotalAmountReporting).

Transação Monetária

A Framework Athena suporta dois tipos de transações monetárias: - Um tipo em que o utilizador pode selecionar a moeda da transação apenas, representado pelo interface IMonetaryData. - Um outro tipo em que o utilizador pode selecionar a moeda da transação e definir o câmbio dessa moeda para a moeda base, representado pelo interface IMonetaryTransaction. Não é possível implementar transações que envolvam valores monetários sem existir a implementação de uma das interfaces referidas acima.

Quando uma entidade master não implementa nenhuma destas interfaces, se as suas entidades detalhe possuírem atributos do tipo Money, devem, elas próprias, implementar a interface IMonetaryData. O mesmo acontece para entidades detalhe de uma entidade detalhe.

Nos casos em que as entidades master e detail possuem atributos Money, apenas a entidade master pode implementar uma das interfaces.

Transações IMonetaryData

Uma transação monetária deste tipo tem as seguintes características: - A entidade respetiva deverá incluir uma moeda (Currency). - Todos os valores Money dessa entidade e de todas as entidades detalhe estarão representados nessa moeda. Nenhum valor pode ser representado noutra moeda. - A moeda base é a da empresa da transação se a entidade respetiva for company depedent.

Transações IMonetaryTransaction

Uma transação monetária deste tipo tem as seguintes características: - O cabeçalho do documento respetivo deverá incluir uma moeda (Currency) e uma taxa de câmbio (ExchangeRate e ExchangeRateDate) dessa moeda para a moeda base. - Todos os valores Money dessa entidade e de todas as entidades detalhe estarão representados nessa moeda. Nenhum valor pode ser representado noutra moeda. - O utilizador poderá alterar a taxa de câmbio sugerida (a partir das taxas de câmbio previamente registadas), o que afetará a conversão para a moeda base. - A moeda base é a da empresa da transação se a entidade respetiva for company depedent.

IMonetaryData

Este interface é usado na Framework de modelação para indicar que uma determinada entidade representa uma transação monetária desse tipo. Tem as seguintes propriedades: - CurrencyId (Guid?) – representa o id da moeda da transação . - CurrencyBaseId – representa o id da moeda base da transação. - CurrencyReportingId – representa o id da moeda de reporting da transação.

Este interface deve ser incluído e usado na modelação de entidades quando se pretender que a transação em causa satisfaça os requisitos descritos no ponto anterior.

IMonetaryTransaction

Este interface é usado na Framework de modelação para indicar que uma determinada entidade representa uma transação monetária. Tem as seguintes propriedades: - CurrencyId (Guid?) – representa o id da moeda da transação. - CurrencyBaseId – representa o id da moeda base da transação. - CurrencyReportingId – representa o id da moeda de reporting da transação. - ExchangeRate (decimal) – representa a taxa de câmbio da moeda da transação para a moeda base e que o utilizador pode manipular. - ExchangeRateDate (datetime) – representa a data de câmbio associada à taxa de câmbio anterior.

Este interface deve ser incluído e usado na modelação de entidades quando se pretender que a transação em causa satisfaça os requisitos descritos no ponto anterior.

Modelação de Transações

No contexto da modelação de transações com valores em dinheiro, existem três cenários principais suportados nativamente:

1. Numa moeda específica, definida pelo utilizador – todos os valores em dinheiro estão registados nessa moeda da transação. Este tipo de transação deve ser modelado com o interface IMonetaryData.
2. Numa moeda específica, definida pelo utilizador e com uma taxa de câmbio para a moeda base. Este tipo de transação deve ser modelado com o interface IMonetaryTransaction.

Com IMonetaryData

Neste caso todos os valores Money da entidade e das entidades detalhe estarão representados na moeda definida no cabeçalho pelo atributo Currency imposto pelo interface IMonetaryData.

Com IMonetaryTransaction

Neste caso todos os valores Money da entidade e das entidades detalhe estarão representados na moeda definida no cabeçalho pelo atributo Currency imposto pelo interface IMonetaryTransaction.

Company-dependent

Qualquer uma das alternativas de modelação descritas anteriormente pode ser concretizada com entidades company-dependent ou, como nos exemplos apresentados, como entidades não company-dependent.

Tipicamente a utilização de valores monetários estará, na maioria dos casos, associada a entidades company-dependent para que a moeda base seja a definida para cada empresa, também porque a maior dos documentos transacionais serão company-dependent.

Cenários

Cenário 1 - Transação Monetária Dependente da Empresa com Registo de Câmbios

A entidade em causa é company-dependent e permite ao utilizador definir a moeda da transação e o câmbio dessa moeda para a moeda base. A entidade é sempre um cabeçalho . A entidade tem um mais valores monetários em si mesma e/ou nos seus detalhes.

Notas sobre a implementação: - A empresa é definida no cabeçalho. - A moeda, a taxa de câmbio e a data de câmbio são definidas no cabeçalho. - A moeda da transação é a selecionada no cabeçalho. - Ou a moeda base da empresa selecionada se a moeda da transação não estiver selecionada. - Ou a moeda de reporting da organização se a empresa não estiver selecionada. - A moeda base é a da empresa selecionada. - Ou a moeda de reporting da organização se a empresa não estiver selecionada. - A moeda de reporting é a da organização de contexto.

Cenário 2 – Transação Monetária Não Dependente da Empresa com Registo de Câmbios

A entidade em causa não é company-dependent e permite ao utilizador definir a moeda da transação e o câmbio dessa moeda para a moeda base. A entidade é sempre um cabeçalho . A entidade tem um mais valores monetários em si mesma e/ou nos seus detalhes.

Notas sobre a implementação: - A moeda, a taxa de câmbio e a data de câmbio são definidas no cabeçalho. - A moeda da transação é a selecionada no cabeçalho. - Ou a moeda de reporting da organização se a moeda da transação não estiver selecionada. - A moeda base é apresentada com o valor Null. - A moeda de reporting é a da organização de contexto.

Cenário 3 – Transação Monetária Dependente da Empresa sem Registo de Câmbios

A entidade em causa é company-dependent e permite ao utilizador definir a moeda da transação. A entidade com estas características pode ser um cabeçalho ou um detalhe de outra entidade. A entidade tem um mais valores monetários em si mesma e/ou nos seus detalhes.

Notas sobre a implementação: - A empresa é definida na entidade. - A moeda da transação é a selecionada da entidade. - Ou a moeda base da empresa selecionada se a moeda da transação não estiver selecionada. - Ou a moeda de reporting da organização se a empresa não estiver selecionada. - A moeda base é a da empresa selecionada. - Ou a moeda de reporting da organização se a empresa não estiver selecionada. - A moeda de reporting é a da organização de contexto.

Cenário 4 – Transação Monetária Não Dependente da Empresa sem Registo de Câmbios

A entidade em causa não é company-dependent e permite ao utilizador definir a moeda da transação. A entidade com estas características pode ser um cabeçalho ou um detalhe de outra entidade. A entidade tem um mais valores monetários em si mesma e/ou nos seus detalhes.

Notas sobre a implementação: - A moeda da transação é a selecionada da entidade. - Ou a moeda de reporting da organização se a moeda da transação não estiver selecionada. - A moeda base é apresentada com o valor Null. - A moeda de reporting é a da organização de contexto.