# راهنمای عیب‌یابی مشکلات حیاتی فلاتر در 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` اضافه کنید: ```xml UIBackgroundModes audio fetch remote-notification ``` --- ## ۲. کار نکردن کلیک‌ها و مشکلات نمایشی در 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 موس را بدون باگ و به زیبایی کنترل می‌کنند.

Orchestration