doc: Как создается и как управлять offer_code для скрытия ID в URL и QR-кодов.

2026-07-15 21:41:51 +03:00
parent f963d21b26
commit 9fe12c4ab7
1 changed files with 112 additions and 0 deletions
@@ -0,0 +1,112 @@
+# Генерирование криптографической соли для OFFER_HASHIDS_SALT
+
+## Для Development (локально)
+
+Текущее значение в `.env`. Если база из dev будет перемещаться в продакшен, то соль не нужно будет заменять
+на уникальную для продакшена. А то все старые QR-коды перестанут работать.
+
+Возможно TODO сделать Django Custom Command для генерации соли и обновления `.env` автоматически.
+
+```
+
+## Для Production (сервер)
+
+**НИКОГДА** не используйте соль из примеров! Генерируйте новую для каждого окружения:
+
+### Способ 1: Python (быстро)
+```bash
+python3 -c "import secrets; print(secrets.token_hex(16))"
+```
+
+Результат:
+```
+a7f3c82b9e1d4a6b5c8f2e3d0a9b4c7f
+```
+
+Скопируйте и обновите в `.env` на сервере:
+```
+OFFER_HASHIDS_SALT=a7f3c82b9e1d4a6b5c8f2e3d0a9b4c7f
+```
+
+### Способ 2: Linux/Mac (встроенный)
+```bash
+openssl rand -hex 16
+```
+
+### Способ 3: Более надежная соль (32 байта вместо 16)
+```bash
+python3 -c "import secrets; print(secrets.token_hex(32))"
+```
+
+Результат (64 символа, очень стойко):
+```
+a7f3c82b9e1d4a6b5c8f2e3d0a9b4c7fa7f3c82b9e1d4a6b5c8f2e3d0a9b4c
+```
+
+## Важные правила
+
+1. **Уникальная для каждого окружения** (каждой реализации LPON под каждого сейлера)
+   - Dev ≠ Staging ≠ Production
+   - Разные соли = разные коды для одного ID
+
+2. **Никогда не меняйте в production!**
+   - Если поменяете соль → старые коды перестанут работать (если будет создана Django Custom Command для перегенерации 
+     s_offer_code под новую "соль", то сделать перегенерацию обязательно)
+   - Существующие QR-коды станут невалидными
+   - Существующие ID в базе не будут декодироваться
+
+3. **Хранить в .env (не в репозитории)**
+   - `.env` в .gitignore ✓
+   - `.env.example` содержит шаблон ✓
+
+## Проверка качества соли
+
+```python
+import secrets
+
+# Хорошая соль (минимум 32 символа, hex-формат)
+salt = secrets.token_hex(16)  # ✓
+salt = secrets.token_hex(32)  # ✓✓ еще лучше
+
+# Плохие соли
+salt = "my-password"          # ✗ слишком короткая
+salt = "12345678"             # ✗ предсказуемая
+salt = "qwerty123"            # ✗ слабая энтропия
+```
+
+## Параметры OFFER_HASHIDS_MIN_LENGTH
+
+| Кол-во оферов | min_length | Пример       | Примечание                            |
+|---------------|------------|--------------|---------------------------------------|
+| До 1 000      | 4          | `a1bC`       | Слишком короткие, может быть коллизии |
+| До 10 000     | 5          | `a1bCd`      | Хорошо для небольших каталогов        |
+| До 100 000    | 6          | `a1bCdE`     | **РЕКОМЕНДУЕМО** для начала           |
+| До 1 000 000  | 8          | `a1bCdEfG`   | Для больших каталогов                 |
+| Более 1M      | 10         | `a1bCdEfGhI` | Очень большие каталоги                |
+
+**Текущее значение:** `OFFER_HASHIDS_MIN_LENGTH=6` (оптимально)
+
+## Как увеличить при необходимости?
+
+Если вырос каталог:
+
+1. Обновите в `.env`:
+   ```
+   OFFER_HASHIDS_MIN_LENGTH=8
+   ```
+
+2. Перезагрузите приложение
+
+3. **Старые коды останутся валидными!** (hashids декодирует любой код независимо от min_length)
+
+4. Новые офферы будут кодироваться с длиной 8
+
+## Итого
+
+✓ Текущая соль: `4ce44e07053ac50e1096d6725a4782ac` (dev)  
+✓ Текущая длина: `6` (оптимальна)  
+✓ Для production: **Генерируйте новую соль**
+
+```bash
+python3 -c "import secrets; print(secrets.token_hex(16))"
+```