# Guida Completa alla Gestione dei Conti in Beancount e Fava

Il tuo piano dei conti è la spina dorsale del tuo registro Beancount. Una gerarchia di conti ben progettata rende ogni report più chiaro, ogni query più veloce e ogni stagione fiscale meno dolorosa. In questa guida, esamineremo tutto ciò che devi sapere sulla creazione, lettura, aggiornamento e chiusura dei conti in Beancount e Fava, dai fondamenti per principianti ai modelli avanzati.



## I Cinque Tipi di Conto

Beancount utilizza il modello standard di contabilità a partita doppia con esattamente cinque tipi di conto radice:

| Tipo              | Scopo                                               | Segno Normale        | Report             |
| ----------------- | --------------------------------------------------- | -------------------- | ------------------ |
| **Attività**      | Risorse che possiedi (contanti, investimenti, immobili) | Positivo (dare)      | Stato Patrimoniale |
| **Passività**     | Debiti che devi (carte di credito, prestiti, mutui)  | Negativo (avere)     | Stato Patrimoniale |
| **Patrimonio Netto** | Capitale del proprietario, utili non distribuiti, saldi di apertura | Negativo (avere)     | Stato Patrimoniale |
| **Reddito**       | Fonti di entrata (stipendio, interessi, dividendi)  | Negativo (avere)     | Conto Economico    |
| **Spese**         | Categorie di costo (cibo, affitto, utenze)          | Positivo (dare)      | Conto Economico    |

L'equazione contabile fondamentale vale sempre:

```
Attività + Spese + Patrimonio Netto + Reddito + Passività = 0
```

Un'euristica utile: se gli importi sono rilevanti solo per un **periodo di tempo** (es. "Quanto ho speso per il cibo questo mese?"), usa Reddito o Spese. Se rappresentano un **saldo in corso** (es. "Quanto c'è nel mio conto corrente?"), usa Attività o Passività.

## Convenzioni di Denominazione dei Conti

I nomi dei conti in Beancount sono identificatori gerarchici separati da due punti. Le regole sono:

- Devono iniziare con uno dei cinque tipi radice: `Assets`, `Liabilities`, `Equity`, `Income`, `Expenses`
- Ogni componente inizia con una **lettera maiuscola o un numero**
- I componenti possono contenere lettere, numeri e trattini (nessuno spazio o trattino basso)
- Sono richiesti **almeno due componenti** (es. `Expenses:Food`, non solo `Expenses`)
- I due punti (`:`) separano i livelli gerarchici

```beancount
; Nomi di conto validi
Assets:US:BofA:Checking
Liabilities:CA:RBC:CreditCard
Equity:Retained-Earnings
Income:US:Acme:Salary
Expenses:Food:Groceries
Assets:Crypto:BTC-Holdings

; Nomi di conto non validi
assets:checking          ; tipo radice in minuscolo
Assets:my checking       ; spazi non consentiti
Expenses                 ; solo un componente
```

Il modello di denominazione raccomandato per i **conti dello stato patrimoniale** è:

```
Tipo : Paese : Istituto : Conto : Sottoconto
```

Ad esempio: `Assets:US:Vanguard:401k:VTSAX` o `Liabilities:US:Chase:Sapphire`.

Per **conti di spesa e reddito**, utilizza invece una denominazione basata sulla categoria:

```
Expenses:Food:Groceries
Expenses:Housing:Utilities:Electric
Income:US:Employer:Salary
```

### Personalizzare i Nomi delle Radici

Puoi rinominare i cinque tipi radice per localizzazione o preferenza personale:

```beancount
option "name_assets"       "Actifs"
option "name_liabilities"  "Passifs"
option "name_equity"       "Capital"
option "name_income"       "Revenus"
option "name_expenses"     "Depenses"
```

## Creazione dei Conti (Direttiva Open)

Ogni conto deve essere dichiarato con una direttiva `open` prima di poter registrare transazioni su di esso. La sintassi completa è:

```
YYYY-MM-DD open Account [ValutaVincolata,...] ["MetodoDiCarico"]
```

### Apertura Base

```beancount
2014-05-01 open Assets:US:BofA:Checking
```

### Con Vincoli di Valuta

Limitare le valute previene la registrazione accidentale della valuta sbagliata:

