add: документация по Custom Command (1)

_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` после истечения тайм-аута модерации.

_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           |