########################################
# 10) CAFETERIA MODULE (الكافتيريا)
########################################

We now want to add a dedicated Cafeteria module to the ERP.
The cafeteria has:
- Its own products (cafeteria products)
- Its own purchases
- Its own inventory (separate stock from the main beauty products)
- Its own sales orders (similar to salon orders, but products only)

However, the design should still reuse:
- The existing suppliers (suppliers table)
- The existing payment_methods
- The existing units table (وحدات القياس) where possible


########################################
# 10.1 CAFETERIA PRODUCTS (منتجات الكافتيريا)
########################################

### Table: cafeteria_products
Fields:
- id (integer, primary key, auto increment)
- name_ar (string, not null)                // اسم الصنف في الكافتيريا (مثال: "قهوة أمريكية", "ساندويتش")
- sku (string, nullable, unique)            // كود داخلي اختياري
- unit_id (integer, foreign key to units.id)// وحدة القياس (مثال: حبة، كوب، علبة)
- default_purchase_price (real, nullable)   // سعر الشراء الافتراضي
- default_sell_price (real, nullable)       // سعر البيع الافتراضي
- has_expiry_date (boolean, default false)  // هل له تاريخ صلاحية
- is_active (boolean, default true)
- created_at (datetime)
- updated_at (datetime)

We intentionally separate cafeteria_products from the main products table to keep cafeteria inventory independent from beauty services/products.


### Table: cafeteria_stock_batches
Track cafeteria stock by product and (optionally) expiry date.

Fields:
- id (integer, primary key, auto increment)
- cafeteria_product_id (integer, foreign key to cafeteria_products.id)
- expiry_date (date, nullable)
- quantity_on_hand (real, not null)    // الكمية الحالية بوحدة القياس المحددة
- unit_cost (real, not null)           // تكلفة الوحدة
- created_at (datetime)
- updated_at (datetime)


### Table: cafeteria_stock_movements
General stock movement log for cafeteria.

Fields:
- id (integer, primary key, auto increment)
- cafeteria_product_id (integer, foreign key to cafeteria_products.id)
- movement_date (date)
- movement_type (string)  // "purchase", "sale", "consume", "damage", "adjustment"
- quantity_in (real, default 0)
- quantity_out (real, default 0)
- unit_cost (real, nullable)
- reference_type (string, nullable)    // "CafeteriaPurchaseInvoice", "CafeteriaSaleOrder", "CafeteriaManualAdjustment", ...
- reference_id (integer, nullable)
- batch_id (integer, nullable, foreign key to cafeteria_stock_batches.id)
- created_at (datetime)


### Cafeteria Products APIs

- CRUD: /cafeteria/products
  - GET /cafeteria/products
  - POST /cafeteria/products
  - GET /cafeteria/products/:id
  - PUT /cafeteria/products/:id
  - DELETE /cafeteria/products/:id (soft delete: is_active = false)

Validation examples:
- name_ar is required → return Arabic error "اسم المنتج مطلوب".
- unit_id must exist in units table.


########################################
# 10.2 CAFETERIA PURCHASES (مشتريات الكافتيريا)
########################################

Cafeteria purchases are similar to the main purchase_invoices module,
but they affect cafeteria_products and cafeteria_stock tables instead of the main products/inventory.

### Table: cafeteria_purchase_invoices
Fields:
- id (integer, primary key, auto increment)
- supplier_id (foreign key to suppliers.id)
- invoice_date (date, not null)
- due_date (date, nullable)
- payment_status (string)   // "unpaid", "partially_paid", "paid"
- subtotal_amount (real, not null, default 0)
- vat_amount (real, not null, default 0)
- total_amount (real, not null, default 0)
- notes (string, nullable)
- created_at (datetime)
- updated_at (datetime)

