# Руководство по кодам атлетов / Athlete Codes Guide

## 🇷🇺 Русский

### Проблема
Один и тот же атлет может участвовать в разных соревнованиях под **разными кодами**. Например:
- Олимпиада 2020: код `1025669`
- Олимпиада 2024: код `1030145`
- Чемпионат мира 2023: код `1028734`

Это один человек, но 3 разных кода!

### Решение
Храним **все коды атлета в массиве** `codes`:

```json
{
  "_id": "...",
  "given_name": "Karl",
  "family_name": "Vilips",
  "birth_date": "2001-08-16",
  "code": "1025669",           // Основной код (первый)
  "codes": [                    // ВСЕ коды атлета
    "1025669",
    "1030145", 
    "1028734"
  ],
  "organisation": "AUS",
  "gender": "M"
}
```

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

#### 1. Консолидация дубликатов
Скрипт `consolidate_athletes.py`:
- Находит записи с одинаковыми именем и датой рождения
- Объединяет их в одну запись
- Сохраняет все коды в массив `codes`

```bash
python consolidate_athletes.py
```

#### 2. Проверка связей
Скрипт `check_relationships.py`:
- Проверяет, что все коды из ODF коллекций существуют в `people.codes`
- Показывает недействительные ссылки

```bash
python check_relationships.py
```

### Структура данных

#### Коллекция `people`
```json
{
  "code": "1025669",              // Основной код
  "codes": ["1025669", "1030145"], // Массив всех кодов
  "given_name": "Karl",
  "family_name": "Vilips",
  "birth_date": "2001-08-16",
  "organisation": "AUS",
  "gender": "M",
  "consolidated_at": "2026-01-12T09:30:00Z",
  "original_record_count": 3
}
```

#### ODF коллекции (rankings, results, medallists)
```json
{
  "competitor": {
    "composition": {
      "athlete": {
        "code": 1025669,  // Ссылается на people.codes
        "description": {
          "given_name": "Karl",
          "family_name": "Vilips"
        }
      }
    }
  }
}
```

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

✅ **Один человек = одна запись** в `people`
✅ **Все коды сохранены** в массиве `codes`
✅ **Связи работают** для всех соревнований
✅ **История участия** полная

---

## 🇬🇧 English

### Problem
The same athlete can participate in different competitions with **different codes**. For example:
- Olympics 2020: code `1025669`
- Olympics 2024: code `1030145`
- World Championship 2023: code `1028734`

This is one person, but 3 different codes!

### Solution
Store **all athlete codes in an array** `codes`:

```json
{
  "_id": "...",
  "given_name": "Karl",
  "family_name": "Vilips",
  "birth_date": "2001-08-16",
  "code": "1025669",           // Primary code (first one)
  "codes": [                    // ALL athlete codes
    "1025669",
    "1030145", 
    "1028734"
  ],
  "organisation": "AUS",
  "gender": "M"
}
```

### How it works

#### 1. Consolidate duplicates
Script `consolidate_athletes.py`:
- Finds records with same name and birth date
- Merges them into one record
- Saves all codes in `codes` array

```bash
python consolidate_athletes.py
```

#### 2. Check relationships
Script `check_relationships.py`:
- Verifies all codes from ODF collections exist in `people.codes`
- Shows invalid references

```bash
python check_relationships.py
```

### Data Structure

#### Collection `people`
```json
{
  "code": "1025669",              // Primary code
  "codes": ["1025669", "1030145"], // Array of all codes
  "given_name": "Karl",
  "family_name": "Vilips",
  "birth_date": "2001-08-16",
  "organisation": "AUS",
  "gender": "M",
  "consolidated_at": "2026-01-12T09:30:00Z",
  "original_record_count": 3
}
```

#### ODF collections (rankings, results, medallists)
```json
{
  "competitor": {
    "composition": {
      "athlete": {
        "code": 1025669,  // References people.codes
        "description": {
          "given_name": "Karl",
          "family_name": "Vilips"
        }
      }
    }
  }
}
```

### Benefits

✅ **One person = one record** in `people`
✅ **All codes preserved** in `codes` array
✅ **Relationships work** for all competitions
✅ **Complete participation history**

---

## 📋 Usage Examples

### Import athletes from JSON
```bash
# Use the Streamlit UI:
# 1. Go to "JSON vs DB" tab
# 2. Select JSON Source: ba_glf_2018
# 3. Select Collection: people
# 4. Click "Load and Compare"
# 5. Import new records
```

### Consolidate duplicates
```bash
python consolidate_athletes.py
```

### Verify relationships
```bash
python check_relationships.py
```

### Fix email index (if needed)
```bash
python fix_email_index.py
```

---

## 🔧 Maintenance

### Regular tasks:
1. Import new competition data
2. Run consolidation script
3. Verify relationships
4. Check for missing codes

### Troubleshooting:
- **Duplicate key error on email**: Run `fix_email_index.py`
- **Invalid relationships**: Import missing athlete data
- **Multiple records for same person**: Run `consolidate_athletes.py`