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

229
.kiro/specs/inventory-barcode-system/design.md Normal file
View File

@ -0,0 +1,229 @@
# Design Document
## Overview
The Inventory Barcode System is a web-based application that bridges traditional Excel-based inventory management with modern barcode scanning technology. The system consists of three main components: Excel import/export functionality, barcode/QR code generation, and a scanning interface for inventory updates.
## Architecture
### System Architecture
```
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ Web Frontend │ │ Backend API │ │ SQLite DB │
│ │◄──►│ │◄──►│ │
│ - File Upload │ │ - Excel Parser │ │ - Products │
│ - Code Display │ │ - Code Generator│ │ - Inventory │
│ - Scanner UI │ │ - Inventory API │ │ - Audit Log │
└─────────────────┘ └─────────────────┘ └─────────────────┘
│ │
│ ┌─────────────────┐
└──────────────►│ File System │
│ - Excel Files │
│ - Generated PDFs│
└─────────────────┘
```
### Technology Stack
- **Frontend**: HTML5, CSS3, JavaScript (with camera API for scanning)
- **Backend**: Node.js with Express.js
- **Database**: SQLite3 with better-sqlite3 driver
- **Excel Processing**: xlsx library
- **Barcode Generation**: jsbarcode and qrcode libraries
- **PDF Generation**: jsPDF for printable layouts
## Components and Interfaces
### 1. Excel Import Service
**Purpose**: Parse Excel files and extract inventory data
**Interface**:
```javascript
class ExcelImportService {
async parseExcelFile(fileBuffer)
async validateData(parsedData)
async importToDatabase(validatedData)
}
```
**Key Functions**:
- Support .xlsx and .xls formats
- Flexible column mapping (auto-detect common patterns)
- Data validation and error reporting
- Batch import with transaction support
### 2. Code Generation Service
**Purpose**: Generate barcodes and QR codes for products
**Interface**:
```javascript
class CodeGenerationService {
async generateBarcode(productCode, format)
async generateQRCode(productData)
async createPrintableLayout(products, layoutOptions)
}
```
**Key Functions**:
- Support multiple barcode formats (Code128, Code39, EAN13)
- QR code generation with embedded product data
- Customizable print layouts
- PDF generation for printing
### 3. Inventory Management Service
**Purpose**: Handle inventory operations and updates
**Interface**:
```javascript
class InventoryService {
async getProductByCode(code)
async updateInventoryLevel(productId, newLevel, userId)
async getInventoryHistory(productId)
async exportToExcel(filters)
}
```
### 4. Scanner Interface
**Purpose**: Web-based barcode/QR code scanning
**Interface**:
```javascript
class ScannerService {
async initializeCamera()
async scanCode()
async processScannedCode(codeData)
}
```
## Data Models
### Database Schema
#### Products Table
```sql
CREATE TABLE products (
id INTEGER PRIMARY KEY AUTOINCREMENT,
product_code VARCHAR(50) UNIQUE NOT NULL,
description TEXT,
category VARCHAR(100),
unit_of_measure VARCHAR(20),
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
updated_at DATETIME DEFAULT CURRENT_TIMESTAMP
);
```
#### Inventory Table
```sql
CREATE TABLE inventory (
id INTEGER PRIMARY KEY AUTOINCREMENT,
product_id INTEGER NOT NULL,
current_level INTEGER NOT NULL DEFAULT 0,
minimum_level INTEGER DEFAULT 0,
maximum_level INTEGER,
last_updated DATETIME DEFAULT CURRENT_TIMESTAMP,
updated_by VARCHAR(100),
FOREIGN KEY (product_id) REFERENCES products(id)
);
```
#### Inventory_History Table
```sql
CREATE TABLE inventory_history (
id INTEGER PRIMARY KEY AUTOINCREMENT,
product_id INTEGER NOT NULL,
old_level INTEGER,
new_level INTEGER NOT NULL,
change_reason VARCHAR(200),
updated_by VARCHAR(100),
updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
FOREIGN KEY (product_id) REFERENCES products(id)
);
```
#### Import_Sessions Table
```sql
CREATE TABLE import_sessions (
id INTEGER PRIMARY KEY AUTOINCREMENT,
filename VARCHAR(255),
total_records INTEGER,
successful_imports INTEGER,
failed_imports INTEGER,
import_date DATETIME DEFAULT CURRENT_TIMESTAMP,
status VARCHAR(20) DEFAULT 'completed'
);
```
### Data Storage Strategy
**Primary Storage**: SQLite Database
- **Advantages**:
- ACID compliance ensures data integrity
- No server setup required
- Excellent performance for read-heavy operations
- Built-in backup via file copy
- Supports concurrent reads with write locking
- **Use Cases**: Product data, inventory levels, audit trails
**File Storage**: Local File System
- **Use Cases**:
- Original Excel files (for reference)
- Generated PDF layouts
- Temporary files during processing
- **Organization**:
```
/data
/imports # Original Excel files
/exports # Generated Excel exports
/printouts # Generated PDF layouts
/temp # Temporary processing files
```
**Caching Strategy**:
- In-memory caching for frequently accessed product data
- Redis optional for multi-user deployments
- Browser localStorage for offline scanning capability
## Error Handling
### Import Error Handling
- **File Format Errors**: Clear messages about supported formats
- **Data Validation Errors**: Row-by-row error reporting with specific issues
- **Duplicate Product Codes**: Options to skip, update, or rename
- **Missing Required Fields**: Highlight and allow manual correction
### Scanning Error Handling
- **Camera Access Denied**: Fallback to manual code entry
- **Code Not Found**: Search suggestions and manual lookup options
- **Network Errors**: Offline mode with sync when connection restored
- **Invalid Codes**: Clear error messages with retry options
### Database Error Handling
- **Connection Errors**: Automatic retry with exponential backoff
- **Constraint Violations**: User-friendly messages with correction suggestions
- **Transaction Failures**: Automatic rollback with user notification
- **Backup Failures**: Alert administrators and provide manual backup options
## Testing Strategy
### Unit Testing
- **Excel Import Service**: Test various Excel formats and edge cases
- **Code Generation**: Verify barcode/QR code accuracy and formats
- **Database Operations**: Test CRUD operations and data integrity
- **Validation Logic**: Test all validation rules and error conditions
### Integration Testing
- **End-to-End Import Flow**: Excel upload through database storage
- **Scanning Workflow**: Code scanning through inventory update
- **Export Process**: Database data through Excel generation
- **Concurrent Access**: Multiple users updating inventory simultaneously
### User Acceptance Testing
- **Import Scenarios**: Various Excel file formats and structures
- **Printing Tests**: Different label sizes and printer types
- **Scanning Tests**: Various lighting conditions and code qualities
- **Performance Tests**: Large inventory lists and concurrent users
### Security Testing
- **File Upload Security**: Malicious file detection and sanitization
- **Input Validation**: SQL injection and XSS prevention
- **Access Control**: User authentication and authorization
- **Data Privacy**: Ensure inventory data remains secure