### Table: cafeteria_purchase_invoice_lines
Fields:
- id (integer, primary key, auto increment)
- cafeteria_purchase_invoice_id (foreign key to cafeteria_purchase_invoices.id)
- cafeteria_product_id (foreign key to cafeteria_products.id)
- quantity (real, not null)                // الكمية بوحدة القياس
- purchase_price_per_unit (real, not null) // سعر شراء الوحدة
- vat_type (string, not null)              // "inclusive", "exclusive", "exempt"
- vat_rate (real, not null)                // مثال: 0.15
- vat_amount (real, not null)
- line_subtotal (real, not null)           // بدون ضريبة
- line_total (real, not null)              // مع الضريبة
- expiry_date (date, nullable)

Behavior:
- Same VAT logic as main purchase lines:
  - inclusive / exclusive / exempt.
- For each line:
  - Insert or update a cafeteria_stock_batches row:
    - cafeteria_product_id, expiry_date, quantity_on_hand, unit_cost
  - Insert cafeteria_stock_movements record:
    - movement_type = "purchase"
    - quantity_in = quantity
    - unit_cost = purchase_price_per_unit
    - reference_type = "CafeteriaPurchaseInvoice"
    - reference_id = cafeteria_purchase_invoices.id

### Table: cafeteria_purchase_payments
To handle partial payments for cafeteria purchases.

Fields:
- id (integer, primary key, auto increment)
- cafeteria_purchase_invoice_id (foreign key to cafeteria_purchase_invoices.id, nullable)
- supplier_id (foreign key to suppliers.id)
- payment_method_id (foreign key to payment_methods.id)
- payment_date (date, not null)
- amount (real, not null)
- notes (string, nullable)
- created_at (datetime)
- updated_at (datetime)

Payment behavior:
- Same as main purchase_payments:
  - Update payment_status on cafeteria_purchase_invoices based on sum of payments.


### Cafeteria Purchase APIs

- POST /cafeteria/purchase-invoices
  - Similar to POST /purchase-invoices, but:
    - Uses cafeteria_products instead of products.
    - Affects cafeteria_stock_batches and cafeteria_stock_movements.

- POST /cafeteria/purchase-invoices/:id/payments
  - Similar logic to main purchase payments.

- GET /cafeteria/purchase-invoices/:id
  - Return invoice header + lines + payments.


########################################
# 10.3 CAFETERIA SALES (مبيعات الكافتيريا)
########################################

Cafeteria sales orders are similar to salon orders,
but they are **product-only** (no services) and use cafeteria_products.

### Table: cafeteria_sales_orders
Fields:
- id (integer, primary key, auto increment)
- order_number (string, unique)             // e.g. "CF-0001"
- order_date (datetime, not null)
- source (string, not null)                 // "pos" (from inside the salon/cafeteria)
- client_id (integer, nullable)             // optional customer
- created_by_employee_id (integer, not null)// الموظف الذي سجّل الطلب
- branch_id (integer, nullable)
- status (string, not null)                 // "new", "completed", "canceled"
- notes (string, nullable)
- subtotal_amount (real, not null, default 0)
- vat_amount (real, not null, default 0)
- total_amount (real, not null, default 0)
- created_at (datetime)
- updated_at (datetime)

### Table: cafeteria_sales_order_lines
Fields:
- id (integer, primary key, auto increment)
- cafeteria_sales_order_id (integer, foreign key to cafeteria_sales_orders.id)
- cafeteria_product_id (integer, foreign key to cafeteria_products.id)
- quantity (real, not null)
- unit_price (real, not null)              // قد يأتي من default_sell_price
- vat_type (string, not null)              // "inclusive", "exclusive", "exempt"
- vat_rate (real, not null)
- line_subtotal (real, not null)
- vat_amount (real, not null)
- line_total (real, not null)
- created_at (datetime)
- updated_at (datetime)

Behavior:
- For each line:
  - Calculate line_subtotal, vat_amount, line_total the same as other modules.
- On completing an order (status = "completed"):
  - Create cafeteria_stock_movements entry:
    - movement_type = "sale"
    - quantity_out = quantity
    - reference_type = "CafeteriaSaleOrder"
    - reference_id = cafeteria_sales_orders.id
  - Decrease cafeteria_stock_batches.quantity_on_hand (FIFO or simple method).


