# Quick Start: Skip & Add Approver Features

## 🚀 Setup (One-Time)

### **Step 1: Run Database Migration**

```bash
# Connect to database
psql -U postgres -d re_workflow

# Run migration
\i Re_Backend/src/migrations/add_is_skipped_to_approval_levels.sql

# Verify columns added
\d approval_levels
# Should show: is_skipped, skipped_at, skipped_by, skip_reason
```

### **Step 2: Restart Backend**

```bash
cd Re_Backend
npm run dev
```

---

## 📖 User Guide

### **How to Skip an Approver (Initiator/Approver)**

1. Go to **Request Detail** → **Workflow** tab
2. Find the approver who is pending/in-review
3. Click **"Skip This Approver"** button
4. Enter reason (e.g., "On vacation")
5. Click OK

**Result:**
- ✅ Approver marked as SKIPPED
- ✅ Next approver becomes active
- ✅ Notification sent to next approver
- ✅ Activity logged

---

### **How to Add New Approver (Initiator/Approver)**

1. Go to **Request Detail** → **Quick Actions**
2. Click **"Add Approver"**
3. Review **Current Levels** (shows all existing approvers with status)
4. Select **Approval Level** (where to insert new approver)
5. Enter **TAT Hours** (e.g., 48)
6. Enter **Email** (use @ to search: `@john`)
7. Click **"Add at Level X"**

**Result:**
- ✅ New approver inserted at chosen level
- ✅ Existing approvers shifted automatically
- ✅ TAT jobs scheduled if level is active
- ✅ Notification sent to new approver
- ✅ Activity logged

---

## 🎯 Examples

### **Example 1: Skip Non-Responding Approver**

**Scenario:** Mike (Level 2) hasn't responded for 3 days, deadline approaching

**Steps:**
1. Open request REQ-2025-001
2. Go to Workflow tab
3. Find Mike's card (Level 2 - In Review)
4. Click "Skip This Approver"
5. Reason: "Approver on extended leave - deadline critical"
6. Confirm

**Result:**
```
Before:                    After:
Level 1: Sarah ✅          Level 1: Sarah ✅
Level 2: Mike ⏳    →      Level 2: Mike ⏭️ (SKIPPED)
Level 3: Lisa ⏸️           Level 3: Lisa ⏳ (ACTIVE!)
```

---

### **Example 2: Add Finance Review**

**Scenario:** Need Finance Manager approval between existing levels

**Steps:**
1. Click "Add Approver" in Quick Actions
2. See current levels:
   - Level 1: Sarah (Approved)
   - Level 2: Mike (In Review)
   - Level 3: Lisa (Waiting)
3. Select Level: **3** (to insert before Lisa)
4. TAT Hours: **48**
5. Email: `@john` → Select "John Doe (john@finance.com)"
6. Click "Add at Level 3"

**Result:**
```
Before:                          After:
Level 1: Sarah ✅                Level 1: Sarah ✅
Level 2: Mike ⏳                 Level 2: Mike ⏳
Level 3: Lisa ⏸️         →       Level 3: John ⏸️ (NEW!)
                                  Level 4: Lisa ⏸️ (shifted)
```

---

## ⚙️ API Reference

### **Skip Approver**

```bash
POST /api/v1/workflows/:requestId/approvals/:levelId/skip

Headers:
  Authorization: Bearer <token>

Body:
{
  "reason": "Approver on vacation"
}

Response:
{
  "success": true,
  "message": "Approver skipped successfully"
}
```

---

### **Add Approver at Level**

```bash
POST /api/v1/workflows/:requestId/approvers/at-level

Headers:
  Authorization: Bearer <token>

Body:
{
  "email": "john@example.com",
  "tatHours": 48,
  "level": 3
}

Response:
{
  "success": true,
  "message": "Approver added successfully",
  "data": {
    "levelId": "...",
    "levelNumber": 3,
    "approverName": "John Doe",
    "tatHours": 48
  }
}
```

---

## 🛡️ Permissions

| Action | Who Can Do It |
|--------|---------------|
| Skip Approver | ✅ INITIATOR, ✅ APPROVER |
| Add Approver | ✅ INITIATOR, ✅ APPROVER |
| View Skip Reason | ✅ All participants |

---

## ⚠️ Limitations

| Limitation | Reason |
|------------|--------|
| Cannot skip approved levels | Data integrity |
| Cannot skip rejected levels | Already closed |
| Cannot skip already skipped levels | Already handled |
| Cannot skip future levels | Not yet active |
| Cannot add before completed levels | Would break workflow state |
| Must provide valid TAT (1-720h) | Business rules |

---

## 📊 Dashboard Impact

### **Skipped Approvers in Reports:**

```sql
-- Count skipped approvers
SELECT COUNT(*) 
FROM approval_levels 
WHERE is_skipped = TRUE;

-- Find requests with skipped levels
SELECT r.request_number, al.level_number, al.approver_name, al.skip_reason
FROM workflow_requests r
JOIN approval_levels al ON r.request_id = al.request_id
WHERE al.is_skipped = TRUE;
```

### **KPIs Affected:**

- **Avg Approval Time** - Skipped levels excluded from calculation
- **Approver Response Rate** - Skipped marked separately
- **Workflow Bottlenecks** - Identify frequently skipped approvers

---

## 🔍 Troubleshooting

### **"Cannot skip approver - level is already APPROVED"**
- The level has already been approved
- You cannot skip completed levels

### **"Cannot skip future approval levels"**
- You're trying to skip a level that hasn't been reached yet
- Only current level can be skipped

### **"Cannot add approver at level X. Minimum allowed level is Y"**
- You're trying to add before a completed level
- Must add after all approved/rejected/skipped levels

### **"User is already a participant in this request"**
- The user is already an approver, initiator, or spectator
- Cannot add same user twice

---

## ✅ Testing Checklist

- [ ] Run database migration
- [ ] Restart backend server
- [ ] Create test workflow with 3 approvers
- [ ] Approve Level 1
- [ ] Skip Level 2 (test skip functionality)
- [ ] Verify Level 3 becomes active
- [ ] Add new approver at Level 3 (test add functionality)
- [ ] Verify levels shifted correctly
- [ ] Check activity log shows both actions
- [ ] Verify notifications sent correctly

---

Ready to use! 🎉