ربط الغرامة اليومية بتأخيرات البنود
Backend
The contractor contract has a daily_penalty_rate. For each project item linked to this contract that has delay_days > 0, compute penalty_amount = delay_days × daily_penalty_rate and store it in a contractor_penalties table with fields: contract_id, project_item_id, delay_days, penalty_amount, status (pending / skipped / deducted). Expose an endpoint to list penalties per contractor and another to mark a penalty as skipped or deducted. When deducted, reduce the net payable in the contractor's account statement accordingly.
--------
الجدول الزمني — التواريخ الخاطئة وأيام التأخير
Bug
The timeline endpoint returns planned_start_date: null / planned_end_date: null while the actual planned values are stored in start_date / end_date. Fix the field mapping in the serializer/resource. Additionally: record actual_start_date automatically when an item transitions to in-progress; record actual_end_date when the item is marked complete (on final مستخلص). Fix delay_days which always returns 0 — compute it as max(0, actual_end_date - planned_end_date) in calendar days.
--------------
الجدول الزمني — المقاول المسؤول يُرجع null
Bug
Timeline items return "contractor": null, "contractor_name": null even when a contractor is assigned. Ensure the timeline query eager-loads the contractor relationship on project items. Verify the foreign key, relationship definition on the model, and that the resource serializer maps contractor.id and contractor.name (plus trade_name if available) into the response correctly.
--------------------
مبالغ المستخلص — total_due و net_amount خاطئان
Bug
GET /api/v1/projectFlow/invoice?status=pending returns wrong amounts ignoring retention and tax. Fix the calculation server-side: gross_amount = approved items × unit prices. retention_amount = gross_amount × contract.retention_percentage. tax_amount = computed per contract tax setting. net_amount = gross_amount - retention_amount + tax_amount. total_due = net_amount - paid_amount. All fields must be computed and returned correctly in the listing endpoint.

----------------------------------------

1. خطأ التحقق من صحة المواد عند تحديث بنود تقدير التكلفة
Fix a 422 validation error on the resources-item/update endpoint when updating materials in a cost estimate phase.

**Endpoint:** POST /resources-item/update

**Current Behavior:**
The request fails with:
"The selected materials.0.material_id is invalid."

Even though material_id: 35 exists in the system, the backend validation rejects it.

**Payload sent:**
{
  type: "materials",
  item_phase_id: 1,
  project_id: 1,
  cost_estimate_id: "1",
  project_phase_id: 1,
  materials: [
    {
      id: 1,
      material_id: 35,
      quantity: "50.0000",
      unit_price: 20,
      error_margin: "0.0000",
      unit_id: 35,
      expected_delivery_time: "2026-04-20",
      notes: "",
      supplier_id: null,
      total_cost: "1000.00"
    }
  ]
}

**Expected Behavior:**
The material with material_id: 35 should pass validation and the update should succeed.

**Investigation Steps:**
1. Locate the FormRequest or validation rules used in the resources-item/update endpoint.
2. Check if the validation rule for materials.*.material_id uses a `exists:` rule and whether it scopes by company_id, project_id, or any other tenant scope that might be excluding the material.
3. Check whether the material with id 35 belongs to the correct company scope (multi-tenant global scope may be filtering it out during validation).
4. If the validation uses a custom Rule or closure, inspect whether it queries the correct model/table with the correct scopes.
5. Fix the validation rule so it correctly resolves the material within the active tenant scope.

Do not change unrelated validation rules. Only fix the material_id validation logic.

----------------------------------------

2. مستخلص المقاول يعيد سعر الوحدة من تقديرات التكلفة بدلاً من عقد المقاول
Fix incorrect unit_price returned inside item_phase data when fetching contractor invoice details.

**Endpoint:** GET /projectFlow/invoice/{id}  (e.g. invoice id: 2)

**Current Behavior:**
The response returns "unit_price": 15 inside the item_phase object, but this value is being pulled from the cost estimate, not from the contractor contract.

**Expected Behavior:**
The unit_price inside item_phase should reflect the price agreed upon in the contractor's contract for that item, not the cost estimate price.

