Stores و Selectors و Actions في Gutenberg: بناء مخزن حالة مخصص وقابل للتوسع

أهلاً بيك يا صديقي المطور في ورشة الهندسة المعمارية المتقدمة لمحرر Gutenberg: المثلث الذهبي لإدارة الحالة (Stores, Selectors, and Actions) داخل ووردبريس.

لو أنت بتبني مشروع كبير في ووردبريس—زي بوابة تجارة إلكترونية، أو منصة كورسات وتعليم عن بُعد، أو نظام حجز عيادات وصيدليات—فهيجي عليك وقت تلاقي فيه إن تمرير البيانات بين البلوكات المختلفة أصبح كابوساً لا يطاق! لما يكون عندك بلوك في أول الصفحة بيعرض “سلة الأدوية”، وبلوك في نص المقال بيعرض “منتجات مقترحة”، وبلوك في الشريط الجانبي بيحسب “الخصومات والضرائب”، فمحاولة ربطهم بـ React Props أو Local State عادية بتنتهي دائماً بحالة من الفوضى والبطء القاتل وتضارب البيانات.

الحل الهندسي النظيف هو بناء مخزن بيانات مخصص ومستقل (Dedicated Scoped Store) يمتلك حالة نقية، ويوفر Selectors مذكرنة وسريعة للقراءة، و Actions واضحة وموثقة للتعديل. في المقال ده، هنشرح تشريح المخزن من الألف للياء، إزاي تبني Reducer نقي يحترم قواعد الـ Immutability، إزاي تستخدم مكتبات المذكرنة (Memoization) لمنع إعادة حساب العمليات المعقدة، ودراسة حالة حقيقية لشبكة صيدليات في الإسكندرية بالعامية المصرية التقنية الأصيلة.

تشريح المخزن: الأركان الأربعة لمعمارية @wordpress/data

أي مخزن بيانات حقيقي في جوتنبرج يتكون من أربعة أركان هندسية متكاملة تتحدث مع بعضها بدقة:

1. الحالة (State):

   كائن جافاسكريبت نقي في الذاكرة الحية يمثل مصدر الحقيقة الوحيد (Single Source of Truth). لا يجوز لأي كود تعديله مباشرة.

2. منشئات الإجراءات (Action Creators):

   دوال بسيطة تصف “ماذا حدث في التطبيق”. كل Action يرجع كائناً يحتوي على type إلزامي (مثل: 'ADD_PRESCRIPTION') ومصفوفة بيانات مرافقة payload.

3. المحول النقي (Reducer):

   الدالة الصافية المسؤولة الوحيدة عن استلام الحالة الحالية والإجراء، وتوليد حالة جديدة تماماً (New Immutable State) دون لمس الحالة القديمة.

4. المحددات المذكرنة (Selectors):

   بوابات القراءة الرسمية؛ دوال تستخرج البيانات من الـ State وتجري العمليات الحسابية والفرز مع تخزين النتيجة مؤقتاً في الذاكرة لسرعة الاسترجاع.

تطبيق عملي كامل: بناء مخزن شبكة الصيدليات وفحص تعارض الأدوية (Pharmacy Store)

تعال نبني كود إنتاجي متكامل لمخزن صيدليات (enterprise/pharmacy) يدير قائمة الأدوية الموصوفة، ويفحص التداخلات الدوائية الخطيرة (Drug-Drug Interactions) باستخدام محددات مذكرنة فائقة الأداء:

1. ملف منشئات الإجراءات: actions.js

/**
 * ملف الإجراءات الرسمية لمخزن الصيدلية
 * File: store/actions.js
 */

export function addMedication( medication ) {
    return {
        type: 'ADD_MEDICATION',
        payload: {
            id: medication.id || Date.now().toString(),
            name: medication.name,
            dosage: medication.dosage,
            activeIngredient: medication.activeIngredient, // المادة الفعالة
            price: parseFloat( medication.price ) || 0,
        },
    };
}

export function removeMedication( id ) {
    return {
        type: 'REMOVE_MEDICATION',
        payload: id,
    };
}

export function clearPrescription() {
    return {
        type: 'CLEAR_PRESCRIPTION',
    };
}

2. ملف المحول النقي: reducer.js

/**
 * المحول الصافي لحالة الصيدلية مع الحفاظ على Immutability
 * File: store/reducer.js
 */

