quality_recticel/py_app/documentation.md

Quality Control Management System - Documentation

Table of Contents

1. Login System
2. Dashboard System
3. User Authentication
4. Role-Based Access Control

---

Login System

Overview

The Quality Control Management System features a dual-database authentication system that provides flexible user management and robust access control. The login system supports both internal SQLite database users and external MariaDB database users.

Authentication Flow

1. Login Page Access

• URL: /login
• Template: login.html
• Methods: GET, POST

2. User Interface

The login page features:

• Company Logo: Displayed prominently on the left side
• Login Form: Clean, centered form on the right side
• Required Fields:
  • Username (text input)
  • Password (password input)
• Responsive Design: Adapts to different screen sizes

3. Authentication Methods

Internal Database Authentication

Users can access the system using the internal SQLite database by prefixing their username with #:

Format: #username Example: #admin for internal admin user

Database Details:

• Location: py_app/instance/users.db
• Table: users
• Schema: username, password, role
• Use Case: System administrators, fallback authentication

External Database Authentication

Standard authentication uses the external MariaDB database:

Format: username (no prefix) Example: john.doe for external user

Database Details:

• Type: MariaDB
• Configuration: Loaded from external_database_settings
• Table: users
• Schema: username, password, role
• Use Case: Regular operational users

4. Authentication Logic

# Authentication Process Flow
if username.startswith('#'):
    # Internal SQLite Database Authentication
    username_clean = username[1:].strip()
    # Query: py_app/instance/users.db
    
else:
    # External MariaDB Database Authentication
    # Primary: External database query
    # Fallback: Internal database if external fails

5. Security Features

Input Validation

• Required Fields: Both username and password must be provided
• Sanitization: Automatic trimming of whitespace
• Error Handling: Clear error messages for invalid inputs

Database Connection Security

• Dual Fallback: External database with internal fallback
• Error Isolation: Database errors don't expose system details
• Connection Management: Proper connection opening/closing

Session Management

• Secure Sessions: User credentials stored in Flask session
• Role Tracking: User role preserved for authorization
• Session Data:
  • session['user']: Username
  • session['role']: User role

6. User Roles

The system supports multiple user roles with different access levels:

• superadmin: Full system access, all modules and administrative functions
• admin: Administrative access with some limitations
• quality: Quality control module access
• warehouse: Warehouse management module access
• scan: Scanning operations access
• etichete: Label management access
• management: Management reporting and oversight

7. Login Process

1. User Navigation: User accesses /login URL
2. Form Display: Login form rendered with company branding
3. Credential Submission: User enters username/password and submits
4. Authentication Check:
   • Internal users: Check SQLite database
   • External users: Check MariaDB database with SQLite fallback
5. Session Creation: Valid credentials create user session
6. Redirect: Successful login redirects to /dashboard
7. Error Handling: Invalid credentials display error message

8. Error Messages

• Missing Credentials: "Please enter both username and password."
• Invalid Credentials: "Invalid credentials. Please try again."
• Database Errors: Handled gracefully with fallback mechanisms

9. Post-Login Behavior

After successful authentication:

• Session Establishment: User session created with username and role
• Dashboard Redirect: User redirected to main dashboard
• Access Control: Role-based permissions applied throughout system
• Navigation: Header displays logged-in user information

10. Security Considerations

Password Security

• Storage: Passwords stored in plaintext (consider encryption upgrade)
• Transmission: Form-based submission over HTTPS recommended
• Session: Password not stored in session, only username/role

Database Security

• Connection Strings: External database settings in separate config
• Error Handling: Database errors logged but not exposed to users
• Fallback System: Ensures availability even if external database fails

Technical Implementation

Frontend Components

• Template: templates/login.html
• Styling: Login-specific CSS in static/style.css
• Assets: Company logo (static/logo_login.jpg)

Backend Components

• Route Handler: @bp.route('/login', methods=['GET', 'POST'])
• Database Connections: SQLite and MariaDB integration
• Session Management: Flask session handling
• Error Handling: Comprehensive exception management

Configuration Files

• External Database: Configuration loaded from external_database_settings
• Internal Database: SQLite database in instance/users.db

Usage Examples

Standard User Login

Username: john.doe
Password: userpassword
Result: Queries external MariaDB database

Internal Admin Login

Username: #admin
Password: adminpassword  
Result: Queries internal SQLite database

System Administrator Login

Username: #superadmin
Password: superpass
Result: Internal database, full system access

---

Dashboard System

Overview

The dashboard serves as the central hub of the Quality Control Management System, providing authenticated users with access to various system modules based on their assigned roles. It features a clean, card-based interface that displays available modules and ensures proper access control.

Dashboard Access

1. Dashboard Page Access

• URL: /dashboard
• Template: dashboard.html
• Methods: GET
• Authentication Required: Yes (redirects to login if not authenticated)

2. User Interface Design

The dashboard features a modern, responsive card-based layout:

• Container: Full-width responsive grid layout
• Module Cards: Individual cards for each system module
• Visual Hierarchy: Clear headings, descriptions, and call-to-action buttons
• Responsive Design: Adapts to different screen sizes and devices

3. Available Modules

Scanning Module

• Card Title: "Access Scanning Module"
• Description: "Final scanning module for production orders"
• Button: "Launch Scanning Module"
• Route: /scan
• Required Roles: superadmin, scan
• Purpose: Quality control scanning operations for production orders

Reports Module (Quality)

• Card Title: "Access Reports Module"
• Description: "Module for verification and quality settings configuration"
• Button: "Launch Reports Module"
• Route: /quality
• Required Roles: superadmin, quality
• Purpose: Quality reporting, defects analysis, and quality control reports

