# Task 15 — Stock Movements

## Goal
Build the Stock Movements module to record inventory in/out/adjustment operations.
This module will be the transactional layer of inventory and will support future stock reports and financial integration.

---

## Database

Table: `stock_movements`

Fields:
- id
- movement_number (string, unique)
- movement_date (date)
- movement_type (string)
  - in
  - out
  - adjustment
- warehouse_id (FK to warehouses.id)
- item_id (FK to items.id)
- quantity (decimal 18,2)
- unit_cost (decimal 18,2, nullable)
- total_cost (decimal 18,2, nullable)
- reference_type (string, nullable)
- reference_id (unsignedBigInteger, nullable)
- notes (json, nullable, translatable)
- branch_id (nullable, FK to branches.id)
- created_by (nullable, FK to admins.id)
- updated_by (nullable, FK to admins.id)
- created_at
- updated_at

Indexes:
- unique movement_number
- index movement_date
- index movement_type
- index warehouse_id
- index item_id
- index branch_id
- index reference_type
- index reference_id

---

## Relations

StockMovement model relations:
- warehouse() -> belongsTo Warehouse
- item() -> belongsTo Item
- branch() -> belongsTo Branch
- creator() -> belongsTo Admin
- updater() -> belongsTo Admin

---

## Business Rules

1. Movement number must be unique and generated using NumberSequenceService.
2. Movement type must be one of: in, out, adjustment.
3. Only stock items can be used in stock movements.
4. Quantity must be greater than zero.
5. `out` and `adjustment` may later affect stock balances and financial posting.
6. Notes must use HasTranslations if stored.
7. Total cost may be calculated as quantity * unit_cost.
8. Branch should usually match warehouse branch when applicable.

---

## Files

### Model
- app/Models/Inventory/StockMovement.php

### Service
- app/Services/Inventory/StockMovementService.php

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

### Requests
- app/Http/Requests/Admin/Inventory/StoreStockMovementRequest.php
- app/Http/Requests/Admin/Inventory/UpdateStockMovementRequest.php

### Views
- resources/views/dashboard/inventory/stock_movements/index.blade.php
- resources/views/dashboard/inventory/stock_movements/create.blade.php
- resources/views/dashboard/inventory/stock_movements/edit.blade.php
- resources/views/dashboard/inventory/stock_movements/show.blade.php

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

---

## Permissions

- inventory.stock.view
- inventory.stock.create
- inventory.stock.update
- inventory.stock.delete
- inventory.stock.adjust

---

## Validation Rules

- movement_date: required, date
- movement_type: required, in:in,out,adjustment
- warehouse_id: required, exists:warehouses,id
- item_id: required, exists:items,id
- quantity: required, numeric, gt:0
- unit_cost: nullable, numeric, min:0
- reference_type: nullable, string
- reference_id: nullable, integer
- notes.ar: nullable, string
- notes.en: nullable, string
- branch_id: nullable, exists:branches,id

---

## UI

Views path:
`resources/views/dashboard/inventory/stock_movements/`

Fields in form:
- movement_date
- movement_type
- warehouse
- item
- quantity
- unit_cost
- total_cost
- reference_type
- reference_id
- notes_ar
- notes_en
- branch

Index columns:
- movement_number
- movement_date
- movement_type
- warehouse
- item
- quantity
- status/actions

---

## Lang Keys

Suggested keys:
- stock_movements
- stock_movement
- create_stock_movement
- edit_stock_movement
- movement_number
- movement_date
- movement_type
- warehouse
- item
- quantity
- unit_cost
- total_cost
- reference
- notes
- in
- out
- adjustment

---

## Seeder

Update RolePermissionSeeder with:
- inventory.stock.view
- inventory.stock.create
- inventory.stock.update
- inventory.stock.delete
- inventory.stock.adjust

---

## Steps

### Step 1
Create migration for `stock_movements` table.

### Step 2
Create `StockMovement` model with HasTranslations for notes.

### Step 3
Create `StockMovementService`.

### Step 4
Create Form Requests.

### Step 5
Create `StockMovementController`.

### Step 6
Create routes.

### Step 7
Create views.

### Step 8
Create lang files.

### Step 9
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