Perfiles de Formato de Origen

📑 Perfiles de Formato de Origen

Un mapeador de columnas estándar puede deducir fácilmente que una columna llamada Comisión se corresponde con fee_amount.

Sin embargo, estructuralmente es incapaz de determinar:

• Si el valor de esa columna representa una valoración en euros o tokens retenidos en el propio activo transferido.
• Si una operación completa se exporta en una sola fila o en dos filas separadas (una para la compra y otra para el cobro).
• Si una fila refleja la cantidad en ambas columnas direccionales (amount_in y amount_out) a la vez.

Estos son hechos sobre el exchange de origen, no sobre el nombre de una columna. En Criptofolio, estas convenciones se declaran formalmente como perfiles de datos inmutables en packages/core-domain/src/domain/services/sourceProfile/.

---

🏛️ La Interfaz SourceFormatProfile

packages/core-domain/src/domain/services/sourceProfile/types.ts

export interface SourceFormatProfile {
  readonly id: SourceProfileId;
  readonly label: string;
  readonly market: DeclaredMarket;           // SPOT | FUTURES | UNDECLARED
  readonly signature: HeaderSignature;       // Detección por firma antes del mapeo
  readonly feeDenomination: FeeDenomination; // NATIVE | VALUED_IN_FIAT | INCLUDED_IN_TOTAL
  readonly feeConvention: FeeConvention;     // GROSS | NET
  readonly directionalFill: DirectionalFill; // ONE_SIDED | BOTH_SIDES_WRITTEN
  readonly columnRoles: ColumnRoles;
  readonly invariant?: ProfileInvariant;     // Comprobación de integridad interna
}

---

🏷️ Los Seis Perfiles Declarados

Criptofolio incorpora perfiles preconfigurados para las principales plataformas y billeteras:

ID del Perfil	Plataforma Destino	Reglas de Firma de Cabecera	Comportamiento Clave
kraken-spot	Ledger Spot de Kraken	Contiene txid, refid, time, type, subtype, aclass	Dos filas por operación; comisión en token propio o valorada en EUR.
kraken-futures	Futuros de Kraken	Contiene Trade Id, Fill Type, Effective Margin	Financiación de margen y liquidación de PnL de derivados.
bit2me-spot	Bit2Me	Contiene cabeceras en español (Fecha, Tipo de operación, Operación)	Anota un mismo movimiento en ambas columnas direccionales.
bitvavo-spot	Bitvavo	Contiene Transaction ID, Execution Type, Settled Quantity	Ajustes de comisiones Brutas/Netas y formato temporal ISO.
bitunix-spot	Bitunix	Contiene UID, Order No, Trading Pair, Filled Amount	Formato ordenado específico para operaciones Spot.
tangem	Billetera Tangem	Contiene las cabeceras de exportación de la app Tangem	Entradas de custodia de almacenamiento en frío con hashes on-chain.
generic	Genérico Neutral	Perfil por defecto alcanzado solo si ninguna firma encaja	Mapeo neutral estándar de hojas de cálculo.

---

🔍 Detección Determinista por Firmas

La detección se ejecuta sobre la primera fila cruda de cabeceras antes de realizar cualquier extracción de datos:

import { detectSourceProfile } from '@/domain/services/sourceProfile/detectSourceProfile';

const detected = detectSourceProfile(rawCsvHeaders);
// Retorna: { status: 'MATCH', profile: krakenSpotProfile }
// O bien:  { status: 'AMBIGUOUS', candidates: [...] }
// O bien:  { status: 'NONE' } -> Perfil genérico

Reglas de Coincidencia de Firmas:

1. Cabeceras Obligatorias: Todas las columnas listadas en signature.required deben existir en el archivo.
2. Cabeceras Prohibidas: Ninguna de las cabeceras en signature.forbidden puede aparecer (evita que un perfil de Spot capture por error un archivo de Futuros del mismo exchange).
3. Protección contra Ambigüedad: Si varios perfiles coinciden, el sistema reporta ambigüedad en vez de seleccionar el primero de la lista. Esto asegura que añadir un perfil nuevo nunca modifique silenciosamente el procesamiento de ficheros existentes.