quality_recticel/py_app/ENHANCED_PRINT_CONTROLLER.md

Enhanced Print Controller - Features & Usage

Overview

The print module now includes an advanced Print Controller with real-time monitoring, error detection, pause/resume functionality, and automatic reprint capabilities for handling printer issues like paper jams or running out of paper.

Key Features

1. Real-Time Progress Modal

• Visual progress bar showing percentage completion
• Live counter showing "X / Y" labels printed
• Status messages updating in real-time
• Detailed event log with timestamps

2. Print Status Log

• Timestamped entries for all print events
• Color-coded status messages:
  • Green: Successful operations
  • Yellow: Warnings and paused states
  • Red: Errors and failures
• Auto-scrolling to show latest events
• Scrollable history of all print activities

3. Control Buttons

⏸️ Pause Button

• Pauses printing between labels
• Useful for:
  • Checking printer paper level
  • Inspecting print quality
  • Loading more paper
• Progress bar turns yellow when paused

▶️ Resume Button

• Resumes printing from where it was paused
• Appears when print job is paused
• Progress bar returns to normal green

🔄 Reprint Last Button

• Available after each successful print
• Reprints the last completed label
• Useful when:
  • Label came out damaged
  • Print quality was poor
  • Label fell on the floor

❌ Cancel Button

• Stops the entire print job
• Shows how many labels were completed
• Progress bar turns red
• Database not updated on cancellation

4. Automatic Error Detection

• Detects when a label fails to print
• Automatically pauses the job
• Shows error message in log
• Progress bar turns red
• Prompts user to check printer

5. Automatic Recovery

When a print error occurs:

1. Job pauses automatically
2. Error is logged with timestamp
3. User checks and fixes printer issue (refill paper, clear jam)
4. User clicks "Resume"
5. Failed label is automatically retried
6. If retry succeeds, continues with next label
7. If retry fails, user can cancel or try again

6. Smart Print Management

• Tracks current label being printed
• Remembers last successfully printed label
• Maintains list of failed labels
• Prevents duplicate printing
• Sequential label numbering (CP00000777/001, 002, 003...)

Usage Instructions

Normal Printing Workflow

1. Start Print Job

   • Select an order from the table
   • Click "Print Label (QZ Tray)" button
   • Print Controller modal appears

2. Monitor Progress

   • Watch progress bar fill (green)
   • Check "X / Y" counter
   • Read status messages
   • View timestamped log entries

3. Completion

   • All labels print successfully
   • Database updates automatically
   • Table refreshes to show new status
   • Modal closes automatically
   • Success notification appears

Handling Paper Running Out Mid-Print

Scenario: Printing 20 labels, paper runs out after label 12

1. Detection

   • Label 13 fails to print
   • Controller detects error
   • Job pauses automatically
   • Progress bar turns red
   • Log shows: "✗ Label 13 failed: Print error"
   • Status: "⚠️ ERROR - Check printer (paper jam/out of paper)"

2. User Action

   • Check printer
   • See paper is empty
   • Load new paper roll
   • Ensure paper is feeding correctly

3. Resume Printing

   • Click "▶️ Resume" button
   • Controller automatically retries label 13
   • Log shows: "Retrying label 13..."
   • If successful: "✓ Label 13 printed successfully (retry)"
   • Continues with labels 14-20
   • Job completes normally

Handling Print Quality Issues

Scenario: Label 5 of 10 prints too light

1. During Print

   • Wait for label 5 to complete
   • "🔄 Reprint Last" button appears
   • Click button
   • Label 5 reprints with current settings

2. Adjust & Continue

   • Adjust printer darkness setting
   • Click "▶️ Resume" if paused
   • Continue printing labels 6-10

Manual Pause for Inspection

Scenario: Want to check label quality mid-batch

1. Click "⏸️ Pause" button
2. Progress bar turns yellow
3. Remove and inspect last printed label
4. If good: Click "▶️ Resume"
5. If bad:
   • Click "🔄 Reprint Last"
   • Adjust printer settings
   • Click "▶️ Resume"

Emergency Cancellation

Scenario: Wrong order selected or major printer malfunction

1. Click "❌ Cancel" button
2. Printing stops immediately
3. Log shows labels completed (e.g., "7 of 25")
4. Progress bar turns red
5. Modal stays open for 2 seconds
6. Warning notification appears
7. Database NOT updated
8. Can reprint the order later

Technical Implementation

Print Controller State

{
    isPaused: false,           // Whether job is paused
    isCancelled: false,        // Whether job is cancelled
    currentLabel: 0,           // Current label number being printed
    totalLabels: 0,            // Total labels in job
    lastPrintedLabel: 0,       // Last successfully printed label
    failedLabels: [],          // Array of failed label numbers
    orderData: null,           // Order information
    printerName: null          // Selected printer name
}

Event Log Format

[17:47:15] Starting print job: 10 labels
[17:47:15] Printer: Thermal Printer A
[17:47:15] Order: CP00000777
[17:47:16] Sending label 1 to printer...
[17:47:16] ✓ Label 1 printed successfully

Error Detection

• Try/catch around each print operation
• Errors trigger automatic pause
• Failed label number recorded
• Automatic retry on resume

Progress Calculation

percentage = (currentLabel / totalLabels) * 100

Color States

• Green: Normal printing
• Yellow: Paused (manual or automatic)
• Red: Error or cancelled

Benefits

1. ✅ Prevents Wasted Labels: Automatic recovery from errors
2. ✅ Reduces Operator Stress: Clear status and easy controls
3. ✅ Handles Paper Depletion: Auto-pause and retry on paper out
4. ✅ Quality Control: Easy reprint of damaged labels
5. ✅ Transparency: Full log of all print activities
6. ✅ Flexibility: Pause anytime for inspection
7. ✅ Safety: Cancel button for emergencies
8. ✅ Accuracy: Sequential numbering maintained even with errors

Common Scenarios Handled

Issue	Detection	Solution
Paper runs out	Print error on next label	Auto-pause, user refills, resume
Paper jam	Print error detected	Auto-pause, user clears jam, resume
Poor print quality	Visual inspection	Reprint last label
Wrong order selected	User realizes mid-print	Cancel job
Need to inspect labels	User decision	Pause, inspect, resume
Label falls on floor	Visual observation	Reprint last label
Printer offline	Print error	Auto-pause, user fixes, resume

Future Enhancements (Possible)

• Printer status monitoring (paper level, online/offline)
• Print queue for multiple orders
• Estimated time remaining
• Sound notifications on completion
• Email/SMS alerts for long jobs
• Print history logging to database
• Batch printing multiple orders
• Automatic printer reconnection

Testing Recommendations

1. Normal Job: Print 5-10 labels, verify all complete
2. Paper Depletion: Remove paper mid-job, verify auto-pause and recovery
3. Pause/Resume: Manually pause mid-job, wait, resume
4. Reprint: Print job, reprint last label multiple times
5. Cancel: Start job, cancel after 2-3 labels
6. Error Recovery: Simulate error, verify automatic retry

Browser Compatibility

• Chrome/Edge: ✅ Fully supported
• Firefox: ✅ Fully supported
• Safari: ✅ Fully supported
• Mobile browsers: ⚠️ Desktop recommended for QZ Tray

Support

For issues or questions:

• Check browser console for detailed error messages
• Verify QZ Tray is running and connected
• Check printer is online and has paper
• Review print status log in modal
• Restart QZ Tray if connection issues persist