# MSA Implementation - Testing Guide

## ✅ Implementation Complete!

All MSA components are now integrated and ready for testing.

---

## What Was Done

### Backend ✅
1. Database migration created and run
2. MsaDocument model with relationships
3. MsaService with complete business logic
4. MsaController with all API endpoints
5. API routes added
6. PDF template created

### Frontend ✅
1. MSA Signing Modal (3-step wizard)
2. Signature Pad component (canvas-based)
3. Integration with quotation acceptance flow

---

## Testing Flow

### Step 1: Create Test Quotation
1. Go to coverage check
2. Enter address with MEDIUM feasibility
3. Request quotation
4. Wait for quotation to be created

### Step 2: Accept Quotation (Triggers MSA)
1. Go to quotations list
2. Click on the quotation
3. Click "Accept Quotation" button
4. **Expected**: MSA modal should open automatically

### Step 3: Complete MSA Signing
**Step 1 - Review Terms**:
- Review MSA terms
- Click "Next"

**Step 2 - Fill Information**:
- Verify pre-filled data
- Complete any missing fields
- Click "Next"

**Step 3 - Sign**:
- Draw signature on canvas
- Click "Save Signature"
- Check "I accept terms"
- Click "Sign Agreement"

### Step 4: Verify Results
1. **Frontend**: Success message should appear
2. **Database**: Check `msa_documents` table for new record
3. **Storage**: Check `storage/app/public/msa-documents/` for PDF
4. **Odoo**: Check for attachment on customer record

---

## API Testing

### 1. Check if MSA Required
```bash
curl -X GET "http://localhost:8000/api/msa/quotation/1/check" \
  -H "Authorization: Bearer YOUR_TOKEN"
```

**Expected Response**:
```json
{
  "required": true,
  "quotation_id": 1,
  "feasibility": "MEDIUM"
}
```

### 2. Initiate MSA
```bash
curl -X POST "http://localhost:8000/api/msa/initiate" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"quotation_id": 1}'
```

**Expected Response**:
```json
{
  "message": "MSA draft created successfully",
  "msa": {
    "id": 1,
    "document_number": "MSA-2026-0001",
    "status": "draft",
    "customer_data": {...}
  }
}
```

### 3. Update Customer Data
```bash
curl -X PUT "http://localhost:8000/api/msa/1/data" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "customer_name": "Test Company",
    "customer_registration_number": "1234/2020",
    "customer_physical_address": "123 Test St",
    "customer_telephone": "+263123456",
    "customer_email": "test@company.com",
    "customer_contact_person": "John Doe",
    "signing_location": "Harare"
  }'
```

### 4. Upload Signature
```bash
curl -X POST "http://localhost:8000/api/msa/1/signature" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"signature": "data:image/png;base64,iVBORw0KG..."}'
```

### 5. Sign MSA
```bash
curl -X POST "http://localhost:8000/api/msa/1/sign" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"accept_terms": true}'
```

### 6. Download PDF
```bash
curl -X GET "http://localhost:8000/api/msa/1/download" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  --output msa.pdf
```

---

## Database Verification

### Check MSA Record
```sql
SELECT * FROM msa_documents WHERE id = 1;
```

**Expected Fields**:
- `id`: 1
- `customer_id`: Customer ID
- `quotation_id`: Quotation ID
- `document_number`: MSA-2026-0001
- `status`: completed
- `signature_path`: Path to signature image
- `pdf_path`: Path to PDF file
- `signed_at`: Timestamp
- `ip_address`: IP address
- `user_agent`: Browser info

---

## File System Verification

### Check Signature Image
```bash
ls -la storage/app/public/msa-signatures/
```

**Expected**: `signature-1-{timestamp}.png`

### Check PDF Document
```bash
ls -la storage/app/public/msa-documents/
```

**Expected**: `msa-MSA-2026-0001-{timestamp}.pdf`

---

## Frontend Testing Checklist

### Modal Behavior
- [ ] Modal opens when accepting MEDIUM feasibility quotation
- [ ] Modal does NOT open for HIGH feasibility (resubscription)
- [ ] Modal backdrop is blurred (matches portal style)
- [ ] Can close modal with X button
- [ ] Can close modal by clicking backdrop

### Step 1: Review Terms
- [ ] Terms display correctly
- [ ] "Next" button works
- [ ] Can go back to quotation page

### Step 2: Fill Information
- [ ] Form pre-filled with customer data
- [ ] All fields editable
- [ ] Validation works (required fields)
- [ ] Email validation works
- [ ] "Back" button works
- [ ] "Next" button saves data

### Step 3: Sign
- [ ] Signature pad renders
- [ ] Can draw signature with mouse
- [ ] Can draw signature with touch (mobile)
- [ ] "Clear" button works
- [ ] "Save Signature" button works
- [ ] Signature saved indicator shows
- [ ] Terms checkbox works
- [ ] "Sign Agreement" button disabled until signature + checkbox
- [ ] "Sign Agreement" button works

### After Signing
- [ ] Success message appears
- [ ] Modal closes
- [ ] Redirects to quotation accept page
- [ ] Can proceed with quotation acceptance

---

## Backend Testing Checklist

### MSA Requirement Logic
- [ ] MEDIUM feasibility → MSA required
- [ ] HIGH feasibility + first installation → MSA required
- [ ] HIGH feasibility + resubscription → MSA NOT required
- [ ] LOW feasibility → MSA required

