Initial V1 Backup
This commit is contained in:
Javier
337
README.md
Normal file
337
README.md
Normal file
@@ -0,0 +1,337 @@
|
||||
# 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* 🚀
|
||||
Reference in New Issue
Block a user