Docs & Testing Audit — SoccerPredictAI¶

Date: 2026-04-24 Auditor: GitHub Copilot (Claude Sonnet 4.6) Scope: Документация, ADR, README, покрытие тестами, contract тесты, расхождения Method: анализ docs/, README.md, tests/, docs/status.md

1. Документация¶

1.1 Структура docs/¶

docs/
├── adr/              — Architecture Decision Records
├── architecture/     — система архитектуры
├── cicd/             — CI/CD docs
├── data/             — data docs
├── guides/           — operational guides
├── ml/               — ML docs
├── monitoring/       — observability docs
├── reference/        — API reference
├── runbooks/         — operational runbooks
├── serving/          — serving docs
├── validation/
│   └── audit/report/ — ← аудиты (эта серия)
├── index.md
├── demo.md
├── quickstart.md
├── review-guide.md
└── status.md

✅ Хорошая структура: отделены architecture, runbooks, adr, ml, serving.

1.2 README.md¶

Аспект	Статус
Описание проекта	✅
Quickstart (как запустить)	✅ `quickstart.md` существует
Stack summary	✅
Badges (CI, coverage)	проверить
Ссылки на docs	✅ mkdocs

1.3 docs/status.md¶

Аспект	Статус
Canonical source of truth	✅ явно помечен
Последнее обновление	2026-04-19 — актуально
Implemented/Partial/Planned разделение	✅ явное

Расхождения status.md vs действительность (обнаружены в ходе аудитов):

Компонент	Заявлено в status.md	Реальность
`Streamlit UI`	✅ Operational — "match list, predictions, async result polling"	⚠️ `pages/` пуста — только livescores. Predictions page NOT реализована
`pytest ~200 tests`	✅	✅ Актуально (294 test functions найдено)
`API authentication`	"All public endpoints unauthenticated. TLS-only."	✅ Явно задокументировано как ограничение

⚠️ P1: status.md заявляет Streamlit UI как "match list, predictions, async result polling" — но pages/ пуста, prediction page отсутствует. Это расхождение docs vs code.

2. Тестирование¶

2.1 Инвентаризация тестов¶

Директория / Файл	Тип	Test count
`tests/unit/` (10 файлов)	Unit	~120
`tests/property/` (4 файла)	Property (Hypothesis)	~30
`tests/service/` (2 файла)	Service/integration	~20
`tests/contract/test_pipeline_contracts.py`	Contract	~40
`tests/load/locustfile.py`	Load (Locust)	—
`tests/test_api.py`	API integration	~20
`tests/test_features.py`	Feature	~20
`tests/test_metrics.py`	Metrics	~15
`tests/test_params.py`	Params validation	~5
Прочие	Ablation, ECE, data quality	~25
Итого		~294

2.2 Contract Tests — Расхождения с dvc.yaml¶

CRITICAL FINDING — тест упадёт при запуске:

# tests/contract/test_pipeline_contracts.py
EXPECTED_STAGES = [
    ...
    "validate_interim",  # ← ожидается
    ...
]

# dvc.yaml — actual stages:
# load_data_from_sources, validate_raw, export_metadata, preprocessing,
# validate_finished, validate_future, feature_engineering, validate_features,
# split_data, batch_inference, classification_models, ablation_study,
# tune_xgb, final_train, register_model

Ожидается в тесте	В dvc.yaml	Статус
`validate_interim`	❌ отсутствует	FAIL
`validate_finished`, `validate_future`	✅ есть	Не тестируются
`ablation_study`, `tune_xgb`, `final_train`	✅ есть	Не тестируются

⚠️ P0: test_expected_stage_exists["validate_interim"] — упадёт. Контракт рассинхронизирован с фактическим dvc.yaml.

Также в EXPECTED_UPSTREAM_DEPS:

"validate_interim": ["data/interim/finished.parquet"],

— тест для этого stage тоже упадёт, так как stage отсутствует.

2.3 Property Tests¶

Файл	Что тестируется
`test_elo_property.py`	ELO: score range, ordering, monotonicity
`test_features_property.py`	Features: no leakage, shape consistency
`test_metrics_property.py`	Metrics: range, calibration properties
`test_splitting_property.py`	Splitting: temporal ordering preserved

✅ Property тесты покрывают критические ML invariants.

2.4 Gaps в покрытии¶

Область	Покрытие
`src/data/storage.py` (MinIO)	⚠️ минимально (mocked)
`src/app/routers/predict.py`	✅ в test_api.py
`src/ui/app/`	❌ нет тестов для UI
Airflow DAGs	❌ нет тестов
`src/app/tasks/predict.py`	✅ `tests/service/test_tasks.py`
`src/models/tuning.py`	⚠️ нет явных unit тестов
Feature leakage	✅ property тесты
Schema validation	✅ `tests/unit/test_schemas.py`

2.5 CI Integration¶

# Из docs/status.md:
# Integration Tests — 🚧 Partial
# "API mock tests; no live MLflow/Celery required in CI"

✅ CI тесты не требуют live инфраструктуры — запускаются на моках.

3. ADRs¶

Аспект	Статус
`docs/adr/` существует	✅
ADRs документируют ключевые решения	требует отдельной проверки

4. Findings¶

ID	Severity	Описание
DOC-01	P0	`test_pipeline_contracts.py` ожидает `validate_interim` — stage отсутствует в dvc.yaml, тест упадёт
DOC-02	P1	`docs/status.md` заявляет Streamlit с predictions и async polling — фактически `pages/` пуста
DOC-03	P2	Contract тесты не покрывают существующие stages: `validate_finished`, `validate_future`, `ablation_study`, `tune_xgb`, `final_train`
DOC-04	P2	Нет тестов для Airflow DAGs — логика DAG не верифицируется в CI
DOC-05	P2	Нет тестов для `src/ui/app/` — Streamlit код без покрытия
DOC-06	P3	`src/data/storage.py` (MinIO interaction) тестируется только через mock — нет интеграционных тестов