Lots de Beancount, base de cost i mètodes d'imputació

El sistema d'inventari de Beancount és una característica potent per fer el seguiment d'actius que es compren i es venen al llarg del temps, com ara accions, fons d'inversió o divises estrangeres. Permet un seguiment precís de la base de cost, cosa essencial per calcular els guanys de capital i entendre el rendiment de la cartera. Aquest tutorial cobreix la mecànica fonamental de la gestió d'inventaris al vostre llibre major.

Conceptes bàsics​

En essència, la gestió d'inventaris gira al voltant del seguiment de posicions. Una "posició" és simplement una quantitat d'un producte mantinguda en un compte. Beancount distingeix entre dos tipus fonamentals de posicions.

Tipus de posició​

1. Posició simple (sense cost): Es tracta d'un apunt de saldo estàndard. Representa una quantitat d'un producte sense cap cost d'adquisició associat. És adequat per a efectiu o asserció de saldos simples.

   Assets:Bank:Checking      100.00 USD

2. Posició amb base de cost: Aquest tipus de posició inclou no només el nombre d'unitats i el producte, sinó també el cost al qual es va adquirir. Aquesta és la base del seguiment d'inventaris. El cost s'especifica dins d'unes claus {}.

   Assets:Invest:VTSAX      10 VTSAX {100.00 USD, "lot-1"}

   En aquest exemple, tenim 10 unitats de VTSAX. Cada unitat es va adquirir a un cost de 100,00 USD. Aquest lot específic d'accions s'identifica com un "lot".

Operacions d'inventari​

Hi ha dues operacions principals que podeu fer sobre un inventari:

