quality_app-v2/documentation/WAREHOUSE_ROLES_AND_ACCESS_CONTROL.md

Warehouse Module: Roles, Access Control & Worker-Manager Binding

Executive Summary

This document proposes a comprehensive role-based access control (RBAC) system for the warehouse module, including:

1. New warehouse module roles (warehouse_manager, warehouse_worker)
2. Worker-Manager binding model for hierarchical access control
3. Granular access control rules differentiating manager vs worker capabilities
4. Database schema extensions to support these features

---

1. Current System Architecture

Existing Roles (in access_control.py)

ROLES = {
    'superadmin': Level 100 - Full system access (all modules)
    'admin': Level 90 - Administrative access (quality, settings)
    'manager': Level 70 - Full quality module access
    'worker': Level 50 - Limited quality inspections
}

Current Module Structure

• quality: Inspections + Reports
  • Workers can: View + Create inspections
  • Managers can: View, Create, Edit, Delete inspections + Export/Download reports
• settings: System configuration
  • Only superadmin/admin can access
• warehouse: NEW - Boxes management, locations, inventory

---

2. Proposed Warehouse Module Roles

2.1 New Roles for Warehouse Module

warehouse_manager (Level 75)

• Description: Full warehouse module access - manages operations, inventory, and reports
• Assigned Modules: ['quality', 'warehouse'] (if quality access granted)
• Page Access: ALL warehouse pages (input + report/analytics)
• Key Capabilities:
  • Set box locations (input pages)
  • Create/manage warehouse locations
  • View inventory reports and analytics
  • Export warehouse data
  • Download reports
  • Manage warehouse users/workers

warehouse_worker (Level 35)

• Description: Limited warehouse module access - can only input data, no reports
• Assigned Modules: ['warehouse']
• Page Access: INPUT PAGES ONLY
• Key Capabilities:
  • Set box locations
  • Create/update warehouse entries
  • View own submitted data
  • ✗ Cannot view reports
  • ✗ Cannot access analytics
  • ✗ Cannot export data
  • ✗ Cannot manage other users

---

3. Warehouse Module Page Structure

3.1 Input Pages (accessible to both manager & worker)

/warehouse/                              Dashboard/launcher
/warehouse/set-boxes-locations           Add/update box inventory
/warehouse/locations                     Create/manage location codes
/warehouse/set-boxes-locations           Quick entry form

3.2 Report/Analytics Pages (MANAGER ONLY)

/warehouse/reports                       Analytics & reports dashboard
/warehouse/reports/inventory-summary     Inventory overview
/warehouse/reports/location-usage        Location utilization stats
/warehouse/reports/stock-movements       Historical movements
/warehouse/reports/export                Data export interface
/warehouse/analytics/trends              Trend analysis

---

4. Worker-Manager Binding Model

4.1 Database Schema: worker_manager_bindings

CREATE TABLE worker_manager_bindings (
    id INT AUTO_INCREMENT PRIMARY KEY,
    manager_id INT NOT NULL,              -- warehouse_manager user ID
    worker_id INT NOT NULL,               -- warehouse_worker user ID
    warehouse_zone VARCHAR(100),          -- OPTIONAL: restrict worker to specific zone
    is_active TINYINT(1) DEFAULT 1,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    UNIQUE KEY unique_binding (manager_id, worker_id),
    FOREIGN KEY (manager_id) REFERENCES users(id) ON DELETE CASCADE,
    FOREIGN KEY (worker_id) REFERENCES users(id) ON DELETE CASCADE,
    CHECK (manager_id != worker_id)       -- Prevent self-binding
);

4.2 Binding Semantics

• One-to-Many Relationship: A manager can oversee multiple workers, but a worker is assigned to ONE primary manager
• Optional Zone Restriction: Workers can be confined to specific warehouse zones (e.g., "Zone A", "Cold Storage", "High Shelf")
• Hierarchy Enforcement:
  • Managers can only view/edit data from their assigned workers
  • Workers can only see their own data
  • Superadmin/admin can override and see everything

