# Quality Control Management System - Documentation

## Table of Contents
1. [Login System](#login-system)
2. [Dashboard System](#dashboard-system)
3. [User Authentication](#user-authentication)
4. [Role-Based Access Control](#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

```python
# 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:

```python
# 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.*