1. Augmentacions (afegir a l'inventari): Quan compreu un producte, augmenteu el vostre inventari. Creeu un lot nou amb un nombre específic d'unitats i una base de cost.

   2024-01-15 * "Buy shares"
     Assets:Invest:STOCK     50 STOCK {25.00 USD, "lot-1"}
     Assets:Bank:Checking   -1250.00 USD

   Aquí, comprem 50 unitats de STOCK a un cost per unitat de 25,00 USD. Això crea un lot al compte Assets:Invest:STOCK.

2. Reduccions (treure de l'inventari): Quan veneu un producte, reduïu el vostre inventari. Heu d'especificar de quin lot esteu venent. Això es fa proporcionant informació coincident dins de les claus.

   2024-01-20 * "Sell shares"
     Assets:Invest:STOCK    -25 STOCK {25.00 USD}
     Assets:Bank:Checking    625.00 USD

   En aquesta transacció, venem 25 unitats de STOCK del lot que es va comprar a 25,00 USD per unitat.

Mètodes de registre​

Quan reduïu un inventari, Beancount necessita una regla per decidir de quin lot específic estirar si diversos lots coincideixen amb la reducció. Aquesta regla s'anomena "mètode d'assignació". Podeu establir un valor per defecte per a tot el fitxer amb una opció, o donar a un compte el seu propi mètode a la directiva open.

Beancount 3.2.3 accepta set noms de mètode: STRICT (el valor per defecte), STRICT_WITH_SIZE, NONE, FIFO, LIFO, HIFO i AVERAGE. Sis d'ells estan implementats; AVERAGE es parseja però genera un error en el moment en què ha d'assignar una reducció, tal com mostra la secció AVERAGE a continuació.

1. STRICT (Predeterminat)​

El mètode STRICT és el valor per defecte i el mètode d'assignació més segur. Imposa una coincidència explícita i no ambigua.

2024-01-01 open Assets:Invest:STOCK "STRICT"

• Requereix una coincidència exacta de lot: L'especificador de cost de l'apunt de reducció ({...}) ha d'identificar un sol lot — per cost, per data d'adquisició, per etiqueta o per qualsevol combinació d'aquests.
• Genera errors amb coincidències ambigües: Si l'especificador coincideix amb més d'un lot, Beancount genera un AmbiguousMatchError en lloc d'endevinar.
• Excepció: Si una reducció elimina exactament el nombre total d'unitats amb què coincideix l'especificador, es permet un especificador buit ({}), i la reducció es reparteix entre aquests lots.

Aquest llibre major conté dos lots i ven un d'ells anomenant el seu cost, cosa que no és ambigua:

1970-01-01 commodity STK
1970-01-01 open Assets:Broker:Strict  STK  "STRICT"
1970-01-01 open Assets:Broker:Cash    USD
1970-01-01 open Income:Gains          USD
 
2024-01-10 * "Buy the first lot"
  Assets:Broker:Strict    10 STK {100.00 USD}
  Assets:Broker:Cash   -1000.00 USD
 
2024-02-10 * "Buy the second lot"
  Assets:Broker:Strict    10 STK {120.00 USD}
  Assets:Broker:Cash   -1200.00 USD
 
; The cost identifies exactly one lot, so STRICT is satisfied.
2024-06-01 * "Sell the $120.00 lot"
  Assets:Broker:Strict   -10 STK {120.00 USD} @ 150.00 USD
  Assets:Broker:Cash    1500.00 USD
  Income:Gains

Es carrega sense errors, assigna 300,00 USD de guany a Income:Gains i deixa 10 STK {100.00 USD} al compte.

Substituïu aquest darrer apunt per un especificador buit i el mateix fitxer falla:

; Rejected under STRICT: "-10 STK {}" matches both lots.
2024-06-01 * "Sell 10 shares"
  Assets:Broker:Strict  -10 STK {} @ 150.00 USD
  Assets:Broker:Cash   1500.00 USD
  Income:Gains

Beancount informa de Ambiguous matches for "-10 STK {}" i llista els candidats. Tot i això, vendre tota la posició està bé, perquè no queda res per triar:

; Allowed under STRICT: -20 STK is the entire holding, so the empty
; specifier is split across both lots.
2024-06-01 * "Close the position"
  Assets:Broker:Strict  -20 STK {} @ 150.00 USD
  Assets:Broker:Cash   3000.00 USD
  Income:Gains

Això assigna 800,00 USD de guany — 3.000,00 USD d'ingressos contra 1.000,00 USD + 1.200,00 USD de base — i deixa el compte buit. Aquesta és una propietat del mateix STRICT, no una cosa per la qual hàgiu de canviar a STRICT_WITH_SIZE.

2. FIFO (Primer a Entrar, Primer a Sortir)​

El mètode FIFO assigna automàticament les reduccions contra els lots disponibles més antics primer.

2024-01-01 open Assets:Invest:STOCK "FIFO"

• Resolució automàtica: Resol l'ambigüitat seleccionant els lots coincidents més antics.
• Coincidència cronològica: Assumiu que esteu venent els actius que heu tingut durant més temps. Diverses autoritats fiscals ho tracten com el valor per defecte quan no heu identificat un lot.

3. LIFO (Darrer a Entrar, Primer a Sortir)​

El mètode LIFO és el contrari de FIFO. Assigna les reduccions contra els lots disponibles més nous primer.

2024-01-01 open Assets:Invest:STOCK "LIFO"

• Ordre cronològic invers: Selecciona els lots coincidents adquirits més recentment.
• El més nou, no el més car: LIFO tria només per data d'adquisició. Casualment ven les accions de cost més alt quan els preus han estat pujant, però si el vostre lot més nou és el més barat — que és el que l'exemple següent està construït per mostrar — LIFO realitzarà el guany més gran, no el més petit. El mètode que sempre ven les accions més cares és HIFO, descrit a continuació.

4. HIFO (Highest-In, First-Out)​

El mètode HIFO assigna les reduccions contra els lots disponibles més cars primer, sigui quina sigui la seva data.

2024-01-01 open Assets:Invest:STOCK "HIFO"

• Coincidència per rànquing de cost: Selecciona els lots coincidents amb la base de cost més alta.
• Guany realitzat més petit: Per a un preu de venda determinat, vendre les accions de cost més alt realitza el guany més petit (o la pèrdua més gran). Si podeu fer-lo servir és una qüestió de jurisdicció — als Estats Units, per exemple, triar un lot requereix identificació específica en el moment de la venda — així que tracteu el mètode com un mecanisme de comptabilitat i confirmeu l'elecció fiscal per separat.

5. Comparació de FIFO, LIFO i HIFO en les mateixes lots​

Els tres mètodes només difereixen quan el lot més antic, el més nou i el més car són tres lots diferents. Aquest llibre major ho disposa exactament així — el lot A és el més antic, el lot C és el més nou, i el lot intermedi B és el més car — i després ven 10 accions de tres comptes que només difereixen en el seu mètode d'assignació:

1970-01-01 commodity STK
1970-01-01 open Assets:Broker:Fifo  STK  "FIFO"
1970-01-01 open Assets:Broker:Lifo  STK  "LIFO"
1970-01-01 open Assets:Broker:Hifo  STK  "HIFO"
1970-01-01 open Assets:Broker:Cash  USD
1970-01-01 open Income:Gains        USD
 
; Lot A - the oldest, at $100.00 per share
2024-01-10 * "Buy lot A"
  Assets:Broker:Fifo     10 STK {100.00 USD}
  Assets:Broker:Lifo     10 STK {100.00 USD}
  Assets:Broker:Hifo     10 STK {100.00 USD}
  Assets:Broker:Cash  -3000.00 USD
 
; Lot B - the most expensive, at $120.00 per share
2024-02-10 * "Buy lot B"
  Assets:Broker:Fifo     10 STK {120.00 USD}
  Assets:Broker:Lifo     10 STK {120.00 USD}
  Assets:Broker:Hifo     10 STK {120.00 USD}
  Assets:Broker:Cash  -3600.00 USD
 
; Lot C - the newest, at $90.00 per share
2024-03-10 * "Buy lot C"
  Assets:Broker:Fifo     10 STK {90.00 USD}
  Assets:Broker:Lifo     10 STK {90.00 USD}
  Assets:Broker:Hifo     10 STK {90.00 USD}
  Assets:Broker:Cash  -2700.00 USD
 
; Sell 10 shares out of each account at $150.00 and let each
; account's booking method choose which lot leaves.
2024-06-01 * "Sell 10 shares from each account"
  Assets:Broker:Fifo    -10 STK {} @ 150.00 USD
  Assets:Broker:Lifo    -10 STK {} @ 150.00 USD
  Assets:Broker:Hifo    -10 STK {} @ 150.00 USD
  Assets:Broker:Cash   4500.00 USD
  Income:Gains

Es carrega amb zero errors i assigna 1.400,00 USD de guany en total, repartits així:

La fila de LIFO és la que val la pena mirar fixament: va realitzar el guany més gran dels tres, perquè el lot més nou també era el més barat.

6. STRICT_WITH_SIZE​

STRICT_WITH_SIZE és STRICT més un desempat addicional: quan diversos lots coincideixen però exactament un d'ells conté precisament el nombre d'unitats que esteu traient, es tria aquest lot.

1970-01-01 commodity STK
1970-01-01 open Assets:Broker:Sized  STK  "STRICT_WITH_SIZE"
1970-01-01 open Assets:Broker:Cash   USD
1970-01-01 open Income:Gains         USD
 
2024-01-10 * "Buy 10 shares"
  Assets:Broker:Sized    10 STK {100.00 USD}
  Assets:Broker:Cash  -1000.00 USD
 
2024-02-10 * "Buy 7 shares"
  Assets:Broker:Sized     7 STK {120.00 USD}
  Assets:Broker:Cash   -840.00 USD
 
; Only one lot holds exactly 7 units, so the empty specifier resolves.
2024-06-01 * "Sell 7 shares"
  Assets:Broker:Sized    -7 STK {} @ 150.00 USD
  Assets:Broker:Cash   1050.00 USD
  Income:Gains

Això assigna 210,00 USD de guany contra el lot de 120,00 USD. El fitxer idèntic amb "STRICT" a la línia open falla amb Ambiguous matches for "-7 STK {}".

7. MITJANA (acceptat, però no implementat)​

AVERAGE és un nom vàlid — tant option "booking_method" "AVERAGE" com open … "AVERAGE" es parsegen — però Beancount 3.2.3 no té cap implementació al darrere. Tot aquí es carrega fins a la venda:

1970-01-01 commodity STK
1970-01-01 open Assets:Broker:Avg   STK  "AVERAGE"
1970-01-01 open Assets:Broker:Cash  USD
1970-01-01 open Income:Gains        USD
 
2024-01-10 * "Buy 10 shares at $10.00"
  Assets:Broker:Avg      10 STK {10.00 USD}
  Assets:Broker:Cash  -100.00 USD
 
2024-02-10 * "Buy 10 more at $8.00"
  Assets:Broker:Avg      10 STK {8.00 USD}
  Assets:Broker:Cash   -80.00 USD
 
; An average-cost engine would book this at $9.00 per share. This one refuses.
2024-06-01 * "Sell 5 shares"
  Assets:Broker:Avg      -5 STK {}
  Assets:Broker:Cash    45.00 USD
  Income:Gains

En el moment en què s'ha d'assignar aquesta reducció, el carregador s'atura amb:

AVERAGE method is not supported

No planifiqueu un llibre major al voltant d'això. Si voleu un comportament de cost mitjà avui, manteniu la posició en un compte NONE i calculeu la mitjana vosaltres mateixos, o feu el seguiment de cada lot i accepteu els guanys a nivell de lot.

8. CAP​

El mètode NONE desactiva completament la coincidència de lots.

2024-01-01 open Assets:Invest:STOCK "NONE"

• Sense coincidència de lots: Beancount no intenta fer coincidir les reduccions amb les augmentacions.
• Permet signes barrejats: Això permet que un compte mantingui alhora saldos positius i negatius del mateix producte. Aquest comportament és similar a com l'eina de línia d'ordres Ledger CLI gestiona els productes.

Especificació de lot​

Un "lot" és un bloc específic d'un producte adquirit en un moment i a un preu concrets. Quan creeu o reduïu una posició, podeu especificar els seus atributs de lot en detall.

Especificació completa​

Quan augmenteu un inventari (comprant), podeu especificar fins a tres atributs per al lot, separats per comes dins d'un sol parell de claus:

Assets:Invest:STOCK  10 STOCK {100.00 USD, 2024-01-15, "lot-identifier"}

• 100.00 USD — la base de cost, expressada per unitat.
• 2024-01-15 — la data d'adquisició. Beancount l'omple a partir de la data de la transacció quan l'ometeu, i és per això que els missatges d'error anteriors mostren una data a cada lot.
• "lot-identifier" — una etiqueta de cadena opcional.

Tot i que els tres són opcionals, proporcionar almenys la base de cost és una pràctica estàndard. Les claus han de romandre en una sola línia, i els comentaris dins d'un llibre major comencen amb ;, mai amb #.

Mètodes de coincidència​

Quan reduïu un inventari (venent), feu servir la mateixa sintaxi per especificar de quin lot o lots vendre.

• Coincidència per cost: Aquest és el mètode més comú.

  Assets:Invest:STOCK  -5 STOCK {100.00 USD}

• Coincidència per data: Si els costos són idèntics, podeu desambiguar fent servir la data d'adquisició.

  Assets:Invest:STOCK  -5 STOCK {2024-01-15}

• Coincidència per etiqueta: Les etiquetes proporcionen una manera infal·lible d'identificar un lot.

  Assets:Invest:STOCK  -5 STOCK {"lot-identifier"}

• Deixar el lot al mètode d'assignació: Un conjunt buit de claus {} no anomena cap lot, així que el mètode d'assignació del compte tria. Amb FIFO, LIFO o HIFO aquest és el lot coincident més antic, més nou o més car; amb el STRICT per defecte és un AmbiguousMatchError tret que la reducció buidi exactament els lots coincidents.

  Assets:Invest:STOCK  -5 STOCK {}

Gestió de preus​

És crucial entendre la diferència entre base de cost ({}) i preu (@). Serveixen per a propòsits diferents i no són intercanviables.

Preu vs Cost​

• {cost}: Defineix el cost d'adquisició d'un actiu. Forma part del mateix lot d'inventari i s'utilitza per assignar reduccions i calcular guanys de capital.
• @ price: Una anotació que registra un preu de mercat en el moment d'una transacció. S'utilitza per a conversions de divises o per anotar el valor de mercat en una data concreta.

Aquí teniu els tres escenaris:

1. Anotació de preu (conversió): Feu servir @ per convertir d'una divisa a una altra.

   Assets:Forex     1000 USD @ 0.85 EUR

2. Base de cost (adquisició): Feu servir {} quan compreu un actiu per establir-ne el cost.

   Assets:Invest    10 STOCK {100.00 USD}

3. Tots dos (venda amb registre de preu): Quan veneu un actiu, feu servir {} per identificar el lot que es ven i @ per registrar el preu de venda. Això permet el càlcul automatitzat de guanys de capital.

   Assets:Invest    -10 STOCK {100.00 USD} @ 105.00 USD

   Aquest apunt ven 10 STOCK del lot que va costar 100,00 USD cadascun, a un preu de venda de 105,00 USD cadascun.

Una directiva price independent proporciona dades de referència per a la valoració de mercat. Live Prices pot mantenir aquestes directives per als actius compatibles en llibres majors allotjats. Una actualització deixa els vostres lots, mètode d'assignació, costos d'adquisició i ingressos de venda registrats sense canvis.

Regles d'Ús del Preu​

1. Les anotacions de preu (@) no afecten quin lot s'assigna. La coincidència de lots es gestiona exclusivament per la base de cost ({}) i el mètode d'assignació del compte.
2. El símbol @ s'utilitza només per a:

• Conversions de divises.
• Registrar el valor de mercat d'un actiu en el moment d'una transacció.
• Proporcionar el preu de venda per als càlculs de guanys de capital.

Configuració​

Podeu configurar els mètodes d'assignació globalment o per compte.

Mètode de Registre Global​

Podeu establir un mètode d'assignació per defecte per a tot el vostre fitxer de Beancount fent servir la directiva option.

option "booking_method" "STRICT"

Els valors acceptats són "STRICT" (el valor per defecte quan no establiu res), "STRICT_WITH_SIZE", "NONE", "FIFO", "LIFO", "HIFO" i "AVERAGE". Qualsevol altra cadena es rebutja en el moment de la càrrega amb Error for option 'booking_method'. "AVERAGE" s'accepta aquí i a open, però assignar una reducció amb ell falla, tal com mostra la secció AVERAGE anterior.

Supressió per Compte​

Sovint és útil tenir mètodes diferents per a comptes diferents. Per exemple, podríeu voler FIFO per a un compte de jubilació però STRICT per a un compte de corretatge subjecte a impostos per assegurar-vos que veneu lots fiscals específics. Podeu establir el mètode d'assignació quan obriu el compte.

2024-01-01 open Assets:Retirement:401K "FIFO"
2024-01-01 open Assets:Taxable:Stock  "STRICT"

Millors Pràctiques​

1. Organització de l'inventari: Per mantenir el vostre llibre major net i senzill, es recomana molt utilitzar comptes separats per a cada producte únic que tingueu, i restringir cadascun a aquest producte a la seva directiva open.

   ; GOOD: separate accounts by commodity, each constrained to one
   2024-01-01 open Assets:Invest:VTSAX  VTSAX
   2024-01-01 open Assets:Invest:VFIAX  VFIAX

   Eviteu barrejar accions o fons diferents al mateix compte, ja que complica la gestió de l'inventari. La llista de productes a open fa que Beancount rebutgi un apunt extraviat en lloc de barrejar silenciosament dos inventaris.

2. Gestió de lots:

• Feu servir etiquetes significatives per als lots, especialment per a transaccions específiques com tax-loss harvesting o concessions d'accions d'empleats.

  Assets:Invest:STOCK  10 STOCK {100.00 USD, "tax-loss-harvest-2024"}

• Documenteu les vostres operacions amb comentaris. Això fa que el vostre llibre major sigui més fàcil de llegir i entendre més endavant.

  Assets:Invest:STOCK  -10 STOCK {100.00 USD} @ 110.00 USD ; Gain: 10%

3. Depuració: Si trobeu errors o comportaments inesperats, Beancount proporciona eines per inspeccionar l'estat del vostre inventari.

• Examinar l'estat de l'inventari: Feu servir bea doctor context main.beancount 42 per inspeccionar la transacció de la línia 42, incloent-hi els seus apunts i els saldos dels comptes afectats. Substituïu el nom del fitxer i el número de línia per la transacció que voleu inspeccionar.

  Substituïu <LINENO> pel número de línia just després d'una transacció per veure'n l'efecte.

• Verificar la coincidència de lots: L'eina bea check valida tot el vostre fitxer. Detectarà qualsevol error d'assignació, com ara coincidències de lots ambigües en mode STRICT.