ما الذي ينشئه هذا الشرح العملي المتحقق منه؟

ينشئ هذا الشرح تطبيقاً صغيراً لسير عمل الدعم باستخدام Next.js وReact. يمكن لموظف الدعم إدخال رسالة عميل، واختيار فئة الدعم، وتحديد أسلوب الرد، ثم إرسال الطلب إلى مسار على الخادم ومراجعة النتيجة الموحّدة. ويظل المشروع المكتمل مفيداً عن قصد، من دون الادعاء بأن نموذجاً لغوياً متصل به حين لا يكون عقد المزوّد قد تم التحقق منه.

يدعم السياق المتحقق منه استخدام Next.js بوصفه إطار React لبناء تطبيقات ويب حديثة. ويشمل قدرات مثل App Router والعرض من جهة الخادم والتوليد الثابت ومسارات API ودعم TypeScript وتحسين الصور. يستخدم هذا الدليل App Router ومعالج المسار لأنهما يوفران فصلاً واضحاً بين واجهة تفاعلية في المتصفح ومنطق التطبيق على الخادم.

يصف السياق المتحقق منه حول OpenAI أيضاً مثالاً من OpenAI DevDay، جرى فيه ربط خادم FastAPI بواجهة Next.js أمامية. ويحمل هذا المثال درساً معمارياً مهماً: إذ يمكن لواجهة Next.js العمل مع خدمة Backend مخصصة. لكنه لا يتحقق من SDK JavaScript محدد من OpenAI، أو اسم نموذج، أو endpoint، أو parameter، أو schema للاستجابة، أو سعر، أو حصة استخدام. ولهذا السبب، ينشئ هذا المقال حدود تكامل موثوقة بدلاً من نشر كود غير متحقق منه خاص بالمزوّد.

والنتيجة هي أساس لمنتج دعم: نموذج في المتصفح، وعقد طلبات مكتوب الأنواع، ومسار على الخادم، وبنية استجابة متوقعة، ولوحة مراجعة. وبعد أن تتحقق مؤسستك من وثائق OpenAI API الحالية ومتطلبات التعامل مع بيانات العملاء لديها، يمكن استبدال مسار العينة بمحوّل من جهة الخادم يستدعي خدمة المزوّد المعتمدة.

المتطلبات المسبقة

• تثبيت حديث لإصدار Node.js LTS وnpm.
• إلمام أساسي بمكوّنات React وTypeScript وسطر الأوامر.
• مشروع Next.js جديد أُنشئ مع تفعيل TypeScript وApp Router.
• محرر كود قادر على تحرير ملفات TypeScript وTSX.
• رسائل دعم تجريبية غير حساسة للاختبار المحلي.

لا تستخدم كلمات مرور حقيقية أو رموز وصول أو بيانات بطاقات دفع أو سجلات عملاء سرية في عرض توضيحي محلي. يعالج هذا الشرح نصوصاً تجريبية فقط. يحتاج سير عمل الدعم في بيئة الإنتاج إلى عمليات معتمدة خاصة به للتعامل مع البيانات والاحتفاظ بها والتحكم في الوصول والمراجعة.

الخطوة ١: إنشاء مشروع Next.js

أنشئ تطبيقاً جديداً باستخدام مولّد مشاريع Next.js الحالي. اختر TypeScript وApp Router عند ظهور المطالبات. قد تتغير مطالبات المولّد الدقيقة بين الإصدارات، لذا راجعها قبل تأكيد اختياراتك.

npx create-next-app@latest nextjs-support-workflow
cd nextjs-support-workflow
npm run dev

افتح http://localhost:3000 بعد تشغيل خادم التطوير. يوفر Next.js بنية تطبيق قائمة على الملفات. في هذا الشرح، تُعرض الصفحة الرئيسية من src/app/page.tsx، بينما يُنفذ endpoint الخادم في src/app/api/support-request/route.ts.

