quality_app-v2/documentation/ASSIGN_TO_BOX_QUICK_REFERENCE.md

docker ps# Assign to Box Form - Quick Reference Guide

Overview

When a user scans a product with defect code 000 (good quality) on the FG Scan page with "Scan to Boxes" enabled, a modal popup appears allowing them to assign the scanned CP (Chassis/Part) to a warehouse box.

---

Modal Form At A Glance

╔════════════════════════════════════════╗
║  Assign to Box                    [×]  ║
╠════════════════════════════════════════╣
║                                        ║
║  CP Code: CP-123456789AB               ║
║                                        ║
║  ┌────────────────────────────────┐  ║
║  │ 📦 Quick Box Label Creation   │  ║
║  │ Creates new box and prints... │  ║
║  └────────────────────────────────┘  ║
║                                        ║
║     ━━━━━━━  OR  ━━━━━━━             ║
║                                        ║
║  Scan Box Number:                      ║
║  [____________________]                ║
║  Scan or enter box number manually    ║
║                                        ║
║  Quantity:                             ║
║  [1]                                   ║
║  How many units to assign              ║
║                                        ║
║  [Skip]  [Assign to Box]              ║
╚════════════════════════════════════════╝

---

Form Elements Quick Reference

Element	ID	Type	Input Required	Notes
Modal Container	boxAssignmentModal	div	N/A	Hidden until modal needed
CP Code Display	modal-cp-code	span	N/A	Read-only, JS-populated
Create Box Button	quickBoxLabel	button	N/A	Green button, creates new box
Box Number Input	boxNumber	text	✅	Focus auto-set, barcode scan ready
Quantity Input	boxQty	number	✅	Default: 1, min: 1
Skip Button	cancelModal	button	N/A	Gray, saves scan without box
Assign Button	assignToBox	button	N/A	Blue, submits assignment
Close Button	closeModal	button	N/A	X in header

---

How It Works: Step by Step

Step 1: User Enables Feature

✓ Go to FG Scan page
✓ Check "Scan to Boxes" checkbox
✓ QZ Tray initializes (for label printing)

Step 2: User Scans Good Product

✓ Enter Operator Code: OP01
✓ Enter CP Code: CP-123456789AB
✓ Enter OC1 Code: OC01
✓ Enter OC2 Code: OC02
✓ Enter Defect Code: 000 ← IMPORTANT (must be 000)
✓ Click "Scan" button
✓ Form submits via AJAX

Step 3: Backend Processes

✓ Validates form inputs
✓ Saves scan to database
✓ Returns success response

Step 4: Modal Appears

✓ Modal slides in with CP code displayed
✓ Box number input auto-focused
✓ Ready for user action

Step 5: User Chooses Action

Option A - Create New Box:
  ✓ Click "📦 Quick Box Label Creation"
  ✓ New box created automatically
  ✓ Label printed via QZ Tray
  ✓ CP linked to new box

Option B - Assign to Existing Box:
  ✓ Scan/enter box number: BOX-001
  ✓ Edit quantity if needed (default: 1)
  ✓ Click "Assign to Box"
  ✓ CP linked to existing box

Option C - Skip Assignment:
  ✓ Click "Skip" button
  ✓ Scan remains in database
  ✓ CP NOT linked to any box

Step 6: Completion

✓ Success message displayed
✓ Modal closes
✓ Page reloads
✓ Ready for next scan

---

API Endpoint Reference

Assign CP to Box Endpoint

URL: /quality/api/assign-cp-to-box

Method: POST

Content-Type: application/json

Request Body:

{
  "box_number": "BOX-001",
  "cp_code": "CP-123456789AB",
  "quantity": 1
}

Success Response (200):

{
  "success": true,
  "box_number": "BOX-001",
  "cp_code": "CP-123456789AB"
}

Error Response (404):

{
  "error": "Box BOX-001 not found"
}

Error Response (400):

{
  "error": "Missing box_number or cp_code"
}

---

Validation Rules

Box Number Validation

✓ Must not be empty
✓ Whitespace trimmed automatically
✓ Any string format accepted (server validates actual box exists)
✗ Empty → Warning: "Please enter a box number"

Quantity Validation

✓ Must not be empty
✓ Must be numeric
✓ Must be >= 1
✗ Empty → Warning: "Please enter a valid quantity"
✗ Non-numeric → Warning: "Please enter a valid quantity"
✗ < 1 → Warning: "Please enter a valid quantity"

---

Event Handlers Summary

Form Submission

Trigger: User clicks "Scan" button with valid inputs and defect code = 000

Action:

1. Validate all form fields
2. Send AJAX POST request
3. If successful → Show modal
4. If failed → Show error message

Assign Button Click

Trigger: User clicks "Assign to Box" button

Action:

1. Get box number and quantity from inputs
2. Validate both values
3. If valid → Send API request
4. Show loading state
5. On success → Close modal and reload page
6. On error → Show error message

Skip Button Click

Trigger: User clicks "Skip" button

Action:

1. Show message: "Scan recorded without box assignment"
2. Close modal
3. Reload page after 500ms

Close Button (X) Click

Trigger: User clicks × in modal header

Action:

1. Close modal
2. Reload page after 500ms

Create Box Button Click

Trigger: User clicks "📦 Quick Box Label Creation"

Action:

1. Create new box via API
2. Generate box label PDF
3. Print label via QZ Tray
4. Assign CP to new box
5. Close modal
6. Reload page

---

Notification Messages

Success Messages

✅ Scan saved successfully!
✅ CP CP-123456789AB assigned to box BOX-001!
✅ Scan recorded without box assignment
✅ Box BOX-NNNNNN created and printed!

Warning Messages

