# Trust Creation - Referral Links Usage Guide

## Problem Summary
Previously, when a lawyer tried to create a trust for a specific client using a referral link with `?client_id=X`, the form would require manual client selection and show an error: "The client id field is required."

## Solution
The form now automatically selects the client when accessed via a referral link with the `client_id` parameter.

---

## How to Create Referral Links

### Basic Format
```
/lawyer/trusts/create?client_id=CLIENT_ID
```

### Full URL Example
```
https://yourappname.com/lawyer/trusts/create?client_id=42
```

---

## Step-by-Step Guide for Lawyers

### Creating a Referral Link for a Client

1. **Find the Client ID**
   - Go to your clients list: `/lawyer/clients`
   - Find the desired client
   - Note their ID (often visible in URL or client card)

2. **Create the Link**
   - Format: `/lawyer/trusts/create?client_id=[ID]`
   - Example: `/lawyer/trusts/create?client_id=42`

3. **Share the Link**
   - Send to the client
   - Can be shared via email, SMS, or messaging app

### What Happens When Client Clicks the Link

1. **Client clicks the link** → Takes them to trust creation form
2. **Client name appears** in a pre-filled, read-only field
3. **Green checkmark icon** confirms the client is selected
4. **Client fills remaining form fields** (name, NRIC, DOB, etc.)
5. **Client clicks "Next"** → Form submits successfully
6. **Trust is created** without any "client_id required" error

---

## Use Cases

### Use Case 1: Onboarding New Client
After meeting a client, send them a referral link:
```
https://yourapp.com/lawyer/trusts/create?client_id=42

"Hi, please click here to start your trust creation. Your information is already pre-filled!"
```

### Use Case 2: Follow-up for Existing Client
For a client who needs to complete a trust:
```
https://yourapp.com/lawyer/trusts/create?client_id=42

"You can continue creating your trust here. Your information is already selected."
```

### Use Case 3: Quick Trust Creation
Speed up the process for a client who already exists in the system:
```
https://yourapp.com/lawyer/trusts/create?client_id=42
```

---

## Examples by Client ID

| Client ID | Referral Link |
|-----------|---------------|
| 1 | `/lawyer/trusts/create?client_id=1` |
| 5 | `/lawyer/trusts/create?client_id=5` |
| 42 | `/lawyer/trusts/create?client_id=42` |
| 100 | `/lawyer/trusts/create?client_id=100` |

---

## What Information Is Pre-Filled?

### With Referral Link (`?client_id=X`)
✅ **Client Name** (read-only, auto-selected)
- First Name
- Last Name
- Email

### Without Referral Link
❌ **No information pre-filled**
- Lawyer must manually select client from dropdown
- All fields start empty

### After Selecting Client
Both scenarios then require filling:
- NRIC / ID Number
- Date of Birth
- Nationality
- Gender
- Phone Number
- Residential Address

---

## Feature Behavior

### With `?client_id` Parameter
```
URL: /lawyer/trusts/create?client_id=42

Display:
┌─────────────────────────────────────┐
│ Select Client                       │
│ ✓ John Smith (john@email.com)      │
└─────────────────────────────────────┘
↑ Shows client name with green checkmark
↑ Cannot change without modifying URL
```

### Without `?client_id` Parameter
```
URL: /lawyer/trusts/create

Display:
┌─────────────────────────────────────┐
│ Select Client                       │
│ [▼ -- Select a Client --          │
│   John Smith (john@email.com)      │
│   Jane Doe (jane@email.com)        │
│   Bob Johnson (bob@email.com)      │
│ ]                                   │
└─────────────────────────────────────┘
↑ Shows dropdown list
↑ Lawyer must select manually
```

---

## Security Features

### Authorization Check
- Only lawyers who own/created the client can access referral link
- If another lawyer tries: **403 Forbidden** error

### Tampering Prevention
- Client ID is validated server-side
- Cannot be changed on client-side without modifying URL
- Hidden input field prevents accidental changes