---

5. Access Control Rules (MODULE_PERMISSIONS)

5.1 Updated Structure for Warehouse Module

MODULE_PERMISSIONS = {
    'warehouse': {
        'name': 'Warehouse Module',
        'sections': {
            'input': {
                'name': 'Warehouse Data Input',
                'actions': {
                    'view': 'View warehouse input pages',
                    'create': 'Create warehouse entries',
                    'edit': 'Edit warehouse entries',
                    'delete': 'Delete warehouse entries'
                },
                'superadmin': ['view', 'create', 'edit', 'delete'],
                'admin': ['view', 'create', 'edit', 'delete'],
                'warehouse_manager': ['view', 'create', 'edit', 'delete'],
                'warehouse_worker': ['view', 'create', 'edit'],
                'manager': [],              # Quality managers don't auto-get warehouse access
                'worker': []
            },
            'reports': {
                'name': 'Warehouse Reports & Analytics',
                'actions': {
                    'view': 'View warehouse reports',
                    'export': 'Export warehouse data',
                    'download': 'Download reports',
                    'analytics': 'View analytics'
                },
                'superadmin': ['view', 'export', 'download', 'analytics'],
                'admin': ['view', 'export', 'download', 'analytics'],
                'warehouse_manager': ['view', 'export', 'download', 'analytics'],
                'warehouse_worker': [],     # Workers get NO report access
                'manager': [],
                'worker': []
            },
            'locations': {
                'name': 'Location Management',
                'actions': {
                    'view': 'View locations',
                    'create': 'Create locations',
                    'edit': 'Edit locations',
                    'delete': 'Delete locations'
                },
                'superadmin': ['view', 'create', 'edit', 'delete'],
                'admin': ['view', 'create', 'edit', 'delete'],
                'warehouse_manager': ['view', 'create', 'edit', 'delete'],
                'warehouse_worker': ['view'],  # Workers can only view existing locations
                'manager': [],
                'worker': []
            },
            'management': {
                'name': 'Warehouse User Management',
                'actions': {
                    'manage_workers': 'Manage assigned workers',
                    'manage_zones': 'Manage warehouse zones'
                },
                'superadmin': ['manage_workers', 'manage_zones'],
                'admin': ['manage_workers', 'manage_zones'],
                'warehouse_manager': ['manage_workers'],  # Can assign/manage workers
                'warehouse_worker': [],     # No management access
                'manager': [],
                'worker': []
            }
        }
    }
}

---

6. Implementation Details

6.1 Database Changes Required

1. Insert new roles into roles table:

   INSERT INTO roles (name, description, level) VALUES
   ('warehouse_manager', 'Warehouse Manager - Full warehouse module access', 75),
   ('warehouse_worker', 'Warehouse Worker - Input-only warehouse access', 35);
   

2. Create worker-manager binding table (see schema above)

3. Update user interface to assign warehouse roles

6.2 Code Changes

A. Update access_control.py

Add new roles:

ROLES = {
    # ... existing roles ...
    'warehouse_manager': {
        'name': 'Warehouse Manager',
        'description': 'Full access to warehouse module operations',
        'level': 75,
        'modules': ['warehouse']
    },
    'warehouse_worker': {
        'name': 'Warehouse Worker',
        'description': 'Limited warehouse access - input only, no reports',
        'level': 35,
        'modules': ['warehouse']
    }
}

Add warehouse module permissions (see 5.1 above)

B. Create route decorators

def can_access_warehouse_reports(f):
    """Only warehouse_manager, admin, superadmin can access reports"""
    @wraps(f)
    def decorated_function(*args, **kwargs):
        user_role = session.get('role', 'worker')
        if user_role not in ['superadmin', 'admin', 'warehouse_manager']:
            flash('Access denied: Only managers can view warehouse reports', 'error')
            return redirect(url_for('warehouse.warehouse_index'))
        return f(*args, **kwargs)
    return decorated_function

