راهنمای عیب‌یابی مشکلات حیاتی فلاتر در iOS، امنیت و PWA

در این مستند، دلایل و راه‌حل‌های مربوط به دو چالش بسیار مهم در توسعه فلاتر ثبت شده است:

۱. بسته شدن بی‌صدا و فوری اپلیکیشن در iOS (هنگام تست در TestFlight). ۲. مشکلات عدم کارکرد کلیک/لمس روی دکمه‌ها در محیط دسکتاپ و PWA.

---

۱. بسته شدن فوری و بدون خطای اپلیکیشن در TestFlight (iOS)

شرح مشکل: پس از بیلد گرفتن اپلیکیشن و انتشار آن در TestFlight، به محض کلیک روی آیکون برنامه، اپلیکیشن برای یک لحظه باز شده و بلافاصله (بدون هیچ لاگ یا خطایی) بسته می‌شود.

دلایل و راه‌حل‌ها:

الف) تداخل پکیج امنیتی Talsec (FreeRASP)

پکیج freerasp برای جلوگیری از دستکاری برنامه و هک شدن استفاده می‌شود. اگر امضای اپلیکیشن با مقادیر تنظیم شده مغایرت داشته باشد، برنامه بلافاصله دستور exit(0) را اجرا می‌کند.

• مشکل Team ID و Bundle ID: مقادیر TALSEC_TEAM_ID و TALSEC_BUNDLE_ID باید دقیقاً برابر با مقادیر اپ استور شما باشند. در غیر این صورت، این پکیج امضای برنامه را نامعتبر خوانده و آن را به عنوان یک «تهدید» می‌بندد.
• تشخیص TestFlight به عنوان فروشگاه غیرمجاز: اگر در تنظیمات TalsecConfig متغیر isProd برابر با true باشد، پکیج انتظار دارد برنامه فقط از App Store رسمی دانلود شده باشد. TestFlight از نظر این پکیج یک Unofficial Store است و باعث کرش برنامه می‌شود!

راه‌حل:

• همیشه شناسه‌های تیم و باندل را از طریق دستور بیلد پاس دهید: --dart-define=TALSEC_TEAM_ID=YOUR_TEAM_ID
• برای نسخه‌های POC یا TestFlight، مقدار isProd را false تنظیم کنید.
• (پیشنهاد): برای محیط TestFlight، دستور exit(0) را در کال‌بک onUnofficialStore غیرفعال کنید و فقط خطا را لاگ بگیرید تا از بسته شدن‌های کاذب جلوگیری شود.

ب) عدم مدیریت خطای لود متغیرهای محیطی (Env)

اگر در متد main فلاتر، پیش از اجرای runApp کدی اجرا شود که باعث پرتاب Exception شود (مثل پیدا نشدن فایل .env)، برنامه در iOS قبل از رندر شدن اولین فریم کاملاً کرش می‌کند.

• راه‌حل: همیشه متد dotenv.load را درون یک بلوک try/catch قرار دهید تا در صورت نبود فایل، به یک فایل پیش‌فرض (مثل .env-main) به صورت خودکار تغییر مسیر (Fallback) دهد.

ج) دسترسی‌های پس‌زمینه (Background Modes)

پکیج‌هایی مثل alarm و firebase_messaging در iOS نیازمند مجوز فعالیت در پس‌زمینه هستند. عدم وجود این مجوزها می‌تواند باعث متوقف شدن (Terminate) برنامه توسط سیستم‌عامل شود.

• راه‌حل: کلیدهای زیر را در فایل ios/Runner/Info.plist اضافه کنید:

COPY
<key>UIBackgroundModes</key>
<array>
    <string>audio</string>
    <string>fetch</string>
    <string>remote-notification</string>
</array>

---

۲. کار نکردن کلیک‌ها و مشکلات نمایشی در PWA و دسکتاپ

شرح مشکل: در صفحه وارد کردن PIN، دکمه‌های صفحه کلید عددی روی سیستم مک/وب کار نمی‌کنند و لمس اعداد در گوشی هیچ واکنشی ندارد. همچنین در نمایشگرهای بزرگتر (مثل PWA)، فقط ردیف اول اعداد (۱ تا ۳) دیده می‌شود و بقیه ناپدید می‌شوند!

دلایل و راه‌حل‌ها:

الف) سرریز شدن (Overflow) در GridView

استفاده از GridView با مشخصه childAspectRatio ثابت برای دکمه‌ها در یک صفحه واکنش‌گرا (Responsive) خطرناک است. در صفحات عریض (مثل دسکتاپ و PWA)، عرض GridView زیاد می‌شود و برای حفظ نسبت تصویر، ارتفاع هر دکمه هم به شدت افزایش می‌یابد. این باعث می‌شود ارتفاع کل کیبورد از ارتفاع صفحه نمایش بزرگتر شده و در اصطلاح Overflow رخ دهد.

• نکته مهم در iOS: وقتی یک ویجت دچار سرریز (Overflow) پنهان شود، سیستم‌عامل تشخیص لمس (Hit-Testing) آن ناحیه را متوقف می‌کند؛ بنابراین دکمه‌ها روی صفحه دیده می‌شوند اما هیچ لمسی را ثبت نمی‌کنند!
• راه‌حل: جایگزین کردن GridView با یک ساختار ساده‌تر و پایدارتر شامل یک Column و چند Row که ابعاد مشخص دارند (مثلاً عرض و ارتفاع ۷۲ پیکسل برای هر دکمه).

ب) مشکل Hit-Test Fallthrough در مک و مرورگر وب

در صفحات وب و دسکتاپ (که کاربر با موس کلیک می‌کند)، اگر از ترکیب Material و InkWell با پس‌زمینه Colors.transparent استفاده شود، نشانگر موس از فضای شفاف عبور کرده و کلیک‌ها ثبت نمی‌شوند (فقط کلیک دقیق روی خود پیکسل‌های متن ثبت می‌شود).

• راه‌حل نهایی: به جای اختراع مجدد دکمه با InkWell و Container، همیشه از ویجت‌های استاندارد فلاتر مثل TextButton استفاده کنید. این ویجت‌ها ذاتاً دارای Hit-Testing بهینه‌شده برای پلتفرم‌های دسکتاپ/وب هستند و حالت‌های Hover و Focus موس را بدون باگ و به زیبایی کنترل می‌کنند.