Todd/inventory-barcode-system
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit: Inventory Barcode System

Browse Source
This commit is contained in:
Todd Sales
2025-07-22 20:24:51 -04:00
commit 511b01748d
63 changed files with 26932 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

423
docs/USER_GUIDE.md Normal file
View File

@ -0,0 +1,423 @@
# Inventory Barcode System User Guide
## Table of Contents
1. [Getting Started](#getting-started)
2. [Excel File Requirements](#excel-file-requirements)
3. [Importing Inventory Data](#importing-inventory-data)
4. [Generating Barcodes and QR Codes](#generating-barcodes-and-qr-codes)
5. [Scanning and Updating Inventory](#scanning-and-updating-inventory)
6. [Exporting Data](#exporting-data)
7. [Troubleshooting](#troubleshooting)
8. [Best Practices](#best-practices)
## Getting Started
The Inventory Barcode System helps you convert your existing Excel-based inventory into a modern barcode/QR code system. This guide will walk you through each step of the process.
### System Requirements
- Modern web browser (Chrome, Firefox, Safari, Edge)
- Camera access for barcode scanning (optional)
- Excel files in .xlsx or .xls format
### Accessing the System
1. Open your web browser
2. Navigate to the system URL (typically `http://localhost:3000`)
3. You'll see the main dashboard with four main sections:
- **Import**: Upload Excel files
- **Generate**: Create barcodes/QR codes
- **Scan**: Update inventory levels
- **Export**: Download updated data
## Excel File Requirements
### Supported File Formats
- Microsoft Excel (.xlsx) - Recommended
- Microsoft Excel 97-2003 (.xls)
- Maximum file size: 10MB
### Required Columns
Your Excel file must contain at least these columns (column names are flexible):
| Required Data | Example Column Names | Description |
|---------------|---------------------|-------------|
| Product Code | `Product Code`, `SKU`, `Item Code`, `Code` | Unique identifier for each product |
| Description | `Description`, `Product Name`, `Item Description` | Human-readable product name |
| Current Stock | `Stock`, `Quantity`, `Current Level`, `Qty` | Current inventory quantity |
### Optional Columns
| Optional Data | Example Column Names | Description |
|---------------|---------------------|-------------|
| Category | `Category`, `Type`, `Group` | Product categorization |
| Unit of Measure | `Unit`, `UOM`, `Measure` | Units (pcs, kg, liters, etc.) |
| Minimum Level | `Min Stock`, `Reorder Point` | Minimum stock threshold |
| Maximum Level | `Max Stock`, `Stock Limit` | Maximum stock capacity |
### Excel File Format Examples
#### Example 1: Basic Format
```
| Product Code | Description | Current Stock |
|-------------|--------------------|---------------|
| ABC123 | Widget A | 50 |
| DEF456 | Widget B | 25 |
| GHI789 | Widget C | 100 |
```
#### Example 2: Detailed Format
```
| SKU | Product Name | Category | Stock | Unit | Min | Max |
|--------|--------------------|-------------|-------|------|-----|-----|
| ABC123 | Premium Widget A | Electronics | 50 | pcs | 10 | 200 |
| DEF456 | Standard Widget B | Tools | 25 | pcs | 5 | 100 |
| GHI789 | Deluxe Widget C | Electronics | 100 | pcs | 20 | 300 |
```
### Data Validation Rules
- **Product Code**: Must be unique, 1-50 characters, alphanumeric
- **Description**: Required, maximum 255 characters
- **Current Stock**: Must be a non-negative number
- **Category**: Optional, maximum 100 characters
- **Unit of Measure**: Optional, maximum 20 characters
- **Min/Max Levels**: Optional, must be non-negative numbers
## Importing Inventory Data
### Step-by-Step Import Process
1. **Prepare Your Excel File**
- Ensure your file meets the format requirements
- Remove any empty rows or columns
- Verify all product codes are unique
2. **Access the Import Section**
- Click on the "Import" tab in the main interface
- You'll see a file upload area
3. **Upload Your File**
- Drag and drop your Excel file onto the upload area, OR
- Click "Choose File" to browse and select your file
- The system will begin processing immediately
4. **Review Import Preview**
- The system will display a preview of detected data
- Check that columns are mapped correctly
- Review any validation warnings or errors
5. **Confirm Import**
- If everything looks correct, click "Confirm Import"
- The system will process all records
- You'll see a summary of successful imports and any errors
### Handling Import Errors
Common import errors and solutions:
| Error | Cause | Solution |
|-------|-------|----------|
| "Duplicate product code" | Same code appears multiple times | Ensure all product codes are unique |
| "Invalid product code format" | Code contains invalid characters | Use only letters, numbers, and hyphens |
| "Missing required field" | Description or code is empty | Fill in all required fields |
| "Invalid stock quantity" | Non-numeric stock value | Ensure stock values are numbers |
### Import Options
- **Skip Duplicates**: Ignore products with existing codes
- **Update Existing**: Update existing products with new data
- **Create New Codes**: Automatically generate new codes for duplicates
## Generating Barcodes and QR Codes
### Choosing Code Type
**Barcodes:**
- Best for: Simple product identification
- Formats: Code128 (recommended), Code39, EAN13
- Advantages: Compact, widely supported
- Use when: You need simple, linear codes
**QR Codes:**
- Best for: Rich product information
- Can embed: Product code, description, category
- Advantages: More data capacity, works with smartphones
- Use when: You want to embed additional product details
### Generating Codes
1. **Select Products**
- Go to the "Generate" tab
- Choose products from your imported inventory
- Use filters to find specific products or categories
2. **Choose Code Settings**
- **Code Type**: Barcode or QR Code
- **Format**: Select barcode format (if applicable)
- **Size**: Adjust dimensions for your labels
- **Include Description**: Add product name to labels
3. **Configure Print Layout**
- **Page Size**: A4, Letter, or custom
- **Labels per Row**: Typically 2-4 depending on label size
- **Labels per Column**: Adjust based on your label sheets
- **Font Size**: Readable text size for descriptions
4. **Generate and Download**
- Click "Generate Codes"
- Download the PDF file
- Print on standard label sheets or regular paper
### Print Layout Options
#### Standard Label Sizes
- **Avery 5160**: 30 labels per sheet (2.625" x 1")
- **Avery 5163**: 10 labels per sheet (4" x 2")
- **Custom**: Define your own dimensions
#### Print Tips
- Use high-quality printer settings
- Test print on regular paper first
- Ensure adequate contrast (black codes on white background)
- Verify codes scan properly before mass printing
## Scanning and Updating Inventory
### Setting Up Scanning
1. **Camera Access**
- Allow camera access when prompted
- Ensure good lighting for scanning
- Position camera 6-12 inches from codes
2. **Manual Entry Fallback**
- If camera scanning fails, use manual entry
- Type or paste the product code
- System will look up the product automatically
### Scanning Process
1. **Access Scan Interface**
- Click on the "Scan" tab
- Camera view will appear (if available)
2. **Scan Product Code**
- Point camera at barcode or QR code
- Wait for automatic detection
- Product information will appear
3. **Update Inventory**
- Current stock level is displayed
- Enter new quantity or adjustment amount
- Add reason for change (optional but recommended)
- Click "Update Inventory"
4. **Confirmation**
- System confirms the update
- New stock level is saved immediately
- Change is logged in inventory history
### Scanning Tips
- **Good Lighting**: Ensure adequate lighting on codes
- **Steady Hands**: Hold device steady for better recognition
- **Clean Codes**: Ensure codes aren't damaged or dirty
- **Proper Distance**: Maintain 6-12 inches from code
- **Flat Surface**: Codes should be on flat, non-reflective surfaces
### Bulk Updates
For updating multiple items quickly:
1. Scan first product
2. Update quantity
3. Immediately scan next product
4. System remembers your workflow
5. Use "Quick Mode" for faster updates
## Exporting Data
### Export Options
1. **Full Inventory Export**
- All products with current stock levels
- Includes last update timestamps
- Maintains original Excel structure
2. **Filtered Export**
- Export specific categories
- Low stock items only
- Date range filters
3. **History Export**
- Include inventory change history
- Audit trail for stock movements
- User activity tracking
### Export Process
1. **Access Export Section**
- Click on the "Export" tab
- Choose export options
2. **Configure Export**
- **Format**: Excel (.xlsx) or CSV
- **Include History**: Add change logs
- **Date Range**: Filter by update dates
- **Categories**: Select specific product categories
3. **Generate and Download**
- Click "Generate Export"
- File will be prepared
- Download link will appear
- File includes timestamp in filename
### Export File Structure
The exported Excel file maintains your original structure with additional columns:
- **Last Updated**: Timestamp of last inventory change
- **Updated By**: User who made the last change
- **Change History**: Summary of recent changes (if included)
## Troubleshooting
### Common Issues and Solutions
#### Import Problems
**Problem**: "File format not supported"
- **Solution**: Ensure file is .xlsx or .xls format
- **Check**: File isn't corrupted or password-protected
**Problem**: "No data found in file"
- **Solution**: Verify file has data in first worksheet
- **Check**: Column headers are in first row
**Problem**: "Column mapping failed"
- **Solution**: Ensure required columns exist
- **Check**: Column names match expected patterns
#### Scanning Issues
**Problem**: "Camera not working"
- **Solution**: Check browser permissions for camera access
- **Alternative**: Use manual code entry
**Problem**: "Codes not scanning"
- **Solution**: Improve lighting conditions
- **Check**: Codes aren't damaged or too small
- **Try**: Different scanning angle or distance
**Problem**: "Product not found"
- **Solution**: Verify product was imported correctly
- **Check**: Product code matches exactly (case-sensitive)
#### Mobile Camera Issues (Android/iOS)
**Problem**: "Start Camera button gives error on Android Chrome"
- **Solution**: Ensure you're using HTTPS (required for camera access on mobile)
- **Check**: Allow camera permission when prompted
- **Try**: Refresh the page and try again
- **Alternative**: Clear browser cache and cookies
**Problem**: "Camera permission denied - no settings visible"
- **Solution**: This is a common Chrome Android issue. Try these steps:
1. Look for a camera icon (🎥) in the address bar and tap it
2. If no icon appears, go to Chrome menu (⋮) → Settings → Site settings → Camera
3. Find your website and set to "Allow"
4. Try using an incognito/private tab first, then allow permission
5. Use the "Request Permission Again" button that appears after the error
**Problem**: "Camera permission denied"
- **Solution**: Go to browser settings → Site permissions → Camera → Allow
- **Chrome Android**: Settings → Site Settings → Camera → Allow
- **Safari iOS**: Settings → Safari → Camera → Allow
**Problem**: "Camera shows black screen"
- **Solution**: Close other apps that might be using the camera
- **Check**: Restart the browser
- **Try**: Use a different browser (Chrome, Firefox, Safari)
**Problem**: "Camera is blurry or won't focus"
- **Solution**: Clean the camera lens
- **Check**: Ensure adequate lighting
- **Try**: Hold device 6-12 inches from the barcode
**Problem**: "Camera works but scanning is slow"
- **Solution**: Ensure good lighting conditions
- **Check**: Hold device steady
- **Try**: Use manual entry for faster updates
#### Performance Issues
**Problem**: "System running slowly"
- **Solution**: Clear browser cache and cookies
- **Check**: Close other browser tabs
- **Try**: Refresh the page
**Problem**: "Large file upload fails"
- **Solution**: Split large files into smaller batches
- **Check**: File size is under 10MB limit
### Getting Help
If you encounter issues not covered in this guide:
1. Check the system logs (if you have access)
2. Try refreshing your browser
3. Clear browser cache and cookies
4. Contact your system administrator
5. Refer to the technical documentation
## Best Practices
### File Management
- **Backup Original Files**: Keep copies of your original Excel files
- **Consistent Naming**: Use clear, consistent product codes
- **Regular Updates**: Import new products regularly rather than in large batches
- **Data Validation**: Clean your data before importing
### Code Generation
- **Test Print**: Always test print codes before mass production
- **Quality Check**: Verify codes scan properly after printing
- **Label Management**: Use high-quality label stock for durability
- **Size Considerations**: Ensure codes are large enough to scan reliably
### Inventory Management
- **Regular Scanning**: Update inventory levels frequently
- **Reason Codes**: Always include reasons for inventory changes
- **Audit Trail**: Review inventory history regularly
- **Backup Data**: Export data regularly for backup purposes
### System Maintenance
- **Regular Exports**: Export data weekly for backup
- **Monitor Performance**: Watch for slow response times
- **Update Browsers**: Keep browsers updated for best performance
- **Training**: Ensure all users understand proper procedures
### Security Considerations
- **Access Control**: Limit system access to authorized users
- **Data Privacy**: Protect inventory data from unauthorized access
- **Regular Backups**: Maintain regular data backups
- **Update Procedures**: Keep system software updated
## Conclusion
The Inventory Barcode System streamlines your inventory management by bridging traditional Excel-based tracking with modern barcode technology. By following this guide, you'll be able to:
- Successfully import your existing inventory data
- Generate professional barcode and QR code labels
- Efficiently update inventory levels through scanning
- Export updated data for record-keeping and integration
For additional support or advanced features, consult the technical documentation or contact your system administrator.