61
.kiro/specs/inventory-barcode-system/requirements.md Normal file
View File

@ -0,0 +1,61 @@
# Requirements Document
## Introduction
This feature enables users to convert existing Excel-based inventory lists into a barcode/QR code system for efficient inventory management. The system will read product codes from Excel files, generate corresponding barcodes or QR codes for printing, and provide a mechanism for users to scan codes and update inventory levels in real-time.
## Requirements
### Requirement 1
**User Story:** As an inventory manager, I want to import my existing Excel inventory list, so that I can convert product codes into scannable barcodes/QR codes without manual data entry.
#### Acceptance Criteria
1. WHEN a user uploads an Excel file THEN the system SHALL parse and extract product codes, descriptions, and current inventory levels
2. WHEN the Excel file contains invalid data THEN the system SHALL display clear error messages indicating which rows have issues
3. WHEN the Excel file is successfully processed THEN the system SHALL display a preview of the imported data for user confirmation
### Requirement 2
**User Story:** As an inventory manager, I want to generate printable barcodes or QR codes for each product, so that I can physically label items on shelves for easy identification.
#### Acceptance Criteria
1. WHEN a user selects products from the imported list THEN the system SHALL generate barcodes or QR codes containing the product information
2. WHEN generating codes THEN the system SHALL allow users to choose between barcode and QR code formats
3. WHEN codes are generated THEN the system SHALL provide a printable layout with product codes, descriptions, and corresponding barcodes/QR codes
4. WHEN printing THEN the system SHALL support standard label sizes and printer formats
### Requirement 3
**User Story:** As a warehouse worker, I want to scan barcodes/QR codes to quickly identify products, so that I can update inventory levels without manual lookup.
#### Acceptance Criteria
1. WHEN a user scans a barcode or QR code THEN the system SHALL immediately display the product information and current inventory level
2. WHEN a product is identified THEN the system SHALL allow the user to update the inventory quantity
3. WHEN inventory is updated THEN the system SHALL save the new quantity with a timestamp
4. WHEN a scan fails or code is not recognized THEN the system SHALL display an appropriate error message
### Requirement 4
**User Story:** As an inventory manager, I want to export updated inventory data, so that I can maintain records and integrate with other systems.
#### Acceptance Criteria
1. WHEN a user requests data export THEN the system SHALL generate an Excel file with updated inventory levels
2. WHEN exporting THEN the system SHALL include timestamps of last updates for each product
3. WHEN exporting THEN the system SHALL maintain the original Excel file structure and formatting where possible
4. WHEN export is complete THEN the system SHALL provide download functionality for the updated file
### Requirement 5
**User Story:** As a system administrator, I want inventory data to be stored reliably, so that updates are not lost and the system remains performant.
#### Acceptance Criteria
1. WHEN inventory data is updated THEN the system SHALL persist changes immediately to prevent data loss
2. WHEN multiple users access the system THEN the system SHALL handle concurrent updates without data corruption
3. WHEN the system stores data THEN it SHALL maintain data integrity and provide backup capabilities
4. WHEN querying inventory data THEN the system SHALL respond within 2 seconds for typical operations

162
.kiro/specs/inventory-barcode-system/tasks.md Normal file
View File

@ -0,0 +1,162 @@
# Implementation Plan
- [x] 1. Set up project structure and core dependencies
- Create Node.js project with Express.js framework
- Install required dependencies: sqlite3, better-sqlite3, xlsx, jsbarcode, qrcode, jspdf, multer
- Set up basic project directory structure with separate folders for routes, services, models, and public assets
- _Requirements: 5.1, 5.3_
- [x] 2. Implement database schema and connection utilities
- Create SQLite database initialization script with all required tables
- Implement database connection management with proper error handling
- Write database migration utilities for schema updates
- Create indexes for optimal query performance on product_code and inventory lookups
- _Requirements: 5.1, 5.2, 5.3_
- [x] 3. Create data models and validation
- [x] 3.1 Implement Product model with validation
- Write Product class with validation methods for product_code, description, and category
- Create unit tests for Product model validation and database operations
- Implement CRUD operations for products table
- _Requirements: 1.2, 5.4_
- [x] 3.2 Implement Inventory model with audit trail
- Write Inventory class with current level tracking and history logging
- Create unit tests for inventory updates and history recording
- Implement concurrent update handling with proper locking
- _Requirements: 3.3, 5.1, 5.2_
- [x] 4. Build Excel import functionality
- [x] 4.1 Create Excel parsing service
- Implement ExcelImportService to read .xlsx and .xls files
- Write column detection logic to identify product codes, descriptions, and quantities
- Create unit tests for various Excel file formats and structures
- _Requirements: 1.1, 1.2_
- [x] 4.2 Implement data validation and error handling
- Write validation logic for imported data with detailed error reporting
- Create batch import functionality with transaction support
- Implement duplicate handling options (skip, update, rename)
- Write unit tests for validation scenarios and error conditions
- _Requirements: 1.2, 1.3_
- [x] 5. Develop barcode and QR code generation
- [x] 5.1 Create code generation service
- Implement CodeGenerationService with support for multiple barcode formats
- Write QR code generation with embedded product data
- Create unit tests for code generation accuracy and format validation
- _Requirements: 2.1, 2.2_
- [x] 5.2 Build printable layout generator
- Implement PDF generation for printable barcode/QR code layouts
- Create customizable templates for different label sizes
- Write unit tests for PDF generation and layout formatting
- _Requirements: 2.3, 2.4_
- [x] 6. Create web API endpoints
- [x] 6.1 Implement product management endpoints
- Create REST API endpoints for product CRUD operations
- Write endpoints for bulk product import from Excel files
- Implement proper error handling and response formatting
- Create unit tests for all API endpoints
- _Requirements: 1.1, 1.3_
- [x] 6.2 Implement inventory management endpoints
- Create API endpoints for inventory level updates and queries
- Write endpoints for inventory history retrieval
- Implement concurrent update handling with optimistic locking
- Create unit tests for inventory operations and concurrency scenarios
- _Requirements: 3.1, 3.2, 3.3_
- [x] 6.3 Create code generation and export endpoints
- Implement API endpoints for barcode/QR code generation
- Write endpoints for Excel export with updated inventory data
- Create PDF generation endpoints for printable layouts
- Write unit tests for generation and export functionality
- _Requirements: 2.1, 2.3, 4.1, 4.2_
- [x] 7. Build frontend user interface
- [x] 7.1 Create Excel import interface
- Build file upload component with drag-and-drop support
- Implement data preview and validation error display
- Create progress indicators for import operations
- Write frontend tests for import workflow
- _Requirements: 1.1, 1.2, 1.3_
- [x] 7.2 Implement barcode generation interface
- Create product selection interface for code generation
- Build barcode/QR code format selection and preview
- Implement printable layout customization options
- Write frontend tests for code generation workflow
- _Requirements: 2.1, 2.2, 2.3_
- [x] 7.3 Build scanning interface
- Implement camera-based barcode/QR code scanning using browser APIs
- Create manual code entry fallback option
- Build inventory update interface with quantity input
- Write frontend tests for scanning and update workflow
- _Requirements: 3.1, 3.2, 3.3, 3.4_
- [x] 8. Implement export functionality
- [x] 8.1 Create Excel export service
- Write service to generate Excel files with updated inventory data
- Implement timestamp tracking and audit information inclusion
- Maintain original Excel structure and formatting where possible
- Create unit tests for export accuracy and format preservation
- _Requirements: 4.1, 4.2, 4.3_
- [x] 8.2 Complete export interface and download functionality
- Add export tab to frontend interface with filtering options
- Implement file download functionality with proper headers
- Add export history tracking and management interface
- Connect frontend export interface to backend export endpoints
- _Requirements: 4.1, 4.4_
- [x] 9. Add comprehensive error handling and logging
- Implement centralized error handling middleware for Express app
- Add structured logging system with different log levels
- Enhance user-friendly error messages across all interfaces
- Add error recovery mechanisms and retry logic where appropriate
- _Requirements: 1.2, 3.4, 5.1_
- [x] 10. Create integration tests and performance optimization
- Write end-to-end tests for complete workflows (import → generate → scan → export)
- Add performance tests for large inventory datasets (1000+ products)
- Optimize database queries and add proper indexing
- Test concurrent user scenarios and add appropriate locking
- _Requirements: 5.2, 5.4_
- [x] 11. Build deployment configuration and documentation
- Create production deployment configuration with environment variables
- Write comprehensive API documentation with endpoint specifications
- Create user guide for Excel format requirements and system usage
- Implement database backup and recovery procedures
- Add Docker configuration for containerized deployment
- _Requirements: 5.3_