# Task 16 — Stock Report

## Goal
Build the Stock Report module to show stock balances by item and warehouse.
This report should summarize inventory quantities and optionally values based on stock movements.

---

## Scope

This task covers:
- stock balance query logic
- filters by branch / warehouse / item
- report UI
- summary of quantities and optional values

This task does NOT cover:
- real-time costing engine
- inventory aging
- export implementation
- advanced dashboard widgets

---

## Data Source

Primary source table:
- `stock_movements`

Supporting tables:
- `items`
- `warehouses`
- `branches`

---

## Required Output

For each row:
- item_code
- item_name
- warehouse_name
- total_in
- total_out
- net_quantity
- average_unit_cost (optional if available)
- stock_value (optional if available)

---

## Business Rules

1. Stock Report must summarize from `stock_movements`.
2. `in` movements increase quantity.
3. `out` movements decrease quantity.
4. `adjustment` must be handled according to movement sign strategy used by implementation.
5. Report filters must support:
   - branch_id (optional)
   - warehouse_id (optional)
   - item_id (optional)
6. Item name must use translated JSON field.
7. If no movement exists, row should not appear unless zero-stock mode is added later.

---

## Query Rules

Main joins:
- stock_movements
- items
- warehouses

Suggested grouping:
- item_id
- warehouse_id

Suggested calculations:
- total_in = sum(quantity where movement_type = in)
- total_out = sum(quantity where movement_type = out)
- net_quantity = total_in - total_out +/- adjustments depending on implementation

---

## Files

### Service
- app/Services/Inventory/Reports/StockReportService.php

### Controller
- app/Http/Controllers/Admin/Inventory/StockReportController.php

### Requests
- app/Http/Requests/Admin/Inventory/StockReportFilterRequest.php

### Views
- resources/views/dashboard/inventory/reports/stock_report/index.blade.php

### Lang files
- lang/ar/inventory.php
- lang/en/inventory.php

---

## Permissions

- inventory.reports.stock.view

---

## Validation Rules

- branch_id: nullable, exists:branches,id
- warehouse_id: nullable, exists:warehouses,id
- item_id: nullable, exists:items,id

---

## UI

Views path:
`resources/views/dashboard/inventory/reports/stock_report/`

### Filter fields
- branch
- warehouse
- item
- submit button

### Table columns
- item_code
- item_name
- warehouse
- total_in
- total_out
- net_quantity
- stock_value (optional)

---

## Lang Keys

Suggested keys:
- stock_report
- item_code
- item_name
- warehouse
- total_in
- total_out
- net_quantity
- stock_value
- branch
- filter
- no_data_found

---

## Seeder

Update RolePermissionSeeder with:
- inventory.reports.stock.view

---

## Steps

### Step 1
Create `StockReportFilterRequest`.

### Step 2
Create `StockReportService`.

### Step 3
Create `StockReportController`.

### Step 4
Add routes in `routes/admin.php`.

### Step 5
Create stock report view.

### Step 6
Update lang files.

### Step 7
Update `RolePermissionSeeder`.

---

## Notes for AI

- Follow docs/ai/AI_MASTER_PROJECT.md
- Follow docs/ai/ARCHITECTURE_RULES.md
- Follow docs/ai/DATABASE_SCHEMA.md
- Follow docs/ai/MODULE_STRUCTURE.md
- Execute one step at a time
- Do not modify unrelated files
- Do not generate tests in this task
- Wait for confirmation after each step