quality_recticel/py_app/app/static/documentation/README.md

# Quality Recticel Windows Print Service

## 🏗️ Technical Architecture

Local Windows service providing REST API for silent PDF printing via Chrome extension integration.

```
┌─────────────────────────────────────────────────────────────┐
│                    Quality Recticel Web App                 │
│                  (print_module.html)                       │
└─────────────────────┬───────────────────────────────────────┘
                      │ HTTP Request
                      ▼
┌─────────────────────────────────────────────────────────────┐
│              Windows Print Service                          │
│                (localhost:8765)                            │
│  ┌─────────────┐  ┌──────────────┐  ┌─────────────────┐   │
│  │   Flask     │  │    CORS      │  │   PDF Handler   │   │
│  │   Server    │  │   Support    │  │                 │   │
│  └─────────────┘  └──────────────┘  └─────────────────┘   │
└─────────────────────┬───────────────────────────────────────┘
                      │ Native Messaging
                      ▼
┌─────────────────────────────────────────────────────────────┐
│                Chrome Extension                             │
│  ┌─────────────┐  ┌──────────────┐  ┌─────────────────┐   │
│  │ Background  │  │  Content     │  │     Popup       │   │
│  │ Service     │  │  Script      │  │     UI          │   │
│  │ Worker      │  │              │  │                 │   │
│  └─────────────┘  └──────────────┘  └─────────────────┘   │
└─────────────────────┬───────────────────────────────────────┘
                      │ Windows API
                      ▼
┌─────────────────────────────────────────────────────────────┐
│                Windows Print System                         │
└─────────────────────────────────────────────────────────────┘
```

## 📁 Project Structure

```
windows_print_service/
├── 📄 print_service.py           # Main Flask service
├── 📄 service_manager.py         # Windows service wrapper  
├── 📄 install_service.bat        # Installation script
├── 📄 INSTALLATION_GUIDE.md      # Complete documentation
├── 📄 QUICK_SETUP.md            # User quick reference  
├── 📄 README.md                 # This file
└── 📁 chrome_extension/         # Chrome extension
    ├── 📄 manifest.json         # Extension manifest v3
    ├── 📄 background.js         # Service worker
    ├── 📄 content.js           # Page content integration
    ├── 📄 popup.html           # Extension popup UI
    ├── 📄 popup.js            # Popup functionality
    └── 📁 icons/              # Extension icons
```

## 🚀 API Endpoints

### Base URL: `http://localhost:8765`

| Endpoint | Method | Description | Request Body | Response |
|----------|--------|-------------|--------------|----------|
| `/health` | GET | Service health check | None | `{"status": "healthy", ...}` |
| `/printers` | GET | List available printers | None | `{"printers": [...]}` |
| `/print/pdf` | POST | Print PDF from URL | `{"url": "...", "printer": "..."}` | `{"success": true, ...}` |
| `/print/silent` | POST | Silent print with metadata | `{"pdf_url": "...", "order_id": "..."}` | `{"success": true, ...}` |

### Example API Usage

```javascript
// Health Check
const health = await fetch('http://localhost:8765/health');
const status = await health.json();

// Silent Print
const printRequest = {
    pdf_url: 'http://localhost:5000/generate_labels_pdf/123',
    printer_name: 'default',
    copies: 1,
    silent: true,
    order_id: '123',
    quantity: '10'
};

const response = await fetch('http://localhost:8765/print/silent', {
    method: 'POST',
    headers: {'Content-Type': 'application/json'},
    body: JSON.stringify(printRequest)
});
```

## 🔧 Development Setup

### Prerequisites
- Python 3.8+
- Windows 10/11
- Chrome Browser
- Administrator privileges

### Local Development

```bash
# Clone/download the project
cd windows_print_service

# Install dependencies
pip install flask flask-cors requests pywin32

# Run development server (not as service)
python print_service.py

# Install as Windows service
python service_manager.py install

# Service management
python service_manager.py start
python service_manager.py stop  
python service_manager.py restart
python service_manager.py uninstall
```

### Chrome Extension Development

```bash
# Load extension in Chrome
chrome://extensions/ → Developer mode ON → Load unpacked

# Debug extension
chrome://extensions/ → Details → Background page (for service worker)
chrome://extensions/ → Details → Inspect views (for popup)
```

## 📋 Configuration

### Service Configuration (`print_service.py`)

```python
class WindowsPrintService:
    def __init__(self, host='127.0.0.1', port=8765):
        self.host = host      # Localhost binding only
        self.port = port      # Service port
        self.app = Flask(__name__)
```

### Chrome Extension Permissions (`manifest.json`)

