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
2. Getting Started
3. User Roles
4. Maker Workflow
5. MeasurementTec Workflow
6. Metrologist Workflow
7. Admin Workflow
8. UI Features
9. Keyboard Shortcuts
10. 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