From b63dbb6bd22732bb08b9a52a626cbda8a2bfd7b0 Mon Sep 17 00:00:00 2001 From: erjemin Date: Sat, 22 Aug 2026 20:32:33 +0300 Subject: [PATCH] =?UTF-8?q?add:=20=D0=B4=D0=BE=D0=BA=D1=83=D0=BC=D0=B5?= =?UTF-8?q?=D0=BD=D1=82=D0=B0=D1=86=D0=B8=D1=8F=20=D0=BF=D0=BE=20Custom=20?= =?UTF-8?q?Command=20(1)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- _blueprint/management-commands.md | 71 +++++++++++++++++++++++++++++++ _blueprint/plan-draft.md | 2 + 2 files changed, 73 insertions(+) create mode 100644 _blueprint/management-commands.md diff --git a/_blueprint/management-commands.md b/_blueprint/management-commands.md new file mode 100644 index 0000000..d128b30 --- /dev/null +++ b/_blueprint/management-commands.md @@ -0,0 +1,71 @@ +# Django Management Commands + +В этом документе описаны кастомные консольные команды (`manage.py`), реализованные в проекте **Hypn0** для автоматизации периодических фоновых задач, скоринга и обслуживания хранилища. + +--- + +## 1. `rescore_hypn0_items` — Пакетный пересчет рейтинга и детекция аномалий + +- **Путь:** `hypn0/hypn0_site/management/commands/rescore_hypn0_items.py` +- **Назначение:** Пакетный фоновый пересчет рейтинга популярности (`f_score`) для всех активных картин и выявление аномалий (накрутка лайков / скоординированный шейминг). + +### Базовый запуск: +```bash +# Рабочий запуск +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. Планируемые команды (Roadmap) + +- **`cleanup_storage`** — Удаление старых и низкорейтинговых картин (Smart Retention) при превышении квоты хранилища (использует рассчитанный `f_score`). +- **`cleanup_reports`** — Автоматическая изоляция или удаление картин со статусом `SHAMED` после истечения тайм-аута модерации. diff --git a/_blueprint/plan-draft.md b/_blueprint/plan-draft.md index 760ae0a..88177e7 100644 --- a/_blueprint/plan-draft.md +++ b/_blueprint/plan-draft.md @@ -573,8 +573,10 @@ CLI больше не нужен. | `hypn0/hypn0_site/models.py` | TbHypn0Item, TbVote... | | `hypn0/hypn0_site/services/halftone.py` | Ядро | | `hypn0/hypn0_site/templates/halftone/index.html` | Главная | +| `hypn0/hypn0_site/management/commands/rescore_hypn0_items.py` | Скоринг и детекция аномалий | | `hypn0/hypn0_site/management/commands/cleanup_storage.py` | Очистка SmartRetention | | `hypn0/hypn0_site/management/commands/cleanup_reports.py` | Очистка по жалобам | +| `_blueprint/management-commands.md` | Документация CLI-команд| | `public/static/css/site.css` | Стили | | `public/static/js/site.js` | JS | | `.env.sample` | Env template |