# فصل ۰۶ — یک وب‌اپِ کوچکِ هوش‌مصنوعی‌دار

<div dir="rtl">

# فصل ۰۶ — یک وب‌اپِ کوچکِ هوش‌مصنوعی‌دار

## در این فصل چه یاد می‌گیری

این فصل قلبِ ترم است. هیچ مفهومِ تازه‌ای از `API` یاد نمی‌گیری؛ همه‌چیزی را که در فصل‌های ۳ تا ۵ ساختی برمی‌داری و به یک ابزارِ واقعیِ کامل تبدیل می‌کنی: `دستیارِ من`. تفاوتِ یک تمرین با یک ابزارِ واقعی در مسیرهای **بدِ** کار است — وقتی کاربر دکمه را خالی می‌زند، وقتی اینترنت قطع است، وقتی کلید غلط است، وقتی جواب دارد می‌آید و هنوز نرسیده. ابزارِ خوب در هر کدام از این حالت‌ها به کاربر می‌گوید چه خبر است، به‌جای اینکه ساکت بماند یا بشکند.

![یک دستگاهِ جمع‌وجورِ رومیزی به‌صورتِ برش‌خورده: یک قیفِ ورودی، یک چراغِ وضعیت که نشان می‌دهد کار در جریان است، و یک سینیِ خروجی که جواب روی آن می‌نشیند](/lesson-assets/t5-s06-build-app/prompt/01-image-assistant-device.png)

آخر این فصل می‌توانی:

- چهار حالتِ یک ابزار را بشناسی و مدیریت کنی: ورودیِ خالی، انتظار، جوابِ موفق، خطا
- دکمه را وقتِ کار غیرفعال کنی تا کاربر دو بار پشتِ‌هم درخواست نفرستد
- با `try`/`catch` و چکِ `res.ok` خطاها را به پیامِ دوستانه تبدیل کنی
- کلِ اپِ `BYOK` را با هر سه فایلش سرِ هم و اجرا کنی

## قبل از شروع

- **از فصل ۳:** اپِ پایه — کلید، سؤال، دکمه، و نمایشِ جواب.
- **از فصل ۴:** `system_instruction` در بدنهٔ درخواست.
- **از ترم ۷ تاروپود (پیش‌نیاز):** `try`/`catch` برای قطعیِ شبکه و چکِ `res.ok` برای جوابِ ناسالمِ سرور.

مثلِ همیشه فقط یک مرورگر و کلیدِ رایگانِ خودت لازم داری. یادت باشد کلید از `<input type="password">` خوانده می‌شود و **هرگز داخلِ کدِ منتشرشده نمی‌رود**.

> 🧪 **آزمایشگاه:** [آزمایشگاه این فصل را باز کن](/lab/embed/hamhoosh/term-5-building/session-06-build-app) — اپِ کامل را سرِ هم کن و بعد عمداً هر حالتِ بد را بساز: دکمه را خالی بزن، کلید را غلط بگذار، اینترنت را قطع کن، و ببین هر بار چه پیامی می‌گیری.

## ۱. یک اپ فقط مسیرِ خوش نیست

در فصل‌های قبل کدِ ما فرض می‌کرد همه‌چیز درست پیش می‌رود: کلید هست، سؤال هست، اینترنت وصل است، سرور جواب می‌دهد. این «مسیرِ خوش» است. ولی کاربرِ واقعی گاهی دکمه را بدونِ نوشتنِ چیزی می‌زند؛ گاهی کلید را اشتباه می‌چسباند؛ گاهی وسطِ کار وای‌فای می‌پرد. اگر برنامه برای این‌ها آماده نباشد، یا هیچ واکنشی نشان نمی‌دهد و کاربر گیج می‌ماند، یا با یک خطای قرمز در `console` می‌شکند که کاربر اصلاً نمی‌بیندش.

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

## ۲. نگهبانِ ورودی، حالتِ انتظار، و دکمهٔ غیرفعال

قبل از اینکه اصلاً درخواستی بفرستیم، دو چیز را چک می‌کنیم و دو حالت را روشن می‌کنیم:

</div>

```js
  answer.textContent = "";
  if (key === "" || prompt === "") {
    status.textContent = "کلید و سؤال را بگذار.";
    return;
  }
  status.textContent = "در حالِ فکر کردن…";
  askBtn.disabled = true;
```

<div dir="rtl">

