---
name: schoolos-report-ar
description: |
  مولّد التقارير الرسمية العربية (RTL) لمنصة SchoolOS — PDF عبر core.pdf_utils.render_pdf
  (WeasyPrint) وExcel عبر reports.services.ExcelService (openpyxl، rightToLeft). يضمن ترويسة
  موحّدة بشعار دولة قطر ووزارة التعليم، ترقيم «صفحة X من Y»، تذييل سرّية وتاريخ هجري/ميلادي،
  خطوط عربية صحيحة، وجداول تُطبع على A4/A3 دون كسر الاتجاه. استخدمها دائماً وتلقائياً عند: طلب
  تقرير/كشف/شهادة/بيان رسمي، توليد PDF أو Excel عربي، أو تنسيق مستند للطباعة. Trigger on:
  report, تقرير, كشف, شهادة, PDF عربي, Excel, طباعة, RTL, ترويسة رسمية, بيان درجات, print.
---

# مولّد تقارير SchoolOS الرسمية

> الهدف: كل تقرير يخرج **رسمياً ومتّسقاً وقابلاً للطباعة** بهوية الدولة، ويعيد استخدام محرّكات
> المشروع القائمة لا يخترعها. أي مخرج رسمي يُحتمل أن يُوقَّع ويُختم — الدقّة والاتّساق إلزاميان.

المسار الوحيد: `D:\shschool_mvp` مباشرة.

---

## 1. لا تعِد اختراع المحرّك — أعِد استخدامه

| المخرج | المحرّك الفعلي | كيف |
|--------|----------------|-----|
| PDF | `core.pdf_utils.render_pdf(html, filename, paper_size)` | تبني HTML بقالب Django ثم تمرّره — WeasyPrint أساسي، Playwright/xhtml2pdf احتياطي |
| Excel | `reports.services.ExcelService` / `AcademicReportsExcel` | openpyxl مع `ws.sheet_view.rightToLeft = True` وترويسة الهوية القطرية |
| بيانات التقرير | `reports.services.ReportDataService` / `AcademicReportsService` | تجهيز البيانات (محسّن، بلا N+1) قبل التصيير |

نمط الـ view الحقيقي (`reports/views.py`):
```python
from core.pdf_utils import render_pdf
html = render_to_string("reports/class_results.html", context)
return render_pdf(html, f"نتائج_{class_grp.get_grade_display()}_{year}.pdf", paper_size="A4")
```

عند بناء قالب جديد، ابدأ من `assets/report_template.html` في هذه المهارة (RTL + @page + ترويسة/
تذييل لكل صفحة + خطوط عربية) وعبّئ منطقة المحتوى فقط.

---

## 2. عقد التقرير الرسمي (كل تقرير يلتزم به)

للتفاصيل الكاملة والقياسات: `references/report-contract.md`. الملخّص:

**الترويسة (كل صفحة)**: شعار دولة قطر (يمين) · اسم الوزارة + المدرسة (وسط) · شعار/رقم المدرسة
(يسار) · سطر عنوان التقرير · العام الدراسي والفصل.

**المحتوى**: عنوان واضح → بيانات وصفية (الصف، المادة، المعلّم، التاريخ) → جدول/بيانات →
ملخّص/إجماليات → مكان التوقيع والختم.

**التذييل (كل صفحة)**: تصنيف السرّية (مثال: «سرّي — للاستخدام الرسمي») · التاريخ (ميلادي +
هجري عند اللزوم) · «صفحة X من Y» · بصمة التوليد (المنصة + الوقت).

---

## 3. قواعد RTL والطباعة (لا تُكسر)

- **الاتجاه**: `dir="rtl"` على `<html>`، ومحاذاة منطقية `text-align: start` — لا `left/right`
  صريحة، اتّساقاً مع معيار المشروع (Logical properties: `margin-inline`, `padding-inline`).
- **الأرقام**: استخدم أرقاماً عربية-هندية أو لاتينية باتّساق داخل التقرير الواحد — لا تخلط.
  الجداول الرقمية (درجات) تُحاذى وسطاً.
- **الخطوط** (بالأولوية): Noto Sans Arabic · IBM Plex Sans Arabic · Cairo · Sakkal Majalla.
  تُحمّل عبر `@font-face` من مجلد الخطوط (WeasyPrint يحتاج مساراً فعلياً — انظر `core/pdf_utils`).
- **الجداول العريضة**: إن تجاوزت عرض A4، انتقل إلى A3 (`paper_size="A3"`) بدل تصغير الخط تحت
  الحدّ المقروء (≥ 9pt للبيانات). كرّر رأس الجدول على كل صفحة: `thead { display: table-header-group }`.
- **الهوامش**: 20mm قياسي؛ هامش تجليد 30mm يمين (RTL). المنطقة الآمنة A4 ≈ 170×257mm.
- **فواصل الصفحات**: `page-break-inside: avoid` على صفوف الجدول والبطاقات؛ لا تقطع طالباً بين صفحتين.

---

## 4. Excel رسمي (reports/services.py)

```python
ws.sheet_view.rightToLeft = True              # إلزامي — الورقة من اليمين
# ترويسة الهوية: شعار + عنوان مدموج + ألوان الدولة (كما في ExcelService._add_professional_header)
# تجميد الصفوف العلوية: ws.freeze_panes = "A4"
# عرض أعمدة يناسب المحتوى العربي؛ wrap_text=True؛ محاذاة center للأرقام، start للنصوص
```
أعِد استخدام أنماط `ExcelService` (Font/Alignment/Border/PatternFill) بدل تعريف جديد، لتبقى
كل ملفات المنصة متطابقة الهوية.

---

## 5. الأداء والامتثال

- **جهّز البيانات محسّنةً** عبر `ReportDataService` (select_related/prefetch_related) — تقرير على
  مئات الطلاب يجب ألا يُصدر N+1 (راجع مهارة nplus1-hunter).
- **التوليد الثقيل** (كشوف مدرسة كاملة) → مهمة Celery وتنزيل لاحق، التزاماً بقاعدة >300ms.
- **PDPPL**: التقرير قد يحوي بيانات قُصّر — لا تُدرج حقلاً شخصياً (national_id/هاتف/بيان صحي) إلا
  إذا كان التقرير يستوجبه ولمن يملك الصلاحية. صنّف السرّية في التذييل (راجع مهارة pdppl-pii-audit).
- **أسماء الملفات**: عربية وصفية كما في المشروع (`نتيجة_<اسم>_<العام>.pdf`).

## 6. قائمة تحقّق قبل التسليم
- [ ] الترويسة والتذييل يظهران على **كل** صفحة، والترقيم «X من Y» صحيح.
- [ ] لا كسر اتجاه ولا حروف عربية مقطّعة (خطّ محمّل صحيح).
- [ ] الجدول لا يُقطع طالباً بين صفحتين؛ الرأس يتكرّر.
- [ ] جُرّب على A4 وعلى بيانات فارغة (حارس: reportlab يفشل مع جدول فارغ — عالِجه).
- [ ] لا PII غير مبرّر؛ تصنيف السرّية موجود.
- [ ] Excel: `rightToLeft=True` + تجميد الرأس + هوية موحّدة.