# QC_USER_2 Role Implementation

## 🎯 Overview

This document describes the implementation of the new **QC_USER_2** role, which provides advanced quality control capabilities with access to all QC status options.

## 📋 Role Comparison

| Feature | QC_USER (qc_user_1) | QC_USER_2 (qc_user_2) |
|---------|---------------------|----------------------|
| **Unverified (0)** | ✅ Yes | ✅ Yes |
| **Level 1 Approved (1)** | ✅ Yes | ✅ Yes |
| **Level 2 Hold (2)** | ❌ No | ✅ Yes |
| **Verified (3)** | ❌ No | ✅ Yes |
| **Rejected (4)** | ✅ Yes | ✅ Yes |
| **Dashboard Access** | ✅ Yes | ✅ Yes |
| **Map Access** | ✅ Yes | ✅ Yes |
| **QC Dashboard** | ✅ Yes | ✅ Yes |
| **Survey Inventory** | ✅ Yes | ✅ Yes |

## 🗄️ Database Schema

### User Master Table

```sql
-- Role ID: 7
-- Role Name: QC_USER_2
-- Display Name: Quality Control User Level 2
-- Description: Advanced quality control access with full QC status options
```

### Permissions

```json
{
  "can_view_all_data": true,
  "can_verify_data": true,
  "can_set_level_2_hold": true,
  "can_verify_final": true,
  "can_reject": true
}
```

## 🚀 Installation

### For New Installations

Run the database setup script which will automatically create all 7 roles including QC_USER_2:

```bash
cd Backend
node setupDatabase.js
```

### For Existing Databases

Execute the migration SQL script:

```bash
cd Backend
psql -U your_username -d your_database -f add_qc_user_2_role.sql
```

Or run directly in your database:

```sql
INSERT INTO user_master (id, role_name, role_display_name, description, permissions, is_active, sort_order, "createdAt", "updatedAt")
VALUES (
  7,
  'QC_USER_2',
  'Quality Control User Level 2',
  'Advanced quality control access with full QC status options including Level 2 Hold, Verified, and Rejected',
  '{"can_view_all_data": true, "can_verify_data": true, "can_set_level_2_hold": true, "can_verify_final": true, "can_reject": true}'::json,
  true,
  7,
  NOW(),
  NOW()
)
ON CONFLICT (role_name) DO UPDATE SET
  role_display_name = EXCLUDED.role_display_name,
  description = EXCLUDED.description,
  permissions = EXCLUDED.permissions,
  sort_order = EXCLUDED.sort_order,
  "updatedAt" = NOW();
```

## 📝 Implementation Details

### Backend Changes

#### 1. **setupDatabase.js**
- Added QC_USER_2 role definition with ID 7
- Updated role count from 6 to 7

#### 2. **treelogyController.js**
- Updated project list filtering to include QC_USER_2
- QC_USER_2 users don't see project list (same as QC_USER)

### Frontend Changes

#### 1. **RolesContext.jsx**
- Updated `getAvailableRolesForCreation()` to allow CLIENT_ADMIN to create QC_USER_2 users

#### 2. **QCModal.jsx**
- Added `userRole` prop
- Implemented `getFilteredStatuses()` function that:
  - Returns only statuses 0 and 1 for QC_USER
  - Returns all statuses (0-4) for QC_USER_2, SUPER_ADMIN, and CLIENT_ADMIN

#### 3. **QC.jsx**
- Passed `userRole={user?.role_name}` prop to QCModal

#### 4. **SurveyInventory.jsx**
- Passed `userRole={user?.role_name}` prop to QCModal

#### 5. **Sidebar.jsx**
- Updated navigation to show QC Dashboard and Survey Inventory for both QC_USER and QC_USER_2
- Updated Projects visibility to hide from both QC_USER and QC_USER_2

## 🧪 Testing

### Test QC_USER (Limited Access)

1. Create a QC_USER account
2. Login and navigate to QC Dashboard
3. Click on any survey to open QC Modal
4. Verify dropdown shows only:
   - Unverified (0)
   - Level 1 Approved (1)

### Test QC_USER_2 (Full Access)

1. Create a QC_USER_2 account
2. Login and navigate to QC Dashboard
3. Click on any survey to open QC Modal
4. Verify dropdown shows all 5 options:
   - Unverified (0)
   - Level 1 Approved (1)
   - Level 2 Hold (2)
   - Verified (3)
   - Rejected (4)

