# Task 17 — Customers

## Goal
Build the Customers module to manage customer master data used by sales orders, invoices, collections, and reports.
This module should support bilingual customer names and essential contact information.

---

## Database

Table: `customers`

Fields:
- id
- code (string, unique)
- name (json, translatable)
- phone (string, nullable)
- email (string, nullable)
- address (json, nullable, translatable)
- tax_number (string, nullable)
- branch_id (nullable, FK to branches.id)
- is_active (boolean, default true)
- created_by (nullable, FK to admins.id)
- updated_by (nullable, FK to admins.id)
- created_at
- updated_at

Indexes:
- unique code
- index phone
- index email
- index branch_id
- index is_active

---

## Relations

Customer model relations:
- branch() -> belongsTo Branch
- creator() -> belongsTo Admin
- updater() -> belongsTo Admin

Future relations:
- salesOrders() -> hasMany SalesOrder
- invoices() -> hasMany Invoice

---

## Business Rules

1. Customer code must be unique.
2. Name and address must use HasTranslations.
3. Customer can be active or inactive.
4. Inactive customers should not appear in operational forms unless explicitly allowed later.
5. Customer records are reusable across orders, invoices, and aging reports.

---

## Files

### Model
- app/Models/Sales/Customer.php

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

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

### Requests
- app/Http/Requests/Admin/Sales/StoreCustomerRequest.php
- app/Http/Requests/Admin/Sales/UpdateCustomerRequest.php

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

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

---

## Permissions

- sales.customers.view
- sales.customers.create
- sales.customers.update
- sales.customers.delete

---

## Validation Rules

- code: required, unique:customers,code
- name.ar: required, string
- name.en: nullable, string
- phone: nullable, string
- email: nullable, email
- address.ar: nullable, string
- address.en: nullable, string
- tax_number: nullable, string
- branch_id: nullable, exists:branches,id
- is_active: boolean

---

## UI

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

Fields in form:
- code
- name_ar
- name_en
- phone
- email
- address_ar
- address_en
- tax_number
- branch
- is_active

Index columns:
- code
- name
- phone
- email
- branch
- status
- actions

---

## Lang Keys

Suggested keys:
- customers
- customer
- create_customer
- edit_customer
- customer_code
- customer_name
- phone
- email
- address
- tax_number
- branch
- is_active
- status

---

## Seeder

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

---

## Steps

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

### Step 2
Create `Customer` model with HasTranslations.

### Step 3
Create `CustomerService`.

### Step 4
Create Form Requests.

### Step 5
Create `CustomerController`.

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