# Postman Collection Guide

Complete guide to using the Gym Khana Management System Postman collection.

## 📥 Import Collection

### Step 1: Import Collection File

1. Open Postman
2. Click **Import** button (top left)
3. Select **File** tab
4. Click **Choose Files**
5. Navigate to project root and select:
   - `Gym-Khana-API.postman_collection.json`
   - `Gym-Khana-Environment.postman_environment.json`
6. Click **Import**

### Step 2: Select Environment

1. In the top-right corner, select **Gym Khana - Local** from the environment dropdown
2. The environment contains:
   - `base_url`: http://localhost:3000/api/v1
   - `token`: (empty, will be auto-filled after login)
   - `refreshToken`: (empty, will be auto-filled after login)

## 🚀 Quick Start

### 1. Start Your Server

Make sure your server is running:

```bash
npm run dev
```

### 2. Test Health Check

1. Go to **Utility > Health Check**
2. Click **Send**
3. You should see:
   ```json
   {
     "success": true,
     "message": "API is running"
   }
   ```

### 3. Login as Admin

1. Go to **Authentication > Staff Login**
2. The request body is pre-filled with:
   ```json
   {
     "username": "admin",
     "password": "Admin@1234"
   }
   ```
3. **Update the password** to the one you set when creating super admin
4. Click **Send**
5. ✅ **Token is automatically saved!** Check the **Tests** tab to see the script

### 4. Test Protected Endpoint

1. Go to **Authentication > Get Current User**
2. Click **Send**
3. You should see your user profile (token is automatically used)

## 📁 Collection Structure

### 1. **Authentication** (4 requests)
- **Staff Login** - Login for staff users
- **Member Login** - Login for members
- **Get Current User** - Get logged-in user details
- **Change Password** - Change your password

### 2. **User Management** (7 requests)
- **Create User** - Create new staff user (Admin only)
- **Get All Users** - List all users with pagination
- **Get User by ID** - Get specific user
- **Update User** - Update user details
- **Delete User** - Deactivate user
- **Reset User Password** - Reset user password (Admin)
- **Get All Roles** - Get available roles

### 3. **Membership Management** (9 requests)
- **Register Member** - Register new primary member
- **Add Family Member** - Add spouse/son/daughter
- **Get All Members** - List members with pagination
- **Search Members** - Quick search
- **Get Member by ID** - Get member details + family
- **Update Member Profile** - Update contact info
- **Update Member Status** - Change member status
- **Get Family Members** - List family members
- **Remove Family Member** - Delete family member

### 4. **Utility** (2 requests)
- **Health Check** - API status
- **API Documentation** - Full API docs

## 🔑 Authentication

### How Token Auto-Save Works

Each login request has a **Test** script that automatically saves the token:

```javascript
if (pm.response.code === 200) {
    const response = pm.response.json();
    pm.environment.set("token", response.data.accessToken);
    pm.environment.set("refreshToken", response.data.refreshToken);
    console.log("✅ Token saved to environment");
}
```

### View Your Token

1. Click the **eye icon** in top-right (next to environment dropdown)
2. You'll see your token value
3. All authenticated requests use `{{token}}` variable

### Manual Token Entry

If needed, you can manually set the token:

1. Click **eye icon** > **Edit**
2. Paste token in the `token` field
3. Click **Save**

## 📝 Common Workflows

### Workflow 1: Create a New Front Desk User

1. **Login as Admin** (Authentication > Staff Login)
2. **Create User** (User Management > Create User)
   ```json
   {
     "username": "frontdesk1",
     "email": "frontdesk@gymkhana.pk",
     "password": "FrontDesk@123",
     "firstName": "Front",
     "lastName": "Desk",
     "phone": "03001234567",
     "role": "front_desk"
   }
   ```
3. Verify in **Get All Users**

### Workflow 2: Register a Member with Family

1. **Login as Admin/Front Desk**
2. **Register Member** (Membership > Register Member)
   - Use member ID: `1001`
   - Set all required fields
3. **Add Family Member** (Membership > Add Family Member)
   - URL: `.../members/1001/family`
   - Add spouse (will get ID: `1001-w`)
4. **Get Member by ID** to see family members
5. Repeat for sons (`1001-s1`) and daughters (`1001-d1`)

### Workflow 3: Search and Update Member

1. **Search Members** with query: `?q=Ahmed`
2. Copy the `member_id` from results
3. **Get Member by ID** to see full details
4. **Update Member Profile** to change contact info
5. **Update Member Status** if needed

## 🎯 Request Examples

### Example 1: Register Primary Member

**Endpoint:** `POST /members/register`

**Request Body:**
```json
{
  "memberId": "1001",
  "membershipTypeId": 1,
  "firstName": "Ahmed",
  "lastName": "Khan",
  "fatherName": "Muhammad Khan",
  "cnic": "4210112345678",
  "dateOfBirth": "1980-05-15",
  "gender": "Male",
  "phonePrimary": "03001234567",
  "phoneSecondary": "03219876543",
  "email": "ahmed@example.com",
  "address": "House 123, Street 45, Hyderabad",
  "emergencyContactName": "Ali Khan",
  "emergencyContactPhone": "03331234567",
  "membershipStartDate": "2024-01-01",
  "membershipExpiryDate": "2024-12-31",
  "password": "Member@123"
}
```

**Response:**
```json
{
  "success": true,
  "message": "Member registered successfully",
  "data": {
    "member": {
      "member_id": "1001",
      "first_name": "Ahmed",
      "last_name": "Khan",
      "status": "Active"
    }
  }
}
```

