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