quality_app-v2/documentation/FG_SCAN_BOX_WORKFLOW_ANALYSIS.md

FG Scan Box Workflow - Analysis Summary

Problem Statement

When the checkbox "Scan to Boxes" is enabled and user scans a product with defect code 000 (good quality), a modal popup should appear with three distinct options:

1. Create new box - Create empty box, print label, scan it
2. Scan existing box - Link to already existing box
3. Skip - Don't assign to any box

The old app (/srv/quality_app) implements this correctly. The new app (/srv/quality_app-v2) modal is incomplete and missing the "Create new box" button visibility.

---

Root Cause Analysis

Old App (Reference ✅)

File: /srv/quality_app/py_app/app/templates/fg_scan.html (1242 lines)

Structure:

Modal Body Contains:
├── CP Code display
├── [GREEN BOX BUTTON] ← "📦 Quick Box Label Creation"
├── — OR —
├── Box number input
├── [BUTTONS] Skip + Assign
└── Modal stays open after box creation

Result: All three options visible, user understands workflow

New App (Current Issue ⚠️)

File: /srv/quality_app-v2/app/templates/modules/quality/fg_scan.html (1145 lines)

Structure (PROBLEM):

Form Contains (WRONG PLACE):
├── [Scan to Boxes checkbox]
├── [quick-box-section - HIDDEN by default]
└── └── [BOX BUTTON] ← Hidden, only shows when checkbox enabled

Modal Body Contains (INCOMPLETE):
├── Box number input
├── Quantity input
├── [BUTTONS] Cancel + Assign
└── NO "CREATE BOX" option visible!

Result:

• Modal appears but missing create button
• Users don't see they can create boxes
• Feature appears broken even though code exists
• "quick-box-section" button is in form, not in modal where it appears after scan

---

Why This Breaks the Workflow

What Should Happen:

User scans 000 → Modal IMMEDIATELY shows with Create/Scan/Skip options
↓
User chooses immediately what to do

What's Actually Happening:

User scans 000 → Modal appears
↓
User sees: "Enter box number" field
↓
User thinks: "Can I only enter existing boxes?"
↓
User doesn't know: "I can CREATE boxes too!"
↓
User tries to enter box → Gets error
↓
User confused/frustrated

---

The Solution

Three-Part Fix

Part 1: Delete Hidden Button from Form

• Location: Lines 53-56
• Remove: <div id="quickBoxSection" ...>
• Why: Button should be in modal, not in form

Part 2: Rebuild Modal HTML

• Location: Lines 109-129
• Add: CP code display
• Add: Green "Create" button (moved from form)
• Add: Visual separator "— OR —"
• Keep: Box input field
• Keep: Skip/Assign buttons
• Result: All three options visible

Part 3: Update Modal Display Logic

• When modal shows: Display CP code
• When modal shows: Focus on box input
• When box created: Keep modal open for scanning

---

Implementation Files Referenced

Old App (Reference):

/srv/quality_app/py_app/app/templates/fg_scan.html
├── Lines 15-65: submitScanWithBoxAssignment() function
├── Lines 70-90: showBoxModal() function
├── Lines 100-120: assignCpToBox() function
├── Lines 310-360: Checkbox toggle logic
├── Lines 730-750: Auto-submit with modal trigger
├── Lines 1005-1095: Quick box create handler
├── Lines 1100-1120: Assign to existing box handler
├── Lines 1140-1200: Modal HTML structure
└── Lines 975-985: Modal close handlers

New App (Target):

/srv/quality_app-v2/app/templates/modules/quality/fg_scan.html
├── Lines 53-56: quickBoxSection (TO DELETE)
├── Lines 109-129: Modal HTML (TO REPLACE)
├── Lines 800-810: Modal show logic (TO UPDATE)
├── Lines 835-900: Quick box handler (ALREADY EXISTS - GOOD)
├── Lines 976-985: Modal close (ALREADY EXISTS - GOOD)
└── Lines 22-23: Checkbox input (ALREADY EXISTS - GOOD)

