TieMeasureFlow/docs/USER_GUIDE.md

# TieMeasureFlow User Guide

Welcome to TieMeasureFlow - a comprehensive measurement task management system designed for precision measurement workflows with caliper measurements, barcode tracking, and statistical process control.

## Table of Contents

1. [System Overview](#system-overview)
2. [Getting Started](#getting-started)
3. [User Roles](#user-roles)
4. [Maker Workflow](#maker-workflow)
5. [MeasurementTec Workflow](#measurementtec-workflow)
6. [Metrologist Workflow](#metrologist-workflow)
7. [Admin Workflow](#admin-workflow)
8. [UI Features](#ui-features)
9. [Keyboard Shortcuts](#keyboard-shortcuts)
10. [Tips & Tricks](#tips--tricks)

## System Overview

### What is TieMeasureFlow?

TieMeasureFlow is a web-based measurement management system that enables teams to:

- **Create measurement recipes** - Define measurement procedures with tasks, subtasks, and tolerance specifications
- **Execute measurements** - Record measurements using USB calipers or manual input with automatic pass/fail determination
- **Track traceability** - Associate measurements with lot numbers, serial numbers, and operators
- **Analyze quality** - Generate SPC (Statistical Process Control) charts, capability indices, and quality reports
- **Export data** - Download measurements as CSV or generate PDF reports with configurable formatting

### Key Concepts

| Concept | Description |
|---------|-------------|
| **Recipe** | Master document that defines a set of measurements to perform |
| **Version** | Immutable snapshot of a recipe. Editing creates a new version; old measurements stay linked to original |
| **Task** | Logical group of related subtasks (e.g., "Measure external dimensions") |
| **Subtask** | Individual measurement point with tolerance limits (UTL/UWL/LWL/LTL) |
| **Measurement** | Individual recorded value with automatic pass/fail/warning status |
| **Lot/Serial** | Traceability fields linking measurements to physical parts |

### Architecture

```
TieMeasureFlow
├── Server (FastAPI on port 8000)
│   ├── Authentication & Authorization
│   ├── Recipe versioning & management
│   ├── Measurement storage & analysis
│   └── Statistical calculations
└── Client (Flask on port 5000)
    ├── Maker: Recipe editor
    ├── MeasurementTec: Measurement entry
    ├── Metrologist: SPC dashboard
    └── Admin: User management
```

---

## Getting Started

### Login

1. Open `http://localhost:5000` (or your configured client URL)
2. Enter **username** and **password**
3. Click **Login**

You are now logged in and redirected to your role's dashboard.

### Change Language

Click the **language selector** (top-right) to switch between:
- **Italian (Italiano)** - Default
- **English** - Full UI and data labels translated

Language preference is saved to your profile.

### Change Theme

Click the **theme toggle** (sun/moon icon, top-right) to switch between:
- **Light Mode** - White background, dark text
- **Dark Mode** - Dark background, light text

Theme preference is saved to your profile.

### Profile Settings

1. Click your **username** (top-right)
2. Select **Profile** or **Settings**
3. Update:
   - Display name
   - Email
   - Language preference
   - Theme preference
4. Click **Save**

---

## User Roles

TieMeasureFlow has four primary roles. Users can have multiple roles simultaneously.

### Maker

**Purpose:** Create and maintain measurement procedures

**Permissions:**
- Create new recipes
- Edit recipe structure (tasks, subtasks, tolerances)
- Add measurement points and annotations
- Upload images/PDFs for reference
- View recipe history and versions
- Manage recipe access

**Access:**
- Menu: **Maker** → Recipe Management
- Can see: All recipes and their versions

**Typical Tasks:**
- Define new measurement procedures
- Set tolerance limits (UTL/UWL/LWL/LTL)
- Create visual annotations on images
- Document measurement instructions

---

### MeasurementTec

**Purpose:** Execute measurements in the field/lab

**Permissions:**
- Select recipes to measure
- Record individual measurements
- Use USB caliper for automated input
- Scan barcodes for lot/serial tracking
- View assigned measurement tasks
- Export measurements to CSV

**Access:**
- Menu: **Measure** → Task Execution
- Can see: Published recipes only

**Typical Tasks:**
- Open a recipe via barcode or search
- Follow task instructions
- Record measurements (manual or USB caliper)
- Scan lot and serial numbers
- Monitor real-time pass/fail status

---

### Metrologist

**Purpose:** Analyze measurements and generate quality reports

**Permissions:**
- View all measurements across recipes
- Access SPC statistics and control charts
- View capability indices (Cp, Cpk, Pp, Ppk)
- Generate PDF reports
- Export measurements and charts
- Filter data by recipe, date, operator, lot

**Access:**
- Menu: **Statistics** → SPC Dashboard
- Can see: All measurements and statistics

**Typical Tasks:**
- Monitor process capability
- Generate control charts
- Investigate out-of-control conditions
- Export data for analysis
- Create quality reports

---

### Admin

**Purpose:** System administration and user management

**Permissions:**
- Create/edit/delete users
- Assign roles to users
- Regenerate user API keys
- Configure system settings
- Upload company logo
- Manage CSV export settings

**Access:**
- Menu: **Admin** → User Management
- Can see: All users and system settings

**Typical Tasks:**
- Onboard new users
- Reset lost API keys
- Configure locale/format settings
- Upload company branding
- Manage system access

---

## Maker Workflow

### Create a New Recipe

1. Navigate to **Maker** → **Recipe Management**
2. Click **New Recipe**
3. Enter details:
   - **Code**: Unique identifier (e.g., `RECIPE_MOTOR_001`)
   - **Name**: Human-readable name
   - **Description**: Purpose and context
4. Click **Create Recipe**
5. Recipe v1 is created and ready for editing

### Add Tasks and Subtasks

1. Open a recipe
2. Click **Add Task**
3. Enter task details:
   - **Title**: e.g., "Measure external dimensions"
   - **Directive**: Step-by-step instructions
   - **Description**: Additional context
   - **File Type**: Select if using images/PDFs
4. Click **Add Subtask** for each measurement point
5. For each subtask:
   - **Marker #**: Unique number within task (e.g., 1, 2, 3)
   - **Description**: What is being measured
   - **Measurement Type**: `length`, `angle`, `diameter`, etc.
   - **Nominal**: Target value
   - **UTL**: Upper Tolerance Limit (hard limit)
   - **UWL**: Upper Warning Limit (warning zone)
   - **LWL**: Lower Warning Limit (warning zone)
   - **LTL**: Lower Tolerance Limit (hard limit)
   - **Unit**: `mm`, `inch`, `degree`, etc.

**Tolerance Example:**
```
LTL: 9.5 mm  (FAIL below this)
LWL: 9.8 mm  (WARNING below this)
Nominal: 10.0 mm
UWL: 10.2 mm (WARNING above this)
UTL: 10.5 mm (FAIL above this)
```

### Add Annotations & Images

1. Open a task
2. Click **Upload Image** to add reference photo
3. Click **Annotate** to add visual markers
4. In the annotation editor:
   - **Marker Tool**: Click to place numbered points
   - **Text Tool**: Add labels
   - **Draw Tool**: Add circles/lines
5. Save annotations

### Manage Versions

When you edit a recipe (add/remove tasks, change tolerances), a **new version** is created automatically. This ensures:

- Measurements remain linked to the version they were recorded against
- You can compare results across versions
- Historical record is preserved

**Version Management:**
1. Open recipe
2. Click **Versions** tab
3. View all versions with:
   - Version number and date
   - Who made changes
   - Change notes
   - Measurement count
4. Click version to view its structure

**Warning:** If a version has existing measurements, you cannot edit it directly. Create a new version to make changes.

---

## MeasurementTec Workflow

### Select a Recipe

**Method 1: Search**
1. Navigate to **Measure** → **Select Recipe**
2. Type recipe name or code in search box
3. Click recipe from results

**Method 2: Barcode Scan**
1. Navigate to **Measure** → **Select Recipe**
2. Scan recipe barcode
3. Recipe loads automatically

### Enter Lot & Serial Information

After selecting recipe:
1. **Lot Number**: Scan or type batch identifier
2. **Serial Number**: Scan or type part identifier
3. Click **Continue**

This information is recorded with every measurement for traceability.

### Perform Measurements

For each task:

1. **Read Instructions** - Display shows task directive and reference image
2. **Locate Measurement Points** - Find marked positions on the part
3. **Record Measurement**:

   **Option A: USB Caliper**
   - Connect USB caliper to tablet/computer
   - Place part in caliper
   - Press measurement button on caliper
   - System automatically records value
   - Move to next measurement point

   **Option B: Manual Entry**
   - Type measured value in input field
   - Value field accepts decimals and negative numbers
   - Press Enter or click Next

4. **Monitor Pass/Fail Status**:
   - **GREEN/Pass**: Value within LWL-UWL
   - **YELLOW/Warning**: Value within LTL-LWL or UWL-UTL
   - **RED/Fail**: Value outside LTL or UTL

5. **Submit Measurements** - Click Submit when all tasks complete

### Keyboard Shortcuts

| Shortcut | Action |
|----------|--------|
| `Tab` | Move to next measurement field |
| `Shift+Tab` | Move to previous field |
| `Enter` | Submit measurement and move to next |
| `Esc` | Cancel current task |
| `Ctrl+Z` | Undo last measurement |

### USB Caliper Auto-Detection

TieMeasureFlow automatically detects USB caliper input. To use:

1. Connect caliper via USB
2. Open measurement form
3. Focus on measurement input field
4. Press measurement button on caliper
5. Value appears in field automatically

**Note:** System distinguishes caliper input (rapid <30ms intervals, 3+ keystrokes) from human typing (>100ms intervals).

---

## Metrologist Workflow

### Access SPC Dashboard

1. Navigate to **Statistics** → **SPC Dashboard**
2. Dashboard loads with recipe list

### Select Data to Analyze

1. **Recipe**: Select from dropdown (required)
2. **Version**: Leave blank for all versions, or select specific version
3. **Subtask**: Select specific measurement point, or leave blank for summary
4. **Date Range**: Optional - filter by measurement date
5. **Operator**: Optional - filter by who performed measurement
6. **Lot/Serial**: Optional - filter by part traceability

Click **Apply Filters**

### View Summary Statistics

Card displays:
- **Total Measurements**: Count
- **Pass %**: Percentage passing all limits
- **Warning %**: Percentage in warning zone
- **Fail %**: Percentage outside limits

Use for quick quality assessment.

### Analyze Control Chart

The **control chart** displays:

- **Individual Points**: Each measurement value
- **Center Line**: Mean (average) value
- **UCL/LCL**: Upper/Lower Control Limits
- **Red Markers**: Out-of-control points

**What to Look For:**
- Points outside UCL or LCL → Process out of control
- Trend (6+ consecutive rising/falling) → Process drift
- All points on one side of center → Bias
- Regular oscillation → Calibration problem

### Check Process Capability

**Capability Indices** tell you if the process can consistently meet specifications:

| Index | What It Means | Target |
|-------|---------------|--------|
| **Cp** | Process capability (theoretical) | > 1.33 |
| **Cpk** | Process capability (actual, accounting for centering) | > 1.33 |
| **Pp** | Process performance (single sample) | > 1.67 |
| **Ppk** | Process performance (accounting for centering) | > 1.67 |

**Interpretation:**
- **Cpk > 1.67**: Excellent - process is capable
- **Cpk 1.33-1.67**: Good - process is acceptable
- **Cpk < 1.33**: Poor - process needs improvement

### View Histogram

The **histogram** shows:

- **Bars**: Distribution of measured values across bins
- **Curve**: Theoretical normal distribution overlay
- **Limits**: Vertical lines for LTL/LWL/UWL/UTL

**What to Look For:**
- Normal bell curve → Process is well-behaved
- Bimodal (two peaks) → Two different populations mixing
- Skewed distribution → Process bias
- Values outside limits → Specification violations

### Generate Reports

#### SPC Report (PDF)

1. Select filters (recipe, subtask, date range)
2. Click **Export SPC Report**
3. PDF downloads with:
   - Control chart graph
   - Histogram with curve
   - Capability statistics
   - Summary table

#### Measurements Report (PDF)

1. Select filters (optional subtask filter)
2. Click **Export Measurements Report**
3. PDF downloads with:
   - Complete measurement table
   - Pass/fail status
   - Lot/serial information
   - Operator name and date

#### CSV Export

1. Click **Export Data** button
2. CSV downloads with all filtered measurements
3. Columns: ID, subtask, version, operator, value, pass/fail, deviation, lot, serial, date
4. Delimiter and decimal format per system settings

---

## Admin Workflow

### User Management

#### Create User

1. Navigate to **Admin** → **User Management**
2. Click **Add User**
3. Enter:
   - **Username**: Login identifier (must be unique)
   - **Password**: Initial password (user can change after login)
   - **Display Name**: Full name for display
   - **Email**: Contact email
   - **Roles**: Check one or more:
     - Maker
     - MeasurementTec
     - Metrologist
   - **Admin**: Check if user manages other users
4. Click **Create User**
5. Confirm user was created and notify them to change password

#### Edit User

1. Navigate to **Admin** → **User Management**
2. Click user row to edit
3. Update fields (all optional):
   - Display name
   - Email
   - Roles
   - Admin status
   - Active status
4. Click **Save**

#### Deactivate User

1. Navigate to **Admin** → **User Management**
2. Click user row
3. Click **Deactivate User**
4. Confirm - user is soft-deleted (can be reactivated)
5. User's API key is cleared, login no longer works

#### Reset API Key

If user loses their API key:

1. Navigate to **Admin** → **User Management**
2. Click user row
3. Click **Regenerate API Key**
4. New key is generated and displayed
5. Provide new key to user (display once only)

### System Settings

#### Configure CSV Export

1. Navigate to **Admin** → **Settings**
2. Update:
   - **CSV Delimiter**: `,` (comma) or `;` (semicolon)
   - **CSV Decimal Separator**: `.` (period) or `,` (comma)
3. Click **Save**
4. All future CSV exports use these settings

**Example:**
- European format: Delimiter `;`, Decimal `,`
- US/UK format: Delimiter `,`, Decimal `.`

#### Upload Company Logo

1. Navigate to **Admin** → **Settings**
2. Click **Upload Logo**
3. Select image file (JPEG, PNG, GIF, WebP, SVG, max 50 MB)
4. Click **Upload**
5. Logo appears in header of all pages

---

## UI Features

### Navigation

**Top Navigation Bar:**
- Logo/company branding (left)
- Main menu: Measure, Maker, Statistics, Admin (center)
- Language selector, Theme toggle, User menu (right)

**Breadcrumbs:** Show current page hierarchy

**Search:** Available on list pages to filter by name/code

### Responsive Design

- **Desktop (1024px+)**: Full layout with sidebar
- **Tablet (768px+)**: Sidebar collapses to hamburger menu
- **Mobile (< 768px)**: Touch-optimized layout

### Data Tables

- **Sortable columns**: Click header to sort ascending/descending
- **Pagination**: Navigate between pages
- **Filters**: Narrow results by multiple criteria
- **Export**: Download as CSV

### Forms

- **Auto-save**: Some fields auto-save when you leave the field
- **Validation**: Error messages shown inline
- **Tooltips**: Hover over `?` icons for field help
- **Progress indicators**: Multi-step forms show progress

### Modal Dialogs

- Confirmation for destructive actions
- Forms for data entry
- Information displays
- Close with X button or Cancel

---

## Tips & Tricks

### Maker Best Practices

1. **Use Clear Naming**: Task and subtask names should describe exactly what is measured
2. **Document Units**: Always specify units (mm, inches, degrees) in subtask description
3. **Set Realistic Tolerances**: Ensure UTL/LTL are achievable with your equipment
4. **Version Control**: Add meaningful change notes when creating new versions
5. **Use Annotations**: Visual markers help operators find exact measurement points
6. **Test First**: Do a test measurement before rollout to ensure tolerances are reasonable

### MeasurementTec Best Practices

1. **Barcode Scanning**: Scan lot/serial barcodes rather than typing to avoid errors
2. **Consistent Operator**: Use consistent technique - caliper orientation, pressure, etc.
3. **Check Zero**: Zero your caliper at start of shift
4. **Monitor Warnings**: Watch for warning zone measurements - may indicate drift
5. **Document Deviations**: If you encounter fails, note the cause in observations
6. **Batch Together**: Group measurements from same lot for statistical significance

### Metrologist Best Practices

1. **Regular Reviews**: Check control charts daily for out-of-control conditions
2. **Trend Analysis**: Look beyond individual points - watch for sustained trends
3. **Root Cause**: When investigating failures, cross-reference by operator and time
4. **Baseline**: Establish baseline capability when process starts
5. **Update Limits**: Periodically review if specification limits are appropriate
6. **Archive Reports**: Keep dated PDF reports for audit trail

### Performance Tips

1. **Filter Early**: Use date range and version filters to speed up statistics queries
2. **Batch Operations**: Enter multiple measurements at once rather than one-by-one
3. **Cache Data**: Browser caches filter selections - reuse recent filters
4. **Offline Mode**: Some tablet deployments support offline measurement entry, synced later
5. **Export Over Display**: For large datasets (>1000 measurements), export to CSV and analyze in Excel

### Troubleshooting

**"Recipe not found" when scanning barcode**
- Verify barcode matches recipe code
- Check recipe is active (not deactivated)
- Try searching by name instead

**USB Caliper not working**
- Check USB cable connection
- Try removing and re-inserting caliper
- Check browser console for permission errors
- Use manual entry as backup

**Measurements seem wrong**
- Verify subtask is correct marker number
- Check caliper zero before starting
- Look for outliers - may indicate operator error
- Export data and check in spreadsheet

**Cannot edit recipe**
- Recipe may have existing measurements
- Create new version first
- Check if you have Maker role

**Export file encoding issues**
- If Excel shows garbled characters, check CSV settings
- Try semicolon delimiter with comma decimal separator for European locales
- File is UTF-8 encoded; ensure Excel opens with UTF-8 encoding

---

## Getting Help

### Online Resources

- **API Documentation**: `http://localhost:8000/docs`
- **Project Guide**: See `DEPLOYMENT.md` and `API.md`
- **Database Structure**: See schema in Alembic migrations

### Contact Support

- **System Admin**: For user account issues
- **Maker Manager**: For recipe structure and tolerance questions
- **Quality Engineer**: For SPC interpretation and reporting

---

## Keyboard & Accessibility

### Keyboard Navigation

- `Tab`: Navigate between fields
- `Shift+Tab`: Navigate backwards
- `Enter`: Submit forms
- `Escape`: Close modals/cancel operations
- `Alt+M`: Jump to main menu
- `Alt+S`: Jump to search

### Screen Reader Support

- All UI elements have proper ARIA labels
- Forms announce validation errors
- Tables have accessible headers
- Images have alt text

### High Contrast Mode

Enabled automatically for operating systems with high contrast settings

---

## Version History

**TieMeasureFlow v0.1.0**

Released: February 2025

**Features:**
- Recipe versioning with copy-on-write
- USB caliper integration
- SPC statistics and control charts
- PDF report generation
- Multi-language support (IT/EN)
- Light/Dark theme