quality_app-v2/documentation/BOX_WORKFLOW_COMPARISON_OLD_VS_NEW.md

FG Scan Box Workflow: Old App vs New App - Comparison & Issues

Executive Summary

The old app (/srv/quality_app) has a 3-option workflow that appears more complete than the new app (/srv/quality_app-v2). The new app's modal is missing the "create new box" and "scan existing box" separation that provides users with clear choices.

Workflow Comparison

Old App Workflow (REFERENCE MODEL ✅)

Location: /srv/quality_app/py_app/app/templates/fg_scan.html (Lines 15-1250)

Trigger:

1. User fills all scan fields
2. Checkbox "Enable Scan to Boxes" is CHECKED
3. Defect code entered as 000 (good quality)
4. Scan saved to database
5. Modal appears with 3 options

Modal Options:

┌─────────────────────────────────────┐
│        Assign to Box                │
│  CP Code: CP-123456        [X]      │
├─────────────────────────────────────┤
│                                     │
│  ┌─────────────────────────────┐   │
│  │ 📦 Quick Box Label Creation │   │  ← OPTION 1: CREATE
│  │  Creates new box and prints │   │
│  │  label immediately          │   │
│  └─────────────────────────────┘   │
│                                     │
│         — OR —                      │
│                                     │
│  ┌─────────────────────────────┐   │
│  │ Scan Box Number:            │   │  ← OPTION 2: SCAN EXISTING
│  │ ┌─────────────────────────┐ │   │
│  │ │ [Scan or enter box...]  │ │   │
│  │ └─────────────────────────┘ │   │
│  │ Scan an existing box label  │   │
│  │ to assign this CP to that   │   │
│  │ box                         │   │
│  └─────────────────────────────┘   │
│                                     │
│  [Skip]  [Assign to Box]            │  ← OPTION 3: SKIP
├─────────────────────────────────────┤

Option 1: Create New Box (Green Button)

Flow:
1. Click "📦 Quick Box Label Creation"
2. Backend creates empty box in boxes_crates table
3. Backend generates PDF label
4. QZ Tray prints label (thermal printer)
5. Input field updates: "Scan the printed label now..."
6. User scans newly created box label
7. Modal stays open, ready for assignment
8. Scan box input focuses automatically

Option 2: Scan Existing Box

Flow:
1. User scans existing box label (or enters manually)
2. Click "Assign to Box" button
3. Backend links CP to box (box_contents table)
4. Modal closes, page reloads
5. Scan is complete with box assignment

Option 3: Skip

Flow:
1. Click "Skip" button
2. Modal closes, page reloads
3. Scan is in database but NOT assigned to box
4. Ready for next scan

---

New App Workflow (CURRENT ⚠️)

Location: /srv/quality_app-v2/app/templates/modules/quality/fg_scan.html (Lines 109-1000)

Trigger: Same as old app (appears to work)

Modal Structure:

┌──────────────────────────────────┐
│      Assign to Box        [X]    │
├──────────────────────────────────┤
│                                  │
│ Box Number: ________________     │
│ Quantity:   [1]                  │
│                                  │
│  [Cancel]  [Assign]              │
├──────────────────────────────────┤

Issues with New App Modal:

1. ❌ NO "Create Box" button visible in modal
2. ❌ NO "— OR —" separator
3. ❌ Only shows Box Number + Quantity fields
4. ❌ No distinction between "create" vs "scan existing"
5. ❌ Missing QZ Tray printer integration in modal
6. ⚠️ "Quick Box Label Creation" button is in form, NOT in modal

---

Code Architecture Comparison

OLD APP: Modal With Three Clear Options

File: /srv/quality_app/py_app/app/templates/fg_scan.html

Modal HTML (Lines 1140-1200):

