# مشخصات درس‌نامه: ساخت اپلیکیشن موبایل اندروید و iOS؛ مقایسه و اجرای عملی با Capacitor و Expo
- **شناسه در سیلابس:** `L15.11`
- **فصل:** فصل ۱۵: تکامل محصول با AI (Ch 15)
- **نوع محتوا:** 📘 درس‌نامه متنی
- **زمان تقریبی مطالعه:** ۲۲ دقیقه
- **پیش‌نیازهای مستقیم:** `L15.10` (تبدیل وب‌سایت به وب‌اپلیکیشن پیش‌رونده PWA)

---

## ۱. اهداف یادگیری (Learning Objectives - Bloom's Taxonomy)
دانشجو پس از مطالعهٔ این درس‌نامه باید بتواند:
- [ ] **درک کند (Understand):** دو رویکرد بنیادین ورود به دنیای موبایل را بشناسد: ۱) رویکرد پل بومی بدون بازنویسی با **Capacitor** و ۲) رویکرد فریم‌ورک نیتیو اختصاصی با **React Native / Expo**.
- [ ] **تحلیل/ارزیابی کند (Evaluate):** بده‌بستان‌های مهندسی (Trade-offs) میان کپسیتور (حداکثر اشتراک کد وب، سرعت راه‌اندازی فوق‌العاده) و اکسپو (عملکرد بومی ۶۰ فریم، تعامل عمیق با ژست‌های حرکتی و قطعات سخت‌افزاری) را مقایسه کند.
- [ ] **به‌کار ببندد (Apply):** پروژه Next.js پورتفولیو را با استفاده از قابلیت Static Export و Capacitor به یک پروژه اندروید با خروجی فایل نصبی APK تبدیل نماید.
- [ ] **ایجاد کند (Create):** با کمک ایجنت، یک کامپوننت وب واکنش‌گرا را به کدهای سازگار با المان‌های نیتیو Expo (`<View>`, `<Text>`) تبدیل کرده و آن را در اپلیکیشن موبایل Expo Go اجرا کند.

---

## ۲. محدوده و مرزهای محتوا (Scope & Boundaries)

### آنچه باید پوشش داده شود (In-Scope):
1. **انقلاب موبایل برای وب‌سازها: خروج از حصار مرورگر:**
   * چرا داشتن فایل نصبی اندروید (`.apk`) برای معرفی به کارفرما، پرستیژ حرفه‌ای شما را به اوج می‌رساند؟
2. **مسیر اول: جادوی Capacitor (تبدیل مستقیم وب به موبایل در ۱۵ دقیقه):**
   * کپسیتور چگونه کار می‌کند؟ قرار دادن کدهای بهینه وب درون یک وب‌ویو فوق‌پایدار بومی به همراه پل ارتباطی به سنسورهای گوشی (دوربین، ویبره هپتیک، نوتیفیکیشن).
   * گام‌های عملی:
     - تنظیم `output: 'export'` در `next.config.js`.
     - اجرای بیلد استاتیک با `npm run build` (تولید پوشه `out`).
     - نصب بسته‌های رسمی: `npm install @capacitor/core @capacitor/cli @capacitor/android`.
     - اجرای دستورات `npx cap init` و `npx cap add android`.
     - همگام‌سازی با `npx cap sync` و باز کردن در Android Studio با `npx cap open android`.
     - گرفتن خروجی APK برای نصب روی گوشی واقعی.
3. **مسیر دوم: قدرت بومی React Native و Expo:**
   * چرا و چه زمانی سراغ Expo می‌رویم؟ وقتی که نیازمند کامپوننت‌های بومی سیستم‌عامل، ژست‌های لمسی پیچیده یا اپ‌های بسیار سنگین هستیم.
   * تفاوت المان‌های وب و موبایل: جایگزینی `<div>` با `<View>` و `<p>` با `<Text>`.
   * قدرت ایجنت‌ها در ترجمه سریع کامپوننت‌های وب به کامپوننت‌های Expo.
   * اجرای آنی اپلیکیشن روی گوشی با اسکن کد QR در برنامه Expo Go بدون نیاز به کابل.
4. **جدول مقایسه‌ای جامع: Capacitor در برابر Expo:**
   * مقایسه در ۶ بعد: زمان تا خروجی، میزان نیاز به بازنویسی، دسترسی به سخت‌افزار، پرفورمنس انیمیشن‌ها، اندازه فایل نهایی و منحنی یادگیری.
5. **دستورات چندسکویی برای نصب و کامندهای کپسیتور و اکسپو:**
   * دستورات در منوهای کشویی ویندوز، مک و لینوکس.
