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:**
```json
{
  "box_number": "BOX-001",
  "cp_code": "CP-123456789AB",
  "quantity": 1
}
```

**Success Response (200):**
```json
{
  "success": true,
  "box_number": "BOX-001",
  "cp_code": "CP-123456789AB"
}
```

**Error Response (404):**
```json
{
  "error": "Box BOX-001 not found"
}
```

**Error Response (400):**
```json
{
  "error": "Missing box_number or cp_code"
}
```

---

## Validation Rules

### Box Number Validation
```javascript
✓ 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
```javascript
✓ 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
```sql
SELECT id, box_number, location_id FROM boxes_crates 
WHERE box_number = 'BOX-001';
```

### box_contents
Stores CP codes assigned to boxes
```sql
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
```sql
UPDATE scanfg_orders 
SET box_id = ?, location_id = ?
WHERE cp_code = 'CP-123456789AB';
```

### cp_location_history
Audit trail for CP movements
```sql
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
```javascript
// Show modal
document.getElementById('boxAssignmentModal').style.display = 'flex';

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

### Form Data
```javascript
// 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](ASSIGN_TO_BOX_FORM_ANALYSIS.md)
- [Testing Guide](ASSIGN_TO_BOX_TESTING_GUIDE.md)
- [Implementation Checklist](ASSIGN_TO_BOX_IMPLEMENTATION_CHECKLIST.md)
- [FG Scan Template](app/templates/modules/quality/fg_scan.html)
- [Quality Routes](app/modules/quality/routes.py)

---

## Need Help?

**For Form Structure Issues:**
→ See [ASSIGN_TO_BOX_FORM_ANALYSIS.md](ASSIGN_TO_BOX_FORM_ANALYSIS.md)

**For Testing the Form:**
→ See [ASSIGN_TO_BOX_TESTING_GUIDE.md](ASSIGN_TO_BOX_TESTING_GUIDE.md)

**For Implementation Details:**
→ See [ASSIGN_TO_BOX_IMPLEMENTATION_CHECKLIST.md](ASSIGN_TO_BOX_IMPLEMENTATION_CHECKLIST.md)

**For Backend API:**
→ Check [app/modules/quality/routes.py](app/modules/quality/routes.py)

**For Old App Reference:**
→ See [OLD_APP_BOX_WORKFLOW_REFERENCE.md](OLD_APP_BOX_WORKFLOW_REFERENCE.md)

---

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