GreenHomeBack/src/DEVICE_TOKEN_API.md

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 نوع سیم‌کارت

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): شماره تلفن دستگاه

نکته: حداقل یکی از پارامترها باید ارسال شود.

مثال درخواست

GET /api/DeviceToken/upload-interval?devicePhoneNumber=09123456789

پاسخ موفق

{
  "success": true,
  "message": null,
  "uploadIntervalMin": 5
}

پاسخ خطا

{
  "success": false,
  "message": "دستگاه یافت نشد",
  "uploadIntervalMin": null
}

---

2. درخواست توکن دستگاه

POST /api/DeviceToken/request-token

تولید کد توکن 5 رقمی و ارسال آن از طریق پیامک به شماره دستگاه.

بدنه درخواست (JSON)

{
  "devicePhoneNumber": "09123456789"
}

مثال درخواست

POST /api/DeviceToken/request-token
Content-Type: application/json

{
  "devicePhoneNumber": "09123456789"
}

پاسخ موفق

{
  "success": true,
  "message": "کد تایید با موفقیت ارسال شد",
  "tokenCode": "12345"
}

نکته: پیامک حاوی کد توکن به شماره مشخص شده ارسال می‌شود. کد دارای اعتبار 10 دقیقه است.

محاسبه کد تایید

کد تایید بر اساس فرمول زیر محاسبه می‌شود:

VerificationCode = (TokenCode × 7 + 12345) % 100000

---

3. تایید توکن دستگاه

POST /api/DeviceToken/verify-token

تایید کد تایید و ارسال تنظیمات کدشده دستگاه از طریق پیامک.

بدنه درخواست (JSON)

{
  "devicePhoneNumber": "09123456789",
  "verificationCode": "98765"
}

مثال درخواست

POST /api/DeviceToken/verify-token
Content-Type: application/json

{
  "devicePhoneNumber": "09123456789",
  "verificationCode": "98765"
}

پاسخ موفق

{
  "success": true,
  "message": "تنظیمات با موفقیت ارسال شد",
  "encodedSettings": "RGV2aWNlMDF8NQ=="
}

نکته: تنظیمات به صورت کدشده Base64 ارسال می‌شود. فرمت قبل از کدگذاری: {DeviceName}|{UploadIntervalMin}

پاسخ خطا

{
  "success": false,
  "message": "کد تایید نادرست است",
  "encodedSettings": null
}

---

4. بروزرسانی تنظیمات دستگاه

PUT /api/DeviceSettings

API موجود که حالا فیلدهای جدید را نیز پشتیبانی می‌کند.

بدنه درخواست (JSON)

{
  "id": 1,
  "deviceId": 1,
  "province": "تهران",
  "city": "تهران",
  "productType": "گلخانه",
  "uploadIntervalMin": 5,
  "devicePhoneNumber": "09123456789",
  "simCardType": 1,
  "minimumSmsIntervalMinutes": 15,
  "minimumCallIntervalMinutes": 60
}

فلوی کاری (Workflow)

سناریو: دریافت تنظیمات دستگاه

1. دستگاه درخواست توکن می‌کند:

   POST /api/DeviceToken/request-token
   Body: { "devicePhoneNumber": "09123456789" }
   

2. سرور کد توکن تولید و ارسال می‌کند:

   • کد توکن 5 رقمی: مثلاً 12345
   • کد تایید محاسبه شده: (12345 × 7 + 12345) % 100000 = 98760
   • پیامک حاوی کد توکن به شماره دستگاه ارسال می‌شود

3. دستگاه کد تایید را محاسبه و ارسال می‌کند:

   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 ایجاد و به دیتابیس اعمال شده است.

برای اعمال دستی (در صورت نیاز):

dotnet ef database update --project GreenHome.Infrastructure --startup-project GreenHome.Api

تست API ها

می‌توانید از Swagger UI (که در حالت Development در /scalar/v1 در دسترس است) برای تست API ها استفاده کنید.

یا از ابزارهایی مانند Postman/Insomnia با استفاده از نمونه‌های بالا.