«اشرحه كأني بنيته» — توثيق تقني واضح للمؤسسين غير التقنيين

أنت كاتب تقني خبير متخصص في جعل الأنظمة المعقدة مفهومة لغير المهندسين. عندك قدرة عالية على استخدام التشبيه، والسرد، وتحويل مخططات المعمارية التقنية إلى قصة واضحة وسهلة المتابعة. أحتاج منك تحلل هذا المشروع وتكتب ملف توثيق شامل باسم `FORME.md` يشرح كل شيء عن المشروع بلغة واضحة ومفهومة. ## سياق المشروع - **اسم المشروع:** name - **وش يسوي المشروع؟ جملة واحدة:** [مثال: منصة SaaS تساعد المطاعم على إدارة الطلبات أونلاين مباشرة بدون دفع عمولات عالية لتطبيقات التجميع] - **دوري:** [مثال: أنا المؤسس / مالك المنتج / المصمم — ما أكتب كود، لكني أتخذ قرارات المنتج والمعمارية] - **التقنيات المستخدمة، إذا تعرفها:** [مثال: Next.js, Supabase, Tailwind أو: ما أدري، استنتجها من الكود] - **مرحلة المشروع:** [MVP / v1 في الإنتاج / مرحلة توسّع / إعادة هيكلة نظام قديم] ## الكود [ارفع الملفات، أو أعطِ المسار، أو الصق الملفات الأساسية] ## هيكل المستند اكتب ملف FORME.md بهذه الأقسام وبنفس الترتيب: ### 1. الصورة الكبيرة — نظرة عامة على المشروع ابدأ بملخص تنفيذي من 3 إلى 4 جمل يقدر أي شخص يفهمه. ثم وضّح: - المشكلة التي يحلها المشروع، ولمَن تحديدًا - كيف يتفاعل المستخدمون معه، أي رحلة المستخدم بلغة بسيطة - تشبيه كامل للنظام: «لو كان هذا المشروع مطعمًا» أو تشبيه مناسب مشابه ### 2. المعمارية التقنية — المخطط العام اشرح كيف صُمم النظام ولماذا اختير هذا التصميم. - ارسم المعمارية باستخدام مخطط نصي بسيط، صناديق وأسهم - اشرح كل طبقة أو خدمة رئيسية وكأنك تسوي جولة داخل مبنى: «هذا هو المطبخ، أي طبقة واجهة البرمجة API — هنا يصير الشغل الحقيقي. الطلبات تجي من الاستقبال، أي الواجهة الأمامية، وتُعالَج هنا، ثم تُحفَظ النتائج في دولاب الملفات، أي قاعدة البيانات.» - لكل قرار معماري، جاوب على سؤال: «ليش هذا الخيار وليس البديل البديهي؟» - أبرز أي اختيارات ذكية أو غير معتادة سوّاها المطوّر ### 3. هيكلة الكود — نظام الملفات ارسم خريطة لتنظيم ملفات ومجلدات المشروع. - اعرض شجرة المجلدات، أول مستويين إلى ثلاثة مستويات - لكل مجلد رئيسي، اشرح: - وش الموجود هنا، بلغة بسيطة - متى يحتاج الشخص يفتح هذا المجلد - كيف يرتبط بالمجلدات الأخرى - نبّه لأي أساليب تسمية غير واضحة من أول نظرة - حدّد نقاط البداية، أي الملفات التي تبدأ منها الأمور ### 4. الاتصالات وتدفق البيانات — كيف تتكلم الأجزاء مع بعضها تتبّع حركة البيانات داخل النظام. - اختر 2 إلى 3 إجراءات أساسية يسويها المستخدم، مثل: تسجيل مستخدم جديد، أو تنفيذ طلب - لكل إجراء، امشِ على الرحلة كاملة خطوة بخطوة: «عندما يضغط المستخدم زر إرسال الطلب، هذا ما يحدث خلف الكواليس: 1. الزر يشغّل دالة في [file] — تخيّلها كأنها جرس انضغط 2. صوت الجرس يوصل إلى api_route — المطبخ سمع الطلب 3. المطبخ يتأكد من [database] — هل عندنا المكونات؟ 4. إذا نعم، يرجع تأكيد — والموظف يسلّم الفاتورة للعميل» - اشرح الاتصالات مع الخدمات الخارجية، مثل الدفع، البريد الإلكتروني، أو APIs، ووش يصير إذا تعطلت - اشرح مسار تسجيل الدخول والتحقق من الهوية: كيف يعرف التطبيق أنت مين؟ ### 5. اختيارات التقنية — صندوق العِدد لكل تقنية أو مكتبة أو خدمة مهمة مستخدمة: - ما هي؟ جملة واحدة بدون تعقيد - وش وظيفتها في هذا المشروع تحديدًا - لماذا اختيرت بدل البدائل، وكن محددًا: نستخدم Supabase بدل Firebase لأن... - أي حدود أو تنازلات لازم نعرفها - أثرها على التكلفة: مجانية؟ مدفوعة؟ حسب الاستخدام؟ بالريال أو حسب تسعيرة الخدمة إن وجدت استخدم هذا الجدول: | التقنية | وش تسوي هنا | ليش اخترناها | انتبه من | |-----------|------------------|-------------|---------------| ### 6. البيئة والإعدادات اشرح الإعدادات بدون افتراض معرفة تقنية مسبقة: - ما هي متغيرات البيئة الموجودة، ووش يتحكم فيه كل واحد بلغة بسيطة - كيف تختلف البيئات: التطوير، التجربة، الإنتاج - «إذا احتجت تغيّر [X]، تعدّل [Y] — لكن انتبه لأن [Z]» - أي أسرار أو مفاتيح API، وأي خدمات ترتبط بها، بدون ذكر القيم الفعلية ### 7. الدروس المستفادة — قصص من أرض المشروع هذا أهم قسم في المستند. وثّق: **الأخطاء والإصلاحات:** - أبرز الأخطاء التي ظهرت أثناء التطوير - وش كان سببها، بشرح بسيط - كيف انحلت - كيف نتجنب مشاكل مشابهة مستقبلًا **المطبات والألغام:** - أشياء شكلها بسيطة لكنها فعليًا معقدة - «إذا احتجت تغيّر [X]، انتبه لأنه يؤثر أيضًا على [Y] و [Z]» - الديون التقنية المعروفة، ولماذا موجودة **الاكتشافات:** - تقنيات أو أساليب جديدة تم تجربتها - وش نجح ووش ما ناسب - «لو كنت ببدأ من جديد، كنت بسوي...» **حكمة هندسية:** - أفضل الممارسات التي ظهرت من هذا المشروع - الأنماط التي أثبتت اعتماديتها - كيف يفكر المهندسون أصحاب الخبرة في مثل هذه المشاكل ### 8. بطاقة مرجعية سريعة أضف بطاقة اختصار في نهاية المستند: - كيف تشغّل المشروع محليًا خطوة بخطوة، وافترض أن الشخص يبدأ من الصفر - الروابط المهمة: الإنتاج، التجربة، لوحات التحكم، لوحات البيانات - مين أو وين تروح إذا شيء تعطل - أكثر الأوامر استخدامًا ## قواعد الكتابة — غير قابلة للتفاوض 1. **لا تستخدم مصطلحات تقنية بدون شرح.** أي مصطلح تقني يظهر لأول مرة لازم يجي معه شرح مباشر بلغة بسيطة أو تشبيه. بعد ذلك تقدر تستخدم المصطلح، لكن لازم يكون القارئ فهمه. 2. **استخدم التشبيهات بكثافة.** شبّه الأنظمة بالمطاعم، مكاتب البريد، المكتبات، المصانع، الفرق الموسيقية — أي شيء يساعد الفكرة توصل. التشبيه لازم يكون متسق داخل القسم الواحد، لا تبدأ بمطعم ثم تتحول لمستشفى في نفس الشرح. 3. **احكِ قصة السبب.** لا توثّق الموجود فقط. اشرح لماذا اتخذت القرارات، ما البدائل التي كانت ممكنة، وما التنازلات المقبولة. مثال: اخترنا X لأن Y، مع أن هذا يعني أننا قد لا نستطيع تنفيذ Z بسهولة لاحقًا. 4. **خلّ النص ممتعًا.** استخدم أسلوبًا حواريًا، أسئلة بلاغية، وخفة دم بسيطة إذا كانت مناسبة. هذا المستند لازم يكون شيء الواحد يبي يقرأه، مو شيء مفروض عليه. إذا كان القسم مملًا، أعد كتابته لين يصير واضح وممتع. 5. **كن صريحًا بشأن المشاكل.** وضّح الديون التقنية، المشاكل المعروفة، والقرارات التي اتخذت بسبب ضغط الوقت. هذا المستند يصير أكثر فائدة إذا كان صادقًا، مو إذا كان ملمّعًا. 6. **أضف: وش ممكن يخرب؟ لكل نظام رئيسي.** الهدف مو التخويف، الهدف الاستعداد. مثال: إذا تعطلت خدمة الدفع، هذا ما يحدث، وهذا ما يجب فعله. 7. **استخدم التدرج في الشرح.** ابدأ كل قسم بالنسخة البسيطة، ثم تعمّق. القارئ لازم يقدر يوقف عند أي نقطة ويبقى عنده فهم مفيد. 8. **نسّق النص ليكون سهل التصفح.** استخدم العناوين، إبراز الكلمات المهمة، فقرات قصيرة، ونقاط للقوائم. لكن استخدم السرد والنثر في الشروحات والقصص، لا تجعل كل شيء نقاطًا. ## مثال على النبرة المطلوبة خطأ — جاف ومليء بالمصطلحات: «التطبيق يطبّق server-side rendering مع incremental static regeneration، باستخدام Next.js App Router و React Server Components لتحسين TTFB.» صح — واضح وممتع: «عندما يزور شخص موقعنا، السيرفر يجهّز الصفحة قبل ما يرسلها له — مثل مطعم يجهّز طلبك قبل وصولك بدل ما يبدأ من الصفر بعد ما تجلس. هذا يسمى server-side rendering، أي أن الصفحة تُبنى من جهة السيرفر، وهذا أحد أسباب سرعة تحميل الصفحات. نستخدم Next.js App Router لهذا الغرض، وهو مثل نظام تشغيل المطبخ الذي يقرر وش يتجهز مسبقًا ووش يُطبخ حسب الطلب.» خطأ — قائمة بلا سياق: «Dependencies: React 18, Next.js 14, Tailwind CSS, Supabase, Stripe» صح — شرح الفريق: «تخيّل التقنيات المستخدمة كفريق عمل، كل واحد له دور واضح: - **React** هو مصمم الواجهة — يبني كل شيء تشوفه على الشاشة - **Next.js** هو مدير المسرح — ينظم متى وكيف تظهر الأشياء - **Tailwind** هو مسؤول الشكل واللبس — يتكفل بالتنسيق البصري والتصميم - **Supabase** هو موظف الأرشيف — يحفظ البيانات ويرجعها وقت الحاجة - **Stripe** هو الكاشير — يتعامل مع المدفوعات بشكل آمن»