quality_app-v2/documentation/QUICK_BOX_CHECKPOINT_IMPLEMENTATION_NEEDED.md

Quick Box Checkpoint Implementation - Missing Features

Overview

The "Set Boxes Checkpoint" button/feature is referenced in the old app but needs proper implementation in the new v2 app. This feature allows users to quickly create boxes and print labels directly from the FG Scan page, then assign CP codes to those boxes.

Current Status in v2

✅ What's Already Implemented

1. Scan To Boxes Checkbox - Toggles the feature on/off
2. Quick Box Label Creation Button - Exists but has incomplete implementation
3. Box Assignment Modal - Basic modal exists but incomplete
4. QZ Tray Integration - Library is included, partial setup

❌ What's Missing / Broken

1. Quick Box Creation with Auto-Printing

Location: /srv/quality_app-v2/app/templates/modules/quality/fg_scan.html (Line 820+)

Current Problem:

• The quickBoxLabel button tries to call qz.print() directly without proper configuration
• No backend route to create boxes
• No PDF generation for box labels
• No proper QZ Tray configuration for label printing

What's Needed:

// Should replicate old app workflow:
1. Click "Quick Box Label Creation" button
2. Call backend to create new box (auto-increment number)
3. Generate PDF label with barcode
4. Print label via QZ Tray or browser fallback
5. Keep modal open for scanning printed label
6. Display confirmation message

2. Backend Box Creation Route

Location: Currently missing in app/modules/quality/routes.py

What's Needed:

@quality_bp.route('/api/create-quick-box', methods=['POST'])
def create_quick_box():
    """Create a new box and return the box number"""
    # Should:
    # 1. Get auto-incremented box number
    # 2. Insert into boxes_crates table
    # 3. Return JSON: {success: true, box_number: "BOX00000001"}

3. PDF Label Generation Route

Location: Currently missing in app/modules/quality/routes.py or app/modules/warehouse/routes.py

What's Needed:

@quality_bp.route('/api/generate-box-label-pdf', methods=['POST'])
def generate_box_label_pdf():
    """Generate PDF label with barcode for box"""
    # Should use ReportLab to generate:
    # - 8cm x 5cm landscape label
    # - "BOX Nr: XXXXXXXX" text at top
    # - Code128 barcode at bottom
    # Returns PDF as base64 or blob

4. Complete QZ Tray Integration

Location: /srv/quality_app-v2/app/templates/modules/quality/fg_scan.html (Line ~840+)

Current Issues:

• initializeQzTray() exists but incomplete
• No proper signature/pairing configuration
• No fallback for when QZ Tray is unavailable
• Print configuration is basic

What's Needed:

// Proper QZ Tray workflow:
1. Initialize connection with signature promise
2. Get available printers
3. Select default printer (or let user choose)
4. Configure print job (page size, margins)
5. Send PDF to printer
6. Handle errors and fallback to browser print

5. Box Assignment to CP Code

Location: /srv/quality_app-v2/app/templates/modules/quality/fg_scan.html (Line 880+)

Current Issue:

• Modal shows but doesn't properly save box-to-CP assignment
• No route to handle the assignment
• No database update to boxes_crates/box_contents tables

What's Needed:

# Route to assign CP to box:
@quality_bp.route('/api/assign-cp-to-box', methods=['POST'])
def assign_cp_to_box():
    """Assign CP code to existing box"""
    # Should:
    # 1. Validate box exists
    # 2. Validate CP code
    # 3. Insert into box_contents table
    # 4. Return success

Workflow Diagram

FG Scan Page
    ↓
[Scan CP Code] → [Enable "Scan To Boxes"] → [Click "Quick Box Label Creation"]
    ↓
Frontend:
1. Disable button (prevent double-click)
2. Call /api/create-quick-box → Get BOX00000001
3. Call /api/generate-box-label-pdf → Get PDF as base64
4. Initialize QZ Tray
5. Send PDF to printer
6. Display success message
7. Focus on "Scan Box Label" input
    ↓
User Action:
1. Printer prints label with barcode
2. User scans the printed label OR enters box number manually
    ↓
Frontend:
3. Modal closes
4. Call /api/assign-cp-to-box with {cp_code, box_number}
5. Database updates: box_contents table
6. Display confirmation
7. Ready for next scan

Required Database Operations

1. Create Box

INSERT INTO boxes_crates (box_number, status, created_by, created_at)
VALUES ('BOX00000001', 'open', 'admin', NOW());

2. Assign CP to Box

INSERT INTO box_contents (box_id, cp_code, created_at)
VALUES (1, 'CP00002042-0001', NOW());

Files to Modify/Create

Modify:

1. /srv/quality_app-v2/app/modules/quality/routes.py - Add new API routes
2. /srv/quality_app-v2/app/templates/modules/quality/fg_scan.html - Fix JavaScript logic

Create/Copy from Old App:

1. PDF generation function (from /srv/quality_app/py_app/app/routes.py lines ~3700+)
2. QZ Tray integration code

Reference Implementation

Old App Locations:

• FG Scan template: /srv/quality_app/py_app/app/templates/fg_scan.html (Lines 880-1100)
• Box creation: /srv/quality_app/py_app/app/routes.py - generate_box_label_pdf() function
• QZ Tray printing: Uses qz-tray.js library
• Database operations: Direct box_crates and box_contents table inserts

Implementation Priority

1. High: Backend API routes for box creation and PDF generation
2. High: Fix QZ Tray integration and configuration
3. Medium: Complete box-to-CP assignment logic
4. Low: Browser fallback print option

Testing Checklist

• Create quick box returns valid box number
• PDF label generates with correct format
• QZ Tray connection initializes
• Label prints to selected printer
• Barcode scans correctly
• CP code assigns to box successfully
• Modal opens/closes properly
• Error messages display for missing configurations
• Fallback works when QZ Tray unavailable