def can_access_warehouse_input(f):
    """warehouse_manager and warehouse_worker can access input pages"""
    @wraps(f)
    def decorated_function(*args, **kwargs):
        user_role = session.get('role', 'worker')
        if user_role not in ['superadmin', 'admin', 'warehouse_manager', 'warehouse_worker']:
            flash('Access denied: You do not have warehouse access', 'error')
            return redirect(url_for('main.dashboard'))
        return f(*args, **kwargs)
    return decorated_function

C. Worker data filtering

Workers should only see their own entries. Managers see all their workers' entries.

def get_worker_data_filter(user_id, user_role):
    """Get SQL WHERE clause based on role and worker-manager binding"""
    if user_role == 'superadmin' or user_role == 'admin':
        return ""  # No filter - see everything
    
    if user_role == 'warehouse_manager':
        # Get all workers assigned to this manager
        cursor = get_db().cursor()
        cursor.execute("""
            SELECT worker_id FROM worker_manager_bindings 
            WHERE manager_id = %s AND is_active = 1
        """, (user_id,))
        worker_ids = [row[0] for row in cursor.fetchall()]
        if worker_ids:
            return f"AND created_by_user_id IN ({','.join(map(str, worker_ids))})"
        return "AND created_by_user_id = %s" % user_id  # If no workers, see own data
    
    if user_role == 'warehouse_worker':
        return f"AND created_by_user_id = {user_id}"  # Only their own data
    
    return ""

---

7. User Interface Changes

7.1 User Creation/Edit Form (user_form.html)

Add warehouse role options to the role dropdown:

<!-- Existing roles -->
<option value="superadmin">Super Admin (Level 100)</option>
<option value="admin">Admin (Level 90)</option>
<option value="manager">Manager - Quality (Level 70)</option>
<option value="warehouse_manager">Manager - Warehouse (Level 75)</option>
<option value="worker">Worker - Quality (Level 50)</option>
<option value="warehouse_worker">Worker - Warehouse (Level 35)</option>

7.2 New Page: Warehouse Worker Assignment

Create /settings/warehouse-worker-assignment page:

• Managers can assign workers to themselves
• Shows assigned workers with zone restrictions
• Allows zone-specific filtering

---

8. Configuration in access_control.py

8.1 Complete Updated ROLES Dictionary

ROLES = {
    'superadmin': {
        'name': 'Super Administrator',
        'description': 'Full system access to all modules and features',
        'level': 100,
        'modules': ['quality', 'settings', 'warehouse']
    },
    'admin': {
        'name': 'Administrator',
        'description': 'Administrative access - can manage users and system configuration',
        'level': 90,
        'modules': ['quality', 'settings', 'warehouse']
    },
    'manager': {
        'name': 'Manager - Quality',
        'description': 'Full access to quality module and quality control',
        'level': 70,
        'modules': ['quality']
    },
    'warehouse_manager': {
        'name': 'Manager - Warehouse',
        'description': 'Full access to warehouse module - input and reports',
        'level': 75,
        'modules': ['warehouse']
    },
    'worker': {
        'name': 'Worker - Quality',
        'description': 'Limited access to quality inspections - input only',
        'level': 50,
        'modules': ['quality']
    },
    'warehouse_worker': {
        'name': 'Worker - Warehouse',
        'description': 'Limited access to warehouse - input pages only, no reports',
        'level': 35,
        'modules': ['warehouse']
    }
}

---

9. Page Access Matrix

Page	superadmin	admin	manager (quality)	warehouse_manager	worker (quality)	warehouse_worker
/warehouse/	✓	✓	✗	✓	✗	✓
/warehouse/set-boxes-locations	✓	✓	✗	✓	✗	✓
/warehouse/locations	✓	✓	✗	✓	✗	✓
/warehouse/reports	✓	✓	✗	✓	✗	✗
/warehouse/reports/inventory-summary	✓	✓	✗	✓	✗	✗
/warehouse/analytics/trends	✓	✓	✗	✓	✗	✗

---

10. Implementation Roadmap

Phase 1: Database & Backend (Priority: HIGH)

