399 lines
11 KiB
Markdown
399 lines
11 KiB
Markdown
# ScanLook - Inventory Management System
|
|
|
|
**Barcode-based inventory counting system designed for food production facilities**
|
|
|
|
Replace 5 days of manual year-end physical inventory with a weekend project. Track variances, location errors, phantom lots, and ghost inventory in real-time.
|
|
|
|
---
|
|
|
|
## 🚀 Quick Start
|
|
|
|
### 1. Install Dependencies
|
|
|
|
```bash
|
|
pip install flask werkzeug --break-system-packages
|
|
```
|
|
|
|
### 2. Initialize Database
|
|
|
|
```bash
|
|
cd /path/to/scanlook
|
|
python database/init_db.py
|
|
```
|
|
|
|
This creates the database with default users:
|
|
- **Owner**: `owner` / `owner123`
|
|
- **Admin**: `admin` / `admin123`
|
|
- **Staff**: `staff1` / `staff123`
|
|
- **Staff**: `staff2` / `staff123`
|
|
|
|
### 3. Run Application
|
|
|
|
```bash
|
|
python app.py
|
|
```
|
|
|
|
Access at: **http://localhost:5000**
|
|
|
|
---
|
|
|
|
## 📱 Accessing from Scanner Devices
|
|
|
|
For Zebra MC9300 scanners or tablets on the same network:
|
|
|
|
1. Find your server's IP address:
|
|
```bash
|
|
hostname -I
|
|
```
|
|
|
|
2. On scanner device, open browser and navigate to:
|
|
```
|
|
http://YOUR_SERVER_IP:5000
|
|
```
|
|
|
|
3. Scanner trigger acts as Enter key (keyboard wedge mode)
|
|
|
|
---
|
|
|
|
## 🏗️ Modular Architecture
|
|
|
|
ScanLook uses a modular system designed to grow into a full WMS. Modules can be enabled/disabled per user.
|
|
|
|
### Current Modules:
|
|
- **Counts** - Cycle Counts and Physical Inventory
|
|
|
|
### Planned Modules:
|
|
- Shipping
|
|
- Receiving
|
|
- Transfers
|
|
- Production
|
|
|
|
### Module Access
|
|
- Admins assign modules to users via User Management
|
|
- Users only see modules they have access to on the home screen
|
|
- Route guards prevent URL bypassing
|
|
|
|
---
|
|
|
|
## 👥 User Roles
|
|
|
|
### Owner (Level 1)
|
|
- Super admin privileges
|
|
- Manage all users (admins and staff)
|
|
- Access to all modules
|
|
- View all sessions across branches
|
|
|
|
### Admin (Level 2)
|
|
- Create count sessions
|
|
- Upload MASTER baseline (morning snapshot)
|
|
- Upload CURRENT baseline (refresh anytime)
|
|
- View real-time dashboard
|
|
- Export variance reports
|
|
- Manage staff users and module assignments
|
|
|
|
### Staff/Counter (Level 3)
|
|
- Access assigned modules only
|
|
- Select active count session
|
|
- Scan locations and lots
|
|
- Enter weights
|
|
- Edit/delete their own scans
|
|
- View their progress
|
|
|
|
---
|
|
|
|
## 🔄 Core Workflow (Counts Module)
|
|
|
|
### Phase 1: Session Setup (Admin)
|
|
|
|
1. **Log in as admin**
|
|
2. **Navigate to Admin Console**
|
|
3. **Create new count session**:
|
|
- Session name: "January 17, 2026 - Daily Cycle Count"
|
|
- Type: Cycle Count OR Full Physical Inventory
|
|
4. **Upload MASTER baseline** CSV from NetSuite:
|
|
- Format: `Item, Description, Lot Number, Location, Bin Number, On Hand`
|
|
5. Session status: **Active**
|
|
6. Counters can now begin
|
|
|
|
### Phase 2: Counting (Staff)
|
|
|
|
1. **Log in as staff**
|
|
2. **Select Counts module** from home screen
|
|
3. **Select active session**
|
|
4. **Start a new bin** - scan or enter bin number
|
|
5. **Scan lot barcode**
|
|
6. System checks lot against MASTER baseline:
|
|
- ✅ **MATCH**: Expected here, location correct
|
|
- ⚠️ **WRONG LOCATION**: Lot exists but system says different location
|
|
- ❌ **GHOST LOT**: Not in system at all
|
|
- 🔵 **DUPLICATE**: Lot already scanned (same or different location)
|
|
7. **Enter weight**
|
|
8. Save → returns to scan input (autofocus)
|
|
9. Repeat for all lots in bin
|
|
10. Click **"Finish Location"** to finalize
|
|
|
|
### Phase 3: Admin Monitoring
|
|
|
|
**Real-Time Dashboard Shows:**
|
|
- Total locations & completion percentage
|
|
- Active counters with current location
|
|
- Variance summary (matches, wrong locations, missing, ghost lots)
|
|
|
|
**Optional CURRENT Baseline Refresh:**
|
|
- Admin uploads new CSV from NetSuite
|
|
- System recalculates CURRENT status for all scans
|
|
- Shows what changed in system after count
|
|
- Proves count was correct, lot moved later
|
|
|
|
---
|
|
|
|
## 📊 CSV Import Format
|
|
|
|
**Required columns:**
|
|
```csv
|
|
Item,Description,Lot Number,Location,Bin Number,On Hand
|
|
100001,Beef MDM,20260108-132620-PO25146,Wisconsin G & H,R903B,2030
|
|
100001,Beef MDM,20260108-132700-PO25146,Wisconsin G & H,R903B,2030
|
|
100001,Beef MDM,20260106-150649-PO24949,Wisconsin G & H,R905C,2065
|
|
```
|
|
|
|
**Column Descriptions:**
|
|
- **Item**: SKU or item number
|
|
- **Description**: Product description
|
|
- **Lot Number**: Unique lot identifier
|
|
- **Location**: Warehouse location name
|
|
- **Bin Number**: Specific bin/rack location code
|
|
- **On Hand**: Current quantity in pounds
|
|
|
|
---
|
|
|
|
## 🎯 Key Features
|
|
|
|
### Dual Baseline System
|
|
|
|
**MASTER Baseline**:
|
|
- Uploaded once at session start (e.g., 6:00 AM)
|
|
- Never changes during session
|
|
- What counters validate against
|
|
- Represents "what should have been there when we started"
|
|
|
|
**CURRENT Baseline** (Global):
|
|
- Admin can refresh unlimited times
|
|
- Shared across all sessions
|
|
- Only affects admin dashboard/reporting
|
|
- Counters never see it
|
|
- Shows "where is it in the system NOW"
|
|
- Identifies movement after count
|
|
|
|
### Variance Detection
|
|
|
|
- **Perfect Match**: Right location, weight within tolerance
|
|
- **Weight Variance**: Right location, weight differs (calculates %)
|
|
- **Wrong Location**: Lot exists but scanned in different location
|
|
- **Ghost Lot**: Scanned but not in baseline at all
|
|
- **Missing/Phantom**: In baseline but not found during count
|
|
|
|
### Duplicate Detection
|
|
|
|
- **Status 00**: First scan of lot (no duplicate)
|
|
- **Status 01**: Duplicate in same location by same user
|
|
- **Status 03**: Found in different location
|
|
- **Status 04**: Both same location duplicate AND different location
|
|
|
|
### Count Types
|
|
|
|
**Cycle Count:**
|
|
- Shows expected lots for the bin
|
|
- Staff can see what should be there
|
|
- Good for regular inventory checks
|
|
|
|
**Full Physical Inventory:**
|
|
- Blind count (no expected list shown)
|
|
- Staff only sees what they've scanned
|
|
- Missing lots determined after finalization
|
|
|
|
### Real-Time Dashboard
|
|
|
|
- Active sessions with progress stats
|
|
- Location completion tracking
|
|
- Variance counts updating live
|
|
- Dual view (MASTER vs CURRENT) after refresh
|
|
|
|
### Audit Trail
|
|
|
|
- Every scan timestamped with user
|
|
- Soft deletes tracked
|
|
- Edits tracked with modified timestamp
|
|
- Session archival (archived sessions are read-only)
|
|
|
|
---
|
|
|
|
## 🗂️ Database Schema
|
|
|
|
### Core Tables:
|
|
- **Users**: Authentication and role management
|
|
- **Modules**: Available system modules
|
|
- **UserModules**: Per-user module access
|
|
- **CountSessions**: Count session metadata
|
|
- **BaselineInventory_Master**: Session-specific baseline (immutable)
|
|
- **BaselineInventory_Current**: Global refreshable baseline
|
|
- **LocationCounts**: Bin-by-bin progress tracking
|
|
- **ScanEntries**: Every lot scan with status tracking
|
|
- **MissingLots**: Expected lots not found after finalization
|
|
|
|
### Key Relationships:
|
|
- Users → UserModules → Modules (many-to-many)
|
|
- CountSessions → BaselineInventory_Master (one-to-many)
|
|
- CountSessions → LocationCounts → ScanEntries (hierarchical)
|
|
|
|
---
|
|
|
|
## 🔧 Technology Stack
|
|
|
|
- **Backend**: Python 3.13 + Flask
|
|
- **Database**: SQLite (auto-initializes on first run)
|
|
- **Frontend**: HTML5 + CSS3 + Vanilla JavaScript
|
|
- **Templates**: Jinja2
|
|
- **Icons**: Font Awesome 6.5
|
|
- **Deployment**: Docker (Linux)
|
|
|
|
---
|
|
|
|
## 📂 Project Structure
|
|
|
|
```
|
|
scanlook/
|
|
├── app.py # Main Flask application & routes
|
|
├── db.py # Database helper functions
|
|
├── utils.py # Decorators (login_required, role_required)
|
|
├── blueprints/
|
|
│ ├── counting.py # Counts module routes
|
|
│ ├── sessions.py # Session management routes
|
|
│ ├── users.py # User management routes
|
|
│ ├── data_imports.py # CSV upload routes
|
|
│ └── admin_locations.py # Admin location management
|
|
├── database/
|
|
│ ├── init_db.py # Database initialization & schema
|
|
│ └── scanlook.db # SQLite database (created at runtime)
|
|
├── static/
|
|
│ ├── css/
|
|
│ │ ├── style.css # Base/desktop styles
|
|
│ │ ├── mobile.css # Mobile overrides (360-767px)
|
|
│ │ └── scanner.css # MC9300 scanner overrides (<360px)
|
|
│ ├── js/
|
|
│ │ └── main.js # Client-side JavaScript
|
|
│ ├── manifest.json # PWA manifest
|
|
│ └── sw.js # Service worker
|
|
└── templates/
|
|
├── base.html # Base template with navbar
|
|
├── login.html # Login page
|
|
├── home.html # Module selection (landing page)
|
|
├── admin_dashboard.html
|
|
├── staff_dashboard.html
|
|
├── manage_users.html
|
|
├── create_session.html
|
|
├── session_detail.html
|
|
├── my_counts.html
|
|
└── count_location.html
|
|
```
|
|
|
|
---
|
|
|
|
## 🎨 Design Philosophy
|
|
|
|
**Desktop-First, Multi-Device Optimized:**
|
|
- High contrast dark theme for warehouse lighting
|
|
- Large touch targets (44px minimum)
|
|
- Autofocus on scan inputs
|
|
- Scanner trigger = Enter key
|
|
- Visual feedback with color-coded statuses
|
|
- Minimal typing required
|
|
|
|
**CSS Architecture:**
|
|
- `style.css` - Base/desktop styles (768px+)
|
|
- `mobile.css` - Phone overrides (360-767px)
|
|
- `scanner.css` - MC9300 scanner overrides (<360px)
|
|
|
|
**Color Coding:**
|
|
- ✅ Green (`--color-success`): Perfect match
|
|
- ⚠️ Yellow (`--color-warning`): Wrong location / Expected
|
|
- ❌ Red (`--color-danger`): Missing or ghost lot
|
|
- 🔵 Blue (`--color-duplicate`): Duplicate scan
|
|
- 🟠 Orange (`--color-orange`): Weight variance
|
|
|
|
---
|
|
|
|
## 🐳 Docker Deployment
|
|
|
|
```bash
|
|
# Build
|
|
docker build -t scanlook .
|
|
|
|
# Run (preserves database between updates)
|
|
docker run -d \
|
|
-p 5000:5000 \
|
|
-v /path/to/data:/app/database \
|
|
-e SCANLOOK_SECRET_KEY=your-secret-key \
|
|
scanlook
|
|
```
|
|
|
|
**Important:** Only `/app/database` is volume-mounted to preserve data between container updates.
|
|
|
|
---
|
|
|
|
## 🔐 Security Considerations
|
|
|
|
- Passwords hashed with Werkzeug
|
|
- Session management via Flask sessions
|
|
- SQL injection prevention (parameterized queries)
|
|
- Role-based access control
|
|
- Module-based access control with route guards
|
|
- Soft deletes preserve audit trail
|
|
|
|
---
|
|
|
|
## 🎯 Success Metrics
|
|
|
|
**Current State (Year-End Physical):**
|
|
- Duration: 5 days
|
|
- Data entry: Manual, error-prone
|
|
- Variance resolution: Weeks later
|
|
|
|
**Target State (with ScanLook):**
|
|
- Duration: 1 weekend (2 days max)
|
|
- Data entry: Zero (all scanned)
|
|
- Variance resolution: Real-time flagging
|
|
- Accuracy: 99%+ (no handwriting errors)
|
|
- Time savings: 60%+
|
|
|
|
---
|
|
|
|
## 💡 Future Enhancements
|
|
|
|
- Additional WMS modules (Shipping, Receiving, Transfers, Production)
|
|
- Multi-branch support
|
|
- Direct NetSuite API integration
|
|
- Photo capture for variance proof
|
|
- Barcode generation for location labels
|
|
- Native mobile apps
|
|
- Offline mode with sync
|
|
|
|
---
|
|
|
|
## 📝 Version History
|
|
|
|
- **v0.12.0** - Modular architecture with user-based module access
|
|
- **v0.11.x** - CSS refactoring, multi-device support, duplicate detection
|
|
- **v0.10.x** - Global CURRENT baseline, session archival
|
|
- **v0.9.x** - Core counting workflow, dual baseline system
|
|
|
|
---
|
|
|
|
## 🔧 Support
|
|
|
|
This is a custom internal tool. Contact your system administrator for support.
|
|
|
|
**Built with ❤️ for efficient inventory management**
|
|
|
|
*Inspired by BomLook from the FoxPro days* 🚀
|