6. **کال‌اوت‌های آموزشی و هشدار کوئرا:**
   * کال‌اوت بنفش (`<details class="violet">`): پل ارتباطی کپسیتور (Capacitor Bridge) و نحوه ارسال پیام‌های JSON میان کدهای جاوااسکریپت و کدهای کاتلین/جاوا.
   * کال‌اوت سبز (`<details class="green">`): ارسال فایل APK پورتفولیو به دوستان در تلگرام و دیدن باز شدن اپلیکیشن روی گوشی آن‌ها درست مثل برنامه‌های کافه‌بازار!
   * کال‌اوت قرمز (`<details class="red">`): محدودیت خروجی استاتیک؛ در حالت کپسیتور نمی‌توانید از Server-Side Rendering درون گوشی استفاده کنید؛ تمام فراخوانی‌های دیتابیس باید به دامنه آنلاین پروداکشن ارسال شوند.

### آنچه نباید وارد آن شویم (Out-of-Scope):
- توسعه افزونه‌های اختصاصی C++ یا ماژول‌های Native Bridge سطح پایین با کاتلین خام.
- پرداخت‌های درون‌برنامه‌ای پیچیده کافه‌بازار و مایکت (در پروژه‌های تجاری بعدی).

---

## ۳. مفاهیم کلیدی و کلمات تخصصی (Key Concepts & Terms)

| اصطلاح انگلیسی | معادل فارسی مصوب | توضیح یک‌خطی ساده |
| :--- | :--- | :--- |
| Capacitor | موتور رابط کپسیتور | ابزار متن‌باز شرکت Ionic برای بسته‌بندی برنامه‌های وب در پوسته‌های بومی iOS و Android |
| React Native | فریم‌ورک ری‌اکت نیتیو | فریم‌ورک ساخت اپلیکیشن با کامپوننت‌های بومی واقعی سیستم‌عامل با زبان جاوااسکریپت |
| Expo | پلتفرم ابزاری اکسپو | اکوسیستم مدرن و سریع برای ساخت، اجرا و تست برنامه‌های React Native بدون نیاز به Android Studio |
| APK (Android Package) | بسته نصبی اندروید | فرمت فایل اجرایی استاندارد برای نصب برنامه‌ها روی سیستم‌عامل اندروید |
| Static Export | خروجی استاتیک وب | تبدیل برنامه به مجموعه‌ای از فایل‌های آماده HTML, JS, CSS بدون نیاز به اجرای سرور Node.js |
| Expo Go | اپلیکیشن تست اکسپو گو | برنامه موبایلی که به توسعه‌دهنده اجازه می‌دهد کدهای خود را با اسکن QR کد فوراً روی گوشی تست کند |

---

## ۴. جایگاه‌های تصاویر و نمودارها (Visual & Diagram Placeholders)
> **راهنمای ایجنت نویسنده:** تمام تصاویر باید در پوشهٔ `images/` ذخیره شده و در جدول تک‌خانه‌ای وسط‌چین درج شوند:

1. **تصویر کاور درس:** `images/cover.png`
   * **موضوع:** گوشی هوشمند نئونی با کابل اتصال که همزمان لوگوهای Capacitor و Expo از آن خارج شده و نشان‌دهنده دو مسیر است.
2. **کالبدشکافی نحوه کارکرد موتور Capacitor:** `images/capacitor-bridge-architecture.png`
   * **موضوع:** دیاگرام معماری: کدهای وب پورتفولیو $\rightarrow$ وب‌ویو بومی $\rightarrow$ پل کپسیتور $\rightarrow$ دسترسی به دوربین، فایل‌ها و شتاب‌سنج گوشی.
3. **فرآیند خروجی APK در محیط Android Studio:** `images/android-studio-build-apk.png`
   * **موضوع:** اسکرین‌شات از محیط اندروید استودیو با کلیک روی منوی Build Bundle/APK و نمایش نوتیفیکیشن موفقیت ساخت فایل `.apk`.
4. **اجرای اپلیکیشن در محیط Expo Go با اسکن QR:** `images/expo-go-qr-scan-flow.png`
   * **موضوع:** اینفوگرافیک: اجرای دستور ترمینال `npx expo start` $\rightarrow$ نمایش کد QR $\rightarrow$ اسکن با دوربین گوشی $\rightarrow$ باز شدن آنی اپلیکیشن نیتیو.

---

## ۵. بخش‌بندی و ساختار محتوایی پیشنهادی درس‌نامه (`README.md`)

