الإقليم ٠٨ — خريطة المسرح

يبني فوق: المكوّن كوحدة شكل (١)، الخطاف المخصّص كوحدة منطق (٦). النطاق: أين تعيش الملفات على القرص، ولماذا هذا قرارٌ هندسيٌّ لا ذوقٌ شخصي. لا مفهوم React جديد هنا — تطبيقٌ لكل ما سبق على مقياس مشروعٍ كامل. يفتح: ورشة الأزياء (٩)، خارطة الجولة (١٠).

اللغز المستفزّ

ليش: نظّم حسب "من يملك هذا"، لا "ما شكله"

اسأل سؤالاً مختلفاً: لو أردتُ حذف ميزة الفوترة بالكامل غداً، كم ملفاً علي لمسه، وفي كم مجلّد مختلف؟ في التنظيم أعلاه: أربعة مجلّدات، تبحث يدوياً عن كل ملفٍّ اسمه يبدأ بـBilling/Invoice. في تنظيمٍ حسب الميزة أولاً: مجلّدٌ واحد، تحذفه، انتهى.

الآن أنت وزميلك تعملان في مجلّدين مختلفين تماماً. لا ملفّ مشتركٌ بينكما إلا ما تتّفقان عليه صراحةً (القسم القادم). هذا يحلّ مشكلة التصادم بنيوياً، لا بالتواصل والتنسيق اليدوي المستمر.

ليش وكيف: حدٌّ ثانٍ — الشكل عن المنطق، داخل كل ميزة

افتح ملفّاً واحداً بلا أي فصل:

function TaskList() {
  const [tasks, setTasks] = useState<Task[]>([]);
  const [status, setStatus] = useState<"loading" | "ready" | "error">("loading");

  useEffect(() => {
    fetchTasks().then((data) => { setTasks(data); setStatus("ready"); })
      .catch(() => setStatus("error"));
  }, []);

  if (status === "loading") return <Spinner />;
  if (status === "error") return <p>خطأ في التحميل</p>;

  return (
    <ul className="divide-y">
      {tasks.map((t) => (
        <li key={t.id} className="flex items-center justify-between p-4">
          <span className={t.done ? "line-through opacity-50" : ""}>{t.text}</span>
          <Checkbox checked={t.done} />
        </li>
      ))}
    </ul>
  );
}

الآن تحتاج في مكانٍ آخر من التطبيق (لوحة تحكّمٍ مصغّرة) نفس البيانات بالضبط، لكن معروضة كملخّصٍ صغير: "٣ مهامٍ متبقّية" فقط، بلا قائمة. بما أن جلب البيانات محبوسٌ داخل TaskList نفسها، لا طريقة لإعادة استخدامه إلا نسخ منطق useEffect/fetch بالكامل مجدداً. هذا نفس درس الإقليم ٦ بالضبط — لكن السبب هذه المرّة ليس "نموذجان متشابهان"، بل "شكلان مختلفان لنفس البيانات":

// المنطق — لا يعرف شيئاً عن الشكل النهائي
function useTasks() {
  const [tasks, setTasks] = useState<Task[]>([]);
  const [status, setStatus] = useState<"loading" | "ready" | "error">("loading");

  useEffect(() => {
    fetchTasks().then((data) => { setTasks(data); setStatus("ready"); })
      .catch(() => setStatus("error"));
  }, []);

  return { tasks, status };
}

// شكلٌ أول — لا يعرف شيئاً عن fetch أو useEffect
function TaskListFull() {
  const { tasks, status } = useTasks();
  if (status === "loading") return <Spinner />;
  if (status === "error") return <p>خطأ في التحميل</p>;
  return <ul>{tasks.map((t) => <li key={t.id}>{t.text}</li>)}</ul>;
}

// شكلٌ ثانٍ — نفس المنطق بالضبط، عرضٌ مختلف كلياً
function TaskSummaryWidget() {
  const { tasks, status } = useTasks();
  if (status !== "ready") return null;
  const remaining = tasks.filter((t) => !t.done).length;
  return <span>{remaining} مهامٍ متبقّية</span>;
}

