quality_app-v2/documentation/WORKER_MANAGER_BINDING_MODEL.md

Worker-Manager Binding Model: Visual Guide

Hierarchical Structure

┌─────────────────────────────────────────────────────────────────┐
│                      SUPERADMIN / ADMIN                         │
│              (Unrestricted access to everything)                │
│  - Can view all warehouse data                                  │
│  - Can override all restrictions                                │
│  - Can manage all users and bindings                            │
└────────────────────────┬────────────────────────────────────────┘

                         │
        ┌────────────────┴────────────────┐
        │                                 │
┌───────▼──────────────┐         ┌───────▼──────────────┐
│ WAREHOUSE_MANAGER #1 │         │ WAREHOUSE_MANAGER #2 │
│  - Full access to    │         │  - Full access to    │
│    input pages       │         │    input pages       │
│  - Full access to    │         │  - Full access to    │
│    reports/analytics │         │    reports/analytics │
│  - Can manage        │         │  - Can manage        │
│    assigned workers  │         │    assigned workers  │
└────────┬─────────────┘         └────────┬─────────────┘
         │                                │
    ┌────┴─────────┬──────────┐          │
    │              │          │          │
┌───▼─────┐   ┌───▼─────┐  ┌─▼──────┐   │
│ WORKER1 │   │ WORKER2 │  │WORKER3 │   │
│ (Mgr 1) │   │ (Mgr 1) │  │(Mgr 2) │   │
│         │   │         │  │        │   │
│ Can:    │   │ Can:    │  │ Can:   │   │
│ ✓ Input │   │ ✓ Input │  │✓ Input │   │
│ ✗ Report│   │ ✗ Report│  │✗ Report│   │
│ ✗ Manage│   │ ✗ Manage│  │✗ Manage│   │
└─────────┘   └─────────┘  └────────┘   │
                                        │
                            Unassigned workers
                            (can't access warehouse)

---

Data Access Patterns

SUPERADMIN/ADMIN View

┌─────────────────────────────────────────┐
│         ALL WAREHOUSE DATA              │
│  ├─ All workers' entries                │
│  ├─ All managers' entries               │
│  ├─ All reports                         │
│  └─ All analytics                       │
└─────────────────────────────────────────┘

WAREHOUSE_MANAGER View

┌─────────────────────────────────────────┐
│    MANAGER'S ASSIGNED DATA ONLY         │
│  ├─ Manager's own entries               │
│  ├─ Assigned Worker 1's entries         │
│  ├─ Assigned Worker 2's entries         │
│  ├─ Reports (aggregated from own + workers)
│  └─ Analytics (own + workers' data)     │
└─────────────────────────────────────────┘

WAREHOUSE_WORKER View

┌─────────────────────────────────────────┐
│      WORKER'S OWN DATA ONLY             │
│  ├─ Own entries                         │
│  ├─ Own location assignments            │
│  └─ Own submitted records               │
│                                         │
│  ✗ Cannot see other workers' data      │
│  ✗ Cannot view any reports             │
│  ✗ Cannot access analytics             │
└─────────────────────────────────────────┘

---

Role Hierarchy & Capabilities

Level 100: SUPERADMIN
├─ Can do EVERYTHING
├─ Can override all restrictions
└─ Can manage all users & roles

Level 90: ADMIN
├─ Can do EVERYTHING (in practice)
├─ Can override all restrictions
└─ Can manage all users & roles

Level 75: WAREHOUSE_MANAGER
├─ Can access warehouse INPUT pages
│  ├─ Set box locations
│  ├─ Manage inventory entries
│  └─ Create/edit warehouse data
├─ Can access warehouse REPORTS
│  ├─ View analytics
│  ├─ Export data
│  └─ Download reports
├─ Can manage assigned workers
│  ├─ Assign/unassign workers
│  ├─ Set zone restrictions
│  └─ View worker activity logs
└─ Can view assigned workers' data

Level 70: MANAGER (Quality)
├─ Can access QUALITY module only
├─ Can create/edit/delete inspections
├─ Can export quality reports
└─ Cannot access WAREHOUSE at all

Level 50: WORKER (Quality)
├─ Can access QUALITY module only
├─ Can create quality inspections
├─ Can view inspections
└─ Cannot export or access reports

Level 35: WAREHOUSE_WORKER
├─ Can access INPUT pages ONLY
│  ├─ Set box locations
│  ├─ Create entries
│  └─ Edit own entries
├─ Cannot view reports
├─ Cannot view analytics
├─ Cannot export data
└─ Can only see own submitted data

---

Database Schema Visualization

┌──────────────────────────┐
│       USERS TABLE        │
├──────────────────────────┤
│ id                       │
│ username                 │
│ password_hash            │
│ full_name                │
│ email                    │
│ role    ◄────────┐       │
│ is_active        │       │
│ created_at       │       │
└──────────────────┼───────┘
                   │
        References │
                   │
        ┌──────────┴────────────────────────┐
        │                                   │
        ▼                                   ▼
┌──────────────────────┐          ┌──────────────────────┐
│   ROLES TABLE        │          │  USER_MODULES TABLE  │
├──────────────────────┤          ├──────────────────────┤
│ id                   │          │ id                   │
│ name                 │          │ user_id ───┐        │
│ description          │          │ module_name│        │
│ level                │          │ created_at │        │
│ created_at           │          └────────────┼────────┘
└──────────────────────┘                      │
                                              │
                                    ┌─────────▼────────────────┐
                                    │                          │
                                    ▼                          ▼
                        ┌──────────────────────┐   ┌──────────────────────┐
                        │ WAREHOUSE_MANAGER    │   │  WAREHOUSE_WORKER    │
                        │ role_id: 75          │   │  role_id: 35         │
                        └──────────────────────┘   └──────────────────────┘
                                    │                          │
                                    └──────────┬───────────────┘
                                               │
                        ┌──────────────────────▼──────────────┐
                        │ WORKER_MANAGER_BINDINGS TABLE       │
                        ├─────────────────────────────────────┤
                        │ id                                  │
                        │ manager_id ──────┐ (Foreign Key)   │
                        │ worker_id ────────┼─ (Foreign Key)  │
                        │ warehouse_zone    │ (Optional)      │
                        │ is_active         │ (TINYINT)       │
                        │ created_at        │                 │
                        │ updated_at        │                 │
                        └─────────────────────────────────────┘
                                    │
                                    │ One binding allows:
                                    ├─ Manager to oversee Worker
                                    ├─ Worker to input data
                                    ├─ Manager to view Worker's data
                                    └─ Optional: Restrict to specific zone

---

Example Bindings

Scenario 1: Single Manager, Multiple Workers

Manager: John Smith (ID=5, role=warehouse_manager)
Workers: 
  - Alice Johnson (ID=12, role=warehouse_worker)
  - Bob Wilson (ID=13, role=warehouse_worker)
  - Carol Davis (ID=14, role=warehouse_worker)

Bindings:
  binding_1: manager_id=5, worker_id=12, zone=NULL  (all zones)
  binding_2: manager_id=5, worker_id=13, zone=NULL  (all zones)
  binding_3: manager_id=5, worker_id=14, zone=NULL  (all zones)

Result:
  ✓ John can see data from Alice, Bob, and Carol
  ✓ John can generate reports using all their data
  ✓ Alice/Bob/Carol can only see their own data
  ✓ Alice/Bob/Carol cannot see reports

Scenario 2: Zone-Restricted Workers

Manager: Maria Garcia (ID=6, role=warehouse_manager)
Workers (restricted to zones):
  - David Chen (ID=15, zone="Cold Storage")
  - Eve Martinez (ID=16, zone="High Shelf")

Bindings:
  binding_4: manager_id=6, worker_id=15, zone="Cold Storage"
  binding_5: manager_id=6, worker_id=16, zone="High Shelf"

Result:
  ✓ David can only input in "Cold Storage"
  ✓ Eve can only input in "High Shelf"
  ✓ Maria can filter reports by zone
  ✓ Maria can see which worker handles which zone

Scenario 3: Unassigned Worker

Worker: Frank Thompson (ID=17, role=warehouse_worker)
No binding exists for Frank

Result:
  ✗ Frank cannot access warehouse module
  ✗ Frank's dashboard shows no warehouse option
  ✗ If Frank tries to access /warehouse/*:
    - Gets redirected with "Access denied" message

---

Access Control Decision Tree

User Request → Is user logged in?
              │
              ├─ NO  → Redirect to login
              │
              └─ YES → Get user role
                     │
                     ├─ Is role = 'superadmin'?
                     │  ├─ YES → ALLOW (all access)
                     │  └─ NO  → Continue
                     │
                     ├─ Is role = 'admin'?
                     │  ├─ YES → ALLOW (all access)
                     │  └─ NO  → Continue
                     │
                     ├─ Is user accessing report page?
                     │  ├─ YES → Is role = 'warehouse_manager'?
                     │  │      ├─ YES → ALLOW
                     │  │      └─ NO  → DENY
                     │  │
                     │  └─ NO  → Is user accessing input page?
                     │           ├─ YES → Is role = 'warehouse_manager' OR 'warehouse_worker'?
                     │           │       ├─ YES → Check binding (for worker)
                     │           │       │       ├─ If manager → ALLOW
                     │           │       │       └─ If worker → ALLOW (sees own data only)
                     │           │       └─ NO  → DENY
                     │           │
                     │           └─ NO  → Other page type
                     │                   └─ DENY (unknown page type)
                     │
                     └─ DENY (role not recognized for warehouse)

---

Implementation Checklist

Database Changes

• Insert 2 new roles into roles table
• Create worker_manager_bindings table
• Verify foreign key constraints work
• Test data isolation queries

Backend Code

• Update access_control.py ROLES dictionary
• Update access_control.py MODULE_PERMISSIONS
• Create can_access_warehouse_reports() decorator
• Create can_access_warehouse_input() decorator
• Update warehouse route handlers with decorators
• Implement data filtering logic in queries
• Add binding validation logic

Frontend Code

• Update user_form.html with warehouse role options
• Create warehouse worker assignment page
• Add worker management UI in warehouse module
• Update dashboard to show warehouse module for eligible users

Testing

• Test superadmin access (full access)
• Test admin access (full access)
• Test warehouse_manager access (input + reports)
• Test warehouse_worker access (input only, blocked from reports)
• Test data isolation (worker A cannot see worker B's data)
• Test manager sees assigned workers' data only
• Test zone restriction filtering
• Test unassigned worker cannot access warehouse

---

Security Notes

⚠️ Critical Points

• Always verify user role in EVERY warehouse route
• Always include WHERE clauses to filter data by user/binding
• Never trust frontend filtering alone
• Log all access to reports for audit trail
• Validate zone restrictions server-side
• Regularly audit worker-manager bindings

⚠️ Data Isolation

• Workers MUST be completely isolated from each other
• Managers MUST only see assigned workers' data
• Database queries must reflect this isolation
• Test edge cases (deleted bindings, zone changes, etc.)

⚠️ Role Confusion Prevention

• Quality roles and warehouse roles are SEPARATE
• Explicitly assign each module
• Don't auto-grant cross-module access
• Always check module assignment + permission