Приемка локального продукта
Этот документ связывает требования MVP с файлами репозитория и командами проверки. Локальный продукт считается готовым на sample-данных после успешного make test. Реальный аккаунт считается проверенным только после make acceptance-real с валидным YANDEX_MUSIC_TOKEN.
Матрица требований
| Требование | Где реализовано | Проверка |
|---|---|---|
| Fully local run without cloud services | Makefile, docker-compose.local.yml, dbt/profiles.yml local DuckDB target | make acceptance-local, make compose-smoke-local |
| Local operator entrypoint | make help lists sample, real-account, Docker, export, readiness and cleanup commands | make help |
| Docker Compose local product path | docker-compose.local.yml local profile with one-shot build, dashboard services, set -euo pipefail, real-source readiness enforcement when a token is configured, and compose smoke validation of raw/product/dashboard artifacts | make up-local, make compose-smoke-local, make compose-smoke-real |
| Yandex Music metadata ingestion | yamusic_ingest/__main__.py, yamusic_ingest/yandex_client.py; liked tracks, owned playlists, liked playlists, liked albums and liked artists where exposed by the API | make preflight, make ingest, make acceptance-real |
| No audio download or storage | metadata-only adapter, .gitignore, safety scripts | scripts/check_no_audio_artifacts.py, scripts/check_no_local_sensitive_artifacts.py |
| Raw normalized outputs | tracks, artists, albums, playlists, playlist_tracks, user_library_events JSONL/Parquet writers | make ingest-sample, make raw-contract |
| Bronze/silver/gold data engineering path | data/raw/yamusic, stg_yamusic_*, yamusic_dim_*, yamusic_fact_*, profile/signal marts | make dbt-build, make doctor |
| Source provenance and stale-build protection | stg_yamusic_manifest, manifest fields in yamusic_library_profile, doctor/readiness raw-count alignment checks | make doctor, make readiness, make product-answers-smoke |
| Idempotent local ingestion | overwrite-per-run raw writer, stale Parquet cleanup, and _manifest.json row counts | repeated make ingest-sample, make raw-contract |
| Data quality checks | dbt schema tests, raw contract, doctor, safety checks, empty-account smoke | make test |
| Practical self-analytics answers | yamusic_artist_affinity, yamusic_genre_periods, yamusic_track_signals, yamusic_playlist_signals, yamusic_library_profile, dashboard genre/liked/search filters, dashboard Actions/Data Quality tabs, dashboard content smoke, data/streamify_summary.md, data/streamify_snapshot.json, data/recommendations/*.csv | make product-answers-smoke, make dashboard-smoke, make report, make snapshot, make recommendations, make dashboard |
| Future location enrichment is documented but not implemented | docs/location_enrichment.md; current Yandex Music metadata has no listening-location field, and any future joins require explicit user-provided location timelines plus confidence/provenance labels | Documentation review only |
| Empty/private account handling | typed empty raw files and empty dbt smoke | scripts/smoke_empty_yamusic_dbt.py, make test |
| Token safety | .env.example, .gitignore, no token in manifest/report/status, preflight without raw writes | make status, make preflight, scripts/check_no_local_sensitive_artifacts.py |
Текущий статус приемки
Путь на sample metadata:
make acceptance-localproves local ingestion, raw contract, DuckDB/dbt marts, doctor, report, readiness and dashboard startup.make testproves static contracts, safety guards, empty-account handling, sample acceptance, Python unit tests, Compose config and Compose local smoke.
Путь на реальном аккаунте:
- A valid
YANDEX_MUSIC_TOKENin.envis still required to prove real-account ingestion. - The final real-account command is:
make acceptance-real
make dashboardThe readiness audit must report "real_account_verified": true before the real-account MVP is considered proven. make acceptance-real enforces this through make readiness-real, which runs scripts/audit_yamusic_readiness.py --require-real.
Продуктовые вопросы
| Вопрос пользователя | Основной артефакт |
|---|---|
| Who are my strongest artists? | yamusic_artist_affinity, dashboard Artists tab |
| Which tracks repeat across library contexts? | yamusic_track_signals.repeat_signal, dashboard Tracks tab |
| How has genre composition shifted? | yamusic_genre_periods, dashboard Genres/Periods tabs |
| How diverse or concentrated is my library? | yamusic_library_profile, yamusic_genre_profile |
| Which playlists overlap? | yamusic_playlist_overlap, dashboard Playlists tab |
| Which tracks or playlists look underrated? | yamusic_track_signals, yamusic_playlist_signals, static report |
| What should I do next? | dashboard Actions tab, JSON snapshot next_actions |
| Can I open action queues in a spreadsheet? | data/recommendations/*.csv, make recommendations |
| Can I reuse the answers outside the dashboard? | data/streamify_snapshot.json, make snapshot |
| Is my local data trustworthy? | dashboard Data Quality tab, JSON snapshot quality block, make doctor, make readiness |
| Can Streamify analyze music by where I was? | Future-only contract in docs/location_enrichment.md; not part of current acceptance |
Известные ограничения
- Yandex Music availability depends on the unofficial
yandex-musicpackage and account-visible metadata. - Listening timestamps/history are used only when exposed by the account/API response; otherwise the product falls back to liked-track and playlist-membership events.
- Listening location is not present in current Yandex Music metadata. Future geo enrichment must be opt-in, source-labeled and joined to library events by timestamp with caveats around confidence and inference.
- The dashboard and report are analytics over metadata and derived events, not audio playback or audio feature extraction.