أداة إنشاء التقارير

# بناء التقارير

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

المالكون يسحبون الأرقام يدويًا من ثلاثة لوحات تحكم ويحاولون إيجاد القصة بأنفسهم. الهدف هو إنهاء هذا.

## الخطوة 1 — التحقق من وجود تعريف موجود

قبل أي شيء آخر، اقرأ `reference/saved_reports.md` وتحقق مما إذا كان هذا التقرير موجودًا بالفعل. تحقق أيضًا من وجود ملف `report-definitions.md` في دليل العمل — هذا هو المكان الذي تُسجّل فيه التعريفات عندما لا تكون مجلد المهارة قابلة للكتابة (انظر الخطوة 7).

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

إذا لم يطابق شيء، استمر.

## الخطوة 2 — تحويل الوصف إلى مواصفات

يصف المالكون التقارير بصورة فضفاضة: "كل يوم الاثنين، المبيعات حسب الموقع مقابل السنة الماضية، والذمم المدينة المتأخرة، ونسبة العمالة." تحتوي هذه الجملة على أربعة قرارات منفصلة. حلّها إلى مواصفات باستخدام التنسيق في `reference/report_spec.md`:

- **المقاييس** — كل واحد مسمى مع صيغتها ومصدرها - **التجميع** — حسب الموقع أو المنتج أو العميل أو القناة أو الممثل - **المقارنة** — مقابل الفترة السابقة أو مقابل السنة الماضية أو مقابل الهدف - **الفترة** — النافذة الزمنية التي يغطيها كل تشغيل - **التكرار** — لمرة واحدة أو أسبوعي أو شهري أو ربع سنوي

استنتج ما تستطيع بشكل معقول. "المبيعات حسب الموقع مقابل السنة الماضية" يعطيك المقياس والتجميع والمقارنة — لا تسأل عن تلك. اسأل فقط عما هو غامض حقًا، واسأل في دفعة واحدة بدلاً من سؤال واحد في كل مرة.

السؤالان اللذان يستحقان السؤال في كل مرة تقريبًا:

- أي فترة يغطيها كل تشغيل — الشهر التقويمي أم 30 يومًا متأخرة أم حتى نهاية الشهر؟ - هل يُقاس رقم مثل "نسبة العمالة" مقابل الإيراد أم مقابل إجمالي التكاليف؟

الحصول على هذه بشكل خاطئ ينتج تقرير يبدو صحيحًا وهو خاطئ بهدوء، وهذا أسوأ من السؤال.

## الخطوة 3 — تأكيد المواصفات، مرة واحدة

أظهر المواصفات المحل‌ولة في كتلة مضغوطة. اطلب تأكيدًا واحدًا ثم ابدأ البناء. لا تسير مع المالك في المواصفات حقل تلو حقل — لقد وصف هذا في جملة واحدة ويتوقع إجابة واحدة.

إذا صححوا شيئًا، طبقه واستمر. لا تُعيد التأكيد مرة ثانية.

## الخطوة 4 — سحب البيانات

شغّل كل استدعاء مصدر في دفعة متوازية واحدة. انظر `reference/data_sources.md` لتعيين المقياس إلى الأداة.

المصادر، يتم المحاولة في نفس الوقت:

- **دفتر الأستاذ** — MYOB أو NetSuite أو QuickBooks أو Xero أو Zoho Books، أيهما متصل؛ نُظراء لـ `../../shared/connector-neutrality.md`. بنود قائمة الدخل والإيراد والمصروفات وتأخر الذمم المدينة والذمم الدائنة وتقسيمات الفئة والموقع. MYOB هو قائمة الدخل والذمم المدينة والحسابات الدائنة فقط، ثلاث سنوات مالية للخلف. إذا كان دفتا أستاذ متصلان، اسأل أي واحد هو مصدر السجل واحصل على الإجماليات من هذا - **HubSpot** — الصفقات والمراحل والمالكون وتواريخ الإغلاق وقيمة خط الأنابيب - **PayPal و Square و Stripe** — التسويات والرسوم والاسترجاعات وتفاصيل المعاملة - **Shopify** — الطلبات وإيراد مستوى SKU وحالة الوفاء - **Ramp و Expensify** — نفقات بطاقة التفاصيل. كلاهما مصادر القراءة هنا؛ Expensify للقراءة فقط البحث

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

**عدم وجود موصلات على الإطلاق مسار مدعوم وليس فشلاً.** اطلب تصدير CSV أو XLSX واقرأه وابن التقرير المتطابق من الملف. قل ذلك بوضوح: "لا أرى مصدر بيانات متصلاً. صدّر تقرير المبيعات من نظامك وأسقطه هنا — سأبني نفس التقرير من ذلك." المالكون الذين لديهم انتشار أدوات يعيشون في هذا الوضع، والتقرير جيد تمامًا.

## الخطوة 5 — الحساب والتحقق من المعقولية

احسب كل مقياس مسمى في المواصفات. ثم تحقق من النتائج قبل عرضها. اقرأ `reference/gotchas.md` لأنماط الفشل التي تحدث بالفعل.

الفحوصات التي تمسك الأخطاء الحقيقية:

- **حدود الفترة.** شهر حالي جزئي مقابل شهر سابق كامل يبدو دائمًا مثل انهيار. إما قارن مثل بمثل أو سمِّ الفترة الجزئية صراحة. - **العد المزدوج.** طلب Shopify وتسويته Stripe هما بيع واحد. إذا كان كلا المصدرين متصلاً، اختر واحدًا كمصدر الإيراد وحدد أي واحد. - **مجموعات فارغة.** الموقع بدون مبيعات في هذه الفترة يجب أن يظهر بصفر وليس أن يختفي. الصف الذي يختفي يُقرأ كمشكلة بيانات. - **الإجماليات التي لا تتطابق.** إذا لم تُجمع الصفوف المجمعة إلى الإجمالي، قل ذلك بدلاً من نشر رقم لا تستطيع الدفاع عنه.

## الخطوة 6 — التسليم

عنصران دائمًا، بهذا الترتيب.

**ملخص الدردشة يأتي أولاً.** اتبع `reference/output_template.md`. ابدأ بما تغير وماذا يعني، وليس بتفريغ جدول. طلب المالك تقريرًا لأنه يريد قرارًا وليس جدول بيانات.

قواعد الكتابة، نفسها كما هو الحال في كل مهارة إبلاغ في هذا المكون الإضافي:

- الأرقام في الصدارة والكلمات بعدها. ليس "كانت المبيعات قوية" — "USD 43,200، بزيادة 8% مقابل السنة الماضية." - كل رقم يحمل مقارنته.