### Cafeteria Sales APIs

1) GET /cafeteria/sales-orders
   - List cafeteria sales orders with filters:
     - ?date=YYYY-MM-DD
     - ?status=new|completed|canceled
     - ?branch_id=
     - ?created_by_employee_id=

2) POST /cafeteria/sales-orders
   - Create a new cafeteria sales order.

   Request JSON example:
   {
     "client_id": null,
     "created_by_employee_id": 5,
     "branch_id": 1,
     "notes": "مبيعات كافتيريا",
     "lines": [
       {
         "cafeteria_product_id": 1,
         "quantity": 2
       },
       {
         "cafeteria_product_id": 3,
         "quantity": 1
       }
     ]
   }

   Behavior:
   - For each line, fetch cafeteria_product.default_sell_price, and default VAT settings if needed.
   - Calculate subtotal_amount, vat_amount, total_amount.
   - Set status = "new" initially.

3) GET /cafeteria/sales-orders/:id
   - Return header + lines with product names.

4) PUT /cafeteria/sales-orders/:id
   - Allow:
     - Updating status to "completed" or "canceled".
   - When status changes to "completed":
     - Trigger stock movements as described.


########################################
# 10.4 CAFETERIA INVENTORY REPORTS (تقارير مخزون الكافتيريا)
########################################

Similar to the main inventory reports, but for cafeteria:

1) GET /cafeteria/reports/inventory-summary
   - For each cafeteria_product:
     - cafeteria_product_id, name_ar
     - quantity_on_hand (sum of cafeteria_stock_batches.quantity_on_hand)
     - total_cost (sum of quantity_on_hand * unit_cost)

2) GET /cafeteria/reports/inventory-movements?cafeteria_product_id=X
   - Return cafeteria_stock_movements for that product ordered by date:
     - movement_date, movement_type, quantity_in, quantity_out, unit_cost, reference_type, reference_id


########################################
# 11) GENERAL UI & MODULE GROUPING (هيكلة النظام والواجهة الرئيسية)
########################################

IMPORTANT: This backend is part of a full Beauty Salon ERP, not just a purchases/suppliers system.
Please reflect this in:
- The project structure
- The README
- Any example navigation/sidebar structure you generate (if any frontend stubs are added later).

High-level modules of the ERP:
- Dashboard (لوحة التحكم)
- Salon Orders (طلبات الصالون)
- Appointments (حجوزات التطبيق)
- Services & Service Categories (الخدمات وفئاتها)
- Cafeteria (الكافتيريا: مبيعات + مشتريات + مخزون)
- Purchases & Inventory (المشتريات والمخزون)
  - Suppliers (الموردين)
  - Units (وحدات القياس)
  - Products (المنتجات)
  - Purchase Invoices (فواتير المشتريات)
- Finance & Journal Entries (المالية والقيود اليومية)
- Employees, Roles & HR (الموظفين والموارد البشرية)
- Marketing (حزم، كوبونات، نقاط ولاء) [later]

Navigation / ordering requirement:
- In any example menu or README structure:
  - Show "Dashboard / لوحة التحكم" at the top.
  - Directly under it, as the first main module on the right (for RTL):
    - "Salon Orders / طلبات الصالون"
  - "Appointments / الحجوزات" comes next.
  - "Cafeteria / الكافتيريا" comes after orders/appointments.
  - Group "Suppliers, Units, Products" clearly under a "Purchases & Inventory / المشتريات والمخزون" section,
    not as separate top-level modules.

Also update the README introduction to state clearly in Arabic:
- أن هذا النظام هو نظام ERP متكامل لصالون نسائي
- وليس فقط نظام مشتريات وموردين
- وشرح مختصر للوحدات: الطلبات، الحجوزات، الخدمات، الكافتيريا، المشتريات، المخزون، المالية، الموظفين، التسويق.
