Yusuf Khalidd

Posted on Mar 19 • Originally published at apidog.com

كيفية إعداد 5 وكلاء ذكاء اصطناعي لبناء واجهة برمجة تطبيقات كاملة (من المواصفات إلى الاختبار)

#agents #ai #api #tutorial

توقف عن استخدام مساعد ذكاء اصطناعي عام واحد لكل شيء. بدلاً من ذلك، قم بإعداد 5 وكلاء متخصصين لبناء واجهة برمجة تطبيقات (API) متكاملة: مهندس الواجهة الخلفية لتصميم النظام، محسن قاعدة البيانات لمراجعة المخطط، مطور الواجهة الأمامية لبناء العميل، مدقق الكود للفحص الأمني، ومدقق الواقع للتحقق من الصحة قبل الإطلاق.

جرّب Apidog اليوم

عند الحاجة لبناء API سريعاً، قد تميل لاستخدام مساعد ذكاء اصطناعي واحد لكل شيء: تصميم قاعدة البيانات، كتابة نقاط النهاية، بناء الواجهة الأمامية، مراجعة الكود، واختبار النتيجة. لكن غالباً ما ينتج عن ذلك قاعدة بيانات بلا فهارس، نقاط نهاية بها ثغرات، واجهة أمامية تتجاهل حالات الخطأ، واختبارات سطحية.

الحل هو استخدام وكلاء متخصصين، كلٌ في مجاله ومعه قائمة تحقق ومخرجات محددة. في هذا الدليل العملي ستقوم بإعداد 5 وكلاء من The Agency وتشغيل سير عمل بناء API متكامل مع تكامل Apidog لاختبار API وتوثيقه والتأكد من صحة نقاط النهاية مقابل مواصفات OpenAPI قبل النشر.

الوكلاء الخمسة الذين ستستخدمهم

الوكيل	القسم	المسؤولية
مهندس الواجهة الخلفية	الهندسة	تصميم API، مخطط قاعدة البيانات، المصادقة
محسن قاعدة البيانات	الهندسة	توصيات الفهرسة، تحسين الاستعلامات
مطور الواجهة الأمامية	الهندسة	مكونات React، عميل API، إدارة الحالة
مدقق الكود	الهندسة	تدقيق الأمان، أمان الأنواع، معالجة الأخطاء
مدقق الواقع	الاختبار	التحقق المستند إلى الأدلة، إثبات لقطة الشاشة

تثبيت الوكلاء

# استنساخ مستودع The Agency
git clone https://github.com/msitarzewski/agency-agents.git
cd agency-agents

# نسخ الوكلاء إلى Claude Code
cp engineering/engineering-backend-architect.md ~/.claude/agents/
cp engineering/engineering-database-optimizer.md ~/.claude/agents/
cp engineering/engineering-frontend-developer.md ~/.claude/agents/
cp engineering/engineering-code-reviewer.md ~/.claude/agents/
cp testing/testing-reality-checker.md ~/.claude/agents/

الخطوة 1: مهندس الواجهة الخلفية يصمم النظام

ابدأ جلسة Claude Code جديدة وفعّل وضع مهندس الواجهة الخلفية. استخدم النموذج التالي لإنشاء المخرجات التقنية اللازمة:

تفعيل وضع مهندس الواجهة الخلفية.

صمم واجهة برمجة تطبيقات REST لمنصة تجارة إلكترونية تحتوي على:
- مصادقة المستخدم (JWT مع رموز التحديث)
- كتالوج المنتجات مع الفئات والتصفية
- إدارة عربة التسوق
- معالجة الطلبات مع تتبع الحالة
- دمج خطاف دفع الويب (webhook)

المخرجات:
1. مواصفات OpenAPI 3.0
2. مخطط قاعدة بيانات PostgreSQL مع العلاقات
3. هيكل مجلد المشروع (Express.js + TypeScript)
4. رسم بياني لتدفق المصادقة

احفظ المخرجات التقنية التالية لتمريرها للخطوة التالية:

مواصفات OpenAPI (مثال):

openapi: 3.0.0
info:
  title: "E-commerce API"
  version: 1.0.0
paths:
  /auth/login:
    post:
      summary: User login
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                email: { type: string, format: email }
                password: { type: string, minLength: 8 }
      responses:
        '200':
          description: "JWT tokens"
          content:
            application/json:
              schema:
                type: object
                properties:
                  accessToken: { type: string }
                  refreshToken: { type: string }

مخطط قاعدة البيانات:

CREATE TABLE users (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    email VARCHAR(255) UNIQUE NOT NULL,
    password_hash VARCHAR(255) NOT NULL,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

CREATE TABLE products (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    name VARCHAR(255) NOT NULL,
    description TEXT,
    price DECIMAL(10, 2) NOT NULL CHECK (price >= 0),
    category_id UUID REFERENCES categories(id),
    inventory_count INTEGER DEFAULT 0,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

CREATE TABLE orders (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID REFERENCES users(id),
    total_amount DECIMAL(10, 2) NOT NULL,
    status VARCHAR(50) DEFAULT 'pending',
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
);

هيكل المجلدات:

src/
├── controllers/
│   ├── auth.controller.ts
│   ├── products.controller.ts
│   └── orders.controller.ts
├── middleware/
│   ├── auth.middleware.ts
│   └── validation.middleware.ts
├── routes/
│   ├── auth.routes.ts
│   ├── products.routes.ts
│   └── orders.routes.ts
├── services/
│   ├── auth.service.ts
│   ├── products.service.ts
│   └── orders.service.ts
├── models/
│   ├── User.ts
│   ├── Product.ts
│   └── Order.ts
└── index.ts

الخطوة 2: محسن قاعدة البيانات يراجع المخطط

افتح جلسة Claude Code جديدة وفعّل وضع محسن قاعدة البيانات. الصق مخطط PostgreSQL الناتج من الخطوة 1 واستخدم التعليمات التالية:

تفعيل وضع محسن قاعدة البيانات.

راجع مخطط PostgreSQL هذا لواجهة برمجة تطبيقات للتجارة الإلكترونية:

[الصق المخطط من الخطوة 1]

تحقق من:
1. الفهارس المفقودة على المفاتيح الخارجية والأعمدة التي يتم الاستعلام عنها بشكل متكرر
2. أداء الاستعلام على بحث المنتجات (الاسم، الفئة، النطاق السعري)
3. القيود الصحيحة لسلامة البيانات
4. الجداول المفقودة لميزات التجارة الإلكترونية الشائعة (التقييمات، قوائم الأمنيات)
5. أنماط الحذف الناعم (soft delete) لمسارات التدقيق

أخرج عبارات ALTER TABLE محددة وتعريفات جداول جديدة.

نفذ التوصيات التالية وطبّقها على المخطط:

توصيات الفهرسة:

-- إضافة فهارس على المفاتيح الخارجية
CREATE INDEX idx_products_category_id ON products(category_id);
CREATE INDEX idx_orders_user_id ON orders(user_id);

-- إضافة فهرس لبحث المنتج
CREATE INDEX idx_products_name_search ON products USING gin(to_tsvector('english', name));
CREATE INDEX idx_products_price ON products(price) WHERE inventory_count > 0;

-- إضافة فهرس مركب لتصفية الفئات
CREATE INDEX idx_products_category_price ON products(category_id, price);

الجداول المفقودة:

CREATE TABLE reviews (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    product_id UUID REFERENCES products(id),
    user_id UUID REFERENCES users(id),
    rating INTEGER CHECK (rating >= 1 AND rating <= 5),
    comment TEXT,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    UNIQUE(product_id, user_id)
);

CREATE TABLE cart_items (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    user_id UUID REFERENCES users(id),
    product_id UUID REFERENCES products(id),
    quantity INTEGER DEFAULT 1 CHECK (quantity > 0),
    created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    updated_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
    UNIQUE(user_id, product_id)
);

القيود الإضافية:

-- التحقق من تنسيق البريد الإلكتروني
ALTER TABLE users ADD CONSTRAINT chk_email_format
    CHECK (email ~* '^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}$');

-- عمود الحذف الناعم
ALTER TABLE products ADD COLUMN deleted_at TIMESTAMP WITH TIME ZONE NULL;
CREATE INDEX idx_products_deleted_at ON products(deleted_at) WHERE deleted_at IS NULL;

الخطوة 3: مطور الواجهة الأمامية يبني العميل

ابدأ جلسة Claude Code جديدة وفعّل وضع مطور الواجهة الأمامية. الصق مواصفات OpenAPI من الخطوة 1 واستخدم التعليمات التالية:

تفعيل وضع مطور الواجهة الأمامية.

أنشئ لوحة تحكم React لواجهة برمجة تطبيقات التجارة الإلكترونية هذه:

[الصق مواصفات OpenAPI من الخطوة 1]

المتطلبات:
- TypeScript مع الوضع الصارم
- React Query لإدارة حالة الخادم
- قائمة المنتجات مع الفلاتر (الفئة، النطاق السعري، البحث)
- عربة تسوق مع تحديثات في الوقت الفعلي
- سجل الطلبات مع تتبع الحالة
- معالجة الأخطاء وحالات التحميل بشكل صحيح
- تصميم متجاوب (للهاتف، الجهاز اللوحي، سطح المكتب)

المخرجات:
1. إعداد المشروع (Vite + React + TypeScript)
2. عميل واجهة برمجة تطبيقات مع خطافات React Query
3. المكونات الأساسية (ProductList, ProductCard, Cart, OrderHistory)
4. حدود الأخطاء وهياكل التحميل

أمثلة على الأكواد الأساسية:

عميل واجهة برمجة التطبيقات:

// src/lib/api-client.ts
import { QueryClient, useQuery, useMutation } from '@tanstack/react-query';

const API_BASE = 'http://localhost:3000/api';

async function fetcher<T>(endpoint: string, options?: RequestInit): Promise<T> {
  const response = await fetch(`${API_BASE}${endpoint}`, {
    ...options,
    headers: {
      'Content-Type': 'application/json',
      ...options?.headers,
    },
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.message || 'Request failed');
  }

  return response.json();
}

export function useProducts(filters?: ProductFilters) {
  const params = new URLSearchParams(filters as Record<string, string>);
  return useQuery({
    queryKey: ['products', filters],
    queryFn: () => fetcher<Product[]>(`/products?${params}`),
  });
}

export function useAddToCart() {
  return useMutation({
    mutationFn: (item: CartItem) =>
      fetcher<CartItem>('/cart', {
        method: 'POST',
        body: JSON.stringify(item),
      }),
  });
}

مكون قائمة المنتجات:

// src/components/ProductList.tsx
import { useProducts } from '@/lib/api-client';
import { ProductCard } from './ProductCard';
import { FilterSidebar } from './FilterSidebar';
import { Skeleton } from './ui/skeleton';

export function ProductList() {
  const [filters, setFilters] = useState<ProductFilters>({});
  const { data: products, isLoading, error } = useProducts(filters);

  if (error) {
    return <Alert variant="destructive">{error.message}</Alert>;
  }

  return (
    <div className="flex gap-4">
      <FilterSidebar filters={filters} onFilterChange={setFilters} />
      <div className="flex-1 grid grid-cols-1 md:grid-cols-3 gap-4">
        {isLoading ? (
          Array.from({ length: 6 }).map((_, i) => (
            <Skeleton key={i} className="h-64" />
          ))
        ) : products?.length === 0 ? (
          <EmptyState message="No products found" />
        ) : (
          products?.map(product => (
            <ProductCard key={product.id} product={product} />
          ))
        )}
      </div>
    </div>
  );
}

حدود الأخطاء:

// src/components/ErrorBoundary.tsx
export class ErrorBoundary extends React.Component<
  { children: React.ReactNode },
  { hasError: boolean; error: Error | null }
> {
  constructor(props: { children: React.ReactNode }) {
    super(props);
    this.state = { hasError: false, error: null };
  }

  static getDerivedStateFromError(error: Error) {
    return { hasError: true, error };
  }

  render() {
    if (this.state.hasError) {
      return (
        <div className="p-4 bg-red-50 border border-red-200 rounded">
          <h2 className="text-lg font-semibold text-red-800">Something went wrong</h2>
          <p className="text-red-600">{this.state.error?.message}</p>
          <Button onClick={() => window.location.reload()} className="mt-2">
            Reload
          </Button>
        </div>
      );
    }

    return this.props.children;
  }
}

الخطوة 4: مدقق الكود يتحقق من كل شيء

افتح جلسة Claude Code جديدة وفعّل وضع مدقق الكود. الصق الكود من الخطوات 1-3 واطلب تقريراً بالتعليمات التالية:

تفعيل وضع مدقق الكود.

راجع قاعدة الكود هذه بحثًا عن:

1. الثغرات الأمنية:
   - مخاطر حقن SQL
   - ثغرات XSS
   - حماية CSRF
   - إمكانيات تجاوز المصادقة

2. التوافق مع الوضع الصارم لـ TypeScript:
   - لا يوجد "any" ضمني
   - تعريفات أنواع صحيحة
   - معالجة القيم الخالية/غير المعرفة

3. فجوات معالجة الأخطاء:
   - رفض الوعود غير الملتقطة
   - كتل try/catch مفقودة
   - الأعطال الصامتة

[الصق الكود من الخطوات 1-3]

أخرج تقريرًا بتقييمات الخطورة (حرجة، عالية، متوسطة، منخفضة) وإصلاحات محددة.

نموذج تقرير الأمان:

## مشكلات حرجة

### 1. حقن SQL في بحث المنتجات
**الموقع:** `src/controllers/products.controller.ts:24`
**المشكلة:** إدخال المستخدم مدمج مباشرة في استعلام SQL

// ضعيف
const query = `SELECT * FROM products WHERE name LIKE '%${search}%'`;

الإصلاح: استخدم استعلامات معلمة (parameterized queries)

const query = 'SELECT * FROM products WHERE name LIKE $1';
await db.query(query, [`%${search}%`]);

مشكلات عالية الخطورة

2. حماية CSRF مفقودة

الموقع: src/index.ts
المشكلة: لا يوجد وسيط CSRF للعمليات التي تغير الحالة

الإصلاح: أضف وسيط csurf

import csrf from 'csurf';
app.use(csrf({ cookie: true }));

مشكلات متوسطة الخطورة

3. وجود "any" ضمني في استجابة API

الموقع: src/lib/api-client.ts:8
المشكلة: نوع any عام لدالة fetcher

الإصلاح: أضف قيود أنواع مناسبة

async function fetcher<T extends Record<string, unknown>>(
  endpoint: string,
  options?: RequestInit
): Promise<T> { ... }

انتهاكات TypeScript

products.controller.ts:45 - تعليق توضيحي لنوع الإرجاع مفقود
auth.middleware.ts:12 - "any" ضمني في كتلة الالتقاط
orders.service.ts:78 - كائن قد يكون غير معرف

قم بتشغيل tsc --noEmit لرؤية القائمة الكاملة. أصلح قبل النشر.


**نفذ جميع الإصلاحات قبل المتابعة.**

---

## الخطوة 5: مدقق الواقع يتحقق من الصحة قبل الشحن

افتح جلسة Claude Code جديدة وفعّل وضع مدقق الواقع. نفّذ التحقق النهائي كما يلي:

تفعيل وضع مدقق الواقع.

واجهة برمجة تطبيقات التجارة الإلكترونية هذه جاهزة للتحقق من الإنتاج.

قم بتشغيل عملية التحقق الواقعي الإلزامي:

تحقق من وجود الملفات
قارن الميزات المزعومة بالكود الفعلي
اطلب دليل لقطة شاشة من اختبارات Playwright
راجع test-results.json لمقاييس الأداء

عنوان URL للمشروع: http://localhost:3000
نتائج الاختبار: ./public/qa-screenshots/test-results.json

المخرجات: اجتياز (PASS) أو يحتاج إلى عمل (NEEDS WORK) مع مشكلات حظر محددة.


**أوامر تحقق واقعي عملية:**

bash

1. تحقق من وجود الملفات

ls -la src/controllers/ src/services/ src/routes/
ls -la src/components/ src/lib/

2. قارن الميزات المزعومة

grep -r "jwt|jsonwebtoken" . --include=".ts" || echo "NO JWT FOUND"
grep -r "bcrypt|argon2" . --include=".ts" || echo "NO PASSWORD HASHING FOUND"
grep -r "rateLimit|express-rate-limit" . --include="*.ts" || echo "NO RATE LIMITING FOUND"

3. تشغيل التقاط لقطات الشاشة بواسطة Playwright

npx playwright test --config=qa-playwright.config.ts --grep "@screenshot"

4. مراجعة نتائج الاختبار

cat public/qa-screenshots/test-results.json


**نموذج تقرير التحقق النهائي:**

markdown

نتائج التحقق الواقعي

التحقق من الملفات: اجتياز (PASS)

جميع ملفات المتحكمات موجودة
جميع ملفات المكونات موجودة

التحقق من الميزات: يحتاج إلى عمل (NEEDS WORK)

مصادقة JWT: موجودة
تجزئة كلمة المرور: موجودة
تحديد المعدل: غير موجود (معطل)

إثبات لقطة الشاشة: يحتاج إلى عمل (NEEDS WORK)

تخطيط سطح المكتب: اجتياز (PASS)
تخطيط الجهاز اللوحي: اجتياز (PASS)
تخطيط الهاتف المحمول: فشل (شبكة المنتجات معطلة عند 375 بكسل)

مقاييس الأداء: يحتاج إلى عمل (NEEDS WORK)

متوسط وقت التحميل: 2.3 ثانية (الهدف: <1 ثانية)
أخطاء الكونسول: 3 (الهدف: 0)
طلبات الشبكة الفاشلة: 1 (الهدف: 0)

الحالة النهائية: يحتاج إلى عمل (NEEDS WORK)

المشكلات المعطلة:

لم يتم تطبيق تحديد المعدل
تخطيط الهاتف المحمول معطل في قائمة المنتجات
3 أخطاء كونسول تحتاج إلى إصلاح
وقت التحميل يتجاوز الهدف المحدد بـ 1 ثانية

غير معطلة:

أضف هياكل التحميل إلى سجل الطلبات
تحسين رسائل الخطأ


**قم بإصلاح جميع المشكلات المعطلة وأعد تشغيل مدقق الواقع حتى تحصل على PASS.**

---

## ملخص سير العمل

plaintext
┌─────────────────────────────────────────────────────────────────┐
│ مهندس الواجهة الخلفية │
│ → مواصفات OpenAPI، مخطط قاعدة البيانات، هيكل المجلدات │
└─────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────┐
│ محسن قاعدة البيانات │
│ → توصيات الفهرسة، الجداول المفقودة، القيود │
└─────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────┐
│ مطور الواجهة الأمامية │
│ → مكونات React، عميل API، معالجة الأخطاء │
└─────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────┐
│ مدقق الكود │
│ → تدقيق الأمان، أمان الأنواع، فجوات معالجة الأخطاء │
└─────────────────────────────────────────────────────────────────┘
↓
┌─────────────────────────────────────────────────────────────────┐
│ مدقق الواقع │
│ → التحقق المستند إلى الأدلة، إثبات لقطة الشاشة، اجتياز/فشل │
└─────────────────────────────────────────────────────────────────┘


---

## تنفيذ الوكلاء بالتوازي (متقدم)

يمكنك تسريع سير العمل بتشغيل الوكلاء في عدة طرفيات بالتوازي: