QM Zones

🎯 Overview

The QM (Quality Management) Module serves as the central quality control hub for monitoring and managing scan position accuracy and zone-level quality metrics. This comprehensive system provides real-time quality threshold monitoring, automated rule evaluation, and structured approval workflows. The module integrates seamlessly with the scanning system to ensure data quality and operational excellence through continuous monitoring and management oversight.

The QM Module operates with two integrated components accessible through a unified interface:

• 🔍 QM Scans: Individual scan position quality control and verification management
• 🏢 QM Zones: Zone-level quality oversight and compliance monitoring

🔐 Access Requirements

👥 Required Roles & Permissions

• Team Admin: roles.system.teamAdmin
• User Admin: roles.system.userAdmin
• System Admin: roles.system.admin
• Super Admin: roles.system.superAdmin
• Team Manager: roles.project.teamManager
• Area Manager: roles.project.areaManager

🌐 Permission Scope

• Project-Based: Access limited to assigned projects
• Role-Hierarchical: Higher roles have broader access
• Active Project Requirement: Operations require project to be in "running" state

💻 QM Module Interface Layout

🎛️ Module Control Panel

┌─────────────────────────────────────────────────────────────┐
│ � QM Module                                               │
├─────────────────────────────────────────────────────────────┤
│ �🔄 Last updated: Nov 3, 2025 14:30    [🔄 Refresh]        │
├─────────────────────────────────────────────────────────────┤
│ 🟦 Info  🟡 Notify  🔴 Warning  ←— Quality Status Legend   │
├─────────────────────────────────────────────────────────────┤
│ 📊 QM Synchronization Status:                              │
│ ⚠️  There was a change to threshold limits                 │
│ [🔄 Sync Settings] ←— Synchronize quality rule changes    │
├─────────────────────────────────────────────────────────────┤
│ 📋 Navigation: [🔍 QM Scans] [🏢 QM Zones]                │
│ 📂 View Modes: [📊 Unapproved] [✅ Approved]              │
└─────────────────────────────────────────────────────────────┘

� Job Status Indicators

• ⏸️ Paused: Quality rules changed, synchronization required
• ✅ Ready: Job queued for processing
• 🔄 Running: Active synchronization with progress percentage
• ❌ Failed: Error occurred, check logs for details

🔍 QM Scans Component

The QM Scans section provides detailed quality control for individual scan positions, allowing managers to review, verify, and approve scan accuracy at the most granular level.

�📊 QM Scans Table Interface

🔍 QM Scans Table                               [🔍 Show/Hide Filters]
┌─────────────────────────────────────────────────────────────┐
│ Zone | Status | Position | Barcode | Rules | Verify | Action │
├──────┼────────┼──────────┼─────────┼───────┼────────┼────────┤
│ ▼ A1 │ 🟢 Active │   Group   │ABC123   │ ⚠️ 85% │   ✅   │[Verify]│
│   │  │        │    1-5    │        │       │        │[Approve]│
│   ├──┼────────┼──────────┼─────────┼───────┼────────┼────────┤
│   │  │ 🟢 Active │    1     │ABC123   │ ⚠️ 85% │   ✅   │[History]│
│   │  │        │          │Product1 │ 🟡 92% │        │[Approve]│
│   │  │        │          │        │       │        │        │
│   ├──┼────────┼──────────┼─────────┼───────┼────────┼────────┤
│   │  │ 🟢 Active │    2     │DEF456   │ 🔴 78% │   ❌   │[History]│
│   │  │        │          │Product2 │ ⚠️ 88% │        │[Approve]│
└─────┴────────┴──────────┴─────────┴───────┴────────┴────────┘
📄 Page 1 of 5 | 📊 50 total scans

⭐ QM Scans Features

• Position-Level Quality Control: Monitor individual scan positions with detailed metrics
• Grouped Scan Handling: Manage multiple scans per position with expandable group views
• Verification Tracking: Track manual verification status for each scan position
• Approval Workflow: Manager-level approval process with revision history
• Threshold Monitoring: Real-time quality rule evaluation with color-coded indicators

🏢 QM Zones Component

The QM Zones section provides zone-level quality oversight, offering aggregated quality metrics and management controls for entire operational zones.

🏢 QM Zones Table Interface

🔍 QM Zones Table                               [🔍 Show/Hide Filters]
┌─────────────────────────────────────────────────────────────┐
│ Zone Code | Zone Status | Rule 1 | Rule 2 | Timestamp | Action │
├───────────┼─────────────┼────────┼────────┼───────────┼────────┤
│    A1     │ 🟢 Active    │ ⚠️ 85%  │ 🟡 92% │ 14:30     │[History]│
│           │             │        │        │ Nov 3     │[Approve]│
├───────────┼─────────────┼────────┼────────┼───────────┼────────┤
│    B2     │ 🔴 Critical  │ 🔴 65%  │ ⚠️ 80% │ 14:25     │[History]│
│           │             │        │        │ Nov 3     │[Approve]│
├───────────┼─────────────┼────────┼────────┼───────────┼────────┤
│    C3     │ 🟢 Active    │ ✅ 98%  │ ✅ 95% │ 14:20     │[History]│
│           │ (Approved)  │        │        │ Nov 3     │[Unapprove]│
└───────────┴─────────────┴────────┴────────┴───────────┴────────┘
📄 Page 1 of 3 | 📊 15 total zones

⭐ QM Zones Features

• Zone-Level Quality Overview: Aggregate quality metrics per zone with comprehensive reporting
• Status Monitoring: Track zone operational status with real-time updates
• Threshold Compliance: Zone-wide quality rule compliance monitoring
• Approval Management: Zone approval/unapproval workflows with manager oversight

⭐ Core QM Module Features

📊 Quality Rules Engine

• Configurable Thresholds: Customizable quality rules with flexible parameters
• Multi-Level Alerts: Info (🟦), Notify (🟡), Warning (🔴) level classifications
• Real-time Evaluation: Continuous quality monitoring with automated assessments
• Rule Change Tracking: Complete audit trail for rule modifications and updates

🔄 Synchronization System

• Background Jobs: Automated quality data processing with job queue management
• Progress Tracking: Real-time job progress monitoring with percentage completion
• Error Handling: Comprehensive error reporting with detailed failure logs
• Manual Sync: On-demand data synchronization with refresh capabilities

🎯 Integrated Workflow Management

• Unified Interface: Single entry point for both scan and zone quality management
• Cross-Component Navigation: Seamless switching between scans and zones views
• Consistent Approval Process: Standardized approval workflows across components
• Centralized Status Monitoring: Single dashboard for all quality operations

📘 QM Module Usage Guide

� Getting Started

1. Navigate to QM Module via main navigation menu
2. Check Sync Status in the control panel header
3. Select Component: Choose between QM Scans or QM Zones
4. Choose View Mode: Switch between "Unapproved" and "Approved" tabs
5. Apply Filters: Use filter controls to narrow down results
6. Monitor Indicators: Review quality thresholds and alert levels

� Managing QM Synchronization

1. Monitor Sync Status:

   • ⏸️ Paused: Quality rules have changed, synchronization required
   • ✅ Ready: Job is queued and waiting for processing
   • 🔄 Running: Active synchronization with progress percentage
   • ❌ Failed: Error occurred, check error details in tooltip

2. Synchronize Quality Data:

   � Click "Sync Settings" when status shows paused
   📊 Monitor progress percentage during synchronization
   ✅ Wait for completion before performing quality operations
   🔄 Use "Refresh" button to manually update displayed data

🔍 Working with QM Scans

1. Review Scan Quality:

   📊 Navigate to QM Scans component
   🔍 Apply filters by zone, status, verification state
   📋 Review quality rule violations and threshold levels
   ⚠️ Identify scans requiring attention (warning/notify levels)

2. Approve Scan Positions:

   ✅ Individual Approval: Click [Approve] for single scan positions
   📋 Grouped Approval: Approve all scans within a position group
   🔄 Bulk Operations: Select multiple positions for batch approval
   📝 Review approval confirmation dialogs before proceeding

3. Verify Scan Sessions:

   ✅ Single Verification: Click [Verify] for individual zones
   📋 Open Verify Session: Launch verification workflow for zone
   ⚠️ Confirm Verification: Review and confirm verification requirements
   📊 Track verification status in verify status column

4. View Scan History:

   📚 Click [History] button for detailed scan revision history
   👤 Review approval/unapproval actions and responsible users
   📅 Check timestamps for quality changes and approvals
   🔄 Track quality trend over time

🏢 Working with QM Zones

1. Monitor Zone Quality:

   📊 Navigate to QM Zones component
   🎯 Review zone-level quality metrics and rule compliance
   📈 Monitor quality trends and threshold violations
   🏢 Check zone operational status indicators