اول جوابِ قبلی را پاک می‌کنیم تا کاربر جوابِ کهنه را اشتباه نگیرد. بعد اگر کلید یا سؤال خالی بود، یک پیامِ کوتاه می‌دهیم و با `return` همان‌جا می‌ایستیم — بی‌فایده است که یک درخواستِ خالی به سرور بفرستیم. اگر همه‌چیز سرِ جایش بود، حالتِ **انتظار** را روشن می‌کنیم («در حالِ فکر کردن…») و دکمه را با `askBtn.disabled = true` **غیرفعال** می‌کنیم. این دومی مهم است: بدونش کاربرِ بی‌حوصله چند بار پشتِ‌هم دکمه را می‌زند و چند درخواستِ موازی می‌فرستد که هم گیج‌کننده است و هم سهمیه‌ات را زودتر تمام می‌کند.

> 💡 **نکته:** «در حالِ فکر کردن…» فقط ادب نیست؛ کاربردی است. بینِ زدنِ دکمه و رسیدنِ جواب یک لحظهٔ خالی هست، و اگر صفحه هیچ نشانه‌ای ندهد، کاربر فکر می‌کند دکمه خراب است و دوباره می‌زند. یک خطِ کوتاه این را حل می‌کند.

## ۳. مسیرِ خطا: try/catch و res.ok

حالا درخواست را داخلِ یک `try` می‌گذاریم تا اگر اینترنت قطع بود و `fetch` ترکید، به‌جای شکستنِ برنامه به `catch` برویم. و وقتی جواب آمد، قبل از خواندنش سلامتش را می‌سنجیم:

</div>

```js
    if (res.status === 429) {
      status.textContent = "سهمیهٔ الان تمام شد؛ کمی بعد دوباره امتحان کن.";
      return;
    }
    if (!res.ok) {
      status.textContent = "خطا از سرور: " + res.status;
      return;
    }
```

<div dir="rtl">

خطِ اولْ یک حالتِ خاص را می‌گیرد: کدِ `429`، وقتی سرور موقتاً می‌گوید «الان زیادی پرسیدی، کمی صبر کن». فعلاً همین‌قدر بدان؛ چراییِ کامل و مدیریتِ سهمیه را **فصل بعد** باز می‌کنیم. خطِ دوم با `res.ok` — همان که در تاروپود دیدی — هر جوابِ ناسالمِ دیگر را می‌گیرد (مثلاً کلیدِ غلط) و به‌جای ترکیدن، شمارهٔ خطا را نشان می‌دهد.

و در پایانِ کار، چه موفق چه ناموفق، دکمه را دوباره فعال می‌کنیم. جایش در `finally` است، چون `finally` **در هر صورت** اجرا می‌شود — حتی اگر وسطِ راه با `return` بیرون زده باشیم:

</div>

```js
  } catch (e) {
    status.textContent = "در اینترنت یا کلیدت مشکلی هست؛ دوباره امتحان کن.";
  } finally {
    askBtn.disabled = false;
  }
```

<div dir="rtl">

اگر دکمه را در `finally` فعال نکنی، یک اشتباهِ کوچک کلِ ابزار را از کار می‌اندازد: یک‌بار که اینترنت بپرد، دکمه برای همیشه غیرفعال می‌ماند و کاربر مجبور می‌شود صفحه را از نو بارگذاری کند.

## ۴. اپِ کامل: هر سه فایل

حالا همه‌چیز کنارِ هم. این `script.js`ِ نهایی است. یک فرق با فصل ۴ دارد: `generationConfig` را برداشته‌ایم، چون `temperature` روی مدل‌های تازه نادیده گرفته می‌شود و ممکن است روزی با خطا رد شود، و اپی که قرار است بماند نباید به چنین چیزی تکیه کند:

</div>

```js
// script.js
// modelِ رایگان — dar zaman-e khandan az mostanadat-e Gemini check kon:
const MODEL = "gemini-flash-latest";
const URL = "https://generativelanguage.googleapis.com/v1beta/models/" + MODEL + ":generateContent";

const askBtn = document.querySelector("#ask");

askBtn.addEventListener("click", async function () {
  const key = document.querySelector("#key").value.trim();
  const prompt = document.querySelector("#prompt").value.trim();
  const status = document.querySelector("#status");
  const answer = document.querySelector("#answer");

  answer.textContent = "";
  if (key === "" || prompt === "") {
    status.textContent = "کلید و سؤال را بگذار.";
    return;
  }
  status.textContent = "در حالِ فکر کردن…";
  askBtn.disabled = true;

  try {
    const res = await fetch(URL + "?key=" + key, {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        system_instruction: {
          parts: [{ text: "تو یک دستیارِ فارسی، دقیق و کوتاه‌گو هستی." }]
        },
        contents: [{ parts: [{ text: prompt }] }]
      })
    });

    if (res.status === 429) {
      status.textContent = "سهمیهٔ الان تمام شد؛ کمی بعد دوباره امتحان کن.";
      return;
    }
    if (!res.ok) {
      status.textContent = "خطا از سرور: " + res.status;
      return;
    }

    const data = await res.json();
    const text = data.candidates[0].content.parts[0].text;
    status.textContent = "";
    answer.textContent = text;
  } catch (e) {
    status.textContent = "در اینترنت یا کلیدت مشکلی هست؛ دوباره امتحان کن.";
  } finally {
    askBtn.disabled = false;
  }
});
```