### Example 2: Add Spouse

**Endpoint:** `POST /members/1001/family`

**Request Body:**
```json
{
  "firstName": "Fatima",
  "lastName": "Ahmed",
  "relationToPrimary": "Spouse",
  "dateOfBirth": "1985-03-20",
  "gender": "Female",
  "cnic": "4210198765432",
  "password": "Spouse@123"
}
```

**Response:**
```json
{
  "success": true,
  "message": "Family member added successfully",
  "data": {
    "familyMember": {
      "member_id": "1001-w",
      "primary_member_id": "1001",
      "first_name": "Fatima",
      "relation_to_primary": "Spouse"
    }
  }
}
```

### Example 3: Search Members

**Endpoint:** `GET /members/search?q=Ahmed`

**Response:**
```json
{
  "success": true,
  "message": "Search results",
  "data": [
    {
      "member_id": "1001",
      "first_name": "Ahmed",
      "last_name": "Khan",
      "phone_primary": "03001234567",
      "status": "Active",
      "current_balance": 0.00,
      "account_status": "Normal"
    }
  ]
}
```

## 🔧 Environment Variables

The collection uses these variables:

| Variable | Description | Example |
|----------|-------------|---------|
| `base_url` | API base URL | `http://localhost:3000/api/v1` |
| `token` | JWT access token | Auto-set after login |
| `refreshToken` | JWT refresh token | Auto-set after login |

### Change Server URL

To use a different server (e.g., production):

1. Click **eye icon** > **Edit**
2. Change `base_url` to:
   - Production: `https://api.gymkhana.pk/api/v1`
   - Staging: `https://staging-api.gymkhana.pk/api/v1`
3. Click **Save**

## 📊 Pagination

Endpoints with pagination support these query parameters:

| Parameter | Default | Max | Description |
|-----------|---------|-----|-------------|
| `page` | 1 | - | Page number |
| `limit` | 20 | 100 | Items per page |

**Example:**
```
GET /members?page=1&limit=20
GET /users?page=2&limit=50
```

## 🔍 Search & Filters

### User Search

**Endpoint:** `GET /users`

**Available Filters:**
- `role`: Filter by role (admin, front_desk, etc.)
- `search`: Search by username, email, or name
- `isActive`: Filter active/inactive users

**Example:**
```
GET /users?role=front_desk&isActive=true&search=john
```

### Member Search

**Quick Search:** `GET /members/search?q={query}`
- Searches: ID, name, phone, CNIC
- Returns max 20 results

**Advanced Search:** `GET /members`
- `search`: Search term
- `status`: Active/Suspended/Inactive/Expired
- `membershipType`: PERM/TEMP/ASSOC/CORP/YOUTH/SENIOR

**Example:**
```
GET /members?status=Active&membershipType=PERM&search=ahmed
```

## ⚠️ Common Issues

### Issue 1: "Invalid or expired token"

**Cause:** Token expired or not set

**Solution:**
1. Login again (Authentication > Staff Login)
2. Token will be auto-saved
3. Retry the request

### Issue 2: "Access denied. Insufficient permissions"

**Cause:** Your role doesn't have permission

**Solution:**
1. Check required role in request description
2. Login with appropriate user
3. Create new user with correct role if needed

### Issue 3: "Validation failed"

**Cause:** Required fields missing or invalid format

**Solution:**
1. Check request description for required fields
2. Verify data formats:
   - CNIC: 13 digits
   - Phone: 03XXXXXXXXX
   - Date: YYYY-MM-DD
   - Password: min 8 chars, uppercase, lowercase, number

### Issue 4: "ECONNREFUSED"

**Cause:** Server not running

**Solution:**
1. Start server: `npm run dev`
2. Verify it's running on port 3000
3. Check health endpoint

## 📚 Request Descriptions

Each request includes:
- ✅ **Description** - What the endpoint does
- ✅ **Access** - Who can use it
- ✅ **Required Fields** - What data is needed
- ✅ **Examples** - Sample request/response
- ✅ **Notes** - Important information

**To view:**
1. Select any request
2. Look at the description panel on the right

## 🎨 Tips & Tricks

### 1. Use Collection Variables

For frequently used values, add collection variables:

1. Click **...** on collection > **Edit**
2. Go to **Variables** tab
3. Add variables like `test_member_id`, `test_user_id`
4. Use in requests: `{{test_member_id}}`

### 2. Organize with Folders

Create sub-folders for different modules:
1. Right-click collection > **Add Folder**
2. Name it (e.g., "Restaurant APIs")
3. Drag requests into folders

### 3. Save Examples

After successful requests:
1. Click **Save as Example**
2. Name it (e.g., "Success Response")
3. View later in **Examples** dropdown

### 4. Use Console

View detailed request/response:
1. Click **Console** (bottom left)
2. See full headers, body, cookies
3. Debug issues easily

### 5. Keyboard Shortcuts

- **Send Request**: `Ctrl + Enter` (Win) / `Cmd + Enter` (Mac)
- **Save Request**: `Ctrl + S` / `Cmd + S`
- **New Tab**: `Ctrl + T` / `Cmd + T`

## 🔒 Security Best Practices

1. **Never commit tokens** to version control
2. **Use separate environments** for dev/staging/production
3. **Rotate passwords** regularly
4. **Don't share admin credentials**
5. **Use HTTPS** in production

## 📞 Need Help?

- Check request descriptions
- View API docs: `GET /api/v1/docs`
- Check server logs: `logs/combined.log`
- Read README.md for detailed documentation

---

**Happy Testing! 🚀**