<div id="box-assignment-modal" class="box-modal" style="display: none;">
    <div class="box-modal-content">
        <div class="box-modal-header">
            <h3>Assign to Box</h3>
            <span class="box-modal-close" onclick="closeBoxModal()">&times;</span>
        </div>
        <div class="box-modal-body">
            <p>CP Code: <strong id="modal-cp-code"></strong></p>
            
            <!-- OPTION 1: Quick Box Creation -->
            <div style="margin: 20px 0; padding: 15px; background: #f0f8ff; border-radius: 5px;">
                <button type="button" id="quick-box-create-btn" class="btn" 
                        style="width: 100%; background: #28a745; color: white;">
                    📦 Quick Box Label Creation
                </button>
                <p style="font-size: 0.85em; color: #666; margin-top: 8px; text-align: center;">
                    Creates new box and prints label immediately
                </p>
            </div>
            
            <!-- SEPARATOR -->
            <div style="text-align: center; margin: 15px 0; color: #999;">— OR —</div>
            
            <!-- OPTION 2: Scan Existing Box -->
            <div style="margin: 20px 0;">
                <label style="font-weight: bold;">Scan Box Number:</label>
                <input type="text" id="scan-box-input" placeholder="Scan or enter box number" 
                       style="width: 100%; padding: 8px; font-size: 1em; margin-top: 5px;">
                <p style="font-size: 0.85em; color: #666; margin-top: 5px;">
                    Scan an existing box label to assign this CP code to that box
                </p>
            </div>
            
            <!-- BUTTONS -->
            <div class="box-modal-buttons" style="margin-top: 20px;">
                <button type="button" class="btn" onclick="closeBoxModal()" 
                        style="background: #6c757d;">Skip</button>
                <button type="button" id="assign-to-box-btn" class="btn" 
                        style="background: #007bff;">Assign to Box</button>
            </div>
        </div>
    </div>
</div>

Key Functions (Lines 1005-1120):

1. Quick Box Create Button:

document.getElementById('quick-box-create-btn').addEventListener('click', async function() {
    // Step 1: Create box via /warehouse/create_box
    // Step 2: Generate PDF via /generate_box_label_pdf
    // Step 3: Print via QZ Tray
    // Step 4: Update input field placeholder to "Scan the printed label now..."
    // Modal stays open
});

2. Assign to Box Button:

document.getElementById('assign-to-box-btn').addEventListener('click', async function() {
    const boxNumber = document.getElementById('scan-box-input').value.trim();
    // POST to /warehouse/assign_cp_to_box with { box_number, cp_code }
    // Close modal and reload
});

3. Skip Button:

<button type="button" class="btn" onclick="closeBoxModal()">Skip</button>

---

NEW APP: Modal Structure Issue

File: /srv/quality_app-v2/app/templates/modules/quality/fg_scan.html

Modal HTML (Lines 109-129):

<!-- Box Assignment Modal -->
<div id="boxAssignmentModal" class="box-modal" style="display: none;">
    <div class="box-modal-content">
        <div class="modal-header">
            <h2>Assign to Box</h2>
            <button type="button" class="modal-close" id="closeModal">&times;</button>
        </div>
        <div class="modal-body">
            <label for="boxNumber">Box Number:</label>
            <input type="text" id="boxNumber" placeholder="Enter box number">
            <label for="boxQty">Quantity:</label>
            <input type="number" id="boxQty" placeholder="Enter quantity" min="1">
        </div>
        <div class="modal-footer">
            <button type="button" class="btn-secondary" id="cancelModal">Cancel</button>
            <button type="button" class="btn-submit" id="assignToBox">Assign</button>
        </div>
    </div>
</div>

Issues:

1. Modal only has Box Number + Quantity inputs
2. No "Quick Box Label Creation" button inside modal
3. Quick Box button is in the form section, NOT in the modal
4. Modal doesn't guide user through the workflow

Quick Box Button Location (Line 55 - WRONG PLACEMENT):

<div id="quickBoxSection" style="display: none;" class="quick-box-section">
    <button type="button" class="btn-secondary" id="quickBoxLabel">
        Quick Box Label Creation
    </button>
</div>

This button appears in the form, not in the modal where users would see it after scan completion.

---

Side-by-Side Modal Comparison

Aspect	Old App	New App	Status
Location	In modal (modal-body)	In form (above modal)	❌ New app wrong
Create Box Option	Green button, full workflow	Yes but wrong place	⚠️ Needs move
Scan Existing	Input field + button	Input field + button	✅ Similar
Skip Option	Skip button	Cancel button	✅ Similar
Visual Separator	"— OR —" divider	None	❌ Missing
QZ Tray Integration	Inside modal flow	Inside modal flow	✅ Present
"Scan label now" prompt	Dynamic update	Dynamic update	✅ Similar
Modal stays open	After create (for scan)	Unclear	⚠️ May need update

