# Task 18 — Sales Orders

## Goal
Build the Sales Orders module to record customer orders before invoicing.
This module must support header + lines structure and prepare future conversion to invoices.

---

## Database

### Table: `sales_orders`

Fields:
- id
- order_number (string, unique)
- order_date (date)
- customer_id (FK to customers.id)
- branch_id (nullable, FK to branches.id)
- status (string, default `draft`)
  - draft
  - confirmed
  - cancelled
- notes (json, nullable, translatable)
- created_by (nullable, FK to admins.id)
- updated_by (nullable, FK to admins.id)
- created_at
- updated_at

Indexes:
- unique order_number
- index order_date
- index customer_id
- index branch_id
- index status

### Table: `sales_order_lines`

Fields:
- id
- sales_order_id (FK to sales_orders.id)
- item_id (FK to items.id)
- description (json, nullable, translatable)
- quantity (decimal 18,2)
- unit_price (decimal 18,2)
- line_total (decimal 18,2)
- created_at
- updated_at

Indexes:
- index sales_order_id
- index item_id

---

## Relations

### SalesOrder model relations
- customer() -> belongsTo Customer
- branch() -> belongsTo Branch
- lines() -> hasMany SalesOrderLine
- creator() -> belongsTo Admin
- updater() -> belongsTo Admin

### SalesOrderLine model relations
- order() -> belongsTo SalesOrder
- item() -> belongsTo Item

---

## Business Rules

1. Order number must be unique and generated using NumberSequenceService.
2. Customer is required.
3. At least one line is required.
4. Each line must contain item, quantity, and unit price.
5. line_total = quantity * unit_price.
6. Only active customers/items should be selectable.
7. Orders start as `draft`.
8. Later tasks may add conversion to invoices.

---

## Files

### Models
- app/Models/Sales/SalesOrder.php
- app/Models/Sales/SalesOrderLine.php

### Service
- app/Services/Sales/SalesOrderService.php

### Controller
- app/Http/Controllers/Admin/Sales/SalesOrderController.php

### Requests
- app/Http/Requests/Admin/Sales/StoreSalesOrderRequest.php
- app/Http/Requests/Admin/Sales/UpdateSalesOrderRequest.php

### Views
- resources/views/dashboard/sales/orders/index.blade.php
- resources/views/dashboard/sales/orders/create.blade.php
- resources/views/dashboard/sales/orders/edit.blade.php
- resources/views/dashboard/sales/orders/show.blade.php

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

---

## Permissions

- sales.orders.view
- sales.orders.create
- sales.orders.update
- sales.orders.delete

---

## Validation Rules

### Header
- order_date: required, date
- customer_id: required, exists:customers,id
- branch_id: nullable, exists:branches,id
- status: nullable, in:draft,confirmed,cancelled
- notes.ar: nullable, string
- notes.en: nullable, string

### Lines
- lines: required, array, min:1
- lines.*.item_id: required, exists:items,id
- lines.*.description.ar: nullable, string
- lines.*.description.en: nullable, string
- lines.*.quantity: required, numeric, gt:0
- lines.*.unit_price: required, numeric, min:0

---

## UI

Views path:
`resources/views/dashboard/sales/orders/`

### Header fields
- order_date
- customer
- branch
- status
- notes_ar
- notes_en

### Line fields
- item
- description_ar
- description_en
- quantity
- unit_price
- line_total

### Index columns
- order_number
- order_date
- customer
- branch
- status
- actions

---

## Lang Keys

Suggested keys:
- sales_orders
- sales_order
- create_sales_order
- edit_sales_order
- order_number
- order_date
- customer
- branch
- status
- notes
- lines
- item
- quantity
- unit_price
- line_total
- draft
- confirmed
- cancelled

---

## Seeder

Update RolePermissionSeeder with:
- sales.orders.view
- sales.orders.create
- sales.orders.update
- sales.orders.delete

---

## Steps

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

### Step 2
Create migration for `sales_order_lines` table.

### Step 3
Create `SalesOrder` and `SalesOrderLine` models.

### Step 4
Create `SalesOrderService`.

### Step 5
Create Form Requests.

### Step 6
Create `SalesOrderController`.

### Step 7
Create routes.

### Step 8
Create views.

### Step 9
Create lang files.

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