Texto del repositorio público, commit 8729248. Fuente: docs/claude/finance.md.
Motor financiero: algoritmos y consistencia del valor de cartera
Detalle movido desde
CLAUDE.mdel 2026-10-04 para que el fichero que se carga en cada sesión solo lleve el índice y las reglas críticas. Léelo antes de tocar esta zona.
Financial algorithms
- TWR (Time Weighted Return):
performanceService.js— correct method, unaffected by cash flows - El día de una compra es un sub-periodo de la cadena TTWROR, no un eslabón muerto (auditoría 2026-07-31):
isolatedTTWRORse calcula(endPureValue + valor al cierre de lo comprado hoy − D) / DconD = startTotalValue + coste de ejecución de lo comprado hoy— la fórmula canónica GIPSV_f/(V_i+C). Antes, el día de la compraassetsAtStartestaba vacío →startTotalValueBase = 0→ el eslabón valía 0 y el movimiento entre tu precio de ejecución y el cierre de ese día se perdía PARA SIEMPRE (caso real: 1 CSU.TO comprada en la apertura del 26-feb-2026 a C$2465,01 con cierre C$2607,72 → el gráfico marcaba +15,94% sobre un +22,52% real; el ROI sí lo captaba, de ahí que los dos números no cuadrasen nunca). Reglas al tocar esto: el coste usa el precio de ejecución, noeur_total(que lleva la comisión: eso es base de coste, no movimiento de mercado); los BUY consolidados quedan FUERA (un snapshot de import no es dinero entrando hoy — meterlo en el denominador diluye el rendimiento real del día); el eslabón se descarta si superaMAX_BUY_DAY_SWING(35%), porque es el único punto de la cadena alimentado por precios de CSV de broker; y sólo se crea si la divisa de ejecución coincide con la de cotización (AMZN comprado en Xetra se liquida en EUR pero Yahoo lo cotiza en USD: comparar esos dos precios mide el tipo de cambio, no el mercado, y un ±15% así se cuela por debajo del guard de magnitud). Tests:performanceService.buyDay.test.js. - Un TTWROR y un ROI que no cuadran suelen ser un COSTE BASE con la divisa mal etiquetada, no un fallo del motor (caso BTC, 2026-07-31): el TTWROR encadena valores de mercado y es inmune al coste; el ROI divide por él. Si difieren en un factor sospechosamente parecido a un tipo de cambio, mira
portfolioHistory.jslínea ~243: cuandotransaction_currency === preferredCurrencyel coste se toma comoqty × preciosin convertir, así que una compra en USD etiquetada EUR infla el coste (y por tanto la pérdida) exactamente 1/FX. Diagnóstico en un cálculo:coste_registrado / (qty × precio_nativo)debe dar el FX del día de la compra; si da ~1,00 con un activo que no cotiza en tu divisa, la etiqueta está mal. El desglose de la fila lo delata igual:gpMonedaes un RESIDUO (profitConverted − gpProducto), así que absorbe entero cualquier error del coste y aparece como una "G/P Moneda" enorme que el mercado no justifica. - FIFO PnL:
fifoAnalytics.js— tracks cost basis per lot, calculates realized gain/loss - Modified Dietz:
dietzAnalytics.js— solo queda la fórmula puracalculateModifiedDietz(testeada); el consumidor con Supabase se borró en 2026-07 (dependía de tablas inexistentes). El breakdown mensual vivo escartera/MonthlyBreakdownChartsobreprocessedImportData.charts - Puntuación de cartera:
src/services/portfolioScoreService.js(puro, decimal.js, testeado) — CUATRO pilares con pesosWEIGHTS30/30/20/20 que suman 100: diversificación (HHI), rentabilidad, control de costes y gestión de liquidez. Cada pilar calcula sobre su máximo histórico propio (25/25/20/15) y se reescala al peso nuevo al final, de modo que la suma de las barras ES el número grande — invariante fijada por test. "Ingresos pasivos" dejó de puntuar el 2026-09-11 (decisión del owner): una cartera de crecimiento perdía hasta 15 puntos por una elección de estrategia, no por un defecto. Al quitarlo había que repartir sus 15 puntos: dejar el máximo en 85 habría descuadrado las partes con el total. El yield sigue calculándose y viaja enbreakdown.income.dividendYieldSINscorenimax, porque el prompt deserver/routes/scorePortfolio.jslo usa para reconocer un perfil growth — si añades un pilar nuevo, actualizaWEIGHTSy el prompt en el mismo commit. - Rebalancing:
src/services/rebalanceService.js(pure, tested) —buildRebalancePlan(positions, opts)sobre los targets reales (positions.target_percentage): agrupa por ISIN (regla general-view, target = max), pesos/drift víacomputeTargetMetrics(mismos números que el bullet-chart de brokers), banda configurable (bandFor: strict ±1pp / moderate ±3pp / regla 5/25) y DOS modos:trade(BUY/SELL/HOLD con importe = |moneyDelta|) ycontribute(reparte una aportación hacia los déficits sin vender — sin impacto fiscal).RebalancingCalculator.jsxla consume; carga posiciones VÍA BROKERS (no por portfolio — el bug histórico) y acepta?broker=<id>(botón "Rebalancear" en PositionActionBar) y?contribution=<importe>(CTA del ahorro del mes en/app/gastos, que precarga el modo aportación). NUNCA reimplementar la asignación inline en la página.
Portfolio Value consistency rules
Single source of truth for prices: assets.current_price in DB is the last price written by the hourly snapshot cron (server/lib/assetPrices.js, service role only since 2026-10-26 — audit 7f2c915d A1). Dashboard and CarteraPage show live prices but NO LONGER write them back: a client-callable price RPC let any account poison the shared table. Never use entry_price as a proxy for current market price.
¿Es liquidez o es un activo? UNA función: isCashPosition (src/lib/positionKind.js) (2026-08-01). El mismo test de dos señales estaba copiado a mano en ~15 sitios, la MITAD sensibles a mayúsculas (asset_class === 'Cash') y la otra mitad no (asset_class?.toLowerCase() === 'cash'), así que una fila guardada como 'cash'/'CASH' era liquidez en la tabla de posiciones y activo invertido en el Dashboard. Medido en demo con una fila asset_class: 'cash', ticker EUR: 9 pos. en vez de 7, "Cash" a 0 € e "Invertido" a 595.060 € en vez de 213.974 € (además el treemap intentaba cotizar el ticker EUR como si fuese una acción). El módulo exporta también isHeldInvestedPosition (no-liquidez + quantity > 0.0001), que es lo que cuenta el "N pos." del widget INVERTIDO: la liquidez NO es una posición. Al añadir una superficie que separe efectivo de activos, importa la función — no vuelvas a escribir el ||. Es Node-compatible (la importan portfolioHistory/portfolioStats, que usa el share server): imports relativos con .js desde services/.
matchesCashIdentity vs isCashPosition (2026-10-28): no son intercambiables. matchesCashIdentity (src/lib/cashIdentity.js) se usa para casar/reutilizar filas de caja en imports y asientos manuales (solo tickers canónicos CASH_XXX / CASH_XXX (XXX) y divisa coherente). isCashPosition clasifica liquidez para métricas y UI (regla más amplia por asset_class o prefijo CASH). Si separas invertido vs efectivo, usa isCashPosition; si decides si una fila existente de caja puede reutilizarse, usa matchesCashIdentity.
Valor de mercado: UNA función, tres pantallas (2026-08-01). computeInvestedMarketValue(positions, rates) (services/portfolioStats.js, puro) es la ÚNICA definición del valor de mercado de las posiciones no-cash; la consumen computePortfolioStats (brokers → "Valor en Mercado"), el Dashboard (tanto el valor con precio de BD como el liveInvestedValue → "Invertido") y ExpensesPage ("Invertido en cartera" → "Patrimonio total"). Antes cada pantalla tenía su propio reduce "espejo" y los tres números se separaban. Reglas al tocarlo: maneja las DOS formas de fila (merged con _valueComponents/_totalValueInPref y fila plana de BD) y compara current_price con != null (un precio 0 legítimo no puede caer al entry_price).
- La pantalla de Gastos mostraba el COSTE, no el valor: leía
investedHybriddel cache scopegeneral(base de coste FIFO/híbrida) mientras el Dashboard enseñaba valor de mercado — dos magnitudes distintas, así que el "Patrimonio total" nunca cuadró. Ahora resuelve por tres fuentes, de más fresca a menos: snapshot en memoria del Dashboard (PortfolioDataContext, llevascope— sólo vale si es'general', el de un broker suelto NO es el patrimonio), cache<bId>:display(metrics.investedValue, lo EXACTO que pintó la pantalla de brokers) y, por último, valorar las posiciones con los precios de BD. Nunca vuelvas a mezclarinvestedHybrid(coste) coninvestedValue(mercado) en la misma frase de UI. - ⚠️ El precio de una cotización viene en la divisa de la COTIZACIÓN, no en la de la posición.
convertQuotePrice(raw, quoteCur, storedCur, rates)(services/quotePricing.js, puro + tests) es obligatorio antes de (a) multiplicar por el rate de la posición y (b) escribir enassets.current_price. El Dashboard se lo saltaba: con GOOGL comprado en DeGiro (liquidado en EUR, cotizado en USD) multiplicaba el precio USD por el rate EUR (1) — el número medía el tipo de cambio, no el mercado — y además ESCRIBÍA ese precio sin convertir en la tabla compartidaassets, arrastrando a la pantalla de brokers hasta que su propio refresh lo reescribía bien. Resultado: las dos pantallas discrepaban en 1/FX y el número cambiaba según cuál se hubiera cargado la última. - El Dashboard agrupa por ticker resuelto para el treemap: cada grupo guarda
members(unasset_id/divisa/qty por sub-posición). El valor y el cambio diario se suman POR MIEMBRO y el precio se escribe a CADAasset_iden SU divisa — con un solo representante, los assets del resto de brokers nunca recibían precio.
Dashboard Portfolio Value calculation order:
- Fetch positions from DB (with last-known
current_price) - Fetch live quotes for all tickers (for treemap AND for Portfolio Value)
- Compute
liveInvestedValueusing live prices, falling back to DB price if quote failed totalWealth = liveInvestedValue + totalCashConverted- (No write-back: the server cron owns
assets.current_price.)
Exchange rate caching: currencyService.getExchangeRate caches in both memory (in-process) and localStorage (survives reload) with a 10-minute TTL. This prevents portfolio values from jittering between page reloads due to minor FX moves. Cache key format: wf_fx_rates in localStorage.
CarteraPage stats: computed in src/services/portfolioStats.js (pure module, decimal.js) and memoized in CarteraPage with React.useMemo. New aggregation logic goes in that service with unit tests (portfolioStats.test.js) — never inline financial formulas in the component.
Shared history pipeline (Dashboard ↔ brokers screen ↔ shared portfolio): the FIFO/cost-basis/P&L computation over DB transactions lives ONLY in src/services/portfolioHistory.js (computeHistoryTotals). usePositions (brokers screen), Dashboard.jsx AND the share endpoint (server/routes/sharePortfolio.js, which imports it directly from src/) call it — that is what makes "Invertido", realized P&L, dividends and fees identical everywhere. NEVER re-implement or "mirror" this logic locally; any change goes in the service + its tests (portfolioHistory.test.js). The module is Node-compatible (relative imports, injectable rate deps) — keep it that way.
Annualized return (CAGR): always annualize the cumulative TWR — (1 + TWR)^(1/years) − 1, only shown with ≥ 6 months. Never annualize Simple ROI: its denominator (totalBuyCost) counts recycled capital and assumes all capital was deployed on day one, which understates CAGR for periodic contributions.
⚠️ Los años se cuentan desde el primer día INVERTIDO, no desde el primer apunte (2026-09-20, reportado por el owner: TWR +60,44% desde el 6-oct-2024 que salía como +19,08% anual en vez de +27,36%). calculateDailyTWR arranca la serie en la primera transacción de CUALQUIER tipo ("first transaction day to today"), así que un ingreso de efectivo, una comisión o un traspaso meses antes de la primera compra mete un tramo de puntos con value: 0. Ese tramo NO toca el TWR —la cadena multiplica por 1 mientras no hay activos— pero la ventana es el DIVISOR: nueve meses de caja parada convertían una ventana de 1,95 años en una de 2,70 y hundían la anualizada 8 puntos, sin que nada en pantalla lo explicara. Es el mismo fallo que ya se arregló en el benchmark del gráfico, y se arregla con la misma regla: el primer punto con value > 0.
La decisión vive en DOS funciones puras y testeadas de performanceService.js (annualizedReturn.test.js, 12 tests): firstInvestedDate(series) y annualizeReturn(pct, inicio, fin, { minYears }). Las comparten las TRES superficies que enseñan esta métrica —la pantalla de brokers, SharePortfolioModal y el endpoint del share (server/routes/sharePortfolio.js)— porque si divergen, la cartera compartida enseña un número distinto del que ve su dueño. Al añadir una cuarta, importa las funciones; no repitas la fórmula.
Dos corolarios: (a) value sale SOLO de las cantidades de activos (currentAssetQtys, que alimentan BUY/SELL), nunca de la liquidez — por eso > 0 distingue de verdad "invertido" de "tengo el dinero en el broker"; (b) el share guarda el primer día invertido en cached.invested_since para que el server anualice sobre la misma ventana, y los shares creados antes caen a first_trade_date como hasta ahora.
Y no es un promedio, es una tasa compuesta. La intuición de dividir entre los años (60,44 / 2 ≈ 30%) siempre da de más, porque el segundo año crece sobre el primero: lo correcto es 27,36%, y comprobarlo es elevarlo (1,2736^1,955 = 1,6044). El texto del diálogo "¿Cómo se calcula?" (cartera.metric_cagr_desc) lo dice explícitamente desde el mismo commit, junto con la ventana que se usa.
✅ Resuelto el 2026-10-02: la calculadora de interés compuesto ya precarga la MISMA cifra que brokers. Antes DashboardLayout anualizaba portfolioValue / totalInvested entre la primera y la ÚLTIMA compra (CAGR inflado para quien dejó de comprar, y además suponía todo el dinero invertido el día uno). Ahora usa annualizedTwrFromSeries (performanceService, testeada) sobre la serie que ya calculó el Dashboard, leída con peekPerformanceSeries (usePortfolioPerformance, sin descargar nada; acepta series de hasta 6 h). Sin serie a mano devuelve null y la calculadora usa su valor por defecto — no se inventa una cifra.
Per-position FIFO cost is reconciled to the held quantity (scaleOpenCostToHeldQty in portfolioHistory.js, applied in usePositions before attaching _prefCostTotal): when the FIFO open lots cover fewer/more shares than positions.quantity (histories damaged by the old import dedupe, manual edits, partial saves), the cost is scaled by heldQty/openQty (AVCO per remaining share). Never pair a partial FIFO cost with the full market value: the shortfall shows up as a fake FX gain in the G/P Moneda breakdown and inflates the return % (the +186% Amazon / +114% MA bug).
Latent-gain cost basis is the HYBRID per-position cost (investedHybrid), never the raw global FIFO openPositionCost. Broker histories are split between the transactions table (saved) and imported_data JSON (unsaved); openPositionCost only covers the saved ones, so using it directly pairs a partial cost with the full market value and wildly inflates Ganancia Total (this happened the moment the first Binance import was saved). The hybrid lives in computeInvestedHybrid(positions, history, rates) (portfolioHistory.js, pure, tested: per FIFO queue consumed ONCE and scaled to held qty → AVCO buy totals → entry×rate): usePositions publishes it in historyTotals + the metrics cache, and the Dashboard fallback computes it with the SAME function over its DB positions — the cache is a perf shortcut, never a prerequisite for correct numbers. The share server still falls back to entry-based openInvestedEur.
Cross-screen metrics cache: portfolio_metrics_cache (user_id + scope) holds the brokers screen's computed computeHistoryTotals output (+ txCount + posFingerprint). usePositions publishes it on every load; Dashboard uses it verbatim when scope/currency match AND metrics.txCount equals the live transaction count AND metrics.posFingerprint equals computePositionsFingerprint(positions) (txCount alone missed mutations that change cost basis without adding transactions — manual position edits/adds froze the Dashboard's "Invertido" until the next brokers visit); the share server checks scope/currency/txCount. Any mismatch falls back to recomputing (Dashboard's fallback includes computeInvestedHybrid, so it matches the brokers number even on a cache miss). This is why "Invertido" is identical and instant on all three surfaces.
Share exactness (scope <bId>:display): además, CarteraPage publica (effect debounced, tras el memo de stats) las stats de cabecera EXACTAS que el usuario ve — investedValue/gain/gainPercent/realized/dividends/fees/totalCapitalDeployed + su eurRate de cliente y txCount — bajo scope '<bId>:display'. El share live (server/routes/sharePortfolio.js) las sirve VERBATIM (convertidas a EUR con ese mismo eurRate) cuando el scope coincide (general o un solo broker) y txCount iguala las transacciones vivas; si el dueño operó sin volver a abrir la app, cae al recálculo del pipeline compartido. Es lo que garantiza que la página compartida muestre exactamente los números del que comparte.
Binance Transaction History parser: trade legs are grouped by the Observación/Remark value when present (the "Buy Crypto With Fiat" pattern writes its fiat and crypto legs up to ~6 s apart, linked only by the remark), and by ≤3 s gaps between consecutive rows otherwise. Reconstructed BUY/SELLs are real events (isConsolidated: false — they MUST reach the transactions table); fiat deposits/withdrawals become TRANSFER rows so the broker cash balance exists; crypto-denominated fees are deducted from quantity, excluded from the BUY cost basis and emitted once as a FEE row. Regression fixture from a real export lives in binanceCsvParser.test.js.
La serie de rendimiento (TWR/TTWROR/ROI) tiene UNA implementación: usePortfolioPerformance (2026-09-11). La pantalla de brokers llamaba a calculateDailyTWR por su cuenta con otros argumentos (sin roiTransactions, rango 10y frente a 5y, sin la caché de localStorage) y el MISMO indicador daba números distintos según la pantalla — reportado por el owner: +54,80% en el Dashboard contra +54,69% en brokers. CarteraPage consume ahora el hook (refreshKey fuerza el recálculo tras un import o un alta manual, que es lo que hacían las deps de su efecto). Misma regla que portfolioHistory: no reimplementes la serie en una pantalla nueva.
- ⚠️ Un histórico que no llega vale CERO en toda la serie, y eso falsea el %. No es teórico: medido en la demo el 2026-09-11, la misma cartera daba 78,76% en el Dashboard y 98,79% en brokers (1342 puntos en las dos, mismo broker, misma divisa) porque en la primera pantalla Yahoo falló varios tickers y en la segunda ya estaban en caché. Tres defensas, todas en el hook: (a)
fetchWithCacheREINTENTA una vez con espalda + jitter y, si aun así no hay nada, cae a la caché vencida antes que a valorar a 0; (b) las descargas van en POOL de 4 (runPooled) en vez de unPromise.allsobre todos los tickers — Yahoo estrangula las ráfagas, es la misma razón por la quefundNavEnricheryfundSectorsvan secuenciales; (c) lo que aun así falte se publica enmissingTickersyPortfolioGrowthChartlo pinta como aviso ámbar (portfolio_growth.missing_history) en vez de enseñar un porcentaje incompleto como si fuera bueno. - La caché de históricos (
lib/perfHistCache.js) caduca al CAMBIAR DE DÍA, además de por TTL (2026-10-02). Con solo el TTL de 23 h cada ticker vencía a una hora distinta y el TWR mezclaba series que acababan en días distintos —o una barra de media sesión guardada como "cierre"—: el gráfico 1W del owner marcaba −1,64 % y el MISMOcalculateDailyTWR, ejecutado en Node con sus operaciones reales y datos frescos, daba −0,83 % (coherente con las fotos reconstruidas). Método que sirvió para separar "código mal" de "datos mal": replicar los pasos 1–10 deusePortfolioPerformanceen el server (es puro salvo el fetch) y comparar; las cantidades finales cuadraban al céntimo, así que el fallo estaba en la entrada. seriesMemo(módulo, TTL 10 min) es lo que GARANTIZA que las dos pantallas coincidan, no una optimización: la clave es(userId, brokerId, divisa)y NO incluyerefreshKey(cada pantalla pasa el suyo; meterlo las separaría otra vez). Lo que invalida la entrada es que elrefreshKeycambie DENTRO de una pantalla. Verificado en demo: la segunda pantalla reutiliza la serie de la primera y las dos marcan +98,79%.
El ROI del gráfico usa precios VIVOS con el rango completo, no el último cierre (2026-09-11). La serie valora con el cierre diario y la cabecera de brokers con precios vivos: mismo coste base, distinto valor, dos ROI que no cuadran (medido con la cartera del owner: 22,67% en el gráfico contra 22,07% en el chip — 26.245 € de coste en ambos, 32.196 € de valor contra 32.038 €). Con timeRange === 'ALL', PortfolioGrowthChart deriva el % de los DOS números que la propia tarjeta ya enseña en vivo (breakdownStats.liveInvested ÷ capitalInvertido), que es la definición exacta del chip "ROI Cartera actual"; y sobrescribe también el último punto de la línea, para que el tooltip no cuente otra cosa que la cabecera. Verificado en demo: +73,65% en las dos pantallas. El texto de "¿Cómo se calcula?" (portfolio_growth.roi_note / roi_actual_desc) lo explica — al cambiar esta regla, cámbialo en el mismo commit.
El benchmark (S&P 500 TR) se basa en el primer día INVERTIDO, no en el primer punto de la serie (2026-09-11). calculateDailyTWR arranca la serie en la primera transacción, que puede ser un apunte de caja meses antes de comprar nada: ese primer punto tiene value: 0. Basar ahí el índice le regala toda la subida de un tramo en el que la cartera no podía capturar nada — sesgo sistemático A FAVOR del benchmark. Medido: en la demo el primer punto es 2023-01-01 con valor 0 € y el primer día con posiciones es 2023-01-10; nueve días de ventaja movían el marcador de −9,87% a −5,55%. En la cartera del owner el desfase eran meses: la línea del S&P arrancaba ya en +25% y el marcador cantaba "−12,89% vs S&P 500" con la cartera en realidad por delante. La base es rebased.find(d => (d.value || 0) > 0), antes de esa fecha NO se pinta índice (sp500Return: null) y el primer día arranca en 0 aunque caiga en festivo (lastSP ?? 0). La regla vive en UNA función desde el 2026-10-04, mergeBenchmarkSeries (performanceService.js, tests en benchmarkSeries.test.js), que consume PortfolioGrowthChart (Dashboard). La copia de CarteraPage (getFilteredPerformanceData, con su filtro por rango, S&P 500, CAGR y drawdown) resultó ser CÓDIGO MUERTO —restos de un gráfico retirado de esa pantalla: nadie leía sus resultados y setShowSP500 no se llamaba nunca— y se BORRÓ el 2026-10-04. El dateKey: 'name' se conserva por si otra serie con esa forma lo necesita.
El modo ROI del gráfico SOLO se ofrece con el rango completo (2026-09-19, decisión del owner). Sobre un tramo, rebaseFiltered reencuadra la línea a 0% en su primera fecha, así que lo que se pinta deja de ser una rentabilidad: es cuánto ha CAMBIADO el múltiplo valor/coste. Y una aportación suma los MISMOS euros al valor y al coste, lo que arrastra ese cociente hacia el 0% por bien que vaya el mercado — se puede ganar dinero y ver el número en rojo. Medido con la cartera del owner: TTWROR YTD +19,79% con el titular del ROI en −2,39%, y la plusvalía latente pasando de ~3.900 € a 7.155 € en ese mismo periodo. Mismo criterio que retiró gainPercent de la pantalla de brokers: la métrica se sigue calculando, lo que se quita es el sitio donde convivía con otra que mide algo distinto e invitaba a compararlas.
La regla es UNA línea — effectiveChartMode = timeRange === 'ALL' ? chartMode : 'TTWROR' — y se DERIVA a propósito en lugar de corregir el estado desde un efecto: así el modo que se pinta y el rango no pueden desincronizarse ni un solo render, y al volver a ALL se recupera el ROI que el usuario había elegido. Todo lo de aguas abajo (yieldKey, modeConfig, benchmarkApplies, liveRoiPct, el lienzo y la leyenda) consume el modo EFECTIVO: si añades un consumidor nuevo y le pasas chartMode a secas, reabres el fallo. El botón se DESHABILITA con su explicación (portfolio_growth.roi_only_all), no desaparece, igual que el del S&P.
Corolario: fuera de ALL la línea es siempre TTWROR, así que ya no hay dos métricas compartiendo la palabra "ROI" en la misma tarjeta. El número del pie tampoco se llama ya "ROI total" sino Rentabilidad total (total_roi + total_return_tooltip): es totalGainPct, ganancia total con realizado, dividendos y comisiones sobre TODO el capital desplegado — otra magnitud que el latente de las posiciones abiertas que dibuja la línea.
Otras dos reglas del benchmark, de la misma revisión:
- La base es el cierre ESTRICTAMENTE ANTERIOR al primer día del rango, no el de ese mismo día.
rebaseFilteredencadenaisolatedTTWRORincluyendo el primer punto, así que la cartera SÍ cuenta el movimiento de esa sesión; basar el índice en el cierre del mismo día le hacía empezar un día tarde y regalaba esa sesión a la cartera. En1D—que son dos puntos (slice(-2))— eso era la mitad de lo comparado: dos días de cartera contra uno de índice. - El benchmark SOLO aplica al TTWROR (
benchmarkAppliesenPortfolioGrowthChart): en modo ROI el botón se deshabilita con su explicación (portfolio_growth.benchmark_only_twr), no desaparece — un control que se esfuma al cambiar de métrica se lee como un fallo. El TWR encadena rendimientos diarios y es inmune a cuándo entró el dinero, que es justo lo que permite ponerlo al lado de un índice; el ROI divide por el coste base, así que aportar antes de una subida lo diluye aunque el mercado haya hecho lo mismo — enfrentarlo al S&P mide el calendario de aportaciones, no el acierto. Además, desde el 2026-09-11 el último punto del ROI en rango completo usa precios VIVOS mientras el índice va a cierre: ni siquiera serían el mismo instante.
Which TWR series to consume: calculateDailyTWR emits TWO chains per point: ttwror (price + currency return in base currency — the correct portfolio TWR) and yield/cumulativeReturn (native-currency price-only — blind to FX). UI surfaces (TWR tile, CAGR, evolution charts, share sampling) must consume ttwror (with cumulativeReturn fallback for old cached series). Regression tests in performanceService.test.js pin both the FX inclusion and the sold-asset behaviour.
Al cambiar lo que MIDE una métrica, actualiza su explicación en el mismo commit. Los textos del diálogo "¿Cómo se calcula?" del gráfico viven en portfolio_growth.* (es/en) y los pinta GrowthChartExplainer; describen la fórmula, así que envejecen mal en silencio y el usuario acaba leyendo algo que el código ya no hace (roi_note seguía diciendo que el selector de período era "solo un zoom" mucho después de que la línea se rebasase a 0% en la primera fecha del rango).
Component split: extracted pieces of CarteraPage live in src/components/cartera/: PortfolioStatsCards, MetricExplainerDialog, MonthlyBreakdownChart, BrokerDialogs, Import* (selector/method/upload/preview), TransactionListCard, y desde 2026-07-16 DeletePositionDialog, PositionActionBar, HistoryPeriodFilterBar, BrokerTabBar, AddEditPositionDialog, PositionsMobileList, PositionsDesktopTable y TaxReportDialog (informe fiscal anual: agrupa por año fiscal los MISMOS salesWithPL/dividends/commissions de processedImportData vía services/taxReportService.js — puro, testeado; dividendos NETOS porque el parser DeGiro fusiona la retención en el dividendo; export CSV dialecto Excel-ES). Shared display formatters (formatNumber, getCurrencySymbol) are in src/lib/formatters.js. New extractions follow the same pattern: pure presentation components receiving pre-computed values + callbacks (Supabase I/O stays in the page — see handleAddBroker/handleStartEditPosition).
Row metrics compartidas: el cálculo por fila de posición (coste FIFO→AVCO→entry, G/P Producto/Moneda/Obtenida) y el del bullet-chart de target (posición y liquidez) viven en src/services/positionRowMetrics.js (computePositionRowMetrics, computeTargetMetrics, resolveCashTarget) con tests. PositionsMobileList y PositionsDesktopTable los consumen — NUNCA reimplementar esa matemática inline en una vista: era duplicación literal móvil/desktop antes de la extracción.
Total Gain / Total Return formula (CarteraPage & Dashboard):
Total Gain = latentGain + historyTotals.realized + historyTotals.dividends − feesTotalfeesTotal = historyTotals.fees + historyTotals.tradeCommissions + CSV-only commissionsTotal + embedded-JSON fallback— each commission source counts exactly once; seecomputeEmbeddedCommissionsFallbackinportfolioStats.jsTotal Return = Total Gain / historyTotals.totalBuyCost × 100(falls back toinvestediftotalBuyCost = 0)historyTotalsshape:{ realized, dividends, fees, totalBuyCost, openPositionCost, tradeCommissions, tradeCommissionsByBroker }— populated byloadPositionsfrom all DB transactions- Denominator is
totalBuyCost(sum of all historical BUY qty × price) so sold positions contribute to the return % - ⚠️
gainPercent(ROI Simple histórico) ya NO se enseña en la pantalla de brokers (2026-09-11): la tarjeta "Rentabilidad" la preside ahora ROI Cartera actual (latentRoiPct= latente / coste de posiciones abiertas), y los chips son Rentabilidad Anualizada y TWR ajustado. El ROI Simple divide por TODO el capital desplegado alguna vez —capital reciclado incluido—, así que respondía a una pregunta distinta de la que se hace quien mira su cartera hoy, y convivir con el ROI actual a dos centímetros invitaba a compararlos como si midieran lo mismo. La fórmula SIGUE calculándose enportfolioStatsporque la consume el share server; lo que se retiró es su sitio en la cabecera y su entrada en el diálogo de métricas.
General view position grouping: In "All Brokers" mode, positions are grouped by ISIN only (same stock on different exchanges/currencies → one row). Cash rows stay separate by ticker (CASH_EUR ≠ CASH_USD). The representative asset (highest qty sub-position) provides the display currency and current_price. entry_price is computed in step 3.5 after FX rates are fetched: all cost components are converted to preferredCurrency as intermediate, then back to the representative's native currency, so the stats IIFE qty × entry_price × rate[currency] stays correct. all_asset_ids (array) is exposed on each merged position so loadTransactionsForAsset can load transactions from all underlying assets when expanding a row.
CSV import — smart position closing: After saving an import, only positions whose asset had explicit BUY/SELL activity in that CSV are eligible to be closed (set to qty=0). Positions absent from the CSV (e.g. only dividends, or bought before the export date range) are left untouched. This is tracked via processedAssetIds Set inside saveImportedData.
Fund look-through (donut widgets): for index funds, assets.currency is the SHARE CLASS (all EUR) and the ISIN prefix is the legal DOMICILE (IE/LU) — classifying by them shows a 100%-EUR / "Europa+Luxembourg" portfolio for a US/Japan/EM fund mix. src/services/fundExposure.js (getFundExposure(asset), pure, tested) returns the UNDERLYING index exposure (region/currency/sector codes): curated ISIN map for the MyInvestor cartera funds first (same philosophy as MYINVESTOR_FUNDS), then CURATED_BY_SYMBOL (Yahoo symbol root — for ACTIVE funds with opaque names like "Gestión Value A FI", whose exposure must be verified against Yahoo quoteSummary?modules=topHoldings before adding), then name rules (hedge tag EUR H stripped before region matching; trailing share-class Acc EUR never implies Europe; returns null when unsure → caller keeps its stock derivation). The Dashboard donut keyFns (divisaKey/sectorKey/regionKey) consult it FIRST for divisa/región; sector uses the DB sector first (funds have none). Misclassified/unclassified fund → add its ISIN to CURATED_BY_ISIN or its symbol to CURATED_BY_SYMBOL with a test. Only affects donut GROUPING — values/rates still use the share-class currency.
Fund sector look-through (Sectores donut): for fund positions the Sectores donut splits the position's VALUE across the fund's real sector weights: fundSectors.js fetches Yahoo quoteSummary?modules=topHoldings through the crumb proxy (/api/yahoo-profile/:ticker?modules=topHoldings, dev-only like getProfile), reduces it with extractFundSectorWeights (in fundExposure.js: requires stockPosition ≥ 0.5 — bond funds report a junk "financial_services 100%" row and must keep their FUND_BOND bucket; labels are the exact assetProfile sector strings so fund slices MERGE with stock slices), and caches per ticker in localStorage (wf_fund_sectors_v1, 24h, null "no data" results cached too, network errors NOT cached). Fetches are SEQUENTIAL + paced (Yahoo rate limit). Dashboard holds the weights in fundSectorWeights state; buildDonut/buildCompanyMap accept keyFns returning either a string or [{key, weight}] portions. Symbols without data (.MU listings) or fetch failures gracefully keep the single fundExposure bucket.
Previsión de dividendos del año (widget "Próximos dividendos", 2026-10-15)
services/dividendProjection.js (con tests). "AÑO (est.)" = cobrado este año + los pagos cuyo ex-dividendo cae entre hoy y el 31-dic (frecuencia deducida de anual/importe por pago; sin fecha, prorrateo por días). Antes sumaba lo cobrado + el dividendo anual COMPLETO: en la demo, a 15-oct, 825 € en vez de 211 €. "AÑO+1 (est.)" = ritmo anual actual, sin el ×1,05 inventado de antes. Si falla la consulta de lo cobrado, las dos primeras tarjetas dicen "No disponible" — nunca un 0 € que parece real.
Fechas de la serie de rendimiento (2026-10-15)
- El rango de días sale de
isoDateRange(primerDía, localTodayIso())(lib/dates.js, aritmética UTC pura). El bucle anterior —new Date('YYYY-MM-DD')+setDate(hora local) +toISOString(UTC)— desfasaba un día en cuanto la primera operación era de invierno y hoy de verano (UTC+1 → UTC+2): cada punto llevaba la fecha y el cierre de AYER y hoy no aparecía nunca. Test:performanceService.dateRange.test.js(falla con el código viejo). - Para PINTAR una fecha 'YYYY-MM-DD' usa
parseIsoDateLocal:new Date('YYYY-MM-DD')es medianoche UTC y al oeste de UTC rotula el día anterior. Los filtros de rango comparan las fechas ISO como texto. - 1D = una sola sesión (
lib/growthWindow.oneDayWindow): en el resto de rangos el primer día cuenta su propia sesión (regla del benchmark enmergeBenchmarkSeries), pero el 1D necesita dos puntos y encadenaba DOS sesiones (−1,78 % con el Dashboard en −0,76 % hoy). Su primer punto es solo la base y el S&P se cruza con la última sesión. - Si Yahoo no tiene el cierre de un día para un activo (pasó con IWDA/VUSA el 14-oct-2026), ese día vale 0 % y el siguiente se lleva los dos: el 1D puede diferir unas décimas del "hoy" de la tarjeta, que sale de la cotización en vivo.
Informe fiscal: dividendos, retenciones y comisiones por separado (2026-10-16)
DEGIRO e IBKR apuntan la retención del dividendo como línea propia (TAX). El informe la sumaba en "Comisiones y tasas" y llamaba "netos" a unos dividendos que eran BRUTOS. buildTaxReport lleva ahora withholding aparte (filas TAX, misma regla de moneda que las comisiones) y dividendsReceived (lo que apunta el broker: bruto en DEGIRO/IBKR, neto en los que pagan ya neto). Para declarar: el bruto y la retención van por separado. En la pantalla de brokers la retención sigue dentro de Comisiones (lo dice su explicación).
Informe fiscal: tipo de cambio de la fecha de cada operación (2026-10-22)
Hasta esta fecha el informe convertía TODO al cambio de HOY y, en las ventas, el beneficio neto. La AEAT pide: valor de transmisión al tipo del día de la VENTA y valor de adquisición al tipo del día de CADA COMPRA (lote FIFO); dividendos y comisiones al tipo de su fecha. Piezas:
FIFOCalculator.processSelldevuelvelots: [{date, qty, unitCost, fxRate}](aditivo;unitCost= el mismo_pricedel profit, sin comisión).salesWithPLlos guarda.services/tax/fxByDate.js(puro):collectFxNeeds→ pares (divisa, fecha);preloadTaxRates(async,runPooled,getRateinyectable);resolveRate: misma divisa → 1 · fx del bróker · tabla con el día o el último ANTERIOR hasta 7 días. Nunca un tipo posterior, nunca el de hoy.currencyService.getHistoricalRateOnOrBefore— NO usargetHistoricalRatepara fiscalidad: esa coge el cierre de Yahoo MÁS CERCANO (para un domingo, el lunes siguiente). La variante usa clave de caché propiawf_hist_ob_*, exigemeta.gmtoffset(la barra diaria de FX va sellada a las 23:00Z del día anterior; sin offset la fecha UTC engaña) y devuelve{rate, date}.buildTaxReport({sales, dividends, commissions, preferredCurrency, rates})sigue síncrono. Una fila sin tipo NO entra en los totales: va amissingFxcon motivo (missingFxCount). Una venta sin historial de compra (isMissingBuyData/ sin lotes) tampoco: antes sumaba el importe íntegro como ganancia. Por eso, con ventas huérfanas, el informe puede ser MENOR que el "realizado" de la pantalla, a propósito.- En la divisa preferida el resultado es idéntico al profit del pipeline (test de cuadre contra
computeProcessedImportData).
Informe fiscal: FIFO por ISIN, no el de la pantalla (2026-10-22, revisión F1F2 punto 2)
Con buys (lo que pasa SIEMPRE desde TaxReportDialog) el informe decide todo con el FIFO por ISIN del núcleo tax/twoMonthRule: el estado de cada venta (missing_buy_data si ninguna acción vendida tiene compra del ISIN, partial_history, missing_fx), el importe (al tipo de la fecha de la venta, aunque la pantalla no tenga lotes) y los lotes del detalle (en la moneda del informe, con el tipo de cada compra). No lee lots, isMissingBuyData ni sharesMissingHistory de la pantalla.
- Por qué: valores homogéneos = misma entidad y mismos derechos (art. 37.2 LIRPF), sin importar el mercado ni la divisa de cotización. La pantalla (
fifoAnalytics, colaISIN_divisa) separa por divisa por PRESENTACIÓN y no se toca. Caso real de la revisión: compra de un ETF en Xetra (EUR) y venta en NYSE (USD); la pantalla no veía lotes y el informe la marcaba «sin historial» (−350 € declarados de menos). - Consecuencia: con el mismo ISIN en varias divisas, el informe y la pantalla pueden dar resultados distintos, y es correcto. El aviso
fifoMismatch(con su tolerancia de 0,01) se quitó: comparaba con una cifra que no tiene valor fiscal. - Ruta sin
buys(twoMonthRuleApplied=false, legacy): sigue usando los lotes yisMissingBuyDatade la pantalla, sin regla de los dos meses. Solo la usan tests y el contrato; no la uses en una pantalla nueva.
Informe fiscal: comisiones dentro de los valores (2026-10-22, revisión F1F2 punto 1)
Art. 35.1.b y 35.2 LIRPF: los gastos de la operación suman al valor de adquisición y restan del de transmisión, y así lo piden las casillas de la Renta. Con buys, buildTaxReport mete la comisión de la fila (comisiones, facturada en EUR: commissionCurrency) en el importe que recibe el núcleo: compra → unitCostEur = (qty·precio·tipo + comisión·tipoEUR)/qty; venta → netProceedsEur = max(0, qty·precio·tipo − comisión·tipoEUR), cada tipo de SU fecha. Es la misma fórmula que computeCapitalGains, así que app y calculadora pública dan lo mismo para el mismo caso (test de cuadre en taxReportService.twoMonth.test.js). En una venta parcial la comisión de compra se prorratea sola porque va en el coste unitario del lote, y entra también en la pérdida aplazada de los dos meses.
feesdel año = solo gastos sueltos (FEE que no sonisTradeCommission: conectividad, custodia). El diálogo lo dice (tax_report.fees_note).- Consecuencia buscada: el neto del informe es el realizado de la pantalla MENOS las comisiones de compraventa imputadas a lo vendido. Una compra cuya comisión aún no se ha vendido no aparece en ningún año (estará en el coste cuando se venda).
- Si falta el tipo EUR→divisa del informe del día de la comisión (preferida ≠ EUR), esa compra o venta queda sin importe (
missing_fx), como si faltara el tipo de la acción. - La ruta sin
buys(legacy) no cambia: importes sin comisiones y todas las comisiones enfees.
Informe fiscal: historial parcial, la parte conocida computa (2026-10-22, revisión F1F2 punto 3)
Antes una venta con PARTE de las acciones sin compra se excluía entera: el total escondía la pérdida o la ganancia de la parte conocida (caso R8F-3: 9 compradas a 100, 10 vendidas a 50 → −450 € que desaparecían). Ahora el informe llama al núcleo con applyTwoMonthRule(ops, { knownPartOnly: true }): gain = importe × conocidas/vendidas − coste de los lotes, y isLoss y lo aplazado se calculan solo sobre las conocidas. La venta sigue en estado partial_history, pero con importes y DENTRO de los totales; las unidades sin coste y su importe de transmisión excluido van a byYear[y].partialHistory (y partialHistoryCount), que el diálogo enseña en «Unidades vendidas sin coste» y el CSV en su sección. unreliableCount cuenta solo las ventas sin compra de NINGUNA acción, que siguen fuera.
- La opción es explícita: sin ella (calculadora pública) las unidades sin compra siguen a coste 0 y la salida es idéntica (equivalencia de 6000 casos contra
__legacy__). - La ruta sin
buys(legacy) sigue excluyendo la venta entera.
transactions.fx_rate — sentido y estado (comprobado 2026-10-22): el COMMENT de la migración 20260610 dice transaction_currency → EUR, y así lo interpreta brokerFxFor (solo con preferida EUR y para la divisa de la propia fila). Pero hoy ningún parser lo rellena (importPlanner escribe t.fxRate, que nadie pone) y la transformación de filas de BD tampoco lo lee, así que en la práctica siempre se usa la tabla histórica. OJO al cablearlo en DEGIRO: su columna «Tipo» del Account.csv (y fxRate de publicTools/degiroTransactions) va en el sentido CONTRARIO, divisa por EUR (800 USD / 740 EUR = 1,0811) — hay que invertirla antes de guardarla en fx_rate.