338 lines
8.3 KiB
Markdown
338 lines
8.3 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 /home/claude/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 Android 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)
|
|
|
|
---
|
|
|
|
## 👥 User Roles
|
|
|
|
### Owner (Level 1)
|
|
- Super admin privileges
|
|
- Manage all admins
|
|
- 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
|
|
|
|
### Staff/Counter (Level 3)
|
|
- Select active count session
|
|
- Scan locations and lots
|
|
- Enter weights
|
|
- Edit/delete their own scans
|
|
- View their progress
|
|
|
|
---
|
|
|
|
## 🔄 Core Workflow
|
|
|
|
### Phase 1: Session Setup (Admin)
|
|
|
|
1. **Log in as admin**
|
|
2. **Create new count session**:
|
|
- Session name: "January 17, 2026 - Daily Cycle Count"
|
|
- Type: Cycle Count OR Full Physical Inventory
|
|
3. **Upload MASTER baseline** CSV from NetSuite:
|
|
- Format: `Item, Description, Lot Number, Location, Bin Number, On Hand`
|
|
- Creates baseline version 1
|
|
4. Session status: **Active**
|
|
5. Counters can now begin
|
|
|
|
### Phase 2: Counting (Staff)
|
|
|
|
1. **Log in as staff**
|
|
2. **Select active session**
|
|
3. **Scan location barcode** (e.g., R903B)
|
|
- System marks location "in progress"
|
|
- Shows: "Counting R903B"
|
|
4. **Scan lot barcode**
|
|
5. 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
|
|
6. **Enter weight**
|
|
7. Save → returns to scan input (autofocus)
|
|
8. Repeat for all lots in location
|
|
9. Click **"Finish Location"**
|
|
|
|
### 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**:
|
|
- Admin can refresh unlimited times
|
|
- 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
|
|
|
|
### Blind Counting
|
|
|
|
- Counters don't see expected quantities
|
|
- Prevents bias
|
|
- Ensures honest count
|
|
|
|
### Real-Time Dashboard
|
|
|
|
- Active counters with current location
|
|
- Progress by location
|
|
- 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
|
|
- Baseline version tracking
|
|
|
|
---
|
|
|
|
## 🗂️ Database Schema
|
|
|
|
### Tables:
|
|
- **Users**: Authentication and role management
|
|
- **CountSessions**: Count session metadata
|
|
- **BaselineInventory_Master**: Morning baseline (never changes)
|
|
- **BaselineInventory_Current**: Refreshable baseline (soft delete)
|
|
- **LocationCounts**: Location-by-location progress
|
|
- **ScanEntries**: Every lot scan with dual status tracking
|
|
- **MissingLots**: Expected lots not found
|
|
|
|
### Indexes:
|
|
Optimized for fast lookups on lot numbers, locations, and statuses.
|
|
|
|
---
|
|
|
|
## 🔧 Technology Stack
|
|
|
|
- **Backend**: Python 3.13 + Flask
|
|
- **Database**: SQLite
|
|
- **Frontend**: HTML5 + CSS3 + Vanilla JavaScript
|
|
- **Templates**: Jinja2
|
|
|
|
---
|
|
|
|
## 📂 Project Structure
|
|
|
|
```
|
|
scanlook/
|
|
├── app.py # Main Flask application
|
|
├── database/
|
|
│ ├── init_db.py # Database initialization
|
|
│ └── scanlook.db # SQLite database (created)
|
|
├── static/
|
|
│ ├── css/
|
|
│ │ └── style.css # Main stylesheet
|
|
│ └── js/
|
|
│ └── main.js # Client-side JavaScript
|
|
└── templates/
|
|
├── base.html # Base template
|
|
├── login.html # Login page
|
|
├── admin_dashboard.html
|
|
├── staff_dashboard.html
|
|
├── create_session.html
|
|
├── session_detail.html
|
|
├── count_session.html
|
|
└── count_location.html
|
|
```
|
|
|
|
---
|
|
|
|
## 🎨 Design Philosophy
|
|
|
|
**Mobile-First, Warehouse-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
|
|
|
|
**Color Coding:**
|
|
- ✅ Green: Perfect match
|
|
- ⚠️ Yellow: Wrong location
|
|
- ❌ Red: Missing or ghost lot
|
|
- 🔵 Blue: Weight variance
|
|
|
|
---
|
|
|
|
## 🚧 Current Status: Phase 1 Complete (MVP)
|
|
|
|
### ✅ Implemented:
|
|
- User authentication (3 roles)
|
|
- Session creation
|
|
- MASTER baseline upload
|
|
- Location scanning
|
|
- Lot scanning with MASTER status
|
|
- Weight entry
|
|
- Basic dashboard
|
|
- Real-time progress tracking
|
|
- Mobile-optimized UI
|
|
|
|
### 🔜 Next Phases:
|
|
- **Phase 2**: CURRENT baseline refresh & dual status recalculation
|
|
- **Phase 3**: Missing lot detection, enhanced dashboard
|
|
- **Phase 4**: Excel export with multiple tabs
|
|
- **Phase 5**: Data retention automation, user management
|
|
- **Phase 6**: Docker deployment
|
|
|
|
---
|
|
|
|
## 📝 Development Notes
|
|
|
|
### Default Accounts (Testing)
|
|
All passwords should be changed in production!
|
|
|
|
### Security Considerations
|
|
- Passwords are hashed with Werkzeug
|
|
- Session management via Flask sessions
|
|
- SQL injection prevention (parameterized queries)
|
|
- Soft deletes preserve audit trail
|
|
|
|
### Data Retention
|
|
- Plan: Keep data for 30 days
|
|
- Nightly cleanup job (to be implemented)
|
|
- Archive old sessions
|
|
|
|
---
|
|
|
|
## 🎯 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
|
|
|
|
- Multi-branch support
|
|
- Direct NetSuite API integration
|
|
- Photo capture for variance proof
|
|
- Barcode generation for location labels
|
|
- Native mobile apps
|
|
- Offline mode with sync
|
|
|
|
---
|
|
|
|
## 📧 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* 🚀
|