# راهنمای تست اتصال به Qdrant Vector Database

## نمای کلی

این سند راهنمای کاملی برای تست اتصال به پایگاه داده برداری Qdrant در پروژه اسلامی اسکولار است. تست اتصال شامل دو بخش اصلی می‌شود:

1. **تست مستقل** (`test_qdrant_connection.py`) - برای استفاده عملی
2. **تست‌های pytest** (`tests/integration/test_qdrant_connection.py`) - برای محیط توسعه

## ساختار تست‌ها

### ۱. تست‌های واحد (Unit Tests)

#### `test_qdrant_connection_mock_success`
- **هدف**: تست اتصال موفق با استفاده از Mock
- **ورودی‌ها**: embedder ساختگی، پارامترهای اتصال
- **خروجی مورد انتظار**:
  ```
  ✅ تست موفق - بدون خطا
  ```
- **چرا مهم**: تست منطق اتصال بدون نیاز به Qdrant واقعی

#### `test_qdrant_connection_missing_embedder`
- **هدف**: تست مدیریت خطای embedder خالی
- **ورودی**: فراخوانی تابع بدون embedder
- **خروجی مورد انتظار**:
  ```
  ValueError: You must provide an 'embedder' instance to get_qdrant_store!
  ```
- **چرا مهم**: اطمینان از اعتبارسنجی ورودی‌ها

#### `test_qdrant_connection_missing_env_vars`
- **هدف**: تست رفتار با متغیرهای محیطی خالی
- **ورودی**: متغیرهای محیطی پاک شده
- **خروجی مورد انتظار**:
  ```
  ✅ تست موفق - اتصال با پارامترهای مستقیم
  ```
- **چرا مهم**: تست انعطاف‌پذیری تنظیمات

### ۲. تست‌های یکپارچه‌سازی (Integration Tests)

#### `test_qdrant_real_connection_success`
- **هدف**: تست اتصال واقعی به Qdrant
- **پیش‌نیاز**: متغیر محیطی `QDRANT_URL` تنظیم شده باشد
- **خروجی مورد انتظار**:
  ```
  Loading config from: F:\WORK\CODE\WORK\AGNO-DOVOODI\config\embeddings.yaml
  ✅ Embedder loaded: jina-embeddings-v4
  ✅ Vector store initialized
  📊 Found X collections in Qdrant:
     1. collection_name_1
     2. collection_name_2
     ...
     Total collections: X
  ```
- **چرا مهم**: تأیید اتصال واقعی به پایگاه داده

#### `test_qdrant_real_connection_failure`
- **هدف**: تست رفتار با خطای اتصال
- **پیش‌نیاز**: متغیر محیطی `QDRANT_URL` تنظیم نشده باشد
- **ورودی**: URL نامعتبر
- **خروجی مورد انتظار**:
  ```
  httpx.ConnectError: [Errno 11001] getaddrinfo failed
  ```
- **چرا مهم**: اطمینان از مدیریت مناسب خطاهای اتصال

#### `test_qdrant_collection_operations`
- **هدف**: تست عملیات مجموعه‌ها
- **پیش‌نیاز**: متغیر محیطی `QDRANT_URL` تنظیم شده باشد
- **خروجی مورد انتظار**:
  ```
  📋 Current collections in database (X total):
     1. collection_name_1
     2. collection_name_2
     ...
  ℹ️  Test collection test_operations_jina-embeddings-v4 does not exist (this is normal)
  ✅ Verified collection test_operations_jina-embeddings-v4 is not in database
  ```
- **چرا مهم**: تست عملیات مدیریت مجموعه‌ها

## نحوه اجرای تست‌ها

### اجرای تست مستقل

```bash
# از ریشه پروژه
python test_qdrant_connection.py
```

**خروجی نمونه موفق**:
```
🗄️  Qdrant Vector Database Connection Test
Testing connection to Qdrant vector database

🔧 Checking Environment Configuration...
==================================================
✅ QDRANT_URL: http://127.0.0.1:6333
✅ QDRANT_API_KEY: qs-8d9f-...
✅ BASE_COLLECTION_NAME: dovodi_collection
✅ JINA_API_KEY: jina_04d...
❌ OPENAI_API_KEY: Not configured

🔄 Testing Qdrant Basic Connection...
==================================================
📍 Qdrant URL: http://127.0.0.1:6333
✅ Qdrant HTTP health check: OK (endpoint: /)

🔄 Testing Qdrant Client Connection...
==================================================
Loading config from: F:\WORK\CODE\WORK\AGNO-DOVOODI\config\embeddings.yaml
✅ Embedder loaded: jina-embeddings-v4
✅ Vector store initialized
F:\WORK\CODE\WORK\AGNO-DOVOODI\.venv\Lib\site-packages\agno\vectordb\qdrant\qdrant.py:167: UserWarning: Api key is used with an insecure connection.
✅ Client connection successful
📊 Available collections: 9
📋 Collections:
   - islamic_knowledge_free
   - test_collection
   - dovodi_collection_jina-embeddings-v4
   - islamic_knowledge_jina-embeddings-v4
   - dovodi_collection
   ... and 4 more

🔄 Testing Qdrant Collection Operations...
==================================================
🧪 Testing with collection: test_connection_jina-embeddings-v4
📂 Collection exists: False
ℹ️  Note: Collection will be created on first vector operation
   This is normal behavior for Qdrant
✅ Collection access: OK (collection doesn't exist yet)

==================================================
📊 TEST RESULTS SUMMARY
==================================================
Environment Configuration: ✅ PASSED
Basic HTTP Connection: ✅ PASSED
Client Connection: ✅ PASSED
Collection Operations: ✅ PASSED

🎉 ALL TESTS PASSED!
✨ Your Qdrant vector database is connected and ready to use.
```

