# Creamy Utopia API Testing Flow

This document outlines the complete API testing flow for administrators and users. Follow these steps in order to test all system functionality.

---

## Table of Contents

1. [Authentication](#1-authentication)
2. [Branch Management (Admin Only)](#2-branch-management-admin-only)
3. [User & Role Management (Admin Only)](#3-user--role-management-admin-only)
4. [Category Management](#4-category-management)
5. [Ingredient Management](#5-ingredient-management)
6. [Option Set Management](#6-option-set-management)
7. [Product Management](#7-product-management)
8. [Recipe Management](#8-recipe-management)
9. [Stock/Inventory Management](#9-stockinventory-management)
10. [Customer Management](#10-customer-management)
11. [Order Management (POS)](#11-order-management-pos)
12. [Expense Management](#12-expense-management)
13. [Cash Flow Management](#13-cash-flow-management)
14. [Analytics & Reports](#14-analytics--reports)

---

## Prerequisites

- Base URL: `http://localhost/creamy-utopia/public/api/v1`
- All requests require `Accept: application/json` header
- Authenticated requests require `Authorization: Bearer {token}` header

---

## 1. Authentication

### 1.1 Admin Login (First Step - Always)

```
POST /auth/login
```

**Request Body:**
```json
{
    "email": "admin@creamy-utopia.com",
    "password": "123456"
}
```

**Save the token from response for all subsequent requests.**

### 1.2 View Current User Profile

```
GET /auth/me
```

### 1.3 Logout (End of Session)

```
POST /auth/logout
```

---

## 2. Branch Management (Admin Only)

> **Required Permission:** `branches.view`, `branches.create`, `branches.update`, `branches.delete`

### 2.1 List All Branches

```
GET /branches
```

### 2.2 Create a New Branch

```
POST /branches
```

**Request Body:**
```json
{
    "name": "Downtown Branch",
    "code": "DTB001",
    "address": "456 Downtown Avenue, City Center",
    "phone": "555-0102",
    "email": "downtown@creamyutopia.com",
    "is_active": true,
    "settings": {
        "stock_restriction_enabled": true,
        "allow_negative_stock": false
    }
}
```

**Save the `branch_id` from response.**

### 2.3 View Branch Details

```
GET /branches/{branch_id}
```

### 2.4 Update Branch

```
PUT /branches/{branch_id}
```

### 2.5 Update Branch Settings

```
PUT /branches/{branch_id}/settings
```

**Request Body:**
```json
{
    "settings": {
        "stock_restriction_enabled": true,
        "allow_negative_stock": false,
        "default_tax_rate": 10
    }
}
```

---

## 3. User & Role Management (Admin Only)

### 3.1 Roles & Permissions

#### List All Permissions

```
GET /permissions
```

#### List Permissions by Module

```
GET /permissions/by-module
```

#### List All Roles

```
GET /roles
```

#### Create a New Role

```
POST /roles
```

**Request Body:**
```json
{
    "name": "cashier",
    "permissions": ["pos.access", "pos.create-order", "orders.view", "orders.create", "customers.view"]
}
```

#### View Role Permissions

```
GET /roles/{role_id}/permissions
```

#### Sync Permissions to Role

```
POST /roles/{role_id}/permissions
```

**Request Body:**
```json
{
    "permissions": ["pos.access", "pos.create-order", "orders.view", "orders.create", "orders.update"]
}
```

### 3.2 User Management

#### List All Users

```
GET /users
```

#### Create a New User

```
POST /users
```

**Request Body:**
```json
{
    "name": "John Cashier",
    "email": "john.cashier@creamyutopia.com",
    "password": "password123",
    "password_confirmation": "password123",
    "branch_id": 1
}
```

**Save the `user_id` from response.**

#### Assign Role to User

```
POST /users/{user_id}/roles
```

**Request Body:**
```json
{
    "role": "pos-operator"
}
```

#### View User Permissions

```
GET /users/{user_id}/permissions
```

#### Revoke Role from User

```
DELETE /users/{user_id}/roles
```

**Request Body:**
```json
{
    "role": "pos-operator"
}
```

---

## 4. Category Management

> **Required Permission:** `categories.view`, `categories.create`, `categories.update`, `categories.delete`

### 4.1 List All Categories

```
GET /categories
```

### 4.2 Create Parent Category

```
POST /categories
```

**Request Body:**
```json
{
    "name": "Ice Cream",
    "description": "All ice cream products",
    "is_active": true
}
```

**Save the `category_id` from response.**

### 4.3 Create Subcategory

```
POST /categories
```

**Request Body:**
```json
{
    "name": "Sundaes",
    "description": "Ice cream sundaes with toppings",
    "parent_id": 1,
    "is_active": true
}
```

### 4.4 View Category Tree

```
GET /categories/tree
```

### 4.5 View Category with Products

```
GET /categories/{category_id}
```

---

## 5. Ingredient Management

> **Required Permission:** `ingredients.view`, `ingredients.create`, `ingredients.update`, `ingredients.delete`

### 5.1 List All Ingredients

```
GET /ingredients
```

### 5.2 Create Ingredients

Create base ingredients needed for recipes:

```
POST /ingredients
```

**Request Body (Vanilla Extract):**
```json
{
    "name": "Vanilla Extract",
    "unit": "ml",
    "cost_per_unit": 0.50,
    "minimum_stock": 100,
    "is_active": true
}
```

**Request Body (Sugar):**
```json
{
    "name": "Sugar",
    "unit": "g",
    "cost_per_unit": 0.01,
    "minimum_stock": 5000,
    "is_active": true
}
```

**Request Body (Fresh Milk):**
```json
{
    "name": "Fresh Milk",
    "unit": "ml",
    "cost_per_unit": 0.003,
    "minimum_stock": 10000,
    "is_active": true
}
```

**Request Body (Cream):**
```json
{
    "name": "Heavy Cream",
    "unit": "ml",
    "cost_per_unit": 0.008,
    "minimum_stock": 5000,
    "is_active": true
}
```

**Save all `ingredient_id` values for recipes.**

---

## 6. Option Set Management

> **Required Permission:** `option-sets.view`, `option-sets.create`, `option-sets.update`, `option-sets.delete`

### 6.1 List All Option Sets

```
GET /option-sets
```

### 6.2 Create Option Set (Size)

```
POST /option-sets
```

**Request Body:**
```json
{
    "name": "Size",
    "display_name": "Choose Size",
    "is_required": true,
    "is_multiple": false,
    "options": [
        {"name": "Small", "price_modifier": 0},
        {"name": "Medium", "price_modifier": 1.50},
        {"name": "Large", "price_modifier": 3.00}
    ]
}
```

**Save the `option_set_id` from response.**

### 6.3 Create Option Set (Toppings)

```
POST /option-sets
```

**Request Body:**
```json
{
    "name": "Toppings",
    "display_name": "Add Toppings",
    "is_required": false,
    "is_multiple": true,
    "max_selections": 5,
    "options": [
        {"name": "Chocolate Chips", "price_modifier": 0.75},
        {"name": "Sprinkles", "price_modifier": 0.50},
        {"name": "Whipped Cream", "price_modifier": 1.00},
        {"name": "Caramel Sauce", "price_modifier": 0.75},
        {"name": "Nuts", "price_modifier": 1.00}
    ]
}
```

### 6.4 Create Inner Option Set

```
POST /inner-option-sets
```

**Request Body:**
```json
{
    "name": "Cone Type",
    "display_name": "Choose Cone",
    "option_set_id": 1,
    "options": [
        {"name": "Waffle Cone", "price_modifier": 0.50},
        {"name": "Sugar Cone", "price_modifier": 0},
        {"name": "Cup", "price_modifier": 0}
    ]
}
```

---

## 7. Product Management

> **Required Permission:** `products.view`, `products.create`, `products.update`, `products.delete`

### 7.1 List All Products

```
GET /products
```

### 7.2 Create Product

```
POST /products
```

**Request Body:**
```json
{
    "name": "Vanilla Dream",
    "sku": "VAN-001",
    "description": "Classic vanilla ice cream made with real vanilla beans",
    "base_price": 5.99,
    "category_id": 1,
    "is_active": true,
    "option_sets": [1, 2]
}
```

**Save the `product_id` from response.**

### 7.3 Create More Products

```
POST /products
```

**Request Body (Chocolate Delight):**
```json
{
    "name": "Chocolate Delight",
    "sku": "CHO-001",
    "description": "Rich chocolate ice cream",
    "base_price": 6.49,
    "category_id": 1,
    "is_active": true,
    "option_sets": [1, 2]
}
```

**Request Body (Strawberry Bliss):**
```json
{
    "name": "Strawberry Bliss",
    "sku": "STR-001",
    "description": "Fresh strawberry ice cream",
    "base_price": 6.99,
    "category_id": 1,
    "is_active": true,
    "option_sets": [1, 2]
}
```

### 7.4 View Product Details

```
GET /products/{product_id}
```

### 7.5 Search Products

```
GET /products?search=vanilla
```

---

## 8. Recipe Management

> **Required Permission:** `recipes.view`, `recipes.create`, `recipes.update`, `recipes.delete`

### 8.1 List All Recipes

```
GET /recipes
```

### 8.2 Create Recipe for Product

```
POST /recipes
```

**Request Body:**
```json
{
    "product_id": 1,
    "name": "Vanilla Dream Recipe",
    "yield_quantity": 1,
    "instructions": "1. Mix ingredients\n2. Churn in ice cream maker\n3. Freeze for 2 hours",
    "ingredients": [
        {"ingredient_id": 1, "quantity": 5},
        {"ingredient_id": 2, "quantity": 50},
        {"ingredient_id": 3, "quantity": 200},
        {"ingredient_id": 4, "quantity": 100}
    ]
}
```

**Save the `recipe_id` from response.**

### 8.3 View Recipe with Cost Calculation

```
GET /recipes/{recipe_id}
```

### 8.4 Calculate Recipe Cost

```
GET /recipes/{recipe_id}/cost
```

---

## 9. Stock/Inventory Management

> **Required Permission:** `stock.view`, `stock.create`, `stock.adjust`

### 9.1 View Stock Levels

```
GET /stock
```

### 9.2 View Stock for Specific Branch

```
GET /stock?branch_id=1
```

### 9.3 Add Initial Stock

```
POST /stock
```

**Request Body:**
```json
{
    "branch_id": 1,
    "ingredient_id": 1,
    "quantity": 500,
    "type": "purchase",
    "notes": "Initial stock purchase",
    "unit_cost": 0.50
}
```

Repeat for all ingredients:

```json
{
    "branch_id": 1,
    "ingredient_id": 2,
    "quantity": 10000,
    "type": "purchase",
    "notes": "Sugar stock",
    "unit_cost": 0.01
}
```

```json
{
    "branch_id": 1,
    "ingredient_id": 3,
    "quantity": 20000,
    "type": "purchase",
    "notes": "Fresh milk stock",
    "unit_cost": 0.003
}
```

```json
{
    "branch_id": 1,
    "ingredient_id": 4,
    "quantity": 10000,
    "type": "purchase",
    "notes": "Heavy cream stock",
    "unit_cost": 0.008
}
```

### 9.4 Adjust Stock

```
POST /stock/adjust
```

**Request Body:**
```json
{
    "branch_id": 1,
    "ingredient_id": 1,
    "quantity": -10,
    "type": "adjustment",
    "reason": "Spillage",
    "notes": "Accidental spillage during preparation"
}
```

### 9.5 View Stock Movements

```
GET /stock/movements?branch_id=1
```

### 9.6 Check Low Stock Alerts

```
GET /stock/alerts
```

---

## 10. Customer Management

> **Required Permission:** `customers.view`, `customers.create`, `customers.update`, `customers.delete`

### 10.1 List All Customers

```
GET /customers
```

### 10.2 Create Customer

```
POST /customers
```

**Request Body:**
```json
{
    "name": "Jane Smith",
    "email": "jane.smith@email.com",
    "phone": "555-0199",
    "address": "789 Customer Lane",
    "notes": "Prefers chocolate flavors"
}
```

**Save the `customer_id` from response.**

### 10.3 Create Walk-in Customer

```
POST /customers
```

**Request Body:**
```json
{
    "name": "Walk-in Customer",
    "phone": "555-0000"
}
```

### 10.4 View Customer Order History

```
GET /customers/{customer_id}
```

### 10.5 Search Customers

```
GET /customers?search=jane
```

---

## 11. Order Management (POS)

> **Required Permission:** `orders.view`, `orders.create`, `orders.update`, `orders.cancel`, `pos.access`, `pos.create-order`, `pos.apply-discount`

### 11.1 List All Orders

```
GET /orders
```

### 11.2 Create New Order

```
POST /orders
```

**Request Body:**
```json
{
    "branch_id": 1,
    "customer_id": 1,
    "order_type": "dine-in",
    "items": [
        {
            "product_id": 1,
            "quantity": 2,
            "unit_price": 5.99,
            "options": [
                {"option_id": 2, "name": "Medium", "price_modifier": 1.50}
            ],
            "notes": "Extra cold"
        },
        {
            "product_id": 2,
            "quantity": 1,
            "unit_price": 6.49,
            "options": [
                {"option_id": 1, "name": "Small", "price_modifier": 0},
                {"option_id": 6, "name": "Whipped Cream", "price_modifier": 1.00}
            ]
        }
    ],
    "notes": "Birthday order"
}
```

**Save the `order_id` from response.**

### 11.3 View Order Details

```
GET /orders/{order_id}
```

### 11.4 Update Order Status

```
PUT /orders/{order_id}
```

**Request Body (Preparing):**
```json
{
    "status": "preparing"
}
```

**Request Body (Ready):**
```json
{
    "status": "ready"
}
```

**Request Body (Completed):**
```json
{
    "status": "completed",
    "payment_method": "cash",
    "payment_status": "paid"
}
```

### 11.5 Apply Discount to Order

```
POST /orders/{order_id}/discount
```

**Request Body:**
```json
{
    "discount_type": "percentage",
    "discount_value": 10,
    "reason": "Loyalty discount"
}
```

### 11.6 Cancel Order

```
POST /orders/{order_id}/cancel
```

**Request Body:**
```json
{
    "reason": "Customer changed mind"
}
```

### 11.7 View Orders by Status

```
GET /orders?status=pending
GET /orders?status=preparing
GET /orders?status=completed
```

### 11.8 View Orders by Date Range

```
GET /orders?start_date=2025-12-01&end_date=2025-12-31
```

---

## 12. Expense Management

> **Required Permission:** `expense-categories.view`, `expense-categories.create`, `expenses.view`, `expenses.create`, `expenses.update`, `expenses.delete`

### 12.1 Expense Categories

#### List Expense Categories

```
GET /expense-categories
```

#### Create Expense Category

```
POST /expense-categories
```

**Request Body:**
```json
{
    "name": "Utilities",
    "description": "Electricity, water, gas bills"
}
```

**Create more categories:**
```json
{
    "name": "Rent",
    "description": "Monthly rent payments"
}
```

```json
{
    "name": "Supplies",
    "description": "Packaging, napkins, utensils"
}
```

```json
{
    "name": "Maintenance",
    "description": "Equipment repairs and maintenance"
}
```

### 12.2 Expenses

#### List All Expenses

```
GET /expenses
```

#### Create Expense

```
POST /expenses
```

**Request Body:**
```json
{
    "branch_id": 1,
    "expense_category_id": 1,
    "amount": 250.00,
    "description": "December electricity bill",
    "expense_date": "2025-12-01",
    "payment_method": "bank_transfer",
    "reference_number": "ELEC-DEC-2025"
}
```

**Create more expenses:**
```json
{
    "branch_id": 1,
    "expense_category_id": 3,
    "amount": 75.50,
    "description": "Packaging supplies - cups and spoons",
    "expense_date": "2025-12-02",
    "payment_method": "cash"
}
```

#### View Expenses by Category

```
GET /expenses?category_id=1
```

#### View Expenses by Date Range

```
GET /expenses?start_date=2025-12-01&end_date=2025-12-31
```

---

## 13. Cash Flow Management

> **Required Permission:** `cash-flows.view`, `cash-flows.create`

### 13.1 List Cash Flows

```
GET /cash-flows
```

### 13.2 Record Cash In

```
POST /cash-flows
```

**Request Body:**
```json
{
    "branch_id": 1,
    "type": "in",
    "amount": 500.00,
    "description": "Opening float",
    "reference": "FLOAT-001"
}
```

### 13.3 Record Cash Out

```
POST /cash-flows
```

**Request Body:**
```json
{
    "branch_id": 1,
    "type": "out",
    "amount": 50.00,
    "description": "Petty cash - office supplies",
    "reference": "PETTY-001"
}
```

### 13.4 View Cash Flow Summary

```
GET /cash-flows?branch_id=1&start_date=2025-12-01&end_date=2025-12-31
```

---

## 14. Analytics & Reports

> **Required Permission:** `analytics.view-dashboard`, `analytics.view-sales`, `analytics.view-orders`, `analytics.view-expenses`, `analytics.view-profitability`

### 14.1 Dashboard Overview

```
GET /analytics/dashboard
```

### 14.2 Sales Analytics

```
GET /analytics/sales
GET /analytics/sales?start_date=2025-12-01&end_date=2025-12-31
GET /analytics/sales?branch_id=1
```

### 14.3 Order Analytics

```
GET /analytics/orders
GET /analytics/orders?group_by=day
GET /analytics/orders?group_by=product
```

### 14.4 Expense Analytics

```
GET /analytics/expenses
GET /analytics/expenses?group_by=category
```

### 14.5 Profitability Report

```
GET /analytics/profitability
GET /analytics/profitability?branch_id=1&start_date=2025-12-01&end_date=2025-12-31
```

---

## Complete Testing Flow Summary

### Phase 1: Setup (Admin)
1. Login as admin
2. Create branches
3. Create roles and permissions
4. Create users and assign roles

### Phase 2: Catalog Setup (Admin/Manager)
1. Create categories
2. Create ingredients
3. Create option sets
4. Create products
5. Create recipes

### Phase 3: Inventory Setup (Admin/Manager)
1. Add initial stock for all ingredients
2. Verify stock levels

### Phase 4: Daily Operations (POS Operator)
1. Login as POS operator
2. Create customers
3. Create orders
4. Process payments
5. Update order statuses

### Phase 5: Financial Management (Admin/Manager)
1. Record expenses
2. Manage cash flows
3. Review analytics

### Phase 6: Reporting (Admin/Manager)
1. View dashboard
2. Generate sales reports
3. Review profitability

---

## Role-Based Access Quick Reference

| Role | Key Permissions |
|------|-----------------|
| **super-admin** | All permissions |
| **branch-admin** | All except branch create/delete, role management |
| **manager** | View/manage products, orders, customers, expenses, analytics |
| **pos-operator** | POS access, orders, customers (view/create), products (view) |
| **kitchen-staff** | Orders (view/update), products (view), recipes (view) |

---

## Error Codes Reference

| Status | Meaning |
|--------|---------|
| 200 | Success |
| 201 | Created |
| 204 | No Content (Deleted) |
| 400 | Bad Request |
| 401 | Unauthorized (Not logged in) |
| 403 | Forbidden (No permission) |
| 404 | Not Found |
| 422 | Validation Error |
| 500 | Server Error |

---

## Tips for Testing

1. **Always login first** - Get your token before any other request
2. **Save IDs** - Store returned IDs for use in subsequent requests
3. **Test permissions** - Try accessing endpoints with different user roles
4. **Check validation** - Test with invalid data to verify error handling
5. **Test order flow** - Create orders and move them through all statuses
6. **Verify stock deduction** - Check stock levels after completing orders