### MSA Creation
- [ ] Draft MSA created with correct data
- [ ] Document number generated correctly
- [ ] Customer data pre-filled from profile
- [ ] Status set to "draft"

### Data Update
- [ ] Customer data updates successfully
- [ ] Validation works
- [ ] Cannot update signed MSA

### Signature Upload
- [ ] Signature image saved to storage
- [ ] Path stored in database
- [ ] Image accessible via URL

### PDF Generation
- [ ] PDF generated with correct data
- [ ] Customer information appears
- [ ] Signature image embedded
- [ ] Document number on PDF
- [ ] Timestamp on PDF

### Odoo Integration
- [ ] PDF uploaded to Odoo
- [ ] Attachment linked to customer
- [ ] Attachment ID stored in database

### Status Transitions
- [ ] draft → signed (when signing)
- [ ] signed → completed (after PDF + Odoo)
- [ ] Cannot modify after signed

---

## Error Scenarios to Test

### 1. Network Errors
- [ ] MSA check fails → Show error, allow retry
- [ ] MSA initiation fails → Show error message
- [ ] Signature upload fails → Show error, allow retry
- [ ] PDF generation fails → Show error message

### 2. Validation Errors
- [ ] Missing required fields → Show validation errors
- [ ] Invalid email → Show email validation error
- [ ] No signature → Cannot sign
- [ ] Terms not accepted → Cannot sign

### 3. Authorization Errors
- [ ] Unauthorized user → 403 error
- [ ] Expired token → Redirect to login
- [ ] Wrong customer → Cannot access MSA

---

## Performance Testing

### Load Times
- [ ] Modal opens quickly (<500ms)
- [ ] Signature pad responsive
- [ ] PDF generation completes (<5s)
- [ ] Odoo upload completes (<10s)

### File Sizes
- [ ] Signature image <100KB
- [ ] PDF document <500KB
- [ ] No memory leaks in signature pad

---

## Mobile Testing

### Responsive Design
- [ ] Modal fits mobile screen
- [ ] Form fields accessible
- [ ] Signature pad works with touch
- [ ] Buttons properly sized for touch

### Touch Interactions
- [ ] Can draw signature smoothly
- [ ] Pinch/zoom disabled on canvas
- [ ] Scroll works outside canvas

---

## Browser Compatibility

Test in:
- [ ] Chrome (latest)
- [ ] Firefox (latest)
- [ ] Safari (latest)
- [ ] Edge (latest)
- [ ] Mobile Safari (iOS)
- [ ] Mobile Chrome (Android)

---

## Security Testing

### Authorization
- [ ] Only authenticated users can access
- [ ] Users can only access their own MSAs
- [ ] Cannot modify other users' MSAs

### Data Validation
- [ ] Server-side validation works
- [ ] SQL injection prevented
- [ ] XSS attacks prevented

### Audit Trail
- [ ] IP address logged
- [ ] User agent logged
- [ ] Timestamp recorded
- [ ] All actions logged

---

## Integration Testing

### Quotation Flow
1. Create quotation (MEDIUM feasibility)
2. Accept quotation → MSA modal opens
3. Complete MSA signing
4. Quotation acceptance continues
5. Order created
6. MSA linked to order

### Odoo Sync
1. MSA signed
2. PDF generated
3. Uploaded to Odoo
4. Attachment visible in Odoo
5. Linked to correct customer

---

## Troubleshooting

### Issue: Modal doesn't open
**Check**:
- Browser console for errors
- Network tab for API call
- MSA requirement check response

**Fix**:
- Verify API endpoint accessible
- Check authentication token
- Verify quotation has correct feasibility

### Issue: Signature not saving
**Check**:
- Browser console for errors
- Network tab for upload request
- Storage permissions

**Fix**:
- Check storage/app/public writable
- Verify signature data format
- Check file size limits

### Issue: PDF not generating
**Check**:
- Laravel logs
- DomPDF installation
- Template syntax errors

**Fix**:
- Install: `composer require barryvdh/laravel-dompdf`
- Check template for errors
- Verify image paths

### Issue: Odoo sync failing
**Check**:
- Odoo credentials in .env
- Network connectivity
- Odoo API logs

**Fix**:
- Verify ODOO_URL, ODOO_DB, credentials
- Test Odoo connection separately
- Check Odoo API permissions

---

## Success Criteria

✅ **All tests pass**
✅ **MSA modal opens for MEDIUM feasibility**
✅ **3-step wizard completes successfully**
✅ **Signature captured and saved**
✅ **PDF generated with correct data**
✅ **PDF uploaded to Odoo**
✅ **Quotation acceptance continues after MSA**
✅ **No console errors**
✅ **No backend errors**
✅ **Mobile experience smooth**

---

## Next Steps After Testing

1. **Fix any bugs found**
2. **Optimize performance**
3. **Add email notifications**
4. **Deploy to staging**
5. **User acceptance testing**
6. **Deploy to production**

---

## Quick Test Command

Run all backend tests:
```bash
cd afinet-portal-backend
php artisan test --filter=Msa
```

Run frontend in dev mode:
```bash
cd afinet-portal
npm run dev
```

---

**Status**: Ready for Testing ✅
**Estimated Testing Time**: 2-3 hours
**Priority**: High (Required for quotation acceptance)