99 lines
7.5 KiB
Markdown
99 lines
7.5 KiB
Markdown
# 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. `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`.
|
|
|
|
### Базовый запуск:
|
|
```bash
|
|
# Тестовая проверка нестыковок (без записи в БД)
|
|
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` после истечения тайм-аута модерации.
|