### اجرای تست‌های pytest

```bash
# اجرای همه تست‌های Qdrant
pytest tests/integration/test_qdrant_connection.py -v

# اجرای تست‌های واحد فقط
pytest tests/integration/test_qdrant_connection.py -m unit -v

# اجرای تست‌های یکپارچه‌سازی فقط
pytest tests/integration/test_qdrant_connection.py -m integration -v

# اجرای تست خاص با جزئیات
pytest tests/integration/test_qdrant_connection.py::TestQdrantConnection::test_qdrant_real_connection_success -v -s
```

## تنظیمات محیطی مورد نیاز

### متغیرهای محیطی اصلی

```bash
# Qdrant connection
QDRANT_URL=http://127.0.0.1:6333          # آدرس Qdrant
QDRANT_API_KEY=your_api_key                # کلید API (اختیاری)

# Collection settings
BASE_COLLECTION_NAME=dovodi_collection     # نام پایه مجموعه

# Embedding API keys
JINA_API_KEY=your_jina_key                 # کلید API Jina
OPENAI_API_KEY=your_openai_key             # کلید API OpenAI (اختیاری)
```

### فایل‌های تنظیمات

- `config/embeddings.yaml` - تنظیمات embedder
- `config/production.env` - تنظیمات تولید
- `config/development.env` - تنظیمات توسعه

## انواع خروجی‌ها

### ✅ خروجی موفق

```
================== 5 passed, 1 skipped, 6 warnings in 2.65s ===================
```

### ❌ خروجی ناموفق

```
FAILED tests/integration/test_qdrant_connection.py::TestQdrantConnection::test_name - Error details
```

### ⚠️ خروجی هشدار

```
PytestUnknownMarkWarning: Unknown pytest.mark.unit
```

## عیب‌یابی مشکلات رایج

### مشکل: اتصال به Qdrant برقرار نیست

**علائم**:
```
❌ Qdrant HTTP health check: FAILED
httpx.ConnectError: [Errno 11001] getaddrinfo failed
```

**راه‌حل‌ها**:
1. بررسی اجرای Qdrant: `docker ps | grep qdrant`
2. بررسی URL: `echo $QDRANT_URL`
3. بررسی فایروال و پورت 6333

### مشکل: API Key نامعتبر

**علائم**:
```
❌ Client connection test failed: Unauthorized
```

**راه‌حل‌ها**:
1. بررسی `QDRANT_API_KEY` در `.env`
2. اطمینان از صحت کلید API
3. بررسی تنظیمات امنیتی Qdrant

### مشکل: Embedder بارگذاری نمی‌شود

**علائم**:
```
❌ Embedder loaded: FAILED
```

**راه‌حل‌ها**:
1. بررسی `config/embeddings.yaml`
2. بررسی کلیدهای API (JINA_API_KEY)
3. بررسی اتصال اینترنت برای embedderهای API-based

### مشکل: مجموعه‌ها پاک نمی‌شوند

**علائم**:
```
❌ Failed to verify/clean up test collection
```

**راه‌حل‌ها**:
1. بررسی مجوزهای نوشتن در Qdrant
2. بررسی فضای دیسک کافی
3. بررسی تنظیمات Qdrant برای عملیات حذف

## ساختار فایل‌ها

```
tests/integration/test_qdrant_connection.py  # تست‌های pytest
test_qdrant_connection.py                   # تست مستقل
docs/QDRANT_CONNECTION_TEST.md             # این سند
src/knowledge/vector_store.py              # کد اتصال Qdrant
config/embeddings.yaml                     # تنظیمات embedder
```

## نکات مهم

1. **تست‌های یکپارچه‌سازی نیاز به Qdrant واقعی دارند**
2. **تست‌های واحد از Mock استفاده می‌کنند**
3. **همه مجموعه‌های موجود در خروجی نمایش داده می‌شوند**
4. **خطاها به طور کامل لاگ می‌شوند**
5. **تنظیمات محیطی باید قبل از اجرا بررسی شوند**

## مثال خروجی کامل

```
🗄️  Qdrant Vector Database Connection Test
Testing connection to Qdrant vector database

🔧 Checking Environment Configuration...
✅ QDRANT_URL: http://127.0.0.1:6333
✅ QDRANT_API_KEY: qs-8d9f-...
✅ BASE_COLLECTION_NAME: dovodi_collection
✅ JINA_API_KEY: jina_04d...
❌ OPENAI_API_KEY: Not configured

🔄 Testing Qdrant Basic Connection...
📍 Qdrant URL: http://127.0.0.1:6333
✅ Qdrant HTTP health check: OK (endpoint: /)

🔄 Testing Qdrant Client Connection...
Loading config from: config/embeddings.yaml
✅ Embedder loaded: jina-embeddings-v4
✅ Vector store initialized
✅ Client connection successful
📊 Available collections: 9
📋 Collections:
   1. islamic_knowledge_free
   2. test_collection
   3. dovodi_collection_jina-embeddings-v4
   4. islamic_knowledge_jina-embeddings-v4
   5. dovodi_collection
   ... and 4 more

🎉 ALL TESTS PASSED!
✨ Your Qdrant vector database is connected and ready to use.
```