# WP3 — تقرير «المنصرف حسب الوسم»

**التذكرة:** ISS-2026-9296 · **الريبو:** BE · **migration: لا**

## الهدف — ده جوهر الطلب
العميل قال حرفيًا: «هو مثلًا **صرف 5 مرات في اليوم على نفس الشغلانة** يعرف يراقب هو بيعمل إيه».
⇒ التقرير لازم يوضّح **عدد مرات الصرف** و**الأصناف والكميات** لكل وسم، بفترة، ويفتح على التفصيل.

## ⭐ فيه تقرير أخ موجود — **اقيس عليه بالظبط، ماتخترعش نمطًا جديد**
`Modules/Inventory/app/Http/Controllers/InventoryReportController.php::productionOrderIssues()` (:189+) ومساره `reports/production-order-issues` (`routes/api.php:109`) — تقرير «المنصرف على أمر إنتاج» من ISS-2026-9165. **نفس فكرة تقريرنا بالظبط**، وفيه القرارات اللي محتاجينها متّخذة أصلًا:
- تحقّق بـ`request()->validate()` مع `from`/`to` و`after_or_equal:from`.
- **company-scope للكيان نفسه الأول** ⇒ كيان شركة تانية أو id غلط = **404**، مفيش تسريب بين المستأجرين.
- **الأعمدة المالية خلف صلاحية:** `$canViewCost = auth()->user()->can('inventory.reports.production_issue_cost')` — «أمين المخزن يشوف الكميات بس».
- استعلام query-builder مع استبعاد الصفوف المحذوفة ناعمًا صراحةً.

⇒ **قرار العميل «الكميات أساسي والقيمة عمود اختياري» بيتنفّذ بنفس البوابة دي بالظبط** — مش خيار في الواجهة، صلاحية. استعمل **نفس الصلاحية الموجودة** لو مناسبة، أو صلاحية أخت بنفس التسمية لو الأنسب — قرّر واشرح.

## الملفات
- `Modules/Inventory/app/Http/Controllers/InventoryReportController.php` — دالتان جديدتان (**ماتلمسش الدوال الموجودة**).
- `Modules/Inventory/routes/api.php` — مساران جنب مسارات `reports/*` الموجودة.
- اختبار: وسّع/أضف تحت `Modules/Inventory/tests/Feature/`.

## المسارات
**1. الملخّص — `GET /api/inventory/reports/issue-tags`**
لكل وسم في الفترة:
- `tag_id` · `name` (المحلّي) · `status`
- **`issues_count`** ← عدد أذون الصرف (**دي الرقم اللي العميل بيدوّر عليه**)
- `items_count` (عدد الأصناف المتمايزة) · `total_quantity`
- `first_issue_date` · **`last_issue_date`**
- `total_value` ← **فقط لو الصلاحية متوفّرة**
فلاتر: `from` · `to` · `status` (نشط/مقفول/الكل) · `search`. مصفّح ومرتّب (افتراضي: الأكثر صرفًا أو الأحدث — قرّر واشرح).

**2. التفصيل — `GET /api/inventory/reports/issue-tags/{tag}`**
كل أذون الصرف على الوسم ده في الفترة: رقم الإذن · التاريخ · المخزن · الحالة · الأصناف والكميات · القيمة (بالصلاحية). company-scoped ⇒ وسم شركة تانية = **404**.

## قواعد الحساب — لازم تكون صريحة
- المصدر: `inventory_issues` بـ`reference_type = 'job_tag'` و`reference_id = tag.id`، مربوطة بسطورها.
- ⚠️ **أي حالات أذون تتحسب؟** الإذن المعتمَد/المرحَّل هو اللي فعلًا خرجت خامته. المسودة والملغي **مايتحسبوش** في الكميات.
  - **قرار مطلوب منك:** حدّد الحالات المحسوبة صراحةً (اتفرّج على `IssueStatus`)، **واشرح اختيارك في التقرير وفي تعليق في الكود**، وخلّي فيه **اختبار** يثبّت إن الملغي مابيتحسبش.
- الحذف الناعم مستبعد صراحةً (أذون وسطور).
- الوسم اللي **اتقفل** لسه بيظهر في التقرير بتاريخه (الأرشيف قرار العميل رقم 4) — **مايختفيش**.

## معايير القبول
1. **5 أذون معتمدة على نفس الوسم في يوم ⇒ `issues_count = 5`** بالأصناف والكميات الصح. ← اختبار قبول المالك الحرفي.
2. من غير صلاحية القيمة: **مفيش أي حقل قيمة في الرد إطلاقًا** (مش صفر — **غايب**).
3. وسم شركة تانية ⇒ 404. القائمة company-scoped.
4. فلتر الفترة بيقصّ صح على الحدّين.
5. الوسم المقفول لسه ليه تقرير.

## الاختبارات
5 أذون على وسم واحد ⇒ العدّاد 5 · إذن **ملغي** مابيتحسبش · **إذن مسودة** مابيتحسبش · فلتر الفترة بيستبعد اللي بره · **القيمة غايبة بلا صلاحية وموجودة معاها** · company-scope في الملخّص والتفصيل (404 لوسم شركة تانية) · وسم مقفول لسه ليه تقرير · وسم بلا أذون ⇒ صفوف صفرية أو غياب (قرّر واشرح، وثبّته باختبار).

**شغّل بـCLI php صراحةً** (الافتراضي php-cgi وبيقتل الرَنَر بصمت — exit 255 بلا مخرجات):
```bash
cd /home/moonui2/moon-erp-be && /opt/cpanel/ea-php82/root/usr/bin/php -d memory_limit=1G vendor/bin/pest Modules/Inventory/tests
```
**الأساس:** Inventory **564 نجاح / 1 فشل سابق** + اللي WP2 ضافه (اقرا العدد الفعلي من آخر تشغيل في `LEDGER.md` قبل ما تبدأ). **صفر فشل جديد.**

## خارج النطاق
- ⛔ أي واجهة · ⛔ تصدير Excel/PDF (لاحقًا لو طلبه) · ⛔ أي أثر محاسبي · ⛔ تعديل الدوال الموجودة في نفس الكونترولر.

## بعد الانتهاء
`./vendor/bin/pint` **على الملفات الملموسة بس** (⚠️ متشغّلوش على الموديول — لوّث 41 ملف قبل كده) + `chown moonui2:moonui2` + `bash local-deploy.sh`. **بلا commit وبلا git.**