حافظ على نطاق التطبيق الأولي محدوداً. لا تحتاج واجهة الدعم إلى مصادقة، أو قاعدة بيانات للعملاء، أو مزود AI، أو تكامل CRM، أو إرسال تلقائي من أجل التحقق من سير العمل الأول. ابدأ بجعل تجربة الطلب والمراجعة واضحة، ثم أضف قدرات اختُبرت بشكل مستقل واحدة تلو الأخرى.

الخطوة ٢: تحديد عقد دعم مشترك

تستفيد واجهة الدعم من عقد مستقر بين المتصفح والخادم. يوفر TypeScript ملاحظات أثناء وقت الترجمة، لكن معالج المسار ما زال يتحقق من القيم الواردة وقت التشغيل. المتصفح ليس نقطة فرض موثوقة: إذ يمكن للمستخدم تعديل قيم النموذج أو إرسال طلب مباشرة إلى المسار.

أنشئ src/lib/support.ts:

export const productAreas = [
  "Billing",
  "Account access",
  "Technical issue",
  "General question",
] as const;

export const tones = ["Warm", "Concise", "Formal"] as const;

export type ProductArea = (typeof productAreas)[number];
export type Tone = (typeof tones)[number];

export type SupportRequest = {
  ticket: string;
  productArea: ProductArea;
  tone: Tone;
};

export type SupportReview = {
  received: boolean;
  ticketLength: number;
  productArea: ProductArea;
  tone: Tone;
  nextStep: string;
};

export function isProductArea(value: unknown): value is ProductArea {
  return typeof value === "string" && productAreas.includes(value as ProductArea);
}

export function isTone(value: unknown): value is Tone {
  return typeof value === "string" && tones.includes(value as Tone);
}

export function parseSupportRequest(value: unknown): SupportRequest | null {
  if (!value || typeof value !== "object") return null;

  const input = value as Record<string, unknown>;
  const ticket = typeof input.ticket === "string" ? input.ticket.trim() : "";

  if (ticket.length < 20 || ticket.length > 8000) return null;
  if (!isProductArea(input.productArea) || !isTone(input.tone)) return null;

  return { ticket, productArea: input.productArea, tone: input.tone };
}

يوفّر هذا الموديول للنموذج ومعالج المسار مفردات مشتركة. يتضمن الطلب نص التذكرة وفئة محدودة وخياراً محدوداً للنبرة. أما الاستجابة فهي تشغيلية عمداً وليست مولّدة بالـAI: فهي تؤكد الاستلام، وتسجل طول النص، وتكرر الخيارات المحددة، وتوفر رسالة بالخطوة التالية. وهذا يجعل التطبيق قابلاً للاختبار من دون تقديم محتوى محاكى على أنه إجابة من AI.

يمثل النطاق من ٢٠ إلى ٨٬٠٠٠ حرف قراراً خاصاً بالمنتج في هذه العينة، وليس حداً من OpenAI. عدّله بعد تقييم أنواع الرسائل التي يتلقاها فريق الدعم لديك وقيود أي خدمة Backend معتمدة.

الخطوة ٣: إضافة معالج مسار الخادم

توفر معالجات المسارات حدود HTTP من جهة الخادم في مشروع App Router. أنشئ src/app/api/support-request/route.ts:

import { NextRequest } from "next/server";
import {
parseSupportRequest,
type SupportReview,
} from "@/lib/support";export async function POST(request: NextRequest) {
let body: unknown;try {
body = await request.json();
} catch {
return Response.json(
{ error: "Send a valid JSON request body." },
{ status: 400 },
);
}const input = parseSupportRequest(body);if (!input) {
return Response.json(
{
error:
"Enter 20 to 8,000 characters and select a supported product area and tone.",
},
{ status: 400 },
);
}const review: SupportReview = {
...
تابع القراءة
سجل دخولك مجاناً لقراءة المقال كاملاً والوصول إلى أدوات الذكاء الاصطناعي.
تسجيل الدخول / إنشاء حساب