quality_recticel/old code/documentation/INSTALLATION_GUIDE.md

# Quality Recticel Windows Print Service - Installation Guide

## 📋 Overview

The Quality Recticel Windows Print Service enables **silent PDF printing** directly from the web application through a Chrome extension. This system eliminates the need for manual PDF downloads and provides seamless label printing functionality.

## 🏗️ System Architecture

```
Web Application (print_module.html)
         ↓
Windows Print Service (localhost:8765)
         ↓
Chrome Extension (Native Messaging)
         ↓
Windows Print System
```

## 📦 Package Contents

```
windows_print_service/
├── print_service.py           # Main Windows service (Flask API)
├── service_manager.py         # Service installation & management
├── install_service.bat        # Automated installation script
├── chrome_extension/          # Chrome extension files
│   ├── manifest.json         # Extension configuration
│   ├── background.js         # Service worker
│   ├── content.js           # Page integration
│   ├── popup.html           # Extension UI
│   ├── popup.js            # Extension logic
│   └── icons/              # Extension icons
└── INSTALLATION_GUIDE.md     # This documentation
```

## 🔧 Prerequisites

### System Requirements
- **Operating System**: Windows 10/11 (64-bit)
- **Python**: Python 3.8 or higher
- **Browser**: Google Chrome (latest version)
- **Privileges**: Administrator access required for installation

### Python Dependencies
The following packages will be installed automatically:
- `flask` - Web service framework
- `flask-cors` - Cross-origin resource sharing
- `requests` - HTTP client library  
- `pywin32` - Windows service integration

## 🚀 Installation Process

### Step 1: Download and Extract Files