**Investigation Steps:**
1. Locate the resource/transformer or Eloquent query responsible for building the item_phase object in the contractor invoice response.
2. Identify where unit_price is being resolved — it is likely reading from the cost_estimate_items or item_phases table directly instead of from the contractor contract items table (e.g. contractor_contract_items or equivalent).
3. Check if there is a relationship between the invoice → contract → contract items that should be used to resolve unit_price.
4. Fix the data source so that unit_price (and any other price fields like total_cost) inside item_phase are taken from the contractor contract, falling back to cost estimate only if no contract exists.
5. Ensure the fix applies consistently for all items returned in the invoice detail response.

Do not change the response structure or other fields. Only correct the source of unit_price resolution.

----------------------------------------

3. القيم المالية الإجمالية في صفحة عرض مستخلص المقاول خاطئة
Fix incorrect financial summary values returned in the contractor invoice view.

**Endpoint:** GET /projectFlow/invoice/{id}  (e.g. invoice id: 2)

**Current Behavior:**
The following financial fields are returning wrong values:
- التكلفة الإجمالية (Total Cost): 500.00  ← incorrect
- قيمة الأعمال السابقة (Previous Works Value): 0.00  ← should reflect prior invoices
- قيمة الأعمال المتبقية (Remaining Works Value): 9,500.00  ← incorrect
- قيمة الأعمال المستحقة (Due Works Value): 500.00  ← incorrect
- قيمة العقد (Contract Value): 10,000.00  ← may or may not be correct
- قيمة الضريبة (Tax Value): 0.00
- الإجمالي مع الضريبة (Total with Tax): 500.00
- الدفعة المقدمة (Advance Payment %): 0.00
- المبلغ المدفوع (Amount Paid): 0.00
- الخصومات (Discounts): 0.00
- المبلغ المطلوب (Requested Amount): 500.00

Also in the progress summary:
- العمل المتبقية (Remaining Work): 2,150.00 USD — Total Quantity: 20.00  ← incorrect

**Root Cause Hypothesis:**
These values are likely being computed using unit_price from cost estimates instead of contractor contract prices (see related bug above). Fix unit_price source first, then verify if these values are recalculated correctly.

**Investigation Steps:**
1. Locate the service or calculation class responsible for computing the financial summary fields of a contractor invoice.
2. Verify each field's formula:
   - Total Cost = sum of (quantity * unit_price from contract) for all invoice items
   - Previous Works Value = sum of total costs of all prior approved invoices for the same contract
   - Remaining Works Value = Contract Value - Total Cost of all invoices including current
   - Due Works Value = current invoice total
   - Requested Amount = Due Works Value - Advance Deduction - Discounts
3. Fix any formula that uses the wrong price source or wrong aggregation scope.
4. Ensure "Previous Works Value" correctly queries all previously submitted/approved invoices for the same contractor and project, excluding the current invoice.
5. Ensure currency and exchange rate are applied consistently across all fields.

Do not alter the response schema. Only fix the calculation logic and data sources.

----------------------------------------

4. تقرير تقدم بنود المشروع لا يعيد أي بيانات
Fix empty results returned by the project items progress report endpoint.

**Endpoint:** GET /project/items-progress-report?contractor_id=1&project_id=1&page=1

**Current Behavior:**
The response returns empty results even though there are cost estimate items and contractor invoices for this project:
{
  "success": true,
  "code": 200,
  "message": "OK",
  "to": null,
  "page": 0,
  "pages": 0,
  "count": 0,
  "result": []
}

**Expected Behavior:**
The endpoint should return a paginated list of project items with their progress data including:
- Item name and phase
- Total planned quantity
- Executed quantity per invoice
- Cumulative executed quantity
- Remaining quantity
- Unit price (from contractor contract)
- Financial values per item

**Investigation Steps:**
1. Locate the controller method and query responsible for this endpoint.
2. Check the base query — it likely queries item_phases or cost_estimate_items joined with contractor invoice items. Inspect whether:
   a. The contractor_id filter is being applied to the wrong relationship or column.
   b. The project_id filter is scoped correctly against the items table.
   c. A required join or whereHas condition is too restrictive and silently excludes all records.
3. Check if the query depends on a contractor contract existing and linked — if no contract is linked yet but invoices exist directly, the query may return nothing.
4. Add debug logging or dd() temporarily to inspect the generated SQL and verify which condition is causing the empty result.
5. Fix the query so it correctly returns all items that have progress entries (invoice items) for the given project and contractor.
6. Ensure pagination metadata (page, pages, count, to) is populated correctly after the fix.

Do not change the response structure. Only fix the data retrieval logic.