Add initial documentation for Merchant Services API including contract status service details

01-BUSINESS/daya-loan-integration.md

@@ -22,9 +22,11 @@
 ```csharp
 public enum DayaLoanStatus
 {
-    PendingReceive = 0,  // در انتظار دریافت وام
-    Received = 1,        // وام دریافت شده (آینده)
-    Rejected = 2         // رد شده (آینده)
+    NotRequested = 0,    // درخواست نشده
+    PendingReceive = 1,  // در انتظار دریافت وام (فعال شده)
+    Received = 2,        // وام دریافت شده
+    Rejected = 3,        // رد شده
+    UnderReview = 4      // در حال بررسی
 }
 ```
 
@@ -133,12 +135,78 @@ public class DayaLoanCheckResult
 }
 ```
 
-**⚠️ Current Status:** این Command فعلاً skeleton است و API واقعی دایا پیاده‌سازی نشده.
+**✅ Current Status:** این Command کاملاً پیاده‌سازی شده و به API واقعی Daya متصل است.
+
+#### **API Integration Details:**
+- **Endpoint**: `POST /api/merchant/contracts`
+- **Base URL**: `https://testdaya.tadbirandishan.com`
+- **Authentication**: `merchant-permission-key` header
+- **Request Body**:
+  ```json
+  {
+    "nationalCodes": ["1234567890", "0987654321"]
+  }
+  ```
+- **Response Structure**:
+  ```json
+  {
+    "succeed": true,
+    "code": 200,
+    "message": "Success",
+    "data": [
+      {
+        "nationalCode": "1234567890",
+        "contractNumber": "DAYA-12345",
+        "statusDescription": "فعال شده (در انتظار تسویه)",
+        "dateTime": "2024-12-06T10:30:00"
+      }
+    ]
+  }
+  ```
+- **Status Mapping**:
+  - "فعال شده (در انتظار تسویه)" → PendingReceive
+  - "تایید شده" → Received
+  - "رد شده" → Rejected
+  - Default → UnderReview
+- **Cache Duration**: 20 minutes (per Daya API spec)
+- **Multiple Contracts**: If user has multiple contracts, system takes the latest one by DateTime
 
 ---
 
 ### Infrastructure Layer
 
+#### **IDayaLoanApiService Implementations**
+
+**1. MockDayaLoanApiService** (Testing):
+- Returns mock data based on NationalCode patterns
+- Instant response for fast testing
+- No external dependencies
+
+**2. DayaLoanApiService** (Production):
+- ✅ Fully implemented with HttpClient
+- Posts to `/api/merchant/contracts` endpoint
+- Handles API errors gracefully
+- Maps Persian status descriptions to enum values
+- Returns empty results on error (prevents worker crashes)
+
+**Configuration** (`appsettings.json`):
+```json
+{
+  "DayaApi": {
+    "UseMock": false,
+    "BaseAddress": "https://testdaya.tadbirandishan.com",
+    "MerchantPermissionKey": "14752708$Db5Wk5h...",
+    "CacheDurationMinutes": 20
+  }
+}
+```
+
+**Service Registration** (`ConfigureServices.cs`):
+- Reads `DayaApi:UseMock` from configuration
+- If `true`: Uses MockDayaLoanApiService
+- If `false`: Uses DayaLoanApiService with HttpClient
+- HttpClient configured with BaseAddress, headers, and 30s timeout
+
 #### **Background Worker: DayaLoanCheckWorker**
 Worker خودکار که هر 15 دقیقه کاربران با وام pending را چک می‌کند.
 
@@ -293,11 +361,23 @@ grpcurl -d '{
 
 ---
 
-## 📋 Pending Tasks
+## ✅ Completed Implementation
 
-### High Priority
-- [ ] پیاده‌سازی API واقعی دایا در CheckDayaLoanStatusCommandHandler
+### High Priority (All Done)
+- ✅ پیاده‌سازی API واقعی دایا در DayaLoanApiService (December 6, 2025)
+  - HTTP POST to `/api/merchant/contracts`
+  - Request/Response models with JSON serialization
+  - Status description mapping (Persian → Enum)
+  - Error handling and logging
+  - Configurable via appsettings.json
+- ✅ Conditional service registration (Mock vs Real)
+- ✅ HttpClient configuration with authentication
+- ✅ Worker fully operational with real API
+
+### Low Priority (Optional)
 - [ ] اضافه کردن Proto definitions برای Daya commands
+- [ ] Admin UI for Daya contract management
+- [ ] Unit tests for API service
 - [ ] اضافه کردن gRPC service endpoints
 - [ ] تست Worker در محیط development