# Geolocation Package

این پکیج شامل تمام فایل‌های مرتبط با 3 API زیر است که از پروژه اصلی استخراج شده‌اند:

## API Endpoints

| API | URL | View | Description |
|-----|-----|------|-------------|
| IP Geolocation | `geolocation/` | `IPGeolocationAPIView` | دریافت اطلاعات موقعیت مکانی بر اساس IP کاربر |
| Reverse Geolocation | `geolocation/coordinates/` | `ReverseGeolocationAPIView` | دریافت اطلاعات شهر/کشور بر اساس مختصات جغرافیایی |
| Region Info | `auth/user/region/` | `RegionInfoView` | دریافت اطلاعات منطقه کاربر (شامل browser detection) |

---

## 📁 ساختار پوشه‌ها

```
geolocation_package/
├── __init__.py
├── README.md
├── views/
│   ├── __init__.py
│   ├── geolocation.py          # IPGeolocationAPIView, ReverseGeolocationAPIView
│   └── region_info.py          # RegionInfoView + detect_browser_from_user_agent
├── serializers/
│   ├── __init__.py
│   └── geolocation.py          # IPGeolocationSerializer, ReverseGeolocationSerializer, ReverseGeolocationResponseSerializer
├── models/
│   ├── __init__.py
│   └── geoNames.py             # GeoNamesCity model
├── utils/
│   ├── __init__.py
│   ├── city_detection_ip.py    # get_location_by_coordinates, get_location_by_ip
│   └── geo.py                  # توابع کمکی برای geocoding از API‌های مختلف
└── data/
    ├── GeoLite2-City.mmdb      # MaxMind GeoIP2 City database (61.5 MB)
    ├── GeoLite2-Country.mmdb   # MaxMind GeoIP2 Country database (9.2 MB)
    └── geonames_city.sqlite    # SQLite export of GeoNamesCity (628.6 MB, 5,115,708 records)
```

---

## 📋 فایل‌های استخراج شده

### Views (ویوها)

| فایل | مبدا | توضیحات |
|------|------|---------|
| `views/geolocation.py` | `apps/account/views/geolocation.py` | شامل `IPGeolocationAPIView` و `ReverseGeolocationAPIView` |
| `views/region_info.py` | `apps/account/views/location_history.py` (lines 138-248) | شامل `RegionInfoView` و `detect_browser_from_user_agent` |

### Serializers (سریالایزرها)

| فایل | مبدا | توضیحات |
|------|------|---------|
| `serializers/geolocation.py` | `apps/account/serializer/geolocation.py` | شامل `IPGeolocationSerializer`, `ReverseGeolocationSerializer`, `ReverseGeolocationResponseSerializer` |

### Models (مدل‌ها)

| فایل | مبدا | توضیحات |
|------|------|---------|
| `models/geoNames.py` | `apps/account/models/geoNames.py` | مدل `GeoNamesCity` با 5,115,708 رکورد شهر از سراسر جهان |

### Utils (ابزارها)

| فایل | مبدا | توضیحات |
|------|------|---------|
| `utils/city_detection_ip.py` | `city_detection_ip.py` | شامل `get_location_by_coordinates`, `get_location_by_ip`, `SPECIAL_COORDINATES` |
| `utils/geo.py` | `utils/geo.py` | توابع fallback برای geocoding از API‌های مختلف (Nominatim, BigDataCloud, etc.) |

### Data Files (فایل‌های داده)

| فایل | مبدا | سایز | توضیحات |
|------|------|------|---------|
| `data/GeoLite2-City.mmdb` | `utils/country_city_db/GeoLite2-City.mmdb` | 61.5 MB | دیتابیس MaxMind برای IP to City |
| `data/GeoLite2-Country.mmdb` | `utils/country_city_db/GeoLite2-Country.mmdb` | 9.2 MB | دیتابیس MaxMind برای IP to Country |
| `data/geonames_city.sqlite` | از PostgreSQL (GeoNamesCity model) | 628.6 MB | SQLite export با 5,115,708 رکورد |

---

## 🔧 وابستگی‌ها (Dependencies)

```txt
geoip2>=4.0.0
djangorestframework>=3.14.0
drf-yasg>=1.21.0
```

---

## 💾 SQLite Database Schema

جدول `geonames_city`:

```sql
CREATE TABLE geonames_city (
    id INTEGER PRIMARY KEY,
    name TEXT NOT NULL,
    country_code TEXT NOT NULL,
    latitude REAL NOT NULL,
    longitude REAL NOT NULL,
    feature_class TEXT NOT NULL,
    population INTEGER
);

-- Indexes
CREATE INDEX idx_lat_lon ON geonames_city (latitude, longitude);
CREATE INDEX idx_country_code ON geonames_city (country_code);
CREATE INDEX idx_feature_class ON geonames_city (feature_class);
CREATE INDEX idx_feature_lat_lon ON geonames_city (feature_class, latitude, longitude);
```

---

## 🚀 نحوه استفاده در پروژه جدید

### 1. کپی فولدر به پروژه

```bash
cp -r geolocation_package /path/to/new_project/apps/
```

### 2. تنظیم urls.py

```python
from apps.geolocation_package.views import (
    IPGeolocationAPIView,
    ReverseGeolocationAPIView,
    RegionInfoView
)

urlpatterns = [
    path('geolocation/', IPGeolocationAPIView.as_view(), name='ip-geolocation'),
    path('geolocation/coordinates/', ReverseGeolocationAPIView.as_view(), name='geolocation-by-coordinates'),
    path('auth/user/region/', RegionInfoView.as_view(), name='region-info'),
]
```

### 3. تنظیم مسیر دیتابیس

مسیر فایل‌های MMDB را در کد به محل جدید تغییر دهید:

```python
# در views/geolocation.py و views/region_info.py
CITY_DB_PATH = Path("apps/geolocation_package/data/GeoLite2-City.mmdb")
```

### 4. استفاده از SQLite به جای PostgreSQL (اختیاری)

اگر نمی‌خواهید GeoNamesCity را در PostgreSQL نگه دارید، می‌توانید مستقیماً از SQLite استفاده کنید:

```python
import sqlite3
from pathlib import Path

DB_PATH = Path("apps/geolocation_package/data/geonames_city.sqlite")

def get_city_by_coordinates(lat, lon):
    conn = sqlite3.connect(DB_PATH)
    cursor = conn.cursor()
    
    cursor.execute("""
        SELECT name, country_code FROM geonames_city
        WHERE feature_class = 'P'
          AND latitude BETWEEN ? AND ?
          AND longitude BETWEEN ? AND ?
        LIMIT 1
    """, (lat - 0.5, lat + 0.5, lon - 0.5, lon + 0.5))
    
    result = cursor.fetchone()
    conn.close()
    return result
```

---

## 📊 آمار دیتابیس

- **تعداد رکوردها در GeoNamesCity**: 5,115,708
- **حجم SQLite**: 628.59 MB
- **حجم GeoLite2-City.mmdb**: 61.50 MB
- **حجم GeoLite2-Country.mmdb**: 9.22 MB

---

## 📝 نکات مهم

1. **دیتابیس اصلی حذف نشده است** - فقط داده‌ها کپی شده‌اند
2. **GeoLite2 License**: فایل‌های MMDB از MaxMind هستند و نیاز به رعایت لایسنس دارند
3. **آپدیت دیتابیس**: برای آپدیت GeoNames از اسکریپت `export_geonames_to_sqlite.py` استفاده کنید

---

*Generated on: 2026-01-27*