Warehouse Module

• Card Title: "Access Warehouse Module"
• Description: "Access warehouse module functionalities"
• Button: "Open Warehouse"
• Route: /warehouse
• Required Roles: superadmin, warehouse
• Purpose: Warehouse management operations and inventory control

Labels Module

• Card Title: "Access Labels Module"
• Description: "Module for label management"
• Button: "Launch Labels Module"
• Route: /etichete
• Required Roles: superadmin, etichete
• Purpose: Label creation, template management, and printing operations

Settings Module

• Card Title: "Manage Settings"
• Description: "Access and manage application settings"
• Button: "Access Settings Page"
• Route: /settings
• Required Roles: superadmin only
• Purpose: System configuration, user management, and administrative settings

4. Access Control Logic

The dashboard implements role-based access control at both the display and route levels:

Frontend Display Control

All module cards are displayed to all authenticated users, but access is controlled at the route level.

Backend Route Protection

Each module route implements permission checking:

# Quality Module Access Control
@bp.route('/quality')
def quality():
    if 'role' not in session or session['role'] not in ['superadmin', 'quality']:
        flash('Access denied: Quality users only.')
        return redirect(url_for('main.dashboard'))

# Warehouse Module Access Control  
@bp.route('/warehouse')
def warehouse():
    if 'role' not in session or session['role'] not in ['superadmin', 'warehouse']:
        flash('Access denied: Warehouse users only.')
        return redirect(url_for('main.dashboard'))

# Scanning Module Access Control
@bp.route('/scan')
def scan():
    if 'role' not in session or session['role'] not in ['superadmin', 'scan']:
        flash('Access denied: Scan users only.')
        return redirect(url_for('main.dashboard'))

# Labels Module Access Control
@bp.route('/etichete')
def etichete():
    if 'role' not in session or session['role'] not in ['superadmin', 'etichete']:
        flash('Access denied: Etichete users only.')
        return redirect(url_for('main.dashboard'))

# Settings Module Access Control (Superadmin Only)
def settings_handler():
    if 'role' not in session or session['role'] != 'superadmin':
        flash('Access denied: Superadmin only.')
        return redirect(url_for('main.dashboard'))

5. User Experience Flow

1. Authentication Check: User must be logged in to access dashboard
2. Dashboard Display: All module cards shown regardless of role
3. Module Selection: User clicks on desired module button
4. Permission Validation: System checks user role against module requirements
5. Access Grant/Deny:
   • Authorized: User redirected to module interface
   • Unauthorized: Error message displayed, user remains on dashboard

6. Session Management

The dashboard relies on Flask session management:

• Session Check: if 'user' not in session validates authentication
• Role Access: session['role'] determines module permissions
• Debug Logging: Session information logged for troubleshooting

7. Error Handling

Authentication Errors

• Unauthenticated Users: Automatic redirect to login page
• Session Timeout: Redirect to login with appropriate messaging

Authorization Errors

• Insufficient Permissions: Flash message with specific role requirements
• Access Denied: User returned to dashboard with error notification
• Clear Messaging: Specific error messages indicate required permissions

8. Security Features

Session Security

• Authentication Required: All dashboard access requires valid session
• Role Validation: Each module validates user role before access
• Automatic Redirect: Unauthorized access redirected safely

Access Control

• Principle of Least Privilege: Users only access modules for their role
• Superadmin Override: Superadmin role has access to all modules
• Route-Level Protection: Backend validation prevents unauthorized access

9. Module Descriptions

Quality Reports Module

• Primary Function: Generate quality control reports and analytics
• Key Features:
  • Daily, weekly, and custom date range reports
  • Quality defects analysis and tracking
  • Export capabilities (CSV format)
  • Database testing tools (superadmin only)

Scanning Module

• Primary Function: Production order scanning and quality validation
• Key Features:
  • Barcode/QR code scanning interface
  • Real-time quality validation
  • Production order processing

Warehouse Module

• Primary Function: Warehouse operations and inventory management
• Key Features:
  • Inventory tracking and management
  • Location management
  • Warehouse reporting

Labels Module

• Primary Function: Label design, generation, and printing
• Key Features:
  • Label template creation and management
  • Dynamic label generation
  • Print management system

Settings Module

• Primary Function: System administration and configuration
• Key Features:
  • User account management
  • Role and permission configuration
  • Database settings management
  • System configuration options

10. Technical Implementation

Frontend Components

• Template: templates/dashboard.html
• Styling: Dashboard-specific CSS classes in static/style.css
• Layout: CSS Grid/Flexbox responsive card layout
• Navigation: Base template integration with header/footer

Backend Components

• Route Handler: @bp.route('/dashboard')
• Session Management: Flask session integration
• Authentication Check: User session validation
• Logging: Debug output for troubleshooting

Styling Classes

• .dashboard-container: Main container with responsive grid
• .dashboard-card: Individual module cards
• .btn: Standardized button styling
• Responsive breakpoints for mobile/tablet adaptation

Usage Examples

Superadmin User Dashboard Access

Role: superadmin
Available Modules: All (Scanning, Quality, Warehouse, Labels, Settings)
Special Access: Settings module exclusive access

Quality Control User Dashboard Access

Role: quality
Available Modules: Quality Reports module only
Restricted Access: Cannot access other modules

Multi-Role Access Example

Role: warehouse
Available Modules: Warehouse module only
Access Pattern: Click → Permission Check → Module Access

---

This documentation covers the dashboard system implementation. For specific module details, see their respective documentation sections.