<div dir="rtl">

این `index.html`:

</div>

```html
<!DOCTYPE html>
<html lang="fa" dir="rtl">
  <head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <title>دستیارِ من</title>
    <link rel="stylesheet" href="styles.css">
  </head>
  <body>
    <main>
      <h1>دستیارِ من</h1>
      <p class="hint">کلیدِ Gemini خودت را بگذار، بعد بپرس.</p>
      <input type="password" id="key" placeholder="کلیدِ API خودت — روی کامپیوترِ خودت می‌ماند">
      <textarea id="prompt" placeholder="سؤالت را اینجا بنویس"></textarea>
      <button id="ask">بپرس</button>
      <p id="status" class="status"></p>
      <div id="answer" class="answer"></div>
    </main>
    <script src="script.js"></script>
  </body>
</html>
```

<div dir="rtl">

و این `styles.css`:

</div>

```css
/* styles.css */
body { font-family: Vazirmatn, Tahoma, sans-serif; background: #0f1413; color: #e9ede9; }
main { max-width: 640px; margin: 2rem auto; padding: 0 1rem; }
h1 { color: #2fc6ce; }
input, textarea { width: 100%; margin: 0.5rem 0; padding: 0.7rem; box-sizing: border-box;
  background: #151b19; color: #e9ede9; border: 1px solid #253029; border-radius: 8px; }
textarea { min-height: 8rem; }
button { background: #2fc6ce; color: #06130b; border: 0; padding: 0.7rem 1.4rem;
  border-radius: 8px; font-size: 1rem; cursor: pointer; }
button:disabled { opacity: 0.6; }
.status { color: #98a49e; }
.answer { white-space: pre-wrap; margin-top: 1rem; padding: 1rem;
  background: #151b19; border-radius: 8px; min-height: 2rem; }
```

<div dir="rtl">

به دو تکهٔ کوچکِ استایل دقت کن که مستقیم به حالت‌ها وصل‌اند: `button:disabled { opacity: 0.6; }` دکمهٔ غیرفعال را کم‌رنگ نشان می‌دهد تا کاربر ببیند الان نمی‌شود زد، و `white-space: pre-wrap` روی `.answer` باعث می‌شود خط‌شکن‌های جوابِ مدل حفظ شوند.

> ✅ **چک کن:** هر چهار حالت را یکی‌یکی امتحان کن. (۱) دکمه را با کادرِ خالی بزن → «کلید و سؤال را بگذار». (۲) کلید و سؤال بگذار و بزن → «در حالِ فکر کردن…» و بعد جواب. (۳) وسطِ کار به دکمهٔ غیرفعالِ کم‌رنگ نگاه کن. (۴) اینترنت را قطع کن و بزن → پیامِ دوستانهٔ `catch`. اگر هر چهار درست بود، ابزارت واقعاً کامل است.

> 🔧 **اگر جواب نگرفتی:** اگر «خطا از سرور: 400» گرفتی، تقریباً همیشه یعنی کلید غلط است یا بدنهٔ `JSON` خراب است — کلید را دوباره کپی کن و مطمئن شو ساختارِ `body` را دست‌نخورده گذاشته‌ای. اگر پیامِ `catch` را بی‌دلیل می‌گیری، احتمالاً اینترنت یا فیلترِ شبکه جلوی درخواست را گرفته. جدولِ پایین بقیهٔ کدها را می‌گوید.

</div>

| چیزی که روی صفحه می‌بینی | معنایش |
|---|---|
| `خطا از سرور: 400` | کلیدِ غلط یا بدنهٔ خراب |
| `خطا از سرور: 403` | کلید اجازه ندارد؛ مثلاً لو رفته و مسدود شده. یک کلیدِ تازه بساز |
| `خطا از سرور: 404` | نامِ مدل در ثابتِ `MODEL` دیگر معتبر نیست؛ فهرستِ مدل‌ها را چک کن |
| `خطا از سرور: 503` | سرویس موقتاً شلوغ است؛ کمی بعد دوباره بفرست |

