# Архитектура

Консольная утилита на Python, которая читает лайкнутые треки Яндекс.Музыки и раскладывает их
по плейлистам вида `Жанр — RU` / `Жанр — INT`, используя неофициальную библиотеку `yandex-music`.

## Структура

```
sort_ym/
  config.py     — чтение config.toml (throttle, пути к кэшу/токену)
  auth.py       — OAuth device-flow, хранение токена в .token
  ymclient.py   — создание Client, батч-нарезка списков
  fetch.py      — лайки -> полные Track -> cache/tracks.json (докачивается инкрементально)
  genres.py     — реальное дерево жанров Яндекса -> 11 крупных корзин (ROOT_BUCKET)
  language.py   — гибридная детекция языка (API текста / жанр-подсказка / алфавит)
  classify.py   — (корзина, язык) -> имя плейлиста
  report.py     — сборка строк отчёта, запись out/report.csv, сводки
  apply.py      — создание плейлистов + идемпотентное добавление треков
  cli.py        — команды auth / fetch / report / apply

tests/
  test_genres.py, test_language.py — тесты чистых функций (маппинг, детекция языка)

cache/  — кэш API (в .gitignore)
out/    — отчёты (в .gitignore)
```

## Поток данных

```
auth  → .token
fetch → users_likes_tracks() → client.tracks(batch) → cache/tracks.json
report → genres.load_or_fetch_catalog() → cache/genre_catalog.json
       → language.fetch_api_languages() → cache/lyrics_lang.json
       → build_rows() → out/report.csv (dry-run, аккаунт не меняется)
apply --yes → users_playlists_create / users_playlists_insert_track
```

## Ключевые решения

- **Жанр трека** доступен только через альбом (`Track.albums[0].genre`), у самого трека поля
  жанра нет. Раскладка на 11 крупных групп сделана через реальное дерево `client.genres()`
  (родитель → под-жанры), а не через угаданный список слагов — так таблица `ROOT_BUCKET` в
  `genres.py` опирается на подтверждённые id, а не на предположения. Жанры без совпадения падают
  в корзину `other` и печатаются в выводе `report` для ручного дополнения таблицы.

- **Язык** определяется гибридно, в порядке приоритета:
  1. `client.track_supplement(track_id).lyrics.text_language` — единственное поле в библиотеке
     с реальным языком текста песни. Оно есть только в устаревшем (deprecated) методе
     `track_supplement`, а не в новом `tracks_lyrics()` — тот текст возвращает, но язык не отдаёт.
     Используется сознательно, несмотря на пометку deprecated в самой библиотеке.
  2. Подсказка по слагу жанра (`rusrap`, `shanson`, `bard`, ...).
  3. Эвристика по алфавиту названия/исполнителя (кириллица vs латиница, `unicodedata`).
  4. Иначе — `UNKNOWN` → отдельный плейлист «Не определено».

- **Идентификаторы треков**: у трека есть composite `track_id` (`"id:album_id"`, используется как
  ключ кэша и для сверки с уже добавленными треками в плейлисте) и отдельные `id`/`album_id`
  (нужны как раздельные параметры для `track_supplement`, `tracks_lyrics` и
  `users_playlists_insert_track`).

- **Идемпотентность `apply`**: перед добавлением треков в плейлист читается его текущий состав
  (`users_playlists(kind)`), уже присутствующие треки пропускаются. Повторный запуск `apply`
  безопасен и не создаёт дублей. Лайки не трогаются, ничего не удаляется.

- **Троттлинг и резюмируемость**: все сетевые циклы (загрузка треков, языков) делают паузу между
  запросами (`config.toml`, `[throttle]`) и пишут кэш атомарно (temp-файл + rename) после каждого
  батча — прерванный прогон можно просто перезапустить, уже полученное не запрашивается повторно.

## Хранилище

- `.token` — OAuth-токен аккаунта (не коммитится).
- `cache/tracks.json` — метаданные лайкнутых треков.
- `cache/genre_catalog.json` — плоский снимок дерева жанров Яндекса (id -> title, root_id).
- `cache/lyrics_lang.json` — язык текста песни по треку (id -> language code | null).
- `out/report.csv` — предпросмотр распределения по плейлистам перед `apply`.