inventory-barcode-system/docs/USER_GUIDE.md

# 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.