1. **تیتر اصلی:** `# ساخت اپلیکیشن موبایل اندروید و iOS؛ مقایسه و اجرای عملی با Capacitor و Expo`
2. **مقدمه:** پورتفولیوی وب شما آماده است؛ اما چه حسی دارد اگر فایل نصبی اپلیکیشن موبایل خود را در رزومه بگذارید تا کارفرما آن را روی گوشی‌اش نصب کند؟
3. **جدول کاور درس**
4. **دو راهی بزرگ موبایل: کپسیتور (Capacitor) یا اکسپو (Expo)؟**
   * بررسی تفاوت‌های مفهومی؛ چرا هر دو مسیر باارزش هستند و کدام را کی انتخاب کنیم.
5. **کارگاه عملی مسیر اول: خروجی APK پورتفولیو با Capacitor در ۱۰ دقیقه:**
   * گام ۱: فعال‌سازی `output: 'export'` در `next.config.js`.
   * گام ۲: نصب پکیج‌های `@capacitor/core` و `@capacitor/android`.
   * گام ۳: همگام‌سازی و تولید پروژه اندروید با `npx cap add android`.
   * گام ۴: بیلد فایل APK در اندروید استودیو یا خط فرمان.
6. **کارگاه عملی مسیر دوم: دنیای نیتیو با React Native و Expo:**
   * ترجمه عناصر وب (`div`, `p`, `img`) به المان‌های نیتیو (`View`, `Text`, `Image`).
   * ساخت یک صفحه جدید موبایلی با Expo و تست لحظه‌ای با اپلیکیشن Expo Go.
7. **جدول مقایسه‌ای ماتریس تصمیم‌گیری: Capacitor vs Expo:**
   * مقایسه سرعت، حجم، عملکرد و پیچیدگی پیاده‌سازی.
8. **جعبه پرامپت طلایی: ترجمه کامپوننت‌های وب به کدهای موبایل Expo با ایجنت:**
   * پرامپت دقیق:
     > «من این کامپوننت کارت پروژه پورتفولیو را در Next.js دارم: [کد کامپوننت]. لطفاً آن را به یک کامپوننت کاملاً بومی سازگار با React Native و Expo تبدیل کن. تمام تگ‌های div و span را با View و Text جایگزین نما و استایل‌های Tailwind را به StyleSheet نیتیو ترجمه کن.»
9. **دستورات چندسکویی برای راه‌اندازی کپسیتور:**
   * منوی کشویی سه‌گانه برای ویندوز، مک و لینوکس:
     - Windows (PowerShell):
       ```powershell
       npm install @capacitor/core @capacitor/cli @capacitor/android
       npx cap init "Portfolio" "com.portfolio.app" --web-dir out
       npm run build
       npx cap add android
       npx cap copy
       ```
     - macOS (Terminal):
       ```bash
       npm install @capacitor/core @capacitor/cli @capacitor/android @capacitor/ios
       npx cap init "Portfolio" "com.portfolio.app" --web-dir out
       npm run build
       npx cap add android
       npx cap copy
       ```
     - Linux (Bash):
       ```bash
       npm install @capacitor/core @capacitor/cli @capacitor/android
       npx cap init "Portfolio" "com.portfolio.app" --web-dir out
       npm run build
       npx cap add android
       npx cap copy
       ```
10. **باکس نکته Quera (`<details class="violet">`):** اهمیت آدرس‌دهی مطلق (Absolute URLs) به APIهای پروداکشن در اپ موبایل کپسیتور به جای آدرس‌های نسبی (`/api/...`).
11. **باکس هشدار Quera (`<details class="red">`):** برای خروجی iOS به سیستم‌عامل macOS و نرم‌افزار Xcode نیاز دارید؛ اما خروجی اندروید روی ویندوز، مک و لینوکس به راحتی ساخته می‌شود.
12. **باکس رضایت‌بخش Quera (`<details class="green">`):** لمس آیکون اختصاصی اپلیکیشن روی گوشی و تجربه اسکرول نرم و پاسخ‌گویی سریع آن.
13. **جمع‌بندی درس‌نامه:** تسلط بر مهندسی موبایل؛ ورود به آخرین ایستگاه پلتفرم‌ها: بسته‌بندی نرم‌افزار دسکتاپ با Tauri و Electron در درس بعدی.

---

## ۶. معیارهای پذیرش (Acceptance Criteria for Reviewer)
- [ ] هر دو رویکرد Capacitor و Expo به همراه کاربرد و مزایای هرکدام تشریح گردند.
- [ ] گام‌های عملی تبدیل پروژه Next.js به پروژه اندروید کپسیتور به طور دقیق ارائه شود.
- [ ] جدول مقایسه‌ای ماتریس تفاوت‌های Capacitor و Expo در متن لحاظ گردد.
- [ ] پرامپت تبدیل کدهای وب به کدهای نیتیو React Native برای ایجنت آموزش داده شود.