---

What Needs to Change in New App

Issue 1: Move "Quick Box Label Creation" Button INTO Modal

Current (WRONG):

<div id="quickBoxSection" style="display: none;">
    <button type="button" id="quickBoxLabel">
        Quick Box Label Creation
    </button>
</div>

Location: In the form section, hidden

Should be (CORRECT):

<div id="boxAssignmentModal" class="box-modal" style="display: none;">
    <div class="box-modal-content">
        <div class="modal-header">
            <h2>Assign to Box</h2>
            <button type="button" class="modal-close" id="closeModal">&times;</button>
        </div>
        <div class="modal-body">
            <p>CP Code: <strong id="modal-cp-code"></strong></p>
            
            <!-- ADD: Option 1: Quick Box Creation -->
            <div style="margin: 20px 0; padding: 15px; background: #f0f8ff; border-radius: 5px;">
                <button type="button" id="quickBoxLabel" class="btn" 
                        style="width: 100%; background: #28a745; color: white;">
                    📦 Quick Box Label Creation
                </button>
                <p style="font-size: 0.85em; color: #666; margin-top: 8px; text-align: center;">
                    Creates new box and prints label immediately
                </p>
            </div>
            
            <!-- ADD: Separator -->
            <div style="text-align: center; margin: 15px 0; color: #999;">— OR —</div>
            
            <!-- EXISTING: Option 2: Scan Existing Box -->
            <div style="margin: 20px 0;">
                <label style="font-weight: bold;">Scan Box Number:</label>
                <input type="text" id="boxNumber" placeholder="Scan or enter box number" 
                       style="width: 100%; padding: 8px; font-size: 1em; margin-top: 5px;">
            </div>
        </div>
        <div class="modal-footer">
            <button type="button" class="btn-secondary" id="cancelModal">Skip</button>
            <button type="button" class="btn-submit" id="assignToBox">Assign to Box</button>
        </div>
    </div>
</div>

Issue 2: Update Modal Display Logic

Current:

// Show box assignment modal
document.getElementById('boxAssignmentModal').style.display = 'flex';
document.getElementById('quickBoxLabel').focus();

After Move: The code above should work, but verify that:

• Focus goes to Quick Box button
• Modal displays with all three options
• CP code is displayed in modal

Issue 3: Modal Should NOT Close After Quick Box Create

Current Behavior (Old App):

• User clicks "📦 Quick Box Label Creation"
• Box created
• PDF generated
• Label printed
• Input field updates: "Scan the printed label now..."
• Modal stays open ← User can now scan the box
• User scans printed label
• Clicks "Assign to Box"
• Modal closes

New App Issue: Need to verify that modal doesn't close prematurely after box creation. The button handler should keep modal open.

Issue 4: Add CP Code Display in Modal

New App Missing:

// When showing modal, also display the CP code
const cpCode = document.getElementById('cp_code').value.trim();
document.getElementById('modal-cp-code').textContent = cpCode;

Need to add a modal-cp-code element in the modal body.

---

Recommended Changes to fg_scan.html

Change 1: Update Modal HTML Structure

Replace lines 109-129 with:

<!-- Box Assignment Modal -->
<div id="boxAssignmentModal" class="box-modal" style="display: none;">
    <div class="box-modal-content">
        <div class="modal-header">
            <h2>Assign to Box</h2>
            <button type="button" class="modal-close" id="closeModal">&times;</button>
        </div>
        <div class="modal-body">
            <!-- Display CP Code -->
            <p style="margin-bottom: 15px; font-size: 0.9em;">
                CP Code: <strong id="modal-cp-code"></strong>
            </p>
            
            <!-- OPTION 1: Quick Box Creation -->
            <div style="margin: 20px 0; padding: 15px; background: #f0f8ff; border-radius: 5px; border: 1px solid #cce7ff; border-radius: 5px;">
                <button type="button" id="quickBoxLabel" class="btn" 
                        style="width: 100%; background: #28a745; color: white; padding: 10px; font-size: 1em; border: none; border-radius: 4px; cursor: pointer;">
                    📦 Quick Box Label Creation
                </button>
                <p style="font-size: 0.85em; color: #666; margin-top: 8px; text-align: center;">
                    Creates new box and prints label immediately
                </p>
            </div>
            
            <!-- SEPARATOR -->
            <div style="text-align: center; margin: 20px 0; color: #999; font-size: 0.9em;">
                ━━━━━━━━━━━━━  OR  ━━━━━━━━━━━━━
            </div>
            
            <!-- OPTION 2: Scan Existing Box -->
            <div style="margin: 20px 0;">
                <label for="boxNumber" style="font-weight: bold; display: block; margin-bottom: 5px;">Scan Box Number:</label>
                <input type="text" id="boxNumber" placeholder="Scan or enter box number" 
                       style="width: 100%; padding: 8px; font-size: 1em; border: 1px solid #ddd; border-radius: 4px; box-sizing: border-box;">
                <p style="font-size: 0.85em; color: #666; margin-top: 5px;">
                    Scan an existing box label or enter the box number manually
                </p>
            </div>
        </div>
        <div class="modal-footer">
            <button type="button" class="btn-secondary" id="cancelModal">Skip</button>
            <button type="button" class="btn-submit" id="assignToBox">Assign to Box</button>
        </div>
    </div>
</div>

Change 2: Remove quickBoxSection from Form

Delete lines 53-56:

<div id="quickBoxSection" style="display: none;" class="quick-box-section">
    <button type="button" class="btn-secondary" id="quickBoxLabel">Quick Box Label Creation</button>
</div>

Change 3: Update Modal Show Logic

Find (around line 809) and update:

// Show box assignment modal
document.getElementById('boxAssignmentModal').style.display = 'flex';

To:

// Show box assignment modal
const cpCode = document.getElementById('cp_code').value.trim();
document.getElementById('modal-cp-code').textContent = cpCode;
document.getElementById('boxAssignmentModal').style.display = 'flex';
document.getElementById('boxNumber').value = '';  // Clear box number for fresh entry
document.getElementById('boxNumber').focus();  // Focus on box input

Change 4: Update Assign Button Label

Change button text from "Assign" to "Assign to Box" to match old app:

document.getElementById('assignToBox').textContent = 'Assign to Box';

---

Testing Checklist After Changes

• Enable "Scan to Boxes" checkbox
• Scan a product with defect code 000
• Modal appears with CP code displayed
• Modal shows all 3 options (Create/Scan/Skip)
• Click "📦 Quick Box Label Creation"
  • Box created (check database)
  • PDF generated
  • Label prints (if QZ Tray available)
  • Input field updates to "Scan the printed label now..."
  • Modal stays open
• Scan the newly printed box label
• Click "Assign to Box"
  • CP assigned to box (check database)
  • Modal closes
  • Page reloads
• Click "Skip"
  • Modal closes without box assignment
  • CP scan recorded but not assigned
• Test with defect code other than 000
  • Modal should NOT appear
  • Form submits normally

---

Database Endpoints Required

Verify these endpoints exist in your backend:

1. ✅ POST /quality/create_quick_box - Already in code (line 839)
2. ✅ POST /quality/generate_box_label_pdf - Already in code (line 857)
3. ✅ /warehouse/assign_cp_to_box - Needs verification
4. ✅ Form POST endpoint - Already works

---

Files to Update

1. Primary: /srv/quality_app-v2/app/templates/modules/quality/fg_scan.html

   • Lines 53-56: Remove quickBoxSection
   • Lines 109-129: Replace modal HTML
   • Line 809+: Update modal show logic

2. Verify: /srv/quality_app-v2/app/routes.py (or similar)

   • Confirm /warehouse/assign_cp_to_box endpoint exists

---

Reference Files

• Old App Reference: /srv/quality_app/py_app/app/templates/fg_scan.html (Lines 1-1242)
• New App Current: /srv/quality_app-v2/app/templates/modules/quality/fg_scan.html (Lines 1-1145)
• This Doc: /srv/quality_app-v2/documentation/OLD_APP_BOX_WORKFLOW_REFERENCE.md