ske087/quality_app-v2
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
quality_app-v2/documentation/BOXES_QUICK_START.md
Quality App Developer e1f3302c6b Implement boxes management module with auto-numbered box creation 
- Add boxes_crates database table with BIGINT IDs and 8-digit auto-numbered box_numbers
- Implement boxes CRUD operations (add, edit, update, delete, delete_multiple)
- Create boxes route handlers with POST actions for all operations
- Add boxes.html template with 3-panel layout matching warehouse locations module
- Implement barcode generation and printing with JsBarcode and QZ Tray integration
- Add browser print fallback for when QZ Tray is not available
- Simplify create box form to single button with auto-generation
- Fix JavaScript null reference errors with proper element validation
- Convert tuple data to dictionaries for Jinja2 template compatibility
- Register boxes blueprint in Flask app initialization
2026-01-26 22:08:31 +02:00

6.0 KiB
Raw Permalink Blame History

Boxes Management - Quick Start Guide

Accessing the Boxes Page

  1. From Warehouse Menu: Warehouse → Manage Boxes/Crates
  2. Direct URL: /warehouse/boxes
  3. Link from index: Click "Go to Boxes" button on warehouse dashboard

Creating a New Box

Method 1: Auto-Generated Number (Recommended)

  1. Leave "Box Number" field empty
  2. Enter description (optional)
  3. Click "Create Box"
  4. System generates BOX-XXXXXX format

Method 2: Custom Box Number

  1. Enter custom box number in "Box Number" field
  2. Enter description (optional)
  3. Click "Create Box"
  4. Validates uniqueness automatically

Managing Boxes

Viewing Boxes

  • All boxes displayed in center table
  • Click edit button (pencil icon) to modify
  • Status badge shows open (green) or closed (red)
  • Location shows assigned warehouse location (if any)

Editing a Box

  1. Click edit button in table row
  2. Right panel loads box details
  3. Cannot change box number (read-only)
  4. Can change:
    • Status (open/closed)
    • Location (assign to warehouse location)
    • Description (notes/comments)
  5. Click "Save Changes" to update
  6. Click "Delete Box" to remove
  7. Click "Cancel" to close

Changing Status

  1. Select box by clicking edit button
  2. Choose status from dropdown (Open or Closed)
  3. Click "Save Changes"
  4. Status updates immediately

Assigning Location

  1. Select box by clicking edit button
  2. Choose location from "Location" dropdown
  3. Shows all available warehouse locations
  4. Select "No Location" to clear
  5. Click "Save Changes"

Deleting Boxes

Delete Single Box

  1. Click edit button on box
  2. Click "Delete Box" button
  3. Confirm in modal dialog
  4. Box removed permanently

Delete Multiple Boxes

  1. Check boxes in left column of table
  2. "Delete Selected" button shows count
  3. Click "Delete Selected"
  4. Confirm in modal dialog
  5. Selected boxes removed

Select All Feature

  • Click checkbox in table header to select/uncheck all
  • Useful for quick operations

Printing Box Labels

Setup (First Time)

  1. Make sure QZ Tray is installed (optional)
  2. Boxes page shows QZ Tray status:
    • ✅ Connected: Uses thermal printer
    • ❌ Not Available: Will use browser print

Printing Process

  1. Click edit button on desired box
  2. Bottom right panel shows "Print Label"
  3. Box number displays in field
  4. Click "Generate Preview" to see barcode
  5. Barcode appears in preview section
  6. Select printer from dropdown (if available)
  7. Click "Print Label" to send to printer

Printer Selection

  • "Default Printer": Uses system default or first thermal printer
  • Named printers: Shows all available printers if QZ Tray connected
  • No selection needed for browser print

Testing Printer Connection

  1. Go to any box and scroll to Print Label section
  2. Click "Test QZ Tray" button
  3. Shows connection status and available printers
  4. If not connected, browser print will be used automatically

Statistics Display

Left panel shows real-time counts:

  • Total Boxes: All boxes in system
  • Open: Boxes with "open" status
  • Closed: Boxes with "closed" status

Updates automatically after add/edit operations.

Flash Messages

Success Messages (green):

  • Box created successfully
  • Box updated successfully
  • Box deleted successfully

Error Messages (red):

  • Duplicate box number
  • Box not found
  • Database error

Keyboard Shortcuts

Action Shortcut
Select all Check header checkbox
Cancel edit Esc key (or Cancel button)
Generate preview Enter in print section

Tips & Tricks

Faster Operations

  1. Use auto-generated box numbers to save time
  2. Assign locations during creation if possible
  3. Use "Select All" for bulk operations

Better Organization

  1. Use description field for box contents
  2. Assign locations to track warehouse placement
  3. Use status to track workflow (open=in use, closed=archived)

Printing

  1. If printer not found, check QZ Tray installation
  2. Browser print works without QZ Tray
  3. Test printer button helps diagnose issues
  4. Barcode is CODE128 format (standard)

Common Issues & Solutions

Issue: "Box number already exists"

  • Solution: Enter unique box number or leave blank for auto-generation

Issue: Printer dropdown is empty

  • Solution: QZ Tray not installed or connected. Browser print will be used.

Issue: Can't select/delete boxes

  • Solution: Check table checkboxes, then click "Delete Selected"

Issue: Print not working

  • Troubleshoot:
    1. Click "Test QZ Tray" button
    2. If not connected, browser print will open
    3. Check printer is powered on
    4. Try browser print as backup

Issue: Description not saving

  • Solution: Click "Save Changes" button after editing

Data Structure Reference

Box Fields

Field Type Notes
Box Number Text Unique identifier (auto-generated if blank)
Status Dropdown open or closed
Location Dropdown Warehouse location (optional)
Description Text Notes/comments about box
Created Timestamp Auto-filled (read-only)
Updated Timestamp Auto-updated on changes

Barcode Format

  • Type: CODE128
  • Content: Box number
  • Scannable with standard barcode scanners
  • Used for inventory tracking

Performance Notes

  • Page loads with all boxes displayed
  • For 1000+ boxes, consider pagination (feature request)
  • Barcode generation is fast (client-side)
  • Printer operations are non-blocking (async)

Security

  • Session authentication required
  • Only authenticated users can access
  • All data changes logged with timestamps
  • Database uses parameterized queries

Helpful Related Pages

  1. Warehouse Locations - Create/manage storage locations
  2. Set Boxes Locations - Assign articles to boxes
  3. Warehouse Index - Overview and navigation

Getting Help

  • Check the Statistics card for overview
  • Use Test QZ Tray for printer issues
  • Review Flash Messages for operation status
  • Check browser console (F12) for error details

Last Updated: 2025-01-25
Version: 1.0
Status: Production Ready

Reference in New Issue View Git Blame Copy Permalink