add device token

src/DEVICE_TOKEN_API.md

@@ -0,0 +1,243 @@
+# API مدیریت توکن و تنظیمات دستگاه
+
+این سند توضیح دهنده API های جدید اضافه شده برای مدیریت توکن و تنظیمات دستگاه است.
+
+## تغییرات در مدل داده
+
+### فیلدهای جدید در `DeviceSettings`
+
+1. **UploadIntervalMin** (int): فاصله زمانی آپلود داده به دقیقه (پیش‌فرض: 5)
+2. **DevicePhoneNumber** (string): شماره تلفن دستگاه
+3. **SimCardType** (enum, nullable): نوع سیم‌کارت (همراه اول/ایرانسل/رایتل)
+4. **TokenCode** (string, nullable): کد توکن 5 رقمی
+5. **VerificationCode** (string, nullable): کد تایید 5 رقمی
+6. **TokenExpiresAt** (DateTime, nullable): تاریخ انقضای توکن
+
+### Enum نوع سیم‌کارت
+
+```csharp
+public enum SimCardType
+{
+    Hamrahe_Aval = 1,  // همراه اول
+    Irancell = 2,      // ایرانسل
+    Rightel = 3        // رایتل
+}
+```
+
+## API Endpoints
+
+### 1. دریافت فاصله زمانی آپلود
+
+**GET** `/api/DeviceToken/upload-interval`
+
+دریافت مقدار `UPLOAD_INTERVAL_MIN` بر اساس شناسه دستگاه یا شماره تلفن.
+
+#### پارامترها (Query String)
+
+- `deviceId` (int, optional): شناسه دستگاه
+- `devicePhoneNumber` (string, optional): شماره تلفن دستگاه
+
+**نکته:** حداقل یکی از پارامترها باید ارسال شود.
+
+#### مثال درخواست
+
+```http
+GET /api/DeviceToken/upload-interval?devicePhoneNumber=09123456789
+```
+
+#### پاسخ موفق
+
+```json
+{
+  "success": true,
+  "message": null,
+  "uploadIntervalMin": 5
+}
+```
+
+#### پاسخ خطا
+
+```json
+{
+  "success": false,
+  "message": "دستگاه یافت نشد",
+  "uploadIntervalMin": null
+}
+```
+
+---
+
+### 2. درخواست توکن دستگاه
+
+**POST** `/api/DeviceToken/request-token`
+
+تولید کد توکن 5 رقمی و ارسال آن از طریق پیامک به شماره دستگاه.
+
+#### بدنه درخواست (JSON)
+
+```json
+{
+  "devicePhoneNumber": "09123456789"
+}
+```
+
+#### مثال درخواست
+
+```http
+POST /api/DeviceToken/request-token
+Content-Type: application/json
+
+{
+  "devicePhoneNumber": "09123456789"
+}
+```
+
+#### پاسخ موفق
+
+```json
+{
+  "success": true,
+  "message": "کد تایید با موفقیت ارسال شد",
+  "tokenCode": "12345"
+}
+```
+
+**نکته:** پیامک حاوی کد توکن به شماره مشخص شده ارسال می‌شود. کد دارای اعتبار 10 دقیقه است.
+
+#### محاسبه کد تایید
+
+کد تایید بر اساس فرمول زیر محاسبه می‌شود:
+
+```
+VerificationCode = (TokenCode × 7 + 12345) % 100000
+```
+
+---
+
+### 3. تایید توکن دستگاه
+
+**POST** `/api/DeviceToken/verify-token`
+
+تایید کد تایید و ارسال تنظیمات کدشده دستگاه از طریق پیامک.
+
+#### بدنه درخواست (JSON)
+
+```json
+{
+  "devicePhoneNumber": "09123456789",
+  "verificationCode": "98765"
+}
+```
+
+#### مثال درخواست
+
+```http
+POST /api/DeviceToken/verify-token
+Content-Type: application/json
+
+{
+  "devicePhoneNumber": "09123456789",
+  "verificationCode": "98765"
+}
+```
+
+#### پاسخ موفق
+
+```json
+{
+  "success": true,
+  "message": "تنظیمات با موفقیت ارسال شد",
+  "encodedSettings": "RGV2aWNlMDF8NQ=="
+}
+```
+
+**نکته:** تنظیمات به صورت کدشده Base64 ارسال می‌شود. فرمت قبل از کدگذاری: `{DeviceName}|{UploadIntervalMin}`
+
+#### پاسخ خطا
+
+```json
+{
+  "success": false,
+  "message": "کد تایید نادرست است",
+  "encodedSettings": null
+}
+```
+
+---
+
+### 4. بروزرسانی تنظیمات دستگاه
+
+**PUT** `/api/DeviceSettings`
+
+API موجود که حالا فیلدهای جدید را نیز پشتیبانی می‌کند.
+
+#### بدنه درخواست (JSON)
+
+```json
+{
+  "id": 1,
+  "deviceId": 1,
+  "province": "تهران",
+  "city": "تهران",
+  "productType": "گلخانه",
+  "uploadIntervalMin": 5,
+  "devicePhoneNumber": "09123456789",
+  "simCardType": 1,
+  "minimumSmsIntervalMinutes": 15,
+  "minimumCallIntervalMinutes": 60
+}
+```
+
+## فلوی کاری (Workflow)
+
+### سناریو: دریافت تنظیمات دستگاه
+
+1. **دستگاه درخواست توکن می‌کند:**
+   ```http
+   POST /api/DeviceToken/request-token
+   Body: { "devicePhoneNumber": "09123456789" }
+   ```
+
+2. **سرور کد توکن تولید و ارسال می‌کند:**
+   - کد توکن 5 رقمی: مثلاً `12345`
+   - کد تایید محاسبه شده: `(12345 × 7 + 12345) % 100000 = 98760`
+   - پیامک حاوی کد توکن به شماره دستگاه ارسال می‌شود
+
+3. **دستگاه کد تایید را محاسبه و ارسال می‌کند:**
+   ```http
+   POST /api/DeviceToken/verify-token
+   Body: {
+     "devicePhoneNumber": "09123456789",
+     "verificationCode": "98760"
+   }
+   ```
+
+4. **سرور تنظیمات کدشده را ارسال می‌کند:**
+   - تنظیمات: `Device01|5`
+   - Base64: `RGV2aWNlMDF8NQ==`
+   - پیامک حاوی تنظیمات کدشده به شماره دستگاه ارسال می‌شود
+
+5. **دستگاه تنظیمات را decode کرده و اعمال می‌کند**
+
+## نکات امنیتی
+
+1. کد توکن فقط 10 دقیقه اعتبار دارد
+2. پس از تایید موفق، کدهای توکن و تایید از دیتابیس پاک می‌شوند
+3. کدگذاری Base64 یک کدگذاری ساده است و برای امنیت بیشتر می‌توان از روش‌های پیچیده‌تر استفاده کرد
+
+## Migration
+
+Migration با نام `AddDeviceTokenAndPhoneFields` ایجاد و به دیتابیس اعمال شده است.
+
+برای اعمال دستی (در صورت نیاز):
+
+```bash
+dotnet ef database update --project GreenHome.Infrastructure --startup-project GreenHome.Api
+```
+
+## تست API ها
+
+می‌توانید از Swagger UI (که در حالت Development در `/scalar/v1` در دسترس است) برای تست API ها استفاده کنید.
+
+یا از ابزارهایی مانند Postman/Insomnia با استفاده از نمونه‌های بالا.
+