# WP1 — BE: "issued to a production order" report endpoint + cost permission

## Goal
A warehouse report: for a chosen production order (+ optional date range), list per material how much was issued to it — quantity, unit, planned-vs-issued, إذن-صرف numbers/dates, and cost — with cost gated by a NEW permission so the storekeeper can see the report without cost.

## Exact files
- `Modules/Inventory/app/Http/Controllers/InventoryReportController.php` — add method `productionOrderIssues()` (mirror the shape/company-scoping of the existing `movementSummary()`/`warehouseSummary()` methods; the controller middleware already gates all methods with `permission:inventory.reports.view`).
- `Modules/Inventory/routes/api.php` — add `Route::get('reports/production-order-issues', [InventoryReportController::class, 'productionOrderIssues'])->name('reports.production-order-issues');` next to the other `reports/*` routes (~lines 94-98).
- `Modules/Core/database/seeders/RolePermissionSeeder.php` — add a new permission `inventory.reports.production_issue_cost` to the master `$allPermissions` catalog (near `'inventory.reports.view'` at ~line 695) AND grant it to the roles that should see cost: owner (auto — gets full catalog), manager, accountant, and `production_cost_accountant` if that role exists. Do NOT grant it to plain warehouse/storekeeper roles (cashier, warehouse_storekeeper). Additive, non-breaking.
- Tests: `Modules/Inventory/tests/Feature/InventoryReportApiTest.php` — extend.

## Data (confirmed)
- `MfgMaterialIssue` (cols: production_order_id, inventory_issue_id, issued_at, issued_by) has many `MfgMaterialIssueLine` (product_id, quantity `decimal:3`, unit_id, unit_cost `decimal:4`).
- `inventory_issues.issue_number` = the إذن-صرف number (join via `mfg_material_issues.inventory_issue_id`).
- `production_order_materials` (product_id, planned_quantity, consumed_quantity, unit_id) for the planned column.
- Company scope: `auth()->user()->company_id` on every query.

## Endpoint contract
`GET /api/inventory/reports/production-order-issues?production_order_id={id}&from={date}&to={date}`
- `production_order_id` required (validate exists + belongs to company). `from`/`to` optional (filter on `mfg_material_issues.issued_at`).
- Response 200 JSON:
  ```
  {
    "data": {
      "production_order": { "id", "order_number", "product_name" },
      "materials": [
        { "product_id", "product_name", "product_code", "unit_name",
          "planned_quantity", "issued_quantity",
          "unit_cost"?, "total_cost"?,        // present ONLY if user has cost permission
          "issue_numbers": ["ISS-..."], "last_issued_at" }
      ],
      "totals": { "issued_quantity", "total_cost"? },   // total_cost only with permission
      "can_view_cost": true|false
    }
  }
  ```
- Aggregate `MfgMaterialIssueLine` per product across all the order's issues; sum quantity; sum (quantity×unit_cost) for total_cost; join planned_quantity from production_order_materials; collect distinct issue_numbers + max issued_at.
- **Cost gating:** compute `canViewCost = auth()->user()->can('inventory.reports.production_issue_cost')` (or `hasPermissionTo`). When false, OMIT `unit_cost`, `total_cost`, and `totals.total_cost` from the payload (do not send zeros — omit the keys), and set `can_view_cost=false`. The FE reads `can_view_cost` to hide the columns.

## Acceptance
- For an order with issues → per-material rows with correct issued_quantity (sum of that order's MfgMaterialIssueLine.quantity per product) + planned_quantity + issue_numbers.
- User WITH `inventory.reports.production_issue_cost` → cost fields present + `can_view_cost:true`.
- User WITHOUT it → cost fields absent + `can_view_cost:false` (report still returns quantities).
- Company isolation: an order from another company → 404/403; materials never leak across companies.
- Date filter narrows by issued_at.

## Tests (Pest, sqlite — CLI php `/opt/cpanel/ea-php82/root/usr/bin/php artisan test`)
- report returns per-material issued qty + planned for an order.
- cost present with permission, ABSENT without (assert keys missing).
- company isolation (other-company order rejected; no cross-company material rows).
- date filter.
Baseline: `InventoryReportApiTest` currently green — keep it green.

## Flags
- Money read only (no GL). migration: permission seed only (no schema migration). Conventional commit `feat(inventory): ...` on hazemdev2. No FE, no deploy, no main.

## Verify before reporting back (Codex self-check)
- Run `/opt/cpanel/ea-php82/root/usr/bin/php artisan test Modules/Inventory/tests/Feature/InventoryReportApiTest.php` — green.
- `php -l` clean; `./vendor/bin/pint` on changed files.
- Report: commit SHA, the exact response shape, the permission name, which roles were granted, test counts.