---

Required Endpoints (Backend)

Verify these exist in your Flask routes:

✅ POST /quality/create_quick_box
   Input: {} (empty)
   Output: { success: true, box_number: "BOX-12345" }

✅ POST /quality/generate_box_label_pdf
   Input: FormData { box_number: "BOX-12345" }
   Output: { success: true, pdf_base64: "..." }

✅ POST /warehouse/assign_cp_to_box
   Input: { box_number: "BOX-12345", cp_code: "CP-123456" }
   Output: { success: true, message: "..." }

✅ POST /scan (or current endpoint)
   Input: FormData { operator_code, cp_code, oc1_code, oc2_code, defect_code, date, time }
   Output: { success: true, scan_id: 12345 }

All four endpoints are referenced in the current code. Lines 839 and 857 show Flask url_for() calls to these endpoints.

---

Database Tables Involved

boxes_crates (Main box table)

CREATE TABLE boxes_crates (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    box_number VARCHAR(50) UNIQUE,
    location_id BIGINT,
    created_at TIMESTAMP,
    updated_at TIMESTAMP,
    FOREIGN KEY (location_id) REFERENCES warehouse_locations(id)
);

Used in: Box creation workflow Action: When user clicks "Create", new row inserted here

box_contents (CP to Box linking)

CREATE TABLE box_contents (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    box_id BIGINT,
    cp_code VARCHAR(50),
    location_id BIGINT,
    created_at TIMESTAMP,
    quantity INT,
    FOREIGN KEY (box_id) REFERENCES boxes_crates(id)
);

Used in: Box assignment workflow Action: When user clicks "Assign", new row inserted here linking CP to box

scanfg_orders (Scan records)

CREATE TABLE scanfg_orders (
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    cp_code VARCHAR(50),
    operator_code VARCHAR(50),
    box_id BIGINT,         ← NEW
    location_id BIGINT,    ← NEW
    ... other fields ...,
    FOREIGN KEY (box_id) REFERENCES boxes_crates(id)
);

Used in: After assignment, scan record links to box and location

---

Testing Strategy

Scenario 1: Create New Box

1. Enable "Scan to Boxes" ✓
2. Scan/enter product with 000 (good)
3. Modal appears
4. Click "📦 Quick Box Label Creation"
   - Box created in DB ✓
   - PDF generated ✓
   - Label prints (or shows warning if QZ unavailable) ✓
   - Input field shows "Scan the printed label now..." ✓
   - Modal STAYS OPEN ✓
5. Scan newly created box label
6. Click "Assign to Box"
   - CP linked to box ✓
   - Modal closes ✓
   - Page reloads ✓

Scenario 2: Scan Existing Box

1. Enable "Scan to Boxes" ✓
2. Scan/enter product with 000 (good)
3. Modal appears
4. Scan existing box OR enter box number
5. Click "Assign to Box"
   - CP linked to existing box ✓
   - Modal closes ✓
   - Page reloads ✓

Scenario 3: Skip Assignment

1. Enable "Scan to Boxes" ✓
2. Scan/enter product with 000 (good)
3. Modal appears
4. Click "Skip"
   - Scan saved to DB ✓
   - NOT assigned to any box ✓
   - Modal closes ✓
   - Page reloads ✓

