2026-hypn0-site/_blueprint/management-commands.md

Django Management Commands

В этом документе описаны кастомные консольные команды (manage.py), реализованные в проекте Hypn0 для автоматизации периодических фоновых задач, скоринга и обслуживания хранилища.

---

1. rescore_hypn0_items — Пакетный пересчет рейтинга и детекция аномалий

• Путь: hypn0/hypn0_site/management/commands/rescore_hypn0_items.py
• Назначение: Пакетный фоновый пересчет рейтинга популярности (f_score) для всех активных картин и выявление аномалий (накрутка лайков / скоординированный шейминг).

Базовый запуск:

# Рабочий запуск
poetry run python hypn0/manage.py rescore_hypn0_items

# Тестовый прогон (без записи изменений в базу)
poetry run python hypn0/manage.py rescore_hypn0_items --dry-run

---

Архитектурные принципы и алгоритм:

1. Метрики платформы («Средняя температура по больнице»):

   • Анализирует активность за скользящее окно WINDOW_HOURS = 24.0 часов.
   • Считает среднее число голосов на одну активную картину (моложе 30 дней).
   • Защита «холодного старта» (Cold Start): при пустой базе или отсутствии голосов отключаются относительные детекторы, предотвращая ложные срабатывания и деление на 0.

2. Экспоненциальное затухание голосов (Time-Decay):

   • Сила каждого голоса из TbVote плавно затухает по закону: \text{Weight}(t) = \text{BaseWeight} \times 2^{-\Delta t / \text{HalfLife}}
   • По умолчанию период полураспада силы голоса составляет 14 дней (--half-life-days=14.0).
   • Истинные веса голосов:
     • LIKE = +1
     • AUTHOR = +2
     • CLAIM = -2

3. Детекция аномалий и автоматический перевод уровней (Level):

   • Шейминг (Level.SHAMED = -20): если за последние 24ч доля жалоб среди свежих голосов \ge 35\% (--shame-claim-ratio=0.35).
   • Накрутка / Спайк (Level.SUSPICIOUS = -10): если приток лайков за окно в 4+ раза превышает средний по платформе (--spike-multiplier=4.0) и составляет \ge 20 лайков (или \ge 50 лайков при холодном старте).
   • Прогрев (Level.LEVEL_1 = 10): если картина со статусом CANDIDATE набрала достаточный взвешенный вес (\ge 10 по умолчанию), она автоматически повышается до LEVEL_1 («Плеск бессознательного»), привлекая внимание модератора для витрины.

4. Гравитационная модель скоринга (с логарифмом):

   \text{Score} = \frac{\ln(1 + \max(0, \text{WeightedLikes})) + \text{Bonus}_{\text{level}}}{(\text{Age in hours} + 2.0)^\gamma}
   • LEVEL_1_BONUS = +1.5
   • LEVEL_2_BONUS = +4.0 (Одобрено Мозговым Слизнем)

5. Инерционное сглаживание (EMA — Exponential Moving Average):

   • Чтобы исключить резкие скачки рейтинга от разовых всплесков, итоговый f_score сглаживается с предыдущим значением: \text{Score}_{\text{final}} = 0.7 \times \text{Score}_{\text{new}} + 0.3 \times \text{Score}_{\text{old}}

---

Параметры командной строки (CLI):

Флаг	Тип	По умолчанию	Описание
--gamma	float	1.5	Коэффициент гравитации старения картины
--half-life-days	float	14.0	Период полураспада веса голоса (в днях)
--spike-multiplier	float	4.0	Множитель спайка лайков для детекции накрутки
--shame-claim-ratio	float	0.35	Доля жалоб для признания скоординированного шейминга
--warmup-votes-threshold	int	10	Порог взвешенных голосов для автопрогрева CANDIDATE -> LEVEL_1
--dry-run	flag	False	Пробный запуск без изменения записей в БД

---

2. rehash — Проверка целостности и перегенерация s_hash_id

• Путь: hypn0/hypn0_site/management/commands/rehash.py
• Назначение: Синхронизация публичных коротких хэшей s_hash_id в базе данных с текущим значением HASHIDS_SALT и HASHIDS_MIN_LENGTH.

Когда требуется запуск:

1. При смене или ротации HASHIDS_SALT в .env / settings.py.
2. При переносе/миграции базы данных между разными окружениями (Dev \rightarrow Prod).
3. При обнаружении записей с пустыми или устаревшими s_hash_id.

Базовый запуск:

# Тестовая проверка нестыковок (без записи в БД)
poetry run python hypn0/manage.py rehash --dry-run

# Боевая перегенерация
poetry run python hypn0/manage.py rehash

Параметры командной строки (CLI):

Флаг	Тип	По умолчанию	Описание
--dry-run	flag	False	Только проверить нестыковки без изменения базы данных
--batch-size	int	500	Размер пачки для bulk_update (оптимизация памяти и скорости)

---

3. Планируемые команды (Roadmap)

• cleanup_storage — Удаление старых и низкорейтинговых картин (Smart Retention) при превышении квоты хранилища (использует рассчитанный f_score).
• cleanup_reports — Автоматическая изоляция или удаление картин со статусом SHAMED после истечения тайм-аута модерации.