```beancount
2014-05-01 open Assets:US:BofA:Checking       USD
2014-05-01 open Assets:Cash                    USD,CAD,EUR
2012-03-01 open Assets:US:ETrade:Main:ITOT     ITOT
```

### Con Metodi di Carico

Per i conti di investimento, specifica come vengono abbinate le partite quando vendi:

```beancount
2014-02-11 open Assets:US:ETrade:IVV   IVV   "FIFO"
2014-02-11 open Assets:US:Schwab:AAPL  AAPL  "LIFO"
2014-02-11 open Assets:US:Fidelity     GOOG  "STRICT"
```

Metodi di carico disponibili:

| Metodo     | Comportamento                                                          |
| ---------- | ---------------------------------------------------------------------- |
| `"STRICT"` | Predefinito. Richiede la specifica esatta della partita; errore in caso di ambiguità |
| `"FIFO"`   | First-In-First-Out -- riduce prima le partite più vecchie              |
| `"LIFO"`   | Last-In-First-Out -- riduce prima le partite più recenti               |
| `"AVERAGE"` | Unisce tutte le partite e ricalcola il costo medio                      |
| `"NONE"`   | Nessun abbinamento di partite; qualsiasi prezzo accettato               |

### Con Metadati

```beancount
2013-03-14 open Assets:US:BTrade:HOOLI
  category: "taxable"
  institution: "BTrade Corp"
  account-number: "XX-1234-5678"
```

### Scegliere le Date di Apertura in Modo Strategico

- Usa la tua **data di nascita** per conti universali come `Expenses:Groceries` (questo ti dà somme a vita)
- Usa la **data di inizio del rapporto di lavoro** per i conti di reddito legati al lavoro
- Usa la **data effettiva di creazione del conto** per conti specifici dell'istituto (conti bancari, carte di credito)

### Apertura Automatica con un Plugin

Se vuoi saltare le direttive `open` manuali durante la prototipazione:

```beancount
plugin "beancount.plugins.auto_accounts"
```

Questo genera automaticamente le direttive `open` per qualsiasi conto a cui si fa riferimento nelle transazioni. Tuttavia, ciò riduce il rilevamento degli errori di battitura, quindi **non è raccomandato per la produzione**.

## Elencare e Interrogare i Conti

### Usare bean-query (BQL)

```bash
# Elenca tutti i conti con i saldi
bean-query ledger.beancount "SELECT account, units(sum(position)) GROUP BY 1"

# Elenca solo i conti spesa
bean-query ledger.beancount "SELECT account WHERE account ~ 'Expenses'"

# Estratto conto con saldo progressivo
bean-query ledger.beancount \
  "SELECT date, account, position, balance WHERE account ~ 'BofA:Checking'"

# Vista giornale per un conto specifico
bean-query ledger.beancount "JOURNAL 'Assets:US:BofA:Checking'"
```

### Usare bean-report

```bash
# Bilancio di verifica (tutti i conti con saldi finali)
bean-report ledger.beancount balances

# Stato patrimoniale
bean-report ledger.beancount balsheet

# Conto economico
bean-report ledger.beancount income

# Giornale per un conto specifico
bean-report ledger.beancount journal -a Assets:US:BofA:Checking
```

### Usare Fava

Fava fornisce una ricca interfaccia visiva per esplorare i conti:

- **Pagina Stato Patrimoniale**: albero interattivo di tutte le Attività, Passività e Patrimonio Netto
- **Pagina Conto Economico**: albero interattivo di tutti i Redditi e le Spese
- **Pagina Conto**: clicca su qualsiasi nome di conto per vedere le schede Giornale, Variazioni e Saldi
- **Barra dei filtri**: usa espressioni regolari per mostrare solo i conti corrispondenti (es. `Assets:US`)

## Aggiornamento dei Conti (Rinomina e Riorganizzazione)

Beancount non ha una direttiva di rinomina incorporata, ma esistono diversi approcci.

### 1. Trova e Sostituisci

La semplice ricerca e sostituzione funziona, ma fai attenzione: `Assets:Bank` corrisponderebbe anche a `Assets:Bank:Cash`. Usa pattern che rispettino i confini delle parole:

```bash
sed -i 's/Assets:US:OldBank:Checking/Assets:US:NewBank:Checking/g' *.beancount
```