1. Download the `windows_print_service` folder to your system
2. Extract to a permanent location (e.g., `C:\QualityRecticel\PrintService\`)
3. **Do not move or delete this folder after installation**

### Step 2: Install Windows Service

#### Method A: Automated Installation (Recommended)

1. **Right-click** on `install_service.bat`
2. Select **"Run as administrator"**
3. Click **"Yes"** when Windows UAC prompt appears
4. Wait for installation to complete

#### Method B: Manual Installation

If the automated script fails, follow these steps:

```bash
# Open Command Prompt as Administrator
cd C:\path\to\windows_print_service

# Install Python dependencies
pip install flask flask-cors requests pywin32

# Install Windows service
python service_manager.py install

# Add firewall exception
netsh advfirewall firewall add rule name="Quality Recticel Print Service" dir=in action=allow protocol=TCP localport=8765

# Create Chrome extension registry entry
reg add "HKEY_CURRENT_USER\Software\Google\Chrome\NativeMessagingHosts\com.qualityrecticel.printservice" /ve /d "%cd%\chrome_extension\manifest.json" /f
```

### Step 3: Install Chrome Extension

1. Open **Google Chrome**
2. Navigate to `chrome://extensions/`
3. Enable **"Developer mode"** (toggle in top-right corner)
4. Click **"Load unpacked"**
5. Select the `chrome_extension` folder
6. Verify the extension appears with a printer icon

### Step 4: Verify Installation

#### Check Windows Service Status

1. Press `Win + R`, type `services.msc`, press Enter
2. Look for **"Quality Recticel Print Service"**
3. Status should show **"Running"**
4. Startup type should be **"Automatic"**

#### Test API Endpoints

Open a web browser and visit:
- **Health Check**: `http://localhost:8765/health`
- **Printer List**: `http://localhost:8765/printers`

Expected response for health check:
```json
{
  "status": "healthy",
  "service": "Quality Recticel Print Service",
  "version": "1.0",
  "timestamp": "2025-09-21T10:30:00"
}
```

#### Test Chrome Extension

1. Click the extension icon in Chrome toolbar
2. Verify it shows "Service Status: Connected ✅"
3. Check that printers are listed
4. Try the "Test Print" button

## 🔄 Web Application Integration

The web application automatically detects the Windows service and adapts the user interface:

### Service Available (Green Button)
- Button text: **"🖨️ Print Labels (Silent)"**
- Functionality: Direct printing to default printer
- User experience: Click → Labels print immediately

### Service Unavailable (Blue Button)  
- Button text: **"📄 Generate PDF"**
- Functionality: PDF download for manual printing
- User experience: Click → PDF downloads to browser

### Detection Logic
```javascript
// Automatic service detection on page load
const response = await fetch('http://localhost:8765/health');
if (response.ok) {
    // Service available - enable silent printing
} else {
    // Service unavailable - fallback to PDF download
}
```

## 🛠️ Configuration

### Service Configuration

The service runs with the following default settings:

| Setting | Value | Description |
|---------|-------|-------------|
| **Port** | 8765 | Local API port |
| **Host** | localhost | Service binding |
| **Startup** | Automatic | Starts with Windows |
| **Printer** | Default | Uses system default printer |
| **Copies** | 1 | Default print copies |

### Chrome Extension Permissions

The extension requires these permissions:
- `printing` - Access to printer functionality
- `nativeMessaging` - Communication with Windows service
- `activeTab` - Access to current webpage
- `storage` - Save extension settings

## 🔍 Troubleshooting

### Common Issues

#### 1. Service Not Starting
**Symptoms**: API not accessible at localhost:8765
**Solutions**:
```bash
# Check service status
python -c "from service_manager import service_status; service_status()"

# Restart service manually
python service_manager.py restart

# Check Windows Event Viewer for service errors
```

#### 2. Chrome Extension Not Working
**Symptoms**: Extension shows "Service Status: Disconnected ❌"
**Solutions**:
- Verify Windows service is running
- Check firewall settings (port 8765 must be open)
- Reload the Chrome extension
- Restart Chrome browser

#### 3. Firewall Blocking Connection
**Symptoms**: Service runs but web page can't connect
**Solutions**:
```bash
# Add firewall rule manually
netsh advfirewall firewall add rule name="Quality Recticel Print Service" dir=in action=allow protocol=TCP localport=8765

# Or disable Windows Firewall temporarily to test
```

#### 4. Permission Denied Errors
**Symptoms**: Installation fails with permission errors
**Solutions**:
- Ensure running as Administrator
- Check Windows UAC settings
- Verify Python installation permissions

#### 5. Print Jobs Not Processing
**Symptoms**: API accepts requests but nothing prints
**Solutions**:
- Check default printer configuration
- Verify printer drivers are installed
- Test manual printing from other applications
- Check Windows Print Spooler service

### Log Files

Check these locations for troubleshooting:

| Component | Log Location |
|-----------|--------------|
| **Windows Service** | `print_service.log` (same folder as service) |
| **Chrome Extension** | Chrome DevTools → Extensions → Background page |
| **Windows Event Log** | Event Viewer → Windows Logs → System |

### Diagnostic Commands

```bash
# Check service status
python service_manager.py status

# Test API manually
curl http://localhost:8765/health

# List available printers  
curl http://localhost:8765/printers

# Check Windows service
sc query QualityRecticelPrintService

# Check listening ports
netstat -an | findstr :8765
```

## 🔄 Maintenance

### Updating the Service

1. Stop the current service:
```bash
python service_manager.py stop
```

2. Replace service files with new versions

3. Restart the service:
```bash
python service_manager.py start
```

### Uninstalling

#### Remove Chrome Extension
1. Go to `chrome://extensions/`
2. Find "Quality Recticel Print Service"
3. Click "Remove"

#### Remove Windows Service
```bash
# Run as Administrator
python service_manager.py uninstall
```

#### Remove Firewall Rule
```bash
netsh advfirewall firewall delete rule name="Quality Recticel Print Service"
```

## 📞 Support Information

### API Endpoints Reference

| Endpoint | Method | Purpose |
|----------|--------|---------|
| `/health` | GET | Service health check |
| `/printers` | GET | List available printers |
| `/print/pdf` | POST | Print PDF from URL |
| `/print/silent` | POST | Silent print with metadata |

### Request Examples

**Silent Print Request**:
```json
POST /print/silent
{
    "pdf_url": "http://localhost:5000/generate_labels_pdf/123",
    "printer_name": "default",
    "copies": 1,
    "silent": true,
    "order_id": "123",
    "quantity": "10"
}
```

**Expected Response**:
```json
{
    "success": true,
    "message": "Print job sent successfully",
    "job_id": "print_20250921_103000",
    "printer": "HP LaserJet Pro",
    "timestamp": "2025-09-21T10:30:00"
}
```

## 📚 Technical Details

### Service Architecture
- **Framework**: Flask (Python)
- **Service Type**: Windows Service (pywin32)
- **Communication**: HTTP REST API + Native Messaging
- **Security**: Localhost binding only (127.0.0.1:8765)

### Chrome Extension Architecture  
- **Manifest Version**: 3
- **Service Worker**: Handles background print requests
- **Content Script**: Integrates with Quality Recticel web pages
- **Native Messaging**: Communicates with Windows service

### Security Considerations
- Service only accepts local connections (localhost)
- No external network access required
- Chrome extension runs in sandboxed environment
- Windows service runs with system privileges (required for printing)

---

## 📋 Quick Start Checklist

- [ ] Download `windows_print_service` folder
- [ ] Right-click `install_service.bat` → "Run as administrator"  
- [ ] Install Chrome extension from `chrome_extension` folder
- [ ] Verify service at `http://localhost:8765/health`
- [ ] Test printing from Quality Recticel web application

**Installation Time**: ~5 minutes  
**User Training Required**: Minimal (automatic detection and fallback)  
**Maintenance**: Zero (auto-starts with Windows)

For additional support, check the log files and diagnostic commands listed above.