const INITIAL_STATE = {
    medications: [],
    patientAge: 35,
    isCheckingInteractions: false,
};

export default function reducer( state = INITIAL_STATE, action ) {
    switch ( action.type ) {
        case 'ADD_MEDICATION': {
            // منع إضافة نفس الدواء مرتين بالخطأ
            const exists = state.medications.some( ( med ) => med.name.toLowerCase() === action.payload.name.toLowerCase() );
            if ( exists ) {
                return state;
            }
            return {
                ...state,
                medications: [ ...state.medications, action.payload ],
            };
        }
        case 'REMOVE_MEDICATION':
            return {
                ...state,
                medications: state.medications.filter( ( med ) => med.id !== action.payload ),
            };
        case 'CLEAR_PRESCRIPTION':
            return {
                ...state,
                medications: [],
            };
        default:
            return state;
    }
}

3. ملف المحددات المذكرنة: selectors.js (أعلى درجات الأداء)

/**
 * محددات قراءة البيانات مع مذكرنة العمليات الحسابية
 * File: store/selectors.js
 */
import createSelector from 'rememo';

// 1. محدد أساسي خفيف: قراءة قائمة الأدوية
export function getMedications( state ) {
    return state.medications;
}

// 2. محدد أساسي: قراءة عدد الأدوية
export function getMedicationsCount( state ) {
    return state.medications.length;
}

// 3. محدد مذكرن (Memoized): حساب السعر الإجمالي
export const getTotalPrescriptionPrice = createSelector(
    ( state ) => {
        return state.medications.reduce( ( sum, med ) => sum + med.price, 0 );
    },
    ( state ) => [ state.medications ] // يعاد الحساب فقط إذا تغيرت مصفوفة الأدوية!
);

// 4. محدد مذكرن فائق الذكاء: فحص تعارض المواد الفعالة في الروشتة
export const checkDrugInteractions = createSelector(
    ( state ) => {
        const warnings = [];
        const ingredients = state.medications.map( ( m ) => m.activeIngredient.toLowerCase() );

        // نموذج لفحص تعارض خطير: مثلاً تعارض الأسبرين مع مضادات التجلط
        if ( ingredients.includes( 'aspirin' ) && ingredients.includes( 'warfarin' ) ) {
            warnings.push( 'تحذير حرج: تعارض شديد بين الأسبرين والوارفارين يزيد من خطر النزيف!' );
        }

        // تعارض الباراسيتامول مع جرعات مهدئة معينة
        if ( ingredients.includes( 'paracetamol' ) && ingredients.includes( 'alcohol_extract' ) ) {
            warnings.push( 'تنبيه: تجنب تناول هذا المستحضر مع مستخلصات كحولية لحماية الكبد.' );
        }

        return warnings;
    },
    ( state ) => [ state.medications ]
);

4. ملف تجميع وتسجيل المخزن: index.js

/**
 * تجميع وتسجيل المخزن في سجل @wordpress/data
 * File: store/index.js
 */
import { createReduxStore, register } from '@wordpress/data';
import reducer from './reducer';
import * as actions from './actions';
import * as selectors from './selectors';

export const PHARMACY_STORE_KEY = 'enterprise/pharmacy';

export const pharmacyStore = createReduxStore( PHARMACY_STORE_KEY, {
    reducer,
    actions,
    selectors,
} );

// تسجيل المخزن رسمياً في النواة
register( pharmacyStore );

5. كود استخدام المخزن داخل بلوك التحرير: edit.js

import { useBlockProps } from '@wordpress/block-editor';
import { useSelect, useDispatch } from '@wordpress/data';
import { Button, TextControl, Notice } from '@wordpress/components';
import { useState } from '@wordpress/element';
import { __ } from '@wordpress/i18n';
import { pharmacyStore } from './store';
import './editor.scss';