### 2. Il Plugin rename_accounts

Il pacchetto [beancount_reds_plugins](https://github.com/redstreet/beancount_reds_plugins) fornisce un potente plugin di rinomina:

```beancount
plugin "beancount_reds_plugins.rename_accounts.rename_accounts" "{
  'Expenses:Taxes' : 'Income:Taxes',
  'Assets:House:Capital-Improvements' : 'Expenses:House:Appliances',
}"
```

Questo plugin:

- Usa la corrispondenza di sottostringhe (`Expenses:Taxes:Federal` diventa automaticamente `Income:Taxes:Federal`)
- Supporta regex con backreference
- Genera automaticamente le direttive Open per i conti rinominati
- **Non** modifica i tuoi file sorgente -- cambia solo la rappresentazione in memoria
- Può essere attivato/disattivato commentando la riga del plugin

### 3. Modello Chiudi e Riapri

Per le migrazioni di conti reali (es. cambio banca):

```beancount
; Vecchio conto
2010-01-01 open Assets:US:OldBank:Checking  USD

; Chiudi il vecchio, apri il nuovo
2024-06-15 close Assets:US:OldBank:Checking
2024-06-15 open Assets:US:NewBank:Checking  USD

; Trasferisci il saldo rimanente
2024-06-15 * "Trasferimento alla nuova banca"
  Assets:US:OldBank:Checking    -5000.00 USD
  Assets:US:NewBank:Checking     5000.00 USD
```

## Chiusura dei Conti

La direttiva `close` segna un conto come non più attivo:

```beancount
2016-11-28 close Liabilities:CreditCard:CapitalOne
```

### Cosa Fa la Chiusura

- Genera un errore se si verificano registrazioni **dopo** la data di chiusura
- Filtra il conto dai report al di fuori del suo periodo attivo
- Indica a Fava di nascondere il conto dalle viste ad albero (configurabile)

### Quando Chiudere i Conti

- Quando chiudi un conto bancario o una carta di credito reale
- Quando cambi datore di lavoro
- Quando consolidi o riorganizzi il tuo piano dei conti
- Quando vendi una proprietà o chiudi una posizione di investimento

### Assert Sempre Saldo Zero Prima di Chiudere

Beancount **non** verifica automaticamente un saldo zero alla chiusura. Aggiungi un assert manuale:

```beancount
2023-12-31 balance Assets:US:OldBank:Savings  0.00 USD
2023-12-31 close Assets:US:OldBank:Savings
```

## Organizzare il Tuo Piano dei Conti

### Inizia in Modo Semplice, Perfeziona nel Tempo

Non hai bisogno del piano dei conti perfetto dal primo giorno. Inizia con categorie ampie e suddividile man mano che le tue esigenze di reporting crescono. L'autore di Beancount riferisce di avere oltre 250 conti spesa, tutti creati organicamente nel tempo.

### Modelli di Organizzazione Comuni

**Modello 1: Per Istituto** (per i conti dello stato patrimoniale)

```beancount
Assets:US:BofA:Checking
Assets:US:BofA:Savings
Assets:US:Vanguard:401k:VTSAX
Assets:US:Vanguard:401k:VBTLX
Liabilities:US:Amex:Platinum
Liabilities:US:Chase:Sapphire
```

**Modello 2: Per Categoria** (per i conti di reddito e spesa)

```beancount
Expenses:Food:Groceries
Expenses:Food:Restaurant
Expenses:Food:Coffee
Expenses:Housing:Rent
Expenses:Housing:Insurance
Expenses:Housing:Utilities:Electric
Expenses:Housing:Utilities:Water
Expenses:Transport:Subway
Expenses:Transport:Gas
Expenses:Health:Medical
Expenses:Health:Dental
```

**Modello 3: Per Geografia** (per finanze multinazionali)

```beancount
Assets:US:BofA:Checking
Assets:CA:RBC:Checking
Assets:UK:HSBC:Current
Income:US:Acme:Salary
Income:CA:Freelance:Consulting
```

**Modello 4: Per Proprietà o Progetto** (per immobili o aziende)

```beancount
Assets:US:Loft4530:Property
Income:US:Loft4530:Rental
Expenses:Loft4530:Electricity
Expenses:Loft4530:Insurance
Expenses:Loft4530:Maintenance
```

**Modello 5: Rispecchiamento dei Conti Correlati** (stesso componente istituto)

```beancount
Assets:US:ETrade:Cash
Assets:US:ETrade:AAPL
Income:US:ETrade:Dividends
Income:US:ETrade:PnL
Expenses:US:ETrade:Commissions
```

### Quanto Dovrebbero Essere Profonde le Gerarchie?

- **2-3 livelli** è comune per le categorie di spesa (`Expenses:Food:Restaurant`)
- **3-4 livelli** per articoli patrimoniali strutturati (`Assets:US:Vanguard:401k:VTSAX`)
- **Evita di superare i 5 livelli** a meno che tu non abbia una forte ragione di reporting
- Le gerarchie profonde funzionano bene quando Fava le comprime nelle viste ad albero

### Un Esempio Reale

Ecco un piano dei conti pratico per la finanza personale:

```beancount
; ── Attività ──
Assets:US:BofA:Checking         USD
Assets:US:BofA:Savings          USD
Assets:US:Vanguard:401k:VTSAX  VTSAX
Assets:US:Vanguard:Roth:VTSAX  VTSAX
Assets:US:ETrade:Cash           USD
Assets:US:ETrade:AAPL           AAPL
Assets:Cash:Wallet              USD

; ── Passività ──
Liabilities:US:Amex:Platinum    USD
Liabilities:US:Chase:Freedom    USD
Liabilities:US:BofA:Mortgage    USD

; ── Reddito ──
Income:US:Employer:Salary
Income:US:Employer:Bonus
Income:US:Employer:Match401k
Income:US:ETrade:Dividends
Income:US:BofA:Interest

; ── Spese ──
Expenses:Food:Groceries
Expenses:Food:Restaurant
Expenses:Food:Coffee
Expenses:Housing:Rent
Expenses:Housing:Insurance
Expenses:Housing:Utilities:Electric
Expenses:Housing:Utilities:Water
Expenses:Transport:Subway
Expenses:Transport:Taxi
Expenses:Transport:Gas
Expenses:Health:Medical
Expenses:Health:Dental
Expenses:Health:Pharmacy
Expenses:Shopping:Clothing
Expenses:Shopping:Electronics
Expenses:Entertainment:Streaming
Expenses:Entertainment:Books
Expenses:Travel:Flights
Expenses:Travel:Hotels
Expenses:Taxes:Federal
Expenses:Taxes:State
Expenses:Taxes:SocialSecurity
Expenses:Taxes:Medicare

; ── Patrimonio Netto ──
Equity:Opening-Balances
Equity:Retained-Earnings
```

## Funzionalità Specifiche di Fava

### Indicatori di Aggiornamento

Una delle migliori funzionalità di Fava per la gestione dei conti. Aggiungi questi metadati a qualsiasi conto:

```beancount
2014-05-01 open Assets:US:BofA:Checking  USD
  fava-uptodate-indication: TRUE
```

Fava mostra poi dei punti colorati accanto al conto:

- **Punto verde**: l'ultima voce è un assert di saldo positivo (conto riconciliato)
- **Punto rosso**: l'ultima voce è un assert di saldo fallito (richiede attenzione)
- **Punto giallo**: l'ultima voce esiste ma non è un assert di saldo (non ancora riconciliato)
- **Punto grigio**: nessuna attività nel periodo di lookback

Configura la soglia del grigio:

```beancount
2016-06-14 custom "fava-option" "uptodate-indicator-grey-lookback-days" "60"
```

### Controlli della Vista ad Albero

Controlla come Fava visualizza i conti:

```beancount
; Mostra i conti chiusi nell'albero
2016-06-14 custom "fava-option" "show-closed-accounts" "true"

; Mostra i conti con zero transazioni
2016-06-14 custom "fava-option" "show-accounts-with-zero-transactions" "true"

; Mostra i conti con saldo zero
2016-06-14 custom "fava-option" "show-accounts-with-zero-balance" "true"
```

### Pattern di Compressione

Comprimi i conti profondamente annidati per impostazione predefinita:

```beancount
; Comprimi tutti i conti a 3+ livelli di profondità
2016-06-14 custom "fava-option" "collapse-pattern" ".*:.*:.*"

; Comprimi sottoalberi specifici
2016-06-14 custom "fava-option" "collapse-pattern" "Assets:US:Vanguard:.*"
```

### Includi Figli nel Giornale del Conto

Quando visualizzi il giornale di un conto in Fava, includi le registrazioni dei conti figli:

```beancount
2016-06-14 custom "fava-option" "account-journal-include-children" "true"
```

### Inverti i Segni per Leggibilità

Per impostazione predefinita, reddito e passività vengono mostrati come numeri negativi (il loro segno naturale). Per visualizzarli come positivi:

```beancount
2016-06-14 custom "fava-option" "invert-income-liabilities-equity" "true"
```

### Gestione dei Documenti

Fava integra la gestione dei documenti con la tua gerarchia di conti. Imposta una directory per i documenti:

```beancount
option "documents" "/percorso/dei/documenti"
```

Quindi organizza i file per percorso del conto:

```
/percorso/dei/documenti/
  Assets/
    US/
      BofA/
        Checking/
          2024-01-15.estratto-conto-gennaio.pdf
          2024-02-15.estratto-conto-febbraio.pdf
  Liabilities/
    US/
      Amex/
        Platinum/
          2024-03-15.fattura-marzo.pdf
```

I file che iniziano con `YYYY-MM-DD` vengono scoperti automaticamente da Fava e appaiono nella vista del giornale del conto.

## Errori Comuni e Come Evitarli

### 1. Errori di Battitura nei Nomi dei Conti

Un semplice errore di battitura come `Expenses:Grocries` crea un nuovo conto non intenzionale.

**Soluzione**: Non usare il plugin `auto_accounts` in produzione. Richiedi direttive `open` esplicite. Beancount segnalerà immediatamente un errore per qualsiasi conto non dichiarato:

```
ERROR: Riferimento non valido al conto sconosciuto 'Expenses:Grocries'
```

### 2. Dimenticare i Vincoli di Valuta

Senza vincoli di valuta, puoi registrare accidentalmente EUR su un conto solo USD.

**Soluzione**: Specifica sempre le valute nelle direttive open:

```beancount
2014-01-01 open Assets:US:BofA:Checking  USD
```

### 3. Non Eseguire Assert di Saldo Regolarmente

Senza assert di saldo regolari, gli errori possono passare inosservati per mesi.

**Soluzione**: Aggiungi assert di saldo mensili per ogni conto attivo:

```beancount
2024-01-01 balance Assets:US:BofA:Checking   5,432.10 USD
2024-02-01 balance Assets:US:BofA:Checking   4,890.55 USD
2024-03-01 balance Assets:US:BofA:Checking   6,123.00 USD
```

### 4. Convenzioni di Denominazione Incoerenti

Mescolare modelli (es. `Expenses:Food` vs `Expenses:US:Food`) rende confuse le query e i report.

**Soluzione**: Scegli una convenzione e mantienila. Usa prefissi paese per i conti patrimoniali, denominazione basata sulla categoria per redditi e spese.

### 5. Chiudere Senza Assert di Saldo Zero

La direttiva `close` non verifica il saldo. Potresti chiudere un conto che ha ancora soldi.

**Soluzione**: Associa sempre la chiusura a un assert di saldo:

```beancount
2023-12-31 balance Assets:US:OldBank:Savings  0.00 USD
2023-12-31 close Assets:US:OldBank:Savings
```

## Modelli Avanzati

### Consigli per la Multivaluta

Dichiara le tue valute operative per colonne di report dedicate:

```beancount
option "operating_currency" "USD"
option "operating_currency" "EUR"
```

Per i conti multivaluta, elenca tutte le valute consentite:

```beancount
2014-01-01 open Assets:Cash  USD,CAD,EUR
```

Gli assert di saldo con più valute devono essere eseguiti una valuta alla volta:

```beancount
2024-01-01 balance Assets:Cash     562.00 USD
2024-01-01 balance Assets:Cash     210.00 CAD
2024-01-01 balance Assets:Cash      60.00 EUR
```

### Pad e Saldo per la Configurazione Iniziale

Usa la direttiva `pad` per stabilire i saldi di apertura senza calcolare manualmente gli importi:

```beancount
2000-05-28 open Assets:US:BofA:Checking  USD
2000-05-28 pad Assets:US:BofA:Checking  Equity:Opening-Balances
2024-07-01 balance Assets:US:BofA:Checking  12,345.67 USD
```

Beancount sintetizza automaticamente la transazione di rettifica. Un'importante avvertenza: gli assert di saldo verificano il saldo all'**inizio** della data specificata. Quindi un pad il 2 gennaio necessita di un assert di saldo il 3 gennaio o successivo.

### Metadati dei Conti per la Categorizzazione

Usa i metadati sulle direttive `open` per report personalizzati:

```beancount
2014-01-01 open Assets:US:BofA:Checking  USD
  category: "liquid"
  tax-status: "taxable"

2014-01-01 open Assets:US:Vanguard:401k  USD
  category: "retirement"
  tax-status: "tax-deferred"
```

Interroga i metadati con BQL:

```sql
SELECT account, META("category") WHERE META("tax-status") = "taxable"
```

### Note per la Cronologia del Conto

Allega note datate al giornale di qualsiasi conto:

```beancount
2024-03-20 note Assets:US:BofA:Checking "Chiamato per addebito contestato, rif. #12345"
2024-06-01 note Liabilities:US:Chase:Sapphire "Commissione annuale annullata dopo chiamata alla retention"
```

Queste note appaiono nel giornale del conto in Fava, fornendo una traccia di audit.

### Conti di Monitoraggio e Accantonamento

Beancount non ha le registrazioni virtuali di Ledger, ma puoi usare sottoconti per l'accantonamento:

```beancount
; Monitora il fondo di emergenza all'interno del conto corrente
Assets:US:BofA:Checking:EmergencyFund    USD
Assets:US:BofA:Checking:Operating        USD

; Monitora i rimborsi
Assets:Receivables:Employer:Travel       USD
Assets:Receivables:Friend:SharedDinner   USD
```

### Categorie di Spesa Agevoli per le Tasse

Struttura i conti spesa per facilitare la preparazione fiscale:

```beancount
Expenses:Health:Medical:Deductible
Expenses:Charity:Deductible
Expenses:Business:Office
Expenses:Business:Equipment
Expenses:Education:Professional
```

## Prontuario Rapido

| Compito            | Sintassi                                                                   |
| ------------------ | -------------------------------------------------------------------------- |
| Aprire un conto    | `2024-01-01 open Assets:US:BofA:Checking USD`                              |
| Chiudere un conto  | `2024-12-31 close Assets:US:OldBank:Savings`                               |
| Assert di saldo    | `2024-01-01 balance Assets:US:BofA:Checking 5,432.10 USD`                  |
| Pad per saldo      | `2024-01-01 pad Assets:Cash Equity:Opening-Balances`                       |
| Aggiungere nota    | `2024-01-15 note Assets:US:BofA:Checking "Riconciliazione mensile fatta"`  |
| Allegare documento | `2024-01-15 document Assets:US:BofA:Checking "/percorso/dell/estratto.pdf"`|
| Aggiungere metadati | Coppia chiave-valore indentata sulla riga dopo `open`                      |
| Auto-apertura (dev) | `plugin "beancount.plugins.auto_accounts"`                                |
| Vincolare valuta   | `2024-01-01 open Assets:Cash USD,EUR`                                      |
| Impostare metodo carico | `2024-01-01 open Assets:US:ETrade:AAPL AAPL "FIFO"`                     |

## Riepilogo

Gestire bene i conti è il fondamento di una contabilità Beancount efficace. Ecco i punti chiave:

1. **Usa sempre direttive `open` esplicite** -- catturano errori di battitura e impongono disciplina
2. **Aggiungi vincoli di valuta** per prevenire errori di valuta incrociata
3. **Usa una convenzione di denominazione coerente** -- per istituto per lo stato patrimoniale, per categoria per redditi/spese
4. **Inizia in modo semplice e perfeziona** -- suddividi i conti man mano che le tue esigenze di reporting crescono
5. **Esegui assert di saldo regolarmente** -- la riconciliazione mensile coglie gli errori presto
6. **Chiudi i conti correttamente** -- con un assert di saldo zero
7. **Sfrutta le funzionalità di Fava** -- indicatori di aggiornamento, pattern di compressione e integrazione dei documenti
8. **Usa i metadati** per categorizzazione e reporting personalizzati

Buona contabilità!
