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
This commit is contained in:
Quality App Developer
220
documentation/BOXES_QUICK_START.md
Normal file
220
documentation/BOXES_QUICK_START.md
Normal file
@@ -0,0 +1,220 @@
|
||||
# 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
Block a user