quality_app-v2/documentation/PDF_GENERATION_IMPLEMENTATION_PLAN.md

# Implementation Plan: PDF Generation for Print Functionality

## Current Status

The new Quality App v2 has:
✅ Labels module with routes and templates
✅ print_labels.html and print_lost_labels.html with UI
✅ Database schema (order_for_labels table)
✅ API endpoints for fetching orders
❌ PDF generation functionality (NEEDS IMPLEMENTATION)
❌ `/labels/api/generate-pdf` endpoint
❌ `/labels/api/generate-pdf/{order_id}/true` endpoint

## What Needs to Be Done

### 1. Create PDF Generator Module
**File**: `/srv/quality_app-v2/app/modules/labels/pdf_generator.py`

Copy from old app: `/srv/quality_app/py_app/app/pdf_generator.py`

Key classes:
- `LabelPDFGenerator` - Main PDF generation class
- Methods for single label and batch label generation

### 2. Create/Update Print Module Functions
**File**: `/srv/quality_app-v2/app/modules/labels/print_module.py`

Add to existing functions:
- `update_order_printed_status(order_id, status=1)` - Mark order as printed
- Import PDF generator functions

### 3. Add API Endpoints to Routes
**File**: `/srv/quality_app-v2/app/modules/labels/routes.py`

Add two new routes:

#### Endpoint 1: Single Label PDF (for QZ Tray)
```python
@labels_bp.route('/api/generate-pdf', methods=['POST'])
def api_generate_pdf():
    """Generate single label PDF for QZ Tray thermal printing"""
    # Accept JSON with:
    # - order_data: Complete order information
    # - piece_number: Which label number (1, 2, 3, etc.)
    # - total_pieces: Total quantity
    # Return: PDF binary data
```

#### Endpoint 2: Batch PDF (for download)
```python
@labels_bp.route('/api/generate-pdf/<int:order_id>/true', methods=['POST'])
def api_generate_batch_pdf(order_id):
    """Generate all label PDFs for an order and mark as printed"""
    # Fetch order from database
    # Generate all labels in one PDF
    # Mark order as printed (printed_labels = 1)
    # Return: PDF binary data
```

### 4. Install Required Dependencies

The new app needs these Python packages:
```
reportlab>=3.6.0  (for PDF generation)
```

Check `/srv/quality_app-v2/requirements.txt` and add if needed.

---

## Implementation Details from Old App

### LabelPDFGenerator Class Structure

```python
class LabelPDFGenerator:
    def __init__(self, paper_saving_mode=True):
        self.label_width = 80mm
        self.label_height = 105mm
        # ... other dimensions
    
    def generate_labels_pdf(self, order_data, quantity, printer_optimized=True):
        # Generate multiple labels (one per page)
        # Return BytesIO buffer
    
    def generate_single_label_pdf(self, order_data, piece_number, total_pieces):
        # Generate one label for QZ Tray
        # Return BytesIO buffer
    
    def _draw_label(self, canvas, order_data, sequential_number, current_num, total_qty):
        # Draw all label elements on canvas
    
    def _optimize_for_label_printer(self, canvas):
        # Set printer optimization settings
```

### Label Data Structure

```python
order_data = {
    'id': int,
    'comanda_productie': str,  # Production order (CP00000711)
    'cod_articol': str,        # Article code
    'descr_com_prod': str,     # Product description
    'cantitate': int,          # Quantity (total labels)
    'com_achiz_client': str,   # Customer PO
    'nr_linie_com_client': str,# Customer PO line
    'customer_name': str,
    'customer_article_number': str,
    'data_livrare': str/date,  # Delivery date
    'dimensiune': str,         # Product size
    'printed_labels': bool     # Print status
}
```

### API Request/Response Format

#### Generate Single Label (QZ Tray)
```
POST /labels/api/generate-pdf
Content-Type: application/json

{
    "comanda_productie": "CP00000711",
    "cod_articol": "ART001",
    "descr_com_prod": "Product Description",
    "cantitate": 5,
    "com_achiz_client": "PO2026001",
    "nr_linie_com_client": "001",
    "customer_name": "ACME Corp",
    "customer_article_number": "ACME-001",
    "data_livrare": "2026-02-11",
    "dimensiune": "Standard",
    "piece_number": 1,
    "total_pieces": 5
}

Response: Binary PDF data (Content-Type: application/pdf)
```

#### Generate Batch PDF (Download)
```
POST /labels/api/generate-pdf/711/true

Response: Binary PDF data with all 5 labels
Side effect: Sets order.printed_labels = 1
```

---

## Files to Copy from Old App

1. **pdf_generator.py**
   - Source: `/srv/quality_app/py_app/app/pdf_generator.py`
   - Destination: `/srv/quality_app-v2/app/modules/labels/pdf_generator.py`
   - Status: READY TO COPY

2. **Requirements Update**
   - Add `reportlab>=3.6.0` to `/srv/quality_app-v2/requirements.txt`

---

## Next Steps

1. Copy pdf_generator.py from old app
2. Update requirements.txt with reportlab
3. Add two new API routes to routes.py
4. Update print_module.py with update_order_printed_status function
5. Test the endpoints with test data already inserted

---

## Testing Checklist

- [ ] Single label generation works
- [ ] Batch PDF generation works
- [ ] QZ Tray can print generated labels
- [ ] Order marked as printed after successful generation
- [ ] PDF dimensions correct (80mm x 105mm)
- [ ] Barcodes generate correctly
- [ ] All order data displays correctly on label
- [ ] Thermal printer optimization enabled