We're pleased to share Quote {$quote_number}...
Best regards,
{$sender_name}
We are working together on the opportunity: {$opportunity_name}.
This is a legally binding agreement...
"; ``` ### 4. Page Headers & Titles **Quote Page:** ```php // File: views/quotes/signature/accept.php, Line 179
 ?>){kind=logo}
```
---
## Database Schema
### Quote Signature Tables
#### `quotes` Table Extensions
```sql
ALTER TABLE quotes ADD COLUMN public_token VARCHAR(64) NULL;
ALTER TABLE quotes ADD COLUMN token_expires_at DATETIME NULL;
ALTER TABLE quotes ADD COLUMN customer_response ENUM('accepted', 'declined') NULL;
ALTER TABLE quotes ADD COLUMN accepted_at DATETIME NULL;
ALTER TABLE quotes ADD COLUMN accepted_by_name VARCHAR(255) NULL;
ALTER TABLE quotes ADD COLUMN accepted_by_email VARCHAR(255) NULL;
ALTER TABLE quotes ADD COLUMN declined_at DATETIME NULL;
ALTER TABLE quotes ADD COLUMN declined_by_name VARCHAR(255) NULL;
ALTER TABLE quotes ADD COLUMN declined_by_email VARCHAR(255) NULL;
ALTER TABLE quotes ADD COLUMN declined_reason TEXT NULL;
```
#### `quote_signatures` Table
```sql
CREATE TABLE quote_signatures (
id INT AUTO_INCREMENT PRIMARY KEY,
quote_id INT NOT NULL,
signature_data TEXT NOT NULL, -- Base64 image
accepted_by_name VARCHAR(255) NOT NULL,
accepted_by_email VARCHAR(255) NOT NULL,
accepted_by_title VARCHAR(255) NULL,
company_name VARCHAR(255) NULL,
signed_at DATETIME NOT NULL,
ip_address VARCHAR(45) NULL,
user_agent TEXT NULL,
FOREIGN KEY (quote_id) REFERENCES quotes(id)
);
```
### NDA Tables
#### `ndas` Table
```sql
CREATE TABLE ndas (
id INT AUTO_INCREMENT PRIMARY KEY,
nda_number VARCHAR(50) UNIQUE NOT NULL,
opportunity_id INT NULL,
template_id INT NULL,
nda_type ENUM('unilateral', 'bilateral', 'multilateral'),
company_name VARCHAR(255) NOT NULL,
contact_name VARCHAR(255) NULL,
contact_email VARCHAR(255) NULL,
contact_title VARCHAR(100) NULL,
effective_date DATE NOT NULL,
expiration_date DATE NULL,
term_months INT DEFAULT 12,
document_content LONGTEXT NOT NULL,
notes TEXT NULL,
status ENUM('draft', 'sent', 'viewed', 'signed', 'declined', 'expired'),
public_token VARCHAR(64) NULL,
token_expires_at DATETIME NULL,
sent_at DATETIME NULL,
viewed_at DATETIME NULL,
signed_at DATETIME NULL,
declined_at DATETIME NULL,
declined_reason TEXT NULL,
created_by INT NULL,
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
FOREIGN KEY (opportunity_id) REFERENCES opportunities(id),
FOREIGN KEY (template_id) REFERENCES nda_templates(id),
FOREIGN KEY (created_by) REFERENCES users(id)
);
```
#### `nda_signatures` Table
```sql
CREATE TABLE nda_signatures (
id INT AUTO_INCREMENT PRIMARY KEY,
nda_id INT NOT NULL,
signature_data TEXT NOT NULL, -- Base64 image
signer_name VARCHAR(255) NOT NULL,
signer_email VARCHAR(255) NOT NULL,
signer_title VARCHAR(255) NULL,
signer_company VARCHAR(255) NULL,
acceptance_text TEXT NULL,
signed_at DATETIME NOT NULL,
ip_address VARCHAR(45) NULL,
user_agent TEXT NULL,
FOREIGN KEY (nda_id) REFERENCES ndas(id)
);
```
#### `nda_templates` Table
```sql
CREATE TABLE nda_templates (
id INT AUTO_INCREMENT PRIMARY KEY,
template_name VARCHAR(255) NOT NULL,
template_type ENUM('unilateral', 'bilateral', 'multilateral'),
template_content LONGTEXT NOT NULL, -- HTML with merge fields
is_default BOOLEAN DEFAULT 0,
is_active BOOLEAN DEFAULT 1,
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);
```
#### `opportunities` Table Extensions
```sql
ALTER TABLE opportunities ADD COLUMN requires_nda BOOLEAN DEFAULT 0;
ALTER TABLE opportunities ADD COLUMN nda_status ENUM('not_required', 'sent', 'signed', 'declined') NULL;
ALTER TABLE opportunities ADD COLUMN block_quote_without_nda BOOLEAN DEFAULT 0;
```
---
## API Endpoints
### Quote Endpoints
#### Send Quote Email
```
POST /quotes/general/{id}/send-email
Headers:
Content-Type: application/x-www-form-urlencoded
Body:
to_email: customer@email.com
subject: Quote {quote_number} - Please Review
message: Custom message body
csrf_token: {token}
Response:
{
"success": true,
"message": "Quote email sent successfully to customer@email.com"
}
```
#### View Quote (Public)
```
GET /quotes/accept/{token}
No authentication required
Returns HTML signature page
```
#### Accept Quote
```
POST /quotes/accept/{token}/submit
Body (FormData):
signature_data: data:image/png;base64,...
accepted_by_name: John Doe
accepted_by_email: john@company.com
accepted_by_title: CEO
company_name: ACME Corp
Response:
{
"success": true,
"message": "Quote accepted successfully. Thank you!",
"signature_id": 123
}
```
#### Decline Quote
```
POST /quotes/decline/{token}
Body (FormData):
declined_by_name: John Doe
declined_by_email: john@company.com
declined_reason: Price too high
Response:
{
"success": true,
"message": "Quote declined. Thank you for your response."
}
```
### NDA Endpoints
#### Send NDA Email
```
POST /ndas/{id}/send-email
Headers:
Content-Type: application/x-www-form-urlencoded
Body:
to_email: customer@email.com
subject: NDA {nda_number} - Signature Required
message: Custom message body
csrf_token: {token}
Response:
{
"success": true,
"message": "NDA email sent successfully to customer@email.com"
}
```
#### View NDA (Public)
```
GET /ndas/sign/{token}
No authentication required
Returns HTML signature page
```
#### Sign NDA
```
POST /ndas/sign/{token}/submit
Body (FormData):
signature_data: data:image/png;base64,...
signer_name: John Doe
signer_email: john@company.com
signer_title: CEO
signer_company: ACME Corp
acceptance_agreed: on
acceptance_text: I agree to the terms
Response:
{
"success": true,
"message": "NDA signed successfully. Thank you!",
"signature_id": 456
}
```
#### Decline NDA
```
POST /ndas/decline/{token}
Body (FormData):
declined_reason: Cannot agree to terms
Response:
{
"success": true,
"message": "NDA declined. Thank you for your response."
}
```
#### Check NDA Status
```
GET /api/opportunities/{id}/nda-status
Response:
{
"requires_nda": true,
"nda_status": "signed",
"block_without_nda": true,
"can_proceed": true,
"message": null
}
```
---
## Security Features
### 1. Token-Based Access
- **Public tokens:** 64-character random hex strings
- **Expiration:**
- Quotes: 30 days (configurable)
- NDAs: 90 days (configurable)
- **One-time use:** Token invalidated after acceptance/decline
- **Validation:** Token checked before every action
### 2. CSRF Protection
- All POST endpoints require valid CSRF token
- Token generated per session
- Validated on every state-changing request
### 3. Authentication & Authorization
- Internal endpoints require authentication
- Permission checks: `sales.edit`, `ndas.send`
- Public signature pages accessible without auth
### 4. Audit Trail
Records for compliance:
- **IP Address:** Captured at signature time
- **User Agent:** Browser/device information
- **Timestamp:** Exact date/time of action
- **Signature Image:** Base64-encoded signature
- **Email verification:** Signer email captured
### 5. Input Validation
- Email address format validation
- Required field enforcement
- SQL injection prevention (prepared statements)
- XSS prevention (output escaping with `e()` helper)
### 6. Status Validation
- Prevents re-signing accepted quotes
- Prevents editing signed NDAs
- Blocks quote creation if NDA required and not signed
- Status transitions tracked in database
### 7. Data Sanitization
All user inputs sanitized:
```php
sanitize($_POST['field']) // XSS prevention
e($variable) // Output escaping
```
---
## Troubleshooting
### Email Not Sending
**Check SMTP Configuration:**
```php
// File: services/EmailService.php, Lines 34-40
$this->mailer->Host = '172.104.216.9';
$this->mailer->SMTPAuth = true;
$this->mailer->Username = 'erp_system@mavrix.one';
$this->mailer->Password = 'xyz8468RPMerkuri123!';
$this->mailer->SMTPSecure = PHPMailer::ENCRYPTION_STARTTLS;
$this->mailer->Port = 587;
```
**Check Error Logs:**
```bash
tail -f /path/to/php-error.log
# Look for "EmailService: Failed to send email"
```
**Test Email Function:**
```php
// Create test file: test_email.php
require_once 'services/EmailService.php';
$emailService = new EmailService();
$result = $emailService->sendQuoteForApproval(
'test@example.com',
'Test User',
'Q-2024-00001',
'http://localhost/quotes/accept/testtoken',
1500.00,
'Sales Team',
'2024-12-31'
);
var_dump($result);
```
### Signature Page Not Loading
1. **Check token validity:**
```sql
SELECT public_token, token_expires_at, customer_response
FROM quotes WHERE id = ?;
```
2. **Verify route exists:**
```bash
grep "quotes/accept" public/index.php
```
3. **Check Apache/Nginx rewrite rules**
### Signature Not Saving
**Check browser console for JavaScript errors:**
- Canvas drawing issues
- AJAX request failures
- Form validation errors
**Verify database fields exist:**
```sql
DESCRIBE quotes;
DESCRIBE quote_signatures;
```
### NDA Not Linking to Opportunity
**Check foreign key:**
```sql
SELECT o.id, o.name, n.id, n.nda_number, o.nda_status
FROM opportunities o
LEFT JOIN ndas n ON n.opportunity_id = o.id
WHERE o.id = ?;
```
**Update opportunity NDA status:**
```php
// In NDA model after signature
$this->db->update('opportunities', [
'nda_status' => 'signed'
], 'id = ?', [$nda['opportunity_id']]);
```
---
## Maintenance Tasks
### Weekly
- [ ] Review email send logs
- [ ] Check for expired tokens
- [ ] Monitor signature page access logs
### Monthly
- [ ] Clean up old signatures (if needed)
- [ ] Review accepted/declined ratios
- [ ] Update email templates based on feedback
- [ ] Test email deliverability
### Quarterly
- [ ] Review SMTP credentials/expiration
- [ ] Update legal language in NDA templates
- [ ] Audit security features
- [ ] Performance optimization
---
## Future Enhancements
### Planned Features
- [ ] PDF attachment of quote/NDA in email
- [ ] Reminder emails for unsigned documents
- [ ] Mobile-responsive improvements
- [ ] Bulk email sending
- [ ] Email open tracking
- [ ] Template builder UI
- [ ] Multi-language support
- [ ] SMS notifications
- [ ] Electronic notarization
- [ ] Integration with DocuSign/HelloSign
---
## Support & Documentation
### Related Documentation
- `EMAIL_INTEGRATION.md` - Detailed email service documentation
- `WARP.md` - General development guidelines
- `OPPORTUNITIES_ENHANCEMENTS.md` - CRM opportunities features
- `database/README.md` - Database migration guide
### Questions?
Refer to inline code comments in:
- `services/EmailService.php`
- `controllers/QuoteController.php`
- `controllers/NDAController.php`
- `models/QuoteSignature.php`
- `models/NDA.php`