<div dir="rtl">

یک نکته دربارهٔ پیامِ `catch`: با اینکه می‌گوید «اینترنت یا کلید»، کلیدِ غلط هرگز به آن نمی‌رسد، چون کدِ `400` همان `!res.ok` را فعال می‌کند. این پیام وقتی می‌آید که چیزی داخلِ `try` بترکد. یعنی یا اصلاً جوابی نیامده، یا جواب آمده ولی `candidates[0].content.parts[0].text` در آن نیست. حالتِ دوم نادر است، ولی واقعی است: مثلاً مدل به‌خاطرِ قواعدِ ایمنی جواب نداده باشد. اگر می‌خواهی پیامت دقیق‌تر باشد، متنش را به «جوابی نرسید؛ اینترنت را چک کن و دوباره امتحان کن» عوض کن.

## ۵. یک ابزارِ صیقلی، هنوز یک ماشینِ حدس

حالا اپت تر و تمیز به‌نظر می‌رسد: پیام‌های مرتب، دکمهٔ هوشمند، و جوابی که با اطمینان روی صفحه می‌نشیند. ولی مواظبِ یک تله باش: **صیقلی‌بودنِ ظاهر، درستیِ محتوا را تضمین نمی‌کند.** همان مدل با همان `system_instruction`، پشتِ این رابطِ تمیز، هنوز کلمه‌به‌کلمه حدس می‌زند و می‌تواند مطمئن ولی غلط جواب بدهد.

> ✅ **وارسی:** یک رابطِ حرفه‌ای به جوابِ مدل **اعتبارِ ظاهری** می‌دهد که لزوماً حقش نیست. برای هر جوابی که یک ادعای واقعی دارد، همان عادتِ همیشگی: با یک منبعِ مستقل بسنج، نه با خودِ ابزار. سه قانونِ ثابتِ این دوره: **«اول خودت فکر کن» — «وارسی کن، خط به خط» — «مدل مطمئن است؛ دلیل نمی‌شود درست باشد».**

> ⚠️ **مواظب باش:** این ابزار `BYOK` است — کلید از کادرِ رمز خوانده می‌شود و در کد نیست. همین‌طور نگهش دار: هیچ‌وقت کلید را داخلِ `script.js` ننویس، وگرنه با انتشارِ صفحه هر بازدیدکننده‌ای می‌تواند بخواندش. و یادت باشد ردهٔ رایگان ممکن است پرامپت و جوابت را برای آموزش استفاده کند؛ پس دادهٔ خصوصی به این ابزار نده.

## تمرین‌ها

**تمرین اجباری:** هر چهار حالت را عمداً بساز و بنویس در هر کدام دقیقاً چه پیامی دیدی: (۱) دکمه با کادرِ خالی، (۲) یک سؤالِ سالم، (۳) کلیدِ غلط، (۴) اینترنتِ قطع. بعد یک آزمایشِ آموزنده: خطِ `askBtn.disabled = false;` را از `finally` بردار، یک‌بار اینترنت را قطع کن و دکمه را بزن، و ببین چطور دکمه برای همیشه غیرفعال می‌ماند. بعد برش گردان — حالا می‌فهمی چرا `finally` آنجاست.

**تمرین ستاره‌دار ⭐:** به دستیارت یک نقشِ کاملاً متفاوت بده — مثلاً «تو یک راهنمای سفر هستی» — و یک سؤالِ **واقعی‌محور** بپرس که جوابش یک نام یا عددِ مشخص است. جوابِ صیقلی‌ای را که در رابطِ تمیز می‌بینی با یک منبعِ مستقل تطبیق بده و در یک جمله بنویس: آیا زیبابودنِ ظاهرِ ابزار باعث شد یک لحظه بی‌آنکه وارسی کنی باورش کنی؟

## در فصل بعد

ابزارت کار می‌کند و در برابرِ خطاها محکم است. ولی یک خطِ کوچک در کد بود که رویش سریع گذشتیم — همان `res.status === 429`. فصل بعد سراغِ **هزینه، سهمیه و مرزها** می‌رویم: می‌فهمی چرا سرور گاهی می‌گوید «کمی صبر کن»، چطور با سهمیه مهربان باشی، و چرا این‌که کلید مالِ خودِ کاربر است، هم یک تصمیمِ اخلاقی است و هم یک تصمیمِ عملی دربارهٔ هزینه.

</div>

---
Source: https://yaadestan.com/courses/hamhoosh/lessons/t5/s06-build-app (یادستان, Yaadestan)