2. Approve/Unapprove Zones:

   ✅ Zone Approval: Click [Approve] for zones meeting quality standards
   ❌ Zone Unapproval: Click [Unapprove] to flag quality concerns
   📋 Bulk Operations: Process multiple zones simultaneously
   ⚠️ Confirm actions through approval confirmation dialogs

3. Review Zone History:

   � Click [History] button for zone quality history
   � Review manager approvals and quality decisions
   📊 Track zone quality performance over time
   🔄 Analyze quality improvement or degradation patterns

📊 Understanding QM Module Indicators

• 🟦 Info: Informational threshold (95-100%) - Excellent quality
• 🟡 Notify: Warning threshold (85-94%) - Attention recommended
• 🔴 Warning: Critical threshold (below 85%) - Immediate action required
• ✅ Verified: Scan has been manually verified by operator
• ❌ Unverified: Scan requires manual verification
• 🎯 Approved: Quality approved by manager/supervisor
• ⚠️ Unapproved: Requires quality review and approval
• 🔄 Grouped: Multiple scans grouped by position (expandable)
• 📚 History: Revision history available for review

⚠️ QM Module Troubleshooting

🚫 Common QM Module Issues

❌ "Project not active" Error

• ✅ Check Project State: Ensure project is in "running" status
• ✅ Verify Project Status: Confirm project is not paused or closed
• ✅ Contact Admin: Request project reactivation if needed
• ✅ Project Permissions: Verify access to project settings

❌ "Permission denied" Error

• ✅ Role Verification: Confirm adequate role assignment (Team/Area Manager minimum)
• ✅ Project Membership: Verify membership in target project
• ✅ Role Hierarchy: Check if role level meets QM module requirements
• ✅ Admin Contact: Request role upgrade through system administrator

❌ "QM Synchronization job failed" Status

• ✅ Check Error Details: Review error tooltip for specific failure reason
• ✅ Data Validation: Ensure scan/zone data integrity in source systems
• ✅ Retry Synchronization: Attempt synchronization restart
• ✅ Resource Check: Verify server resources and database connectivity
• ✅ System Admin: Contact administrator for persistent failures

❌ "Unapprove not available" Message

• ✅ Approval Source: Only manually approved items can be unapproved
• ✅ System Approvals: Automated system approvals cannot be manually reverted
• ✅ Check History: Review approval history to understand approval source
• ✅ Alternative Actions: Consider re-running quality evaluation if needed

❌ "No data available" Empty States

• ✅ Synchronization Status: Ensure QM synchronization has completed successfully
• ✅ Filter Settings: Clear all filters to show complete dataset
• ✅ Time Range: Check if quality data exists for current time period
• ✅ Source Data: Verify scans/zones exist in project and are properly configured
• ✅ Refresh Data: Use refresh button to reload latest data

📱 Mobile/Responsive QM Module Usage

• Expandable Groups: Touch to expand/collapse scan position groups
• Horizontal Scrolling: Swipe horizontally to view all table columns
• Filter Controls: Filter panel may collapse on smaller screens
• Touch Actions: All buttons and controls optimized for touch interaction
• Component Switching: Easy navigation between Scans and Zones on mobile

🔄 QM Module Performance Optimization

• Filtered Views: Use specific filters to limit large datasets for better performance
• Pagination: Navigate through data in manageable chunks rather than loading all
• Targeted Refresh: Refresh specific components rather than entire module
• Background Sync: Allow automatic synchronization to complete before manual operations
• Cache Management: Clear browser cache if data appears outdated

🛠️ QM Module Technical Details

🏗️ QM Module Architecture

The QM Module operates as an integrated system with shared infrastructure and specialized components:

// QM Module Structure
{
  controlPanel: {
    synchronizationStatus: "running|paused|ready|failed",
    lastUpdated: Date,
    progressPercentage: Number,
    refreshCapability: Boolean
  },
  components: {
    qmScans: { /* scan-specific functionality */ },
    qmZones: { /* zone-specific functionality */ }
  },
  sharedServices: {
    qualityRulesEngine: { /* threshold evaluation */ },
    approvalWorkflow: { /* approval management */ },
    synchronizationJob: { /* background processing */ }
  }
}

📊 QM Scans Data Structure

