docs: release v1.5.4 - refina lógica de taxas, FIFO e destino declarativo (#11)

Este commit consolida a versão v1.5.4 da especificação técnica, resolvendo as falhas lógicas e omissões apontadas pela comunidade:

- Taxas em Cripto (#4, #5): Adota o feeFiatValue como encargo dedutível puro (Art. 51.º do CIRS) com mais-valia comercial de 0.00€, eliminando o lucro simulado.
- Prioridade FIFO (#6): Implementa a expressão de fallback 'originalAcquisitionDate ?? acquisitionDate' para preservar a antiguidade real em transferências.
- Self-Custody (#7): Repõe a nota explicativa e fundamentação jurídica ancorando o enquadramento de carteiras privadas no Anexo J ao Ofício Circulado 20269/2024, com o devido aviso de salvaguarda técnica.

Closes #4, Closes #5, Closes #6, Closes #7

Author: marotoweb

.gitignore

@@ -0,0 +1 @@
+diff.txt

README.md

@@ -0,0 +1,89 @@
+# Especificação técnica: Modelo de Transações (`Transaction`)
+
+Este documento descreve as propriedades brutas que o motor de cálculo espera receber ao importar movimentos financeiros.
+
+| Campo | Tipo | Descrição | Obrigatório |
+| :--- | :--- | :--- | :--- |
+| `id` | String | Identificador único da transação. | Sim |
+| `date` | String | Data da transação no formato ISO 8601. | Sim |
+| `type` | String | Tipo de transação: `"deposit"`, `"withdrawal"`, `"trade"`. | Sim |
+| `fromAssetSymbol` | String | Símbolo do ativo de origem (para `withdrawal` e `trade`). | Não |
+| `fromAmount` | Number | Quantidade do ativo de origem. | Não |
+| `fromWalletId` | String | ID da carteira de origem. | Não |
+| `toAssetSymbol` | String | Símbolo do ativo de destino (para `deposit` e `trade`). | Não |
+| `toAmount` | Number | Quantidade do ativo de destino. | Não |
+| `toWalletId` | String | ID da carteira de destino. | Não |
+| `feeAmount` | Number | Quantidade da taxa paga. | Não |
+| `feeAssetSymbol` | String | Símbolo do ativo em que a taxa foi paga (ex: "EUR", "BNB"). | Não |
+| `feeFiatValue` | Number | Valor de mercado em euros da taxa de transação no exato momento da operação. Utilizado para deduzir o encargo de forma direta quando a comissão é paga em criptoativos. | Não |
+| `fiatValue` | Number | Valor total em FIAT da transação (para `deposit`/`withdrawal`). | Não |
+| `tag` | String | **Chave fixa em inglês** que categoriza a transação (`"buy"`, `"sell"`, `"staking"`, etc.). | Não |
+| `notes` | String | Notas adicionais do utilizador. | Não |
+
+**Exemplos de `Transaction`:**
+
+*   **Compra (Depósito Fiat):**
+    ```json
+    {
+      "id": "tx_compra_01",
+      "date": "2024-01-20T10:30:00Z",
+      "type": "deposit",
+      "toAssetSymbol": "BTC",
+      "toAmount": 0.2,
+      "toWalletId": "wallet-main-001",
+      "fiatValue": 7000.00,
+      "feeAmount": 14.00,
+      "feeAssetSymbol": "EUR",
+      "tag": "buy"
+    }
+    ```
+
+*   **Venda (Levantamento Fiat):**
+    ```json
+    {
+      "id": "tx_venda_01",
+      "date": "2024-05-22T09:00:00Z",
+      "type": "withdrawal",
+      "fromAssetSymbol": "BTC",
+      "fromAmount": 0.1,
+      "fromWalletId": "wallet-main-001",
+      "fiatValue": 4500.00,
+      "feeAmount": 9.00,
+      "feeAssetSymbol": "EUR",
+      "tag": "sell"
+    }
+    ```
+
+*   **Recompensa de Staking:**
+    ```json
+    {
+      "id": "tx_stake_01",
+      "date": "2024-09-25T13:00:00Z",
+      "type": "deposit",
+      "toAssetSymbol": "ADA",
+      "toAmount": 28.5,
+      "toWalletId": "wallet-main-001",
+      "tag": "staking",
+      "notes": "Recompensa mensal de staking"
+    }
+    ```
+
+*   **Trade (Cripto para Cripto):**
+    ```json
+    {
+      "id": "tx_trade_01",
+      "date": "2024-04-10T14:20:00Z",
+      "type": "trade",
+      "fromAssetSymbol": "BTC",
+      "fromAmount": 0.05,
+      "fromWalletId": "wallet-main-001",
+      "toAssetSymbol": "ETH",
+      "toAmount": 1.0,
+      "toWalletId": "wallet-main-001",
+      "feeAmount": 0.001,
+      "feeAssetSymbol": "ETH",
+      "tag": "trade"
+    }
+    ```
+
+[Voltar](../README.md)

diagrams/fluxograma.dark.png

@@ -0,0 +1,30 @@
+# Especificação técnica: Modelo de entidades (`Wallet`)
+
+Representa uma carteira ou conta numa exchange.
+
+| Campo | Tipo | Descrição | Obrigatório |
+| :--- | :--- | :--- | :--- |
+| `id` | String | Um identificador único para a carteira (ex: UUID). | Sim |
+| `name` | String | Nome dado pelo utilizador à carteira (ex: "Kraken", "Ledger Nano X"). | Sim |
+| `platform` | String | A plataforma ou tipo de hardware (ex: "Kraken", "Ledger"). | Sim |
+| `type` | String | O tipo de carteira. Ex: '*Exchange*', '*Cold Wallet*', '*Hot Wallet*', '*Other*' | Sim |
+| `creationDate`| String | A data de criação no formato ISO 8601. | Sim |
+| `countryCode` | String | Código de duas letras (ISO 3166-1 alfa-2) do país de sede da plataforma ou de residência associada à carteira. | Sim |
+| `fiscalEligibility` | String | **[Calculado]** Classificação do país face à lista de jurisdições fiscais. Valores: `'COOPERATING'`, `'NON_COOPERATING'` (paraísos fiscais), `'UNKNOWN'` (bloqueia o cálculo). | Não |
+
+
+### Propriedades calculadas pelo motor
+* **`fiscalEligibility`:** Determinado de forma automática no início do processamento. O algoritmo cruza o `countryCode` com uma tabela interna de paraísos fiscais (Portaria n.º 150/2004). O estado `'UNKNOWN'` suspende a execução para impedir cálculos errados em jurisdições não mapeadas.
+
+**Exemplo de `Wallet`:**
+```json
+{
+  "id": "wallet-main-001",
+  "name": "Kraken Principal",
+  "platform": "Kraken",
+  "type": "Exchange",
+  "creationDate": "2023-01-01T12:00:00.000Z",
+  "countryCode": "IE"
+}
+```
+[Voltar](../README.md)

diagrams/fluxograma.dark.svg

@@ -51,10 +51,9 @@ flowchart TD
     G4 --> H
 
     H -->|FIAT| H1[Taxa reduz o valor de<br> realização / encargo]
-    H -->|CRYPTO| H2[Micro-alienação: apurar<br> mais/menos-valia da taxa]
-    H2 --> H3{Operação principal<br> tributável?}
-    H3 -->|Sim| H4[Somar taxa como encargo<br> da alienação principal]
-    H3 -->|Não| H5[Registar apenas a<br> micro-alienação da taxa]
+    H -->|CRYPTO| H2[Fixa despesa pelo valor de<br> mercado: feeFiatValue]
+    H2 --> H3[Deduz feeFiatValue como encargo<br> Art. 51.º da operação principal]
+    H3 --> H4[Dá baixa física da fração no FIFO<br> Valor de mercado: Mais-valia taxa = 0€]
 
     %% ESTILIZAÇÃO DO GRAPH
     style A fill:#f9f,stroke:#333,stroke-width:2px,color:#000