Scenario 4: Non-Good Quality (Don't Show Modal)

1. Enable "Scan to Boxes" ✓
2. Scan/enter product with defect code = 001 (rejected)
3. Modal should NOT appear ✓
4. Form submits normally ✓
5. Page reloads normally ✓

---

Files to Create/Modify

Documentation (CREATED):

✅ /srv/quality_app-v2/documentation/OLD_APP_BOX_WORKFLOW_REFERENCE.md ✅ /srv/quality_app-v2/documentation/BOX_WORKFLOW_COMPARISON_OLD_VS_NEW.md ✅ /srv/quality_app-v2/documentation/FG_SCAN_MODAL_FIX_GUIDE.md ✅ /srv/quality_app-v2/documentation/FG_SCAN_MODAL_VISUAL_GUIDE.md ✅ /srv/quality_app-v2/documentation/FG_SCAN_BOX_WORKFLOW_ANALYSIS.md ← THIS FILE

Code (NEEDS MODIFICATION):

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

• Delete lines 53-56 (quickBoxSection)
• Replace lines 109-129 (modal HTML)
• Update lines 803-810 (modal show logic)

---

Before & After Comparison

Before (Current Problem):

Checkbox enabled? ✓
Scan with 000? ✓
Modal shows? ✓
Can see "Create Box"? ✗ PROBLEM!
User confused? ✓ YES
Feature works? ⚠️ Partially (hidden)

After (Fixed):

Checkbox enabled? ✓
Scan with 000? ✓
Modal shows? ✓
Can see "Create Box"? ✓ FIXED!
User confused? ✗ NO
Feature works? ✓ YES - Complete

---

Quick Reference: What Goes Where

IN THE MODAL (After clicking scan with 000):

• ✅ CP Code display
• ✅ "📦 Quick Box Label Creation" button (green)
• ✅ "— OR —" separator
• ✅ "Scan Box Number:" input field
• ✅ "Skip" button
• ✅ "Assign to Box" button

NOT IN THE MODAL (Out of scope):

• ❌ Operator code input (in form)
• ❌ CP code input (in form)
• ❌ OC1, OC2, Defect inputs (in form)
• ❌ Date/Time (in form)
• ❌ Submit button (in form)

---

Success Criteria

✅ Functionality:

• Checkbox persists user preference
• Modal appears for defect=000 only
• All three options (Create/Scan/Skip) are visible
• Create option creates box, prints label, keeps modal open
• Scan option links CP to existing box
• Skip option leaves CP unassigned
• Non-000 defects skip modal entirely

✅ User Experience:

• Modal design clearly shows three choices
• CP code displayed so user knows what's being assigned
• Visual separator "— OR —" makes options distinct
• Green button clearly indicates "Create" action
• Input field clearly for "Scan Existing" action
• Skip and Assign buttons obvious in footer

✅ Data Integrity:

• Scans saved before modal appears
• Box assignments linked correctly
• Location tracked properly
• No orphaned records

---

Reference Links in Documentation

1. OLD_APP_BOX_WORKFLOW_REFERENCE.md

   • Detailed breakdown of old app workflow
   • Code line references
   • All three option handlers explained
   • Database endpoints required

2. BOX_WORKFLOW_COMPARISON_OLD_VS_NEW.md

   • Side-by-side HTML comparison
   • Step-by-step workflow analysis
   • Issues identified
   • Recommended changes

3. FG_SCAN_MODAL_FIX_GUIDE.md

   • Implementation steps (4 parts)
   • Exact code locations
   • Before/after code snippets
   • Testing checklist

4. FG_SCAN_MODAL_VISUAL_GUIDE.md

   • Visual diagrams of workflows
   • State machine diagram
   • Error scenarios
   • All three options illustrated

---

Next Steps

1. Review all four documentation files
2. Identify the 3 code changes needed
3. Implement the changes in fg_scan.html
4. Test all four scenarios
5. Verify database updates correctly
6. Deploy updated file

---

Contact/Questions

Refer to:

• Line numbers: Use FG_SCAN_MODAL_FIX_GUIDE.md
• Visual explanation: Use FG_SCAN_MODAL_VISUAL_GUIDE.md
• Side-by-side code: Use BOX_WORKFLOW_COMPARISON_OLD_VS_NEW.md
• Old app reference: Use OLD_APP_BOX_WORKFLOW_REFERENCE.md

All documentation is in: /srv/quality_app-v2/documentation/