// QM Scan Record
{
  _id: "qmScan123",
  scan: {
    scanId: "scan456",
    projectId: "project789",
    zoneId: "zone123",
    position: 1,
    barcode: "ABC123",
    description: "Product Name",
    isVerified: true
  },
  rule: {
    ruleId: "rule456",
    value: 85.5,
    level: "warning", // info, notify, warning
    lastRun: new Date(),
    approved: false,
    ruleChange: "threshold_modified"
  },
  approved: false,
  approvedBy: "user123",
  correlationId: "correlation456",
  history: [
    {
      timestamp: new Date(),
      action: "approved",
      userId: "user123",
      previousValue: { approved: false }
    }
  ],
  deleted: false
}

🏢 QM Zones Data Structure

// QM Zone Record
{
  _id: "qmZone123",
  zone: {
    zoneId: "zone456",
    projectId: "project789",
    zoneCode: "A1",
    zoneStatus: "active"
  },
  rule: {
    ruleId: "zoneRule456",
    value: 92.3,
    level: "notify",
    lastRun: new Date(),
    approved: true
  },
  approved: true,
  approvedBy: "user123",
  correlationId: "correlation789",
  history: [/* revision history */],
  deleted: false
}

🔄 Quality Rules Configuration

// Quality Rule Structure
{
  ruleId: "rule123",
  name: "Accuracy Threshold",
  type: "percentage",
  thresholds: {
    info: { min: 95, max: 100 },      // 🟦 Info level
    notify: { min: 85, max: 94 },     // 🟡 Notify level
    warning: { min: 0, max: 84 }      // 🔴 Warning level
  },
  appliesTo: ["scans", "zones"],
  isActive: true
}

🔧 QM Module Job Processing System

// QM Module Job Structure
{
  _id: "qmJob123",
  type: "qmModule",
  status: "running", // paused, ready, running, completed, failed
  progress: {
    percent: 75,
    completed: 750,
    total: 1000
  },
  data: {
    scope: "projectId",
    objectId: "project123",
    synchronizationType: "full|incremental",
    components: ["scans", "zones"],
    ruleChanges: [
      { ruleId: "rule123", previousThreshold: 85, newThreshold: 90 }
    ]
  },
  failures: [
    { 
      value: "Database connection timeout", 
      timestamp: new Date(),
      component: "scans|zones"
    }
  ],
  created: new Date(),
  started: new Date(),
  completed: null
}

🔐 QM Module Security Features

• Hierarchical Role Access: Multi-level permission system with role inheritance
• Component-Level Security: Separate access controls for scans and zones
• Project Isolation: Strict project-based data segregation
• Audit Trail Integration: Complete history tracking across all components
• Correlation Tracking: Links related operations across scans and zones
• Input Validation: Comprehensive parameter validation for all operations

📈 QM Module Performance Optimizations

• Unified Data Pipeline: Shared aggregation pipelines for efficient processing
• Component Caching: Intelligent caching strategy across scans and zones
• Background Processing: Async quality rule evaluation with job queuing
• Optimized Queries: Database indexes and query optimization for large datasets
• Progressive Loading: Lazy loading of component data based on user navigation

🔄 QM Module Integration Points

• Scan System Integration: Real-time integration with main scanning operations
• Zone Management Sync: Bidirectional synchronization with zone status
• User Management: Role-based permission integration across components
• Project Lifecycle: Respects project state requirements for all operations
• Notification System: Unified quality alerts and status updates
• Reporting Integration: Data feeds for quality reporting and analytics

📊 Quality Metrics Calculation Engine

// Unified Quality Score Calculation
const calculateModuleQualityScore = (scans, zones, rules) => {
  // Scan-level calculations
  const scanQuality = scans.reduce((total, scan) => {
    return total + evaluateQualityRules(scan, rules.scanRules);
  }, 0) / scans.length;
  
  // Zone-level calculations  
  const zoneQuality = zones.reduce((total, zone) => {
    return total + evaluateQualityRules(zone, rules.zoneRules);
  }, 0) / zones.length;
  
  // Combined module score
  return {
    overallScore: (scanQuality + zoneQuality) / 2,
    scanScore: scanQuality,
    zoneScore: zoneQuality,
    trendAnalysis: calculateTrends(historicalData),
    recommendations: generateQualityRecommendations()
  };
};

---

This documentation covers the comprehensive QM Module with integrated scan and zone quality management. The unified interface provides seamless access to both scan-level and zone-level quality control operations. For advanced quality rule configuration, custom threshold setup, or troubleshooting complex quality issues, consult with your system administrator.