### Example:
```
Scenario: Lawyer B tries to access Lawyer A's client
URL: /lawyer/trusts/create?client_id=1 (Lawyer A's client)

Result: 403 Unauthorized error
Message: "You do not have access to this client"
```

---

## Troubleshooting

### Issue: "The client id field is required"
**Solution:** Ensure `?client_id=123` is included in the URL

### Issue: 403 Unauthorized Error
**Solution:** Verify the client ID belongs to your firm/you

### Issue: Dropdown appears instead of client name
**Possible Causes:**
1. Invalid client ID in URL
2. Client ID doesn't exist
3. You don't have access to that client

**Solution:** Start fresh without the client_id parameter

### Issue: Can't find the Client ID
**Solution:** 
1. Go to `/lawyer/clients`
2. Look at the URL when viewing a client profile
3. ID is usually at the end: `/lawyer/clients/**123**`

---

## Generating Referral Links Programmatically

### PHP/Laravel Example
```php
// In your controller or service
$clientId = $client->id;
$referralLink = route('lawyer.trusts.create', [], true) . '?client_id=' . $clientId;

// Result: https://yourapp.com/lawyer/trusts/create?client_id=42
```

### In Blade Templates
```blade
@php
    $clientId = $client->id;
@endphp

<a href="{{ route('lawyer.trusts.create') }}?client_id={{ $clientId }}" class="btn btn-primary">
    Create Trust
</a>
```

### In JavaScript
```javascript
const clientId = 42;
const referralLink = `/lawyer/trusts/create?client_id=${clientId}`;

// Use in href
document.getElementById('trustLink').href = referralLink;
```

---

## Testing the Feature

### Test Case 1: Valid Referral
1. Get a valid client ID from your system
2. Open: `/lawyer/trusts/create?client_id=YOUR_ID`
3. ✓ Client name should appear
4. ✓ Green checkmark visible
5. ✓ Fill other fields and submit
6. ✓ Trust created successfully

### Test Case 2: Invalid Client ID
1. Open: `/lawyer/trusts/create?client_id=999999`
2. ✓ Dropdown appears (fallback to manual selection)
3. ✓ No error message
4. ✓ Still usable

### Test Case 3: Unauthorized Client
1. Get a client ID from another lawyer
2. Open: `/lawyer/trusts/create?client_id=THEIR_CLIENT_ID`
3. ✓ 403 Forbidden error
4. ✓ Cannot proceed

---

## Benefits

| Benefit | Before | After |
|---------|--------|-------|
| **Ease of Use** | Manual selection | Auto-selected |
| **Error Rate** | High ("client_id required") | None |
| **Time to Fill Form** | Longer | Faster |
| **User Experience** | Frustrating | Smooth |
| **Backward Compatible** | N/A | ✓ Still works without client_id |

---

## Common Questions

**Q: Can I share this link with anyone?**  
A: Only with people who have access to your firm's system. The system will ask them to log in first.

**Q: What if the client doesn't exist in the system?**  
A: The form will show a dropdown where they can select from available clients, or you can create the client first.

**Q: Can clients share this link with others?**  
A: Yes, but only lawyers at your firm can use it (others will see 403 error).

**Q: Is the client ID sensitive information?**  
A: It's only useful within your app and requires authentication, so it's safe to share with your clients.

**Q: How long does the referral link work?**  
A: Indefinitely, as long as the client exists in your system.

---

## Migration from Old System

### Old Way (No Referral)
```
Lawyer: Sends client to /lawyer/trusts/create
Client: Opens form, sees empty dropdown, must select manually
Result: Confusion, errors
```

### New Way (With Referral)
```
Lawyer: Sends client to /lawyer/trusts/create?client_id=42
Client: Opens form, sees name pre-filled
Result: Quick, easy, no errors
```

---

## Support & Feedback

If you encounter issues with referral links:
1. Check the client ID is valid
2. Verify you have access to the client
3. Ensure the client exists in the system
4. Try accessing without the client_id parameter

For persistent issues, contact your system administrator.