⚠️ Please enter a box number
⚠️ Please enter a valid quantity
⚠️ "Scan to Boxes" feature is disabled

Error Messages

❌ Error saving scan
❌ Error: Box BOX-001 not found
❌ Error: [specific error message]
❌ Scan submission failed

---

Database Tables Involved

boxes_crates

Stores warehouse box information

SELECT id, box_number, location_id FROM boxes_crates 
WHERE box_number = 'BOX-001';

box_contents

Stores CP codes assigned to boxes

SELECT box_id, cp_code, quantity, added_at FROM box_contents 
WHERE cp_code = 'CP-123456789AB';

scanfg_orders

Main scans table, gets updated with box assignment

UPDATE scanfg_orders 
SET box_id = ?, location_id = ?
WHERE cp_code = 'CP-123456789AB';

cp_location_history

Audit trail for CP movements

INSERT INTO cp_location_history 
(cp_code, box_id, from_location_id, to_location_id, moved_by, reason)
VALUES ('CP-123456789AB', ?, NULL, ?, user_id, 'Assigned to box');

---

Keyboard Shortcuts

Key	Action
Tab	Move to next form field
Shift+Tab	Move to previous form field
Enter	Submit (when focused on Assign button)
Esc	Close modal (if implemented)

---

Barcode Scanner Integration

How It Works

1. Box number field auto-focuses when modal opens
2. Barcode scanner sends scan data directly to input
3. No special handling needed - just scan!

Scanner Configuration

• Append carriage return or tab (standard setting)
• No special formatting needed
• Box number should match format in database

Example Scan Sequence

Scanner reads barcode → Data sent to boxNumber input
↓
Field populated with: BOX-NNNNNN
↓
Ready for user to click "Assign" or continue scanning

---

Mobile/Responsive Design

• Desktop (1920+px): Modal 500px fixed width, centered
• Tablet (768-1024px): Modal scales to 90% width
• Mobile (< 768px): Modal 90% width, full height overflow
• All sizes: Form elements stack vertically

No horizontal scrolling: ✅ All devices

---

Common Issues & Fixes

Modal Doesn't Appear

Check:

• Scan defect code is exactly "000" (not "0", not "00")
• "Scan to Boxes" checkbox is CHECKED
• Browser console for JavaScript errors
• Network tab shows successful POST response

"Please enter a box number" Warning

Check:

• Box number field is not empty
• Box number has no leading/trailing spaces
• Box number is visible in input field

"Box not found" Error

Check:

• Box number matches format in database
• Box actually exists in boxes_crates table
• Box number is typed correctly

Quantity Validation Error

Check:

• Quantity field is not empty
• Quantity is a whole number (not decimal)
• Quantity is >= 1

---

Performance Tips

✅ Good Practices:

• Focus on box input automatically (no manual clicking needed)
• Button disabled during submission (prevents duplicates)
• Page reloads efficiently (not full restart)
• Notifications display instantly

⚠️ Avoid:

• Rapidly clicking buttons (disabled state prevents this)
• Closing modal during submission
• Scanning multiple products simultaneously

---

Accessibility Features

• ✅ Keyboard navigation (Tab key)
• ✅ Focus indicators visible
• ✅ Clear labels for all inputs
• ✅ Color contrast meets WCAG standards
• ✅ Button states clearly indicated
• ✅ Error messages descriptive

---

Browser Support

Browser	Version	Status
Chrome	90+	✅ Supported
Firefox	88+	✅ Supported
Safari	14+	✅ Supported
Edge	90+	✅ Supported
iOS Safari	14+	✅ Supported
Chrome Mobile	Latest	✅ Supported

---

Configuration Options

Scan to Boxes Feature

• Toggle: "Scan to Boxes" checkbox on FG Scan page
• Persistence: Setting saved to localStorage
• State Variable: scanToBoxesEnabled

Quantity Default

• Default Value: 1
• Min Value: 1
• Modifiable: Yes, user can change

Modal Display

• Display Duration: Persistent until closed by user
• Auto-Close: No, only closes on user action or error
• Re-open: Press "Scan" button again with 000 defect code

---

Field Input Sizes

Field	Min Length	Max Length	Format
Box Number	1 char	No limit	Any alphanumeric
Quantity	1 digit	No limit	Numeric only
CP Code	15 chars	15 chars	CP-XXXXXXXXXXX

---

State Management

Modal Visibility

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

// Hide modal
document.getElementById('boxAssignmentModal').style.display = 'none';

Form Data

// Get form values
let boxNumber = document.getElementById('boxNumber').value.trim();
let quantity = document.getElementById('boxQty').value.trim();
let cpCode = currentCpCode;  // Global variable

// Clear form
document.getElementById('boxNumber').value = '';
document.getElementById('boxQty').value = '';
currentCpCode = '';

---

Testing Quick Checklist

• Modal appears on defect 000
• Box number input accepts barcode scan
• Quantity field validates correctly
• "Assign" button submits to API
• Success message displays
• Page reloads after assignment
• Database shows assignment
• Skip button works
• Form resets on next modal
• Error messages display properly

---

Quick Links

• Form Analysis
• Testing Guide
• Implementation Checklist
• FG Scan Template
• Quality Routes

---

Need Help?

For Form Structure Issues: → See ASSIGN_TO_BOX_FORM_ANALYSIS.md

For Testing the Form: → See ASSIGN_TO_BOX_TESTING_GUIDE.md

For Implementation Details: → See ASSIGN_TO_BOX_IMPLEMENTATION_CHECKLIST.md

For Backend API: → Check app/modules/quality/routes.py

For Old App Reference: → See OLD_APP_BOX_WORKFLOW_REFERENCE.md

---

Last Updated: January 29, 2026
Status: ✅ PRODUCTION READY