## 🔐 User Creation

### As SUPER_ADMIN

SUPER_ADMIN can create any user role including QC_USER_2:

1. Navigate to Users → Create User
2. Fill in user details
3. Select **Quality Control User Level 2** from role dropdown
4. Assign to appropriate projects

### As CLIENT_ADMIN

CLIENT_ADMIN can create QC_USER_2 users for their client:

1. Navigate to Users → Create User
2. Fill in user details
3. Select **Quality Control User Level 2** from role dropdown
4. Assign to appropriate projects (within their client)

## 📊 QC Workflow

### QC_USER Workflow (Level 1)

```
1. Review survey
2. Can mark as:
   - Unverified (needs more work)
   - Level 1 Approved (pass to Level 2)
   - Rejected (invalid/needs resurvey)
```

### QC_USER_2 Workflow (Level 2)

```
1. Review survey (typically after Level 1 approval)
2. Can mark as:
   - Unverified (send back)
   - Level 1 Approved (keep at Level 1)
   - Level 2 Hold (pending further review)
   - Verified (final approval)
   - Rejected (needs resurvey)
```

## 🔄 Status Flow

```
Unverified (0)
    ↓
Level 1 Approved (1) ← QC_USER can approve to here
    ↓
Level 2 Hold (2) ← QC_USER_2 can hold for review
    ↓
Verified (3) ← QC_USER_2 final approval
    
Rejected (4) ← QC_USER_2 can reject at any stage
```

## 📁 Files Modified

### Backend
- `Backend/setupDatabase.js` - Added QC_USER_2 role
- `Backend/controllers/treelogyController.js` - Updated project filtering
- `Backend/add_qc_user_2_role.sql` - Migration script

### Frontend
- `Frontend/src/contexts/RolesContext.jsx` - Role creation permissions
- `Frontend/src/components/QCModal.jsx` - Status filtering logic
- `Frontend/src/components/Sidebar.jsx` - Navigation visibility
- `Frontend/src/pages/QC.jsx` - Pass userRole to modal
- `Frontend/src/pages/SurveyInventory.jsx` - Pass userRole to modal

## ✅ Verification Checklist

- [x] QC_USER_2 role created in database
- [x] SQL migration script created
- [x] CLIENT_ADMIN can create QC_USER_2 users
- [x] QCModal filters statuses based on role
- [x] QC_USER sees only 2 status options
- [x] QC_USER_2 sees all 5 status options
- [x] Sidebar shows correct pages for both roles
- [x] Both roles have access to QC Dashboard
- [x] Both roles have access to Survey Inventory
- [x] Both roles don't see Projects list

## 🐛 Troubleshooting

### Issue: QC_USER_2 role not appearing in dropdown

**Solution:** Run the migration script or database setup:
```bash
cd Backend
node setupDatabase.js
```

### Issue: QC_USER_2 sees only 2 options instead of 5

**Solution:** Check that `userRole` prop is being passed correctly:
```javascript
<QCModal
  userRole={user?.role_name}
  // other props...
/>
```

### Issue: Status dropdown shows all options for QC_USER

**Solution:** Verify the filtering logic in QCModal.jsx line 284-294

## 📖 API Endpoints

All existing QC endpoints work with QC_USER_2:

- `GET /api/surveys/project/:treelogy_id/qc` - List QC surveys
- `POST /api/surveys/project/:treelogy_id/qc/:survey_id` - Submit QC review
- `GET /api/surveys/project/:treelogy_id/inventory` - Survey inventory

## 🎓 Best Practices

1. **Use QC_USER for initial review** - First level verification
2. **Use QC_USER_2 for final approval** - Second level verification and final decisions
3. **Assign appropriate roles** - Not all QC staff need Level 2 access
4. **Monitor workflow** - Track surveys at each QC level
5. **Document decisions** - Use remarks field for Level 2 Hold and Rejected statuses

## 🔮 Future Enhancements

Potential improvements for the QC system:

- [ ] QC history tracking (who approved at each level)
- [ ] Automated notifications when surveys reach Level 2
- [ ] QC performance metrics dashboard
- [ ] Bulk QC operations for QC_USER_2
- [ ] Role-based email notifications
- [ ] QC approval workflow automation

---

**Last Updated:** 2025-01-03  
**Version:** 1.0.0  
**Author:** Development Team