القاعدة المشتقّة: مكوّن "شكل" يستقبل بياناته (عبر props أو خطافٍ مخصّص) ويقرّر فقط كيف تُعرَض — لا من أين أتت ولا متى تُجلَب. خطافٌ مخصّص يحمل كل قرارات "المنطق" — لا يعرف ولا يهتمّ كيف سيُعرَض ما يُرجعه. هذا الفصل يعني: تغييرٌ بصريّ بحت (لون، تخطيط) لا يخاطر بلمس منطق الجلب، وتغييرٌ في منطق الجلب (endpoint جديد، تخزينٌ مؤقّت) لا يجبرك على لمس JSX في كل مكانٍ يُستهلَك فيه.

اللغز/البناء من الصفر — الجزء الأول

ليش: مقارنة بالبديل الأكثر صرامة — Feature-Sliced Design

التنظيم أعلاه (حسب الميزة، بحدٍّ بسيط شكل/منطق) يُسمّى غالباً feature-based — مرن، قواعده اتفاقية لا مفروضة. يوجد بديلٌ أكثر صرامة يستحق معرفته: Feature-Sliced Design (FSD)، مواصفةٌ رسمية بطبقاتٍ إجبارية:

القاعدة الحديدية في FSD ("الطبقة تستورد فقط ممّا تحتها") تحلّ مشكلةً لم تظهر بعد في مشروعك الصغير لكنها حتمية في مشروعٍ كبير يعيش سنين: الاعتماديات الدائرية والصاعدة. تخيّل ميزة "أ" تستورد شيئاً من ميزة "ب"، وميزة "ب" تستورد شيئاً من "أ" لاحقاً — الآن لا يمكن حذف أو فهم أيٍّ منهما بمعزلٍ عن الأخرى، ومجلَّدا "الميزتين المستقلّتين" أصبحا متشابكين فعلياً. الطبقات الإجبارية تمنع هذا بنيوياً: لا شيء أسفل يمكنه معرفة شيءٍ أعلاه.

متى تستحقّ FSD الثمن؟ فريقٌ كبير، مشروعٌ طويل العمر، عشرات الميزات المتشابكة محتملة. متى هي مبالغة؟ فريقٌ صغير، عدد ميزاتٍ محدود، مشروعٌ في مراحله الأولى — الطقوس والقواعد الصارمة تُبطئك بلا فائدةٍ تقابلها بعد. القرار ليس "الأفضل مطلقاً"، بل مقايضة تتناسب مع حجم المشكلة الفعلي.

اللغز/البناء من الصفر — الجزء الثاني: دقّق قاعدة الاستيراد

// src/shared/ui/Button.tsx
export function Button() { /* ... */ }

// src/entities/task/model.ts
import { formatDueDate } from "@/features/task-reminder/utils";   // ⚠️
export type Task = { id: string; dueDate: string };

// src/features/task-reminder/utils.ts
export function formatDueDate(iso: string): string { /* ... */ }

// src/pages/TaskBoard.tsx
import { Task } from "@/entities/task/model";
import { Button } from "@/shared/ui/Button";

كيف: قاعدة الترقية إلى shared

قاعدةٌ عملية بسيطة تناسب كلا الأسلوبين: ملفٌّ يبدأ داخل ميزته. أول لحظة يحتاجه قسمٌ ثانٍ (لا أول احتمال نظري — أول استخدامٍ فعلي)، يُنقَل إلى shared/ (أو entities/ في FSD لو كان يمثّل كائن نطاق). قبل ذلك، أي ترقيةٍ مبكرة "تحسّباً" مجرّد تخمين — والتخمين الخاطئ يُنتج طبقة shared/ منتفخة بأشياء يستخدمها قسمٌ واحد فعلياً، فتفقد الكلمة معناها.

الخلاصة — أين تتّصل هذه العقدة بالشجرة

الوصلة بمشروعك