export default function Edit() {
    const blockProps = useBlockProps( { className: 'az-pharmacy-checker-block' } );

    // حالات محلية لحقول الإدخال
    const [ medName, setMedName ] = useState( '' );
    const [ activeIngredient, setActiveIngredient ] = useState( '' );
    const [ price, setPrice ] = useState( '' );

    // استخراج البيانات من المخزن المخصص عبر المحددات المذكرنة
    const { medications, totalPrice, warnings } = useSelect( ( select ) => {
        const store = select( pharmacyStore );
        return {
            medications: store.getMedications(),
            totalPrice: store.getTotalPrescriptionPrice(),
            warnings: store.checkDrugInteractions(),
        };
    }, [] );

    // استخراج دوال التحديث
    const { addMedication, removeMedication, clearPrescription } = useDispatch( pharmacyStore );

    const handleAdd = () => {
        if ( ! medName || ! activeIngredient ) return;
        addMedication( {
            name: medName,
            activeIngredient,
            price: parseFloat( price ) || 50,
        } );
        setMedName( '' );
        setActiveIngredient( '' );
        setPrice( '' );
    };

    return (
        

            
{ __( 'نظام فحص تعارض الأدوية والروشتات الطبية (Store & Selectors)', 'az-pharma' ) }

            { /* إظهار تحذيرات التعارض الطبي فوراً وبأعلى سرعة */ }
            { warnings.length > 0 && (
                

                    { warnings.map( ( warn, idx ) => (
                        
                            { warn }
                        
                    ) ) }
                
            ) }

            

                
                
                
                
                    { __( 'إضافة للروشتة', 'az-pharma' ) }
                
            

            

                
{ __( 'الأدوية المضافة حالياً', 'az-pharma' ) } ({ medications.length })
                

                    { medications.map( ( med ) => (
                        

                            { med.name } ({ med.activeIngredient }) - { med.price } ج.م
                             removeMedication( med.id ) } />
                        
                    ) ) }
                
                

                    إجمالي قيمة الروشتة: { totalPrice.toLocaleString() } ج.م
                    
                        تفريغ الروشتة
                    
                
            
        
    );
}

دراسة حالة واقعية: أزمة شبكة صيدليات الإسكندرية وفحص التعارضات الدوائية

الوصايا العشر لمعمارية Stores و Selectors و Actions

1. دائماً ذكرن العمليات الحسابية في Selectors: استخدم createSelector من rememo لأي عملية تصفية أو حساب لتفادي إرهاق المعالج.
2. اجعل الـ Reducer دالة صافية خالية من الآثار (Pure Function): لا تستدعِ API، لا تضع تواريخ لحظية، ولا تولد أرقاماً عشوائية داخل الـ Reducer.
3. احترم قواعد الـ Immutability بدقة: لا تعدل الحالة الأصلية بيدك؛ استخدم دائماً مشغلات النشر { ...state } لإنشاء نسخ جديدة.
4. سمّ الإجراءات بصيغة الفعل والحدث الواضح: مثل ADD_ITEM أو REMOVE_ITEM واجعل الـ Type معبراً بوضوح عما حدث.
5. افصل مخازن إضافتك بنطاق خاص (Namespace): لا تسجل مخزنك باسم عام؛ استخدم بادئة فريدة مثل my-company/my-store.
6. لا تخزن بيانات مشتقة في الـ State: إذا كان بإمكانك حساب “الإجمالي” عبر Selector، فلا تخزنه في الـ State لتجنب تضارب القيم.
7. استخدم useSelect مع مصفوفة الاعتماديات: مرر مصفوفة فارغة [] أو المتغيرات المستهدفة لضمان عدم إعادة تشغيل الـ Hook دون مبرر.
8. اكتب اختبارات Jest للـ Reducer والـ Selectors: اعزل منطق العمليات الحسابية واختبره بدون الحاجة لتشغيل ووردبريس أو المتصفح.
9. استخدم Redux DevTools لتتبع الـ Actions: راقب تدفق البيانات وتأكد من أن الإجراءات تطلق بالترتيب المتوقع وببيانات صحيحة.
10. اجعل المخزن هو مصدر الحقيقة الوحيد للبلوكات المتصلة: لا توزع نفس المعلومة بين Attributes و Local State؛ اجعل المخزن هو المرجع الأوحد.

معمارية الإجراءات المولدة والضوابط (Generator Actions & Controls)

يا صديقي المطور، من أعظم الأسرار الهندسية في حزمة @wordpress/data هي كيفية التعامل مع العمليات غير المتزامنة (Async Operations) دون تلويث الـ Reducer أو كتابة وعود (Promises) متداخلة ومعقدة داخل الـ Actions.

ووردبريس بتستخدم مفهوم عبقري مأخوذ من مكتبة Redux-Routine يعتمد على دوال التوليد في جافاسكريبت (Generator Functions – function*) مع ما يسمى بـ Controls:

كود عملي: استدعاء الـ API بأسلوب Generator Actions النقي

/**
 * إدارة جلب البيانات غير المتزامنة عبر دوال التوليد والضوابط
 */

// 1. تعريف الإجراء كدالة توليد (Generator Function)
export function* fetchMedicationDetails( medicationId ) {
    // إطلاق إجراء أولي للإشارة ببدء التحميل
    yield { type: 'SET_IS_FETCHING', payload: true };

    try {
        // yield تستدعي الـ Control المخصص لجلب البيانات دون await مباشرة!
        const result = yield {
            type: 'FETCH_FROM_API',
            path: `/enterprise/v1/medications/${ medicationId }`,
        };

        // عند وصول النتيجة، يتم تمريرها للـ Reducer
        yield { type: 'ADD_MEDICATION_SUCCESS', payload: result };
    } catch ( error ) {
        yield { type: 'SET_FETCH_ERROR', payload: error.message };
    } finally {
        yield { type: 'SET_IS_FETCHING', payload: false };
    }
}

// 2. تعريف الضابط (Control) الذي ينفذ الاتصال الشبكي الفعلي
export const controls = {
    FETCH_FROM_API( action ) {
        return wp.apiFetch( { path: action.path } );
    },
};

لماذا هذه المعمارية هي الأقوى على الإطلاق؟
لأن دالة fetchMedicationDetails أصبحت دالة قابلة للاختبار بنسبة 100% دون الحاجة لمكتبات محاكاة الشبكة (No Mock Network Needed)! في اختبارات Jest، كل ما تفعله هو استدعاء generator.next() والتأكد من أنها ترجع كائن الـ Action المتوقع بالترتيب الدقيق!

هندسة الفحص الآلي للمخزن عبر Jest (Unit Testing Stores)

في المؤسسات الطبية والمالية، لا يمكنك رفع كود المخزن إلى السيرفر الحي دون التأكد من أن حسابات الأسعار وفحص التعارضات تعمل بدقة متناهية. إليك نموذج اختبار Jest متكامل ومستقل:

/**
 * فحص سلامة محول ومحددات مخزن الصيدلية
 * File: test/pharmacy-store.test.js
 */
import reducer from '../src/store/reducer';
import { addMedication, removeMedication } from '../src/store/actions';
import { getTotalPrescriptionPrice, checkDrugInteractions } from '../src/store/selectors';

describe( 'فحص سلامة مخزن الصيدلية (enterprise/pharmacy)', () => {
    it( 'يجب أن يضيف الدواء ويحدث الإجمالي بدقة دون تحوير الحالة الأصلية', () => {
        const initialState = { medications: [] };
        
        // إطلاق إضافة دواء الأسبرين
        const stateAfterFirst = reducer( initialState, addMedication( {
            id: '1',
            name: 'Aspirin',
            activeIngredient: 'aspirin',
            price: 50,
        } ) );

        // إطلاق إضافة دواء ثانٍ
        const finalState = reducer( stateAfterFirst, addMedication( {
            id: '2',
            name: 'Vitamin C',
            activeIngredient: 'ascorbic_acid',
            price: 70,
        } ) );

        // فحص عدد الأدوية
        expect( finalState.medications ).toHaveLength( 2 );

        // فحص عمل المحدد المذكرن لحساب الإجمالي
        const total = getTotalPrescriptionPrice( finalState );
        expect( total ).toBe( 120 );
    } );

    it( 'يجب أن يطلق تحذيراً فورياً عند وجود تعارض بين الأسبرين والوارفارين', () => {
        const stateWithConflict = {
            medications: [
                { id: '1', name: 'Aspirin', activeIngredient: 'aspirin', price: 50 },
                { id: '2', name: 'Coumadin', activeIngredient: 'warfarin', price: 110 },
            ],
        };

        const warnings = checkDrugInteractions( stateWithConflict );
        expect( warnings ).toHaveLength( 1 );
        expect( warnings[0] ).toContain( 'تعارض شديد بين الأسبرين والوارفارين' );
    } );
} );

هذا الفصل المعماري التام بين إدارة البيانات وبين شاشة العرض يضمن أن موقعك يمتلك كوداً برمجياً يمكن الوثوق به في أعقد الأنظمة المصرفية والطبية في العالم العربي.