1. Add new roles to database (warehouse_manager, warehouse_worker)
2. Create worker_manager_bindings table
3. Update access_control.py with new ROLES and MODULE_PERMISSIONS
4. Create access check decorators
5. Add data filtering logic in warehouse routes

Phase 2: User Interface (Priority: MEDIUM)

1. Update user_form.html with warehouse role options
2. Create warehouse worker assignment page
3. Add worker-manager binding UI

Phase 3: Warehouse Route Protection (Priority: HIGH)

1. Add decorators to report routes
2. Add decorators to input routes
3. Implement data filtering for workers

Phase 4: Testing & Validation (Priority: HIGH)

1. Test manager access to all pages
2. Test worker access (should block reports)
3. Test superadmin/admin override
4. Test worker-manager binding enforcement

---

11. Security Considerations

11.1 Data Isolation

• Workers MUST NOT see other workers' data
• Workers MUST NOT see any warehouse reports
• Managers see ONLY their assigned workers' data
• Database queries MUST include proper WHERE clauses

11.2 Role Verification

• Always verify role in routes, not just in UI
• Use decorators on ALL sensitive routes
• Log access attempts to reports (audit trail)

11.3 Cross-Module Access

• Quality managers (role='manager') should NOT auto-get warehouse access
• Warehouse staff should NOT auto-get quality access
• Explicitly assign roles per module

---

12. Example SQL Queries

12.1 Create New Roles

INSERT INTO roles (name, description, level) VALUES
('warehouse_manager', 'Warehouse Manager - Full warehouse module access', 75),
('warehouse_worker', 'Warehouse Worker - Input-only warehouse access', 35);

12.2 Create Worker-Manager Binding Table

CREATE TABLE IF NOT EXISTS worker_manager_bindings (
    id INT AUTO_INCREMENT PRIMARY KEY,
    manager_id INT NOT NULL,
    worker_id INT NOT NULL,
    warehouse_zone VARCHAR(100),
    is_active TINYINT(1) DEFAULT 1,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    UNIQUE KEY unique_binding (manager_id, worker_id),
    FOREIGN KEY (manager_id) REFERENCES users(id) ON DELETE CASCADE,
    FOREIGN KEY (worker_id) REFERENCES users(id) ON DELETE CASCADE,
    CHECK (manager_id != worker_id)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;

12.3 Assign Worker to Manager

INSERT INTO worker_manager_bindings (manager_id, worker_id, warehouse_zone)
VALUES (5, 12, NULL);  -- Manager ID 5 oversees Worker ID 12, all zones

12.4 Get All Workers for a Manager

SELECT u.id, u.username, u.full_name, wmb.warehouse_zone
FROM worker_manager_bindings wmb
JOIN users u ON wmb.worker_id = u.id
WHERE wmb.manager_id = ? AND wmb.is_active = 1
ORDER BY u.full_name;

---

13. Summary Table

Feature	Current	Proposed
Warehouse roles	None	2 new roles
Role levels	4 (super, admin, manager, worker)	6 (+ warehouse_manager, warehouse_worker)
Access control granularity	By role	By role + worker-manager binding
Worker data isolation	N/A	Full isolation by worker ID
Report access	By role	Managers only
Zone restrictions	None	Optional per binding
Database tables	0 warehouse-specific	1 new table (worker_manager_bindings)

---

14. Benefits of This Model

✅ Clear Role Hierarchy: Seven distinct roles with clear separation of concerns
✅ Worker Data Privacy: Workers only see their own entries, no cross-worker visibility
✅ Manager Oversight: Managers see all their workers' data for supervision
✅ Scalability: Supports many workers per manager without access conflicts
✅ Compliance: Easily auditable access patterns for compliance/security
✅ Flexibility: Zone restrictions enable specialized warehouse areas
✅ Backward Compatibility: Existing quality roles remain unchanged

---

Next Steps

Would you like me to implement:

1. Database schema changes?
2. Updates to access_control.py?
3. Warehouse route protections?
4. User interface updates?
5. All of the above?

Please confirm and I'll proceed with implementation.