# Руководство по обнаружению дубликатов / Duplicate Detection Guide

## 🇷🇺 Русский

### Проблема
При импорте больших объёмов данных (например, миллион записей) могут быть дубликаты **внутри самих JSON файлов**. Без проверки все они импортируются в базу данных.

### Решение
Система теперь **автоматически проверяет дубликаты в JSON данных ДО импорта**.

---

## 🎯 Как это работает

### 1. **Автоматическая проверка при загрузке**

Когда вы нажимаете **"Load & Compare"**, система:

1. Загружает JSON данные
2. **Проверяет дубликаты внутри JSON** (до сравнения с БД)
3. Показывает предупреждение, если найдены дубликаты
4. Сравнивает с MongoDB

### 2. **Для коллекции `people`**

Дубликаты определяются по:
- `given_name` (имя)
- `family_name` (фамилия)
- `birth_date` (дата рождения)

**Пример:**
```json
// JSON файл содержит:
[
  {"given_name": "John", "family_name": "Smith", "birth_date": "1990-01-01", "code": 1001},
  {"given_name": "John", "family_name": "Smith", "birth_date": "1990-01-01", "code": 1002},
  {"given_name": "John", "family_name": "Smith", "birth_date": "1990-01-01", "code": 1003}
]

// Система обнаружит: 1 дубликат (3 записи одного человека)
```

### 3. **Для других коллекций**

Дубликаты определяются по **business_keys** из `app_config.yaml`.

---

## ⚠️ Предупреждение о дубликатах

При обнаружении дубликатов вы увидите:

```
⚠️ DUPLICATES DETECTED IN JSON DATA!

Found 65 duplicate identities with 130 total duplicate records in your JSON files.

These are duplicates WITHIN your JSON data (same person appearing multiple times).
The system will automatically consolidate them during import by merging their codes.

- Unique identities: 445
- Duplicate identities: 65
- Total records that will be consolidated: 130

💡 What happens during import:
- Duplicates will be merged into single records
- All codes will be stored in 'codes' array
- Only unique people will be imported
```

---

## 🚀 Что происходит при импорте

### Автоматическая консолидация:

1. **Группировка** по имени + дате рождения
2. **Объединение кодов** в массив `codes`
3. **Создание одной записи** вместо нескольких

**Результат:**
```json
{
  "given_name": "John",
  "family_name": "Smith",
  "birth_date": "1990-01-01",
  "code": "1001",
  "codes": ["1001", "1002", "1003"]  // Все коды сохранены!
}
```

---

## 📊 Статистика

В сводке сравнения вы увидите:

```
✅ Comparison Complete

- JSON Records: 510
- JSON Duplicates: 65 identities (130 records)
- MongoDB Records: 1,486
- New Records: 380
```

**Расшифровка:**
- **510 записей** в JSON
- **65 дубликатов** (130 записей одних и тех же людей)
- **380 уникальных новых людей** будет импортировано

---

## ✨ Преимущества

✅ **Видите дубликаты ДО импорта** - не нужно импортировать миллион записей, чтобы потом их чистить

✅ **Автоматическая консолидация** - система сама объединяет дубликаты

✅ **Все коды сохранены** - ничего не теряется, все коды в массиве `codes`

✅ **Экономия места** - вместо 1000 дубликатов импортируется 1 запись

---

## 🔧 Техническая информация

### Файлы:
- `services/diff_engine.py` - метод `detect_json_duplicates()`
- `services/import_preview_engine.py` - метод `_consolidate_people_records()`
- `ui/tabs/json_vs_db.py` - отображение предупреждений

### Логика:
```python
# 1. Обнаружение дубликатов в JSON
json_duplicates = diff_engine.detect_json_duplicates(collection_name, json_records)

# 2. Показ предупреждения
if json_duplicates['has_duplicates']:
    st.warning(f"Found {json_duplicates['duplicate_count']} duplicates")

# 3. Консолидация при импорте
records_to_import = preview_engine.prepare_records_for_import(
    preview_df, json_records, import_indices,
    unflatten=True,
    collection_name='people',
    mongo_service=mongo_service
)
```

---

## 📝 Примеры использования

### Пример 1: Импорт участников соревнований

**Ситуация:** JSON содержит 1000 записей, но 200 из них - дубликаты

**Результат:**
- Система обнаружит 100 дубликатов (200 записей)
- Покажет предупреждение
- Импортирует только 900 уникальных людей
- Все коды сохранены в массивах

### Пример 2: Повторный импорт

**Ситуация:** Импортируете данные из нового соревнования, некоторые атлеты уже в базе

**Результат:**
- Дубликаты в JSON объединяются
- Существующие люди в БД обновляются (добавляются новые коды)
- Новые люди импортируются
- Никаких дубликатов в базе!

---

## 🎓 Лучшие практики

1. **Всегда проверяйте предупреждения** о дубликатах перед импортом
2. **Используйте "Load & Compare"** перед каждым импортом
3. **Проверяйте статистику** - сколько уникальных записей будет импортировано
4. **После импорта** используйте `check_relationships.py` для проверки связей

---

## 🇬🇧 English

### Problem
When importing large volumes of data (e.g., a million records), there may be duplicates **within the JSON files themselves**. Without checking, all of them get imported into the database.

### Solution
The system now **automatically checks for duplicates in JSON data BEFORE import**.

---

## 🎯 How It Works

### 1. **Automatic Check on Load**

When you click **"Load & Compare"**, the system:

1. Loads JSON data
2. **Checks for duplicates within JSON** (before comparing with DB)
3. Shows a warning if duplicates are found
4. Compares with MongoDB

### 2. **For `people` Collection**

Duplicates are identified by:
- `given_name`
- `family_name`
- `birth_date`

### 3. **For Other Collections**

Duplicates are identified by **business_keys** from `app_config.yaml`.

---

## ✨ Benefits

✅ **See duplicates BEFORE import** - no need to import a million records only to clean them up later

✅ **Automatic consolidation** - system merges duplicates automatically

✅ **All codes preserved** - nothing is lost, all codes stored in `codes` array

✅ **Save space** - instead of 1000 duplicates, only 1 record is imported

---

## 📋 Best Practices

1. **Always check warnings** about duplicates before import
2. **Use "Load & Compare"** before each import
3. **Check statistics** - how many unique records will be imported
4. **After import** use `check_relationships.py` to verify relationships