```json
{
    "permissions": [
        "printing",           // Access to printer API
        "nativeMessaging",   // Communication with Windows service
        "activeTab",         // Current tab access
        "storage"           // Extension settings storage
    ]
}
```

## 🔄 Integration Flow

### 1. Service Detection
```javascript
// Web page detects service availability
const isServiceAvailable = await checkServiceHealth();
updatePrintButton(isServiceAvailable);
```

### 2. Print Request Flow
```
User clicks print → Web app → Windows service → Chrome extension → Printer
```

### 3. Fallback Mechanism
```
Service unavailable → Fallback to PDF download → Manual printing
```

## 🛠️ Customization

### Adding New Print Options

```python
# In print_service.py
@app.route('/print/custom', methods=['POST'])
def print_custom():
    data = request.json
    # Custom print logic here
    return jsonify({'success': True})
```

### Modifying Chrome Extension

```javascript
// In background.js - Add new message handler
chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
    if (message.type === 'CUSTOM_PRINT') {
        // Custom print logic
    }
});
```

### Web Application Integration

```javascript
// In print_module.html - Modify print function
async function customPrintFunction(orderId) {
    const response = await fetch('http://localhost:8765/print/custom', {
        method: 'POST',
        body: JSON.stringify({orderId, customOptions: {...}})
    });
}
```

## 🧪 Testing

### Unit Tests (Future Enhancement)

```python
# test_print_service.py
import unittest
from print_service import WindowsPrintService

class TestPrintService(unittest.TestCase):
    def test_health_endpoint(self):
        # Test implementation
        pass
```

### Manual Testing Checklist

- [ ] Service starts automatically on Windows boot
- [ ] API endpoints respond correctly
- [ ] Chrome extension loads without errors
- [ ] Print jobs execute successfully
- [ ] Fallback works when service unavailable
- [ ] Firewall allows port 8765 traffic

## 📊 Monitoring & Logging

### Log Files
- **Service Log**: `print_service.log` (Flask application logs)
- **Windows Event Log**: Windows Services logs
- **Chrome DevTools**: Extension console logs

### Health Monitoring

```python
# Monitor service health
import requests
try:
    response = requests.get('http://localhost:8765/health', timeout=5)
    if response.status_code == 200:
        print("✅ Service healthy")
except:
    print("❌ Service unavailable")
```

## 🔒 Security Considerations

### Network Security
- **Localhost Only**: Service binds to 127.0.0.1 (no external access)
- **No Authentication**: Relies on local machine security
- **Firewall Rule**: Port 8765 opened for local connections only

### Chrome Extension Security
- **Manifest V3**: Latest security standards
- **Minimal Permissions**: Only necessary permissions requested
- **Sandboxed**: Runs in Chrome's security sandbox

### Windows Service Security
- **System Service**: Runs with appropriate Windows service privileges
- **Print Permissions**: Requires printer access (normal for print services)

## 🚀 Deployment

### Production Deployment

1. **Package Distribution**:
```bash
# Create deployment package
zip -r quality_recticel_print_service.zip windows_print_service/
```

2. **Installation Script**: Use `install_service.bat` for end users

3. **Group Policy Deployment**: Deploy Chrome extension via enterprise policies

### Enterprise Considerations

- **Silent Installation**: Modify `install_service.bat` for unattended install
- **Registry Deployment**: Pre-configure Chrome extension registry entries
- **Network Policies**: Ensure firewall policies allow localhost:8765

## 📚 Dependencies

### Python Packages
```
flask>=2.3.0          # Web framework
flask-cors>=4.0.0     # CORS support
requests>=2.31.0      # HTTP client
pywin32>=306          # Windows service integration
```

### Chrome APIs
- `chrome.printing.*` - Printing functionality
- `chrome.runtime.*` - Extension messaging
- `chrome.nativeMessaging.*` - Native app communication

## 🐛 Debugging

### Common Debug Commands

```bash
# Check service status
sc query QualityRecticelPrintService

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

# Check listening ports
netstat -an | findstr :8765

# View service logs
type print_service.log
```

### Chrome Extension Debugging

```javascript
// In background.js - Add debug logging
console.log('Print request received:', message);

// In popup.js - Test API connection
fetch('http://localhost:8765/health')
    .then(r => r.json())
    .then(data => console.log('Service status:', data));
```

---

## 📄 License & Support

**Project**: Quality Recticel Print Service  
**Version**: 1.0  
**Compatibility**: Windows 10/11, Chrome 88+  
**Maintenance**: Zero-maintenance after installation  

For technical support, refer to `INSTALLATION_GUIDE.md` troubleshooting section.