fin-tracker/docs/ai/csv-import.md

Универсальный CSV импорта событий

Фаза 3. Формат — экспорт Snowball Income, но парсер (sources/reports/csv_universal/parser.py, broker = "csv", name = "csv") обращается с ним как с универсальным CSV событий: файл узнаётся по набору колонок заголовка, а не по имени. Любая будущая выгрузка с тем же заголовком читается тем же кодом.

Общие правила проекта действуют: деньги и количества — Decimal (ни одного float ни в событиях, ни в meta), даты — ISO, знаки — как в models/ledger.Event (quantity: + в позицию, − из позиции; amount: + получено, − уплачено; fee/tax положительные и уже внутри amount).

Файл

• UTF-8, допускается BOM; запасная кодировка — cp1251.
• Разделитель — запятая, все значения в кавычках (заголовок — без).
• Десятичный разделитель — запятая (4,48, 11353,38392), но целые пишутся без неё (219). Пробелы (обычный, NBSP, узкий NBSP) внутри числа вырезаются.
• Пустая ячейка — это None, а не ноль. Пустой NKD значит «это не облигация», NKD = 0 — «облигация, но НКД нулевой»; схлопывать их нельзя.
• Дата: 2025-02-26 09:22:54 (принимаются также 2025-02-26T… и 2025-02-26). В леджер идёт только дата; время используется для seq (см. «Дедупликация»).

Колонки

Обязательные (без них sniff → False, parse → ParseError): Event, Date, Symbol, Price, Quantity, Currency.

Необязательные: FeeTax, Exchange, NKD, FeeCurrency, DoNotAdjustCash, Note. Выгрузка без них читается; DoNotAdjustCash парсер игнорирует — это внутренний флаг Snowball о том, правил ли он остаток, а не факт о деньгах.

Смысл колонок зависит от типа события

Это главная особенность формата: Quantity — это штуки на BUY и рубли на DIVIDEND, Price — цена на сделке и коэффициент на SPLIT.

Event	Symbol	Price	Quantity	FeeTax	Остальное
BUY / SELL	тикер или ISIN	цена за штуку (для облигаций — рубли за бумагу, не % номинала)	штук	комиссия сделки	NKD — весь НКД сделки, Exchange = MCX или CUSTOM_HOLDING, FeeCurrency — валюта комиссии
DIVIDEND	тикер/ISIN	0	сумма денег	0	на облигации это купон, см. «Контракт с ingest»
AMORTISATION	ISIN облигации	0	сумма денег	0
CASH_IN / CASH_OUT	код валюты (RUB)	1	сумма	0	Note отличает реальный поток от правки остатка
FEE / TAX / TAX_RETURN	пусто	0	0	сумма	инструмента нет даже если сбор относится к бумаге — формат не говорит, к какой
SPLIT	тикер	коэффициент (10)	0	0	деньги и позиция не двигаются
CUSTOM_HOLDING_PRICE	тикер	ручная цена	0	0	Exchange = CUSTOM_HOLDING
CUSTOM_HOLDING_SETTINGS	тикер	0	0	0	Note — JSON, где " заменены на @*@

Деньги считаются так:

• BUY: amount = −(Quantity·Price + NKD + FeeTax), quantity = +Quantity;
• SELL: amount = +(Quantity·Price + NKD − FeeTax), quantity = −Quantity;
• DIVIDEND / AMORTISATION: amount = +Quantity, quantity = None;
• CASH_IN / CASH_OUT: amount = ±Quantity, валюта — из Symbol, инструмента нет;
• FEE / TAX: amount = −FeeTax; TAX_RETURN: amount = +FeeTax;
• SPLIT: amount = 0, quantity = None, коэффициент — в meta.

Маппинг в EventKind

Event	EventKind
BUY	buy
SELL	sell
CASH_IN	deposit
CASH_OUT	withdrawal
DIVIDEND	dividend (+ meta["payout_hint"] = "coupon" для облигаций)
AMORTISATION	amortization
FEE	commission
TAX	tax
TAX_RETURN	tax_refund
SPLIT	split (EventKind.stock_split)

Событиями леджера не становятся CUSTOM_HOLDING_PRICE и CUSTOM_HOLDING_SETTINGS (см. ниже) и строки-правки остатка.

Неизвестный тип события

Строка пропускается, в warnings добавляется неизвестный тип события 'X': пропущено строк — N, счётчик кладётся в meta["unknown_events"]. В EventKind.other такие строки не маппятся сознательно: other — молчаливая корзина, а нам нужен сигнал в data quality о том, что формат отрастил новый тип строки.

Инструменты

Symbol — либо ISIN, либо тикер. ISIN распознаётся по форме (12 символов, две буквы, контрольная цифра) с проверкой контрольной суммы и с явным исключением секьюрити-id ОФЗ вида SU26212RMFS9: он проходит ту же контрольную сумму, но ISIN-ом не является, и резолвер искал бы по нему несуществующую бумагу. ОФЗ уходят тикером.

asset_class_hint = "bond" ставится, когда символ — валидный ISIN или секьюрити-id ОФЗ. Кастомный холдинг вроде SIBN6P4 облигацией по символу не выглядит и подсказки не получает — класс определится при резолве инструмента.

Exchange (MCX / CUSTOM_HOLDING) кладётся в InstrumentRef.meta["exchange"]; доской (board) он не является, поэтому поле board остаётся пустым.

CUSTOM_HOLDING_SETTINGS — карточка пользовательского инструмента

Note — это JSON, в котором все " заменены на @*@ (чтобы CSV не пришлось экранировать), а не-ASCII текст записан \uXXXX-escape'ами. Парсер делает обратную замену и json.loads, после чего берёт:

• Holding.Description → InstrumentRef.name (в фикстуре — «Газпром Нефть 006Р-04»);
• Holding.Currency → InstrumentRef.currency;
• Holding.Sector → meta["sector"], плюс meta["custom_holding"] = True и весь блок Settings в meta["settings"].

Если JSON не разобрался — это warning, а не исключение: одна битая строка настроек не должна стоить пользователю пятисот хороших сделок. Инструмент тогда остаётся голым тикером.

CUSTOM_HOLDING_PRICE — цена, а не событие

Это цена, введённая пользователем для бумаги, которую биржа не котирует. Её место — price_manual. В BrokerEvent положить цену некуда, поэтому строки едут в ParsedReport.meta["manual_prices"]:

{"instrument_key": "TICKER:SIBN6P4", "d": date(2026, 9, 14),
 "price": Decimal("12320.94504"), "currency": "RUB"}

Сами инструменты дублируются в ParsedReport.instruments, чтобы ingest сначала отрезолвил бумагу обычным путём (pending instrument), а потом записал цены.

Правки остатка — не поток и не сделка

Snowball сам вставляет строки CASH_IN/CASH_OUT с Note вида

Эта сделка добавлена с целью корректировки баланса по этой валюте, т.к. баланс по данным брокера (…) не соответствует балансу рассчитанному по сделкам (…).

Это правка расхождения его собственного пересчёта с остатком брокера, а не деньги, которые пересекли границу портфеля. Эмитить их как deposit/withdrawal нельзя: XIRR получит фиктивный внешний поток.

Такие строки в events не попадают, а уходят в ParsedReport.meta["balance_adjustments"] ({"kind", "d", "amount", "currency", "note", "line_no"}) и каждая — в warnings.

Определяются по тексту Note (маркеры корректировки баланса и не соответствует балансу), а не по величине суммы: в реальной выгрузке такая правка бывает и на 0,0024 ₽, и на 1017,84 ₽, тогда как настоящий вывод — на 32 ₽. Любой порог по сумме ошибся бы на обоих.

Дедупликация

Номеров сделок в формате нет, поэтому dedupe_key всегда fingerprint_key(...), и всю работу по различению «две реальные сделки» и «одна сделка, выгруженная дважды» делает seq.

seq — это ранг пары (время суток, Note) строки среди различных таких пар у всех строк с тем же содержимым отпечатка (kind, инструмент, дата, quantity, price, валюта, amount). Отсюда два следствия, оба намеренные:

• два настоящих пополнения по 1100 ₽ с разницей в секунду получают разные ключи, а повторный импорт того же файла воспроизводит те же ключи — ранг зависит только от содержимого и времени, никогда от номеров строк;
• две строки, совпадающие вплоть до секунды и до Note, дают один ключ и схлопываются. Для этого формата это правильное поведение по умолчанию: колонки счёта в нём нет, поэтому повторённая строка почти всегда — одно событие, увиденное на двух счетах (в фикстуре — две строки SPLIT по T на 2026-04-16 03:00:00), а применить коэффициент сплита дважды к единственному целевому счёту означало бы умножить позицию на 100 вместо 10.

Цена компромисса честная: перекрывающаяся выгрузка, в которой части одинаковых строк нет, сдвинет ранги оставшихся, и перекрытие импортируется как новые строки вместо upsert. Формат с номерами сделок этой проблемы не имел бы — здесь номеров нет.

Область действия выгрузки

Файл покрывает все брокерские счета сразу: в фикстуре 49 инструментов трёх брокеров (T-Invest, Сбер, ВТБ) вперемешку за 2025-02-26…2026-09-17. Номера счёта в формате нет и вывести его неоткуда.

Поэтому account_external_id заполняется именем портфеля из имени файла (Snowball_Export_<портфель>_<дд.мм.гггг>.csv → Мой капитал; то же значение — в meta["portfolio_name"]), и парсер добавляет warning: целевой счёт обязан указать пользователь, а по plan §1.6 B у счёта один primary_event_source — значит почти все события лягут со status = shadow и работают как сверка, а не как леджер.

positions_end и cash_end формат не даёт вообще: закрывающих позиций и остатков денег в нём нет. Об этом тоже говорит warning — сверка остатков по этой выгрузке невозможна.

Контракт с ledger/ingest.py

1. Дивиденд на облигации — это купон. Парсер не ходит в БД и не знает класс актива, поэтому kind остаётся dividend, а подозрение едет в meta["payout_hint"] = "coupon". Окончательную переклассификацию в EventKind.coupon делает ingest после резолва инструмента, по его настоящему asset_class. Подсказка — ускорение для резолвера, а не ответ: кастомный холдинг-облигация подсказки не получит, и решать всё равно ingest.
2. meta["manual_prices"] пишутся в price_manual после резолва инструментов из instruments (ключ — InstrumentRef.key()).
3. meta["balance_adjustments"] в леджер не пишутся никогда; их место — data quality (расхождение derived vs брокер, которое Snowball уже зафиксировал).
4. meta["split_ratio"] / meta["ratio"] на событии split — это заявленный коэффициент. ledger/corporate_actions.py:_stated_ratio читает обе эти ключевые метки, поэтому сплит из CSV попадает в corporate_action как заявленный, и выводить коэффициент из пары переводов не нужно.
5. meta["csv_event"] хранит исходный тип строки — по нему в raw_report_line видно, из чего получилось событие.
6. Ожидаемый статус событий — shadow для всех счетов, у которых primary_event_source не csv.