# finsync

Финучёт и управленческая аналитика школы музыки Марс поверх **Финтабло** (REST API) и **AlfaCRM** (v2 API), с выводом в Google Sheets и ежедневным отчётом в Телеграм.

## Модули-основания

- `core.py` — единственный клиент Финтабло и AlfaCRM: `.env`, ретраи (POST не повторяем — это живые деньги), пагинация, календарь. **Год нигде не хардкодится**: `FIN_YEAR` = текущий календарный год, переопределяется `FINSYNC_YEAR=2026`.
- `matching.py` — единственный алгоритм матчинга план↔факт (каскад по контрагентам). Им пользуются и отчёт («ещё платить»), и `plan_sync` (какие планки отработали).
- `margins.py` — бизнес-логика направлений (маппинг доходов CRM, разнесение ЗП-лампы).
- `pay_config.py` — ставки и даты выплат (единый источник).

## Занос операций в Финтабло

Идемпотентно, дедуп по `externalId`; всегда dry-run → `--commit`:

- `enter_akty.py` — выплаты самозанятым «Рабочие руки» из PDF-актов (нужен `pdftotext`)
- `enter_alfa_income.py` — наличная выручка из AlfaCRM за месяц
- `enter_cash_expenses.py` — наличные расходы из Google-таблицы Оли (+ ловит «сирот»: заносы, чья строка в таблице изменилась после оплаты)
- `enter_olya_plan.py` — плановые «события Оли» из её таблицы
- `plan_income.py` — плановые доходы месяца (6 строк)
- `plan_sync.py` — план расходов на месяц из канона + удаление отработавших планок
- `export_cash_outcome.py`, `export_b2c_gap.py`, `reconcile_b2b.py` — выгрузки и сверки

## Аналитика → Google Sheet «mars fin» (3 листа)

- `rebuild_matrix.py` + `push_to_gsheet.py` — P&L и маржинальность по направлениям (contribution margin)
- `cashflow.py` — кассовый прогноз (`--dry` — посчитать и напечатать, не трогая лист)
- `plan_fact.py` — финмодель (план) ↔ факт Финтабло по месяцам (`--dry` — то же)

## Отчёт владельцу

`report.py [pulse|full|flag|auto] [--send]` — пульс каждый день, полный разбор по понедельникам, красный флаг при риске кассового разрыва.

## Обновление

```bash
bash update_all.sh       # всё сразу (крон на Pi); о сбоях шагов пишет в Телеграм
bash update_margins.sh   # только P&L/маржа (тяжело, ~1-2 мин; пересчёт из CRM+Финтабло)
bash update_cash.sh      # только Касса + План-факт (быстро, ~15 сек)
```

## Установка

```bash
pip install -r requirements.txt
brew install poppler          # macOS, для enter_akty; на Pi: apt install poppler-utils
python3 -m pytest -q          # тесты (без сети)
```

## Конфиг (не в git)

- `.env` — токены Финтабло + AlfaCRM + Телеграм (`TELEGRAM_BOT_TOKEN`, `TELEGRAM_CHAT_ID`)
- `gsheets_sa.json` — ключ service-account для записи в Google Sheets

## Данные (не в git)

- `exports/` — выгрузки, логи заносов, rollback-файлы
- `.sdd/` — чекпоинты пересчёта матрицы

## Грабли, о которых помнит код

- AlfaCRM понимает даты **только через дефисы** (`2026-07-01`); с точками фильтр молча игнорируется и отдаётся вся история.
- В ответе AlfaCRM `count` — размер страницы, а не общее число: конец пагинации определяем по `total`.
- «Текущий месяц» берём из календаря, а не из первой операции API: там лежат **плановые** операции следующего месяца.
- Номера строк финмодели магические — перед расчётом сверяем подписи (`cashflow.check_plan_layout`).
- Филиалы AlfaCRM: 2 и 3. Филиал 5 («ОП») отдаёт те же платежи, что 2; филиал 4 — ТЕСТ.

Справочник по эксплуатации — `projects/vibe-coding/agents.md` в Obsidian-волте.