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
Station	A physical measurement post (typically one tablet on a production line). Each station has a unique code (STATION_CODE) and a list of assigned recipes
Station assignment	Many-to-many link between a station and the recipes available to the operators using that station's tablet

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, user management and station deployment

Permissions:

• Create/edit/delete users
• Assign roles to users
• Regenerate user API keys
• Create/edit/delete stations and assign recipes to them
• Configure system settings
• Upload company logo
• Manage CSV export settings

Access:

• Menu: Admin → Utenti / Stazioni
• Can see: All users, all stations and system settings

Typical Tasks:

• Onboard new users
• Reset lost API keys
• Roll out a new tablet: create the matching station, assign recipes, hand the STATION_CODE to devops
• 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

Recipes you see are filtered by station

Each tablet/PC running the Flask client is configured at deployment time with a STATION_CODE environment variable (for example ST-LINEA-A). Whenever you open Select Recipe, the page only lists recipes that the admin has assigned to that station. If your tablet shows fewer recipes than you expect, ask the admin to assign the missing recipes to your station — see Admin Workflow → Station Management.

If the page shows "Stazione non configurata" (HTTP 503), the deployment is missing the STATION_CODE setting; this is a deploy-time configuration issue, not something the operator can fix from the UI.

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)

Station Management

Stations are how TieMeasureFlow enforces "this tablet is responsible for these measurements". Each physical measurement post in the shop floor is modelled as a station; each tablet's Flask client identifies itself through a STATION_CODE env var that must match a station's code in the database.

The page is reachable from the navbar entry "Stazioni" (workstation icon) for any user with the admin flag, or directly at /admin/stations.

Mental model

• One station = one tablet/PC in the shop floor. The station's identity (STATION_CODE) is configured once at deploy time in the tablet's .env, never changed at runtime.
• A station has a list of assigned recipes. The operator using that tablet sees exactly that list — no more, no less.
• A recipe can be assigned to several stations (e.g. a calibration recipe everyone needs).
• A station can be temporarily disabled (active = false) to take a line offline without losing its history; tablets pointing at a disabled station get HTTP 404 from the recipe endpoint.

Create a Station

1. Navigate to Admin → Stazioni
2. Click Nuova Stazione
3. Fill in the modal:
   • Codice (required, unique): ST-LINEA-A. This is the value the tablet will set as STATION_CODE in its .env. Use ASCII letters, digits and hyphens only — no spaces, no accented characters. Once created the code cannot be changed (changing it would break every tablet pointing at it).
   • Nome (required): human-readable description, e.g. Linea A — Tornitura alberi.
   • Postazione (optional): physical location, e.g. Reparto 2 — Cella 3.
   • Note (optional): free text, useful for tracking who set up the station.
   • Attiva (default checked): uncheck only when retiring the station.
4. Click Crea Stazione

Naming convention: prefix every station code with ST- and use a stable identifier that survives shop-floor reorganisations.

Assign Recipes to a Station

1. From the stations table, click the checklist icon on the row of the target station
2. The "Ricette Assegnate" modal opens with two columns:
   • Ricette disponibili (left): every recipe in the system not yet assigned to this station. Each row has an inline + Assegna button that immediately moves the recipe to the right column.
   • Assegnate alla stazione (right): the list the operator at this station's tablet will see. The X button removes the assignment.
3. Use the search field at the top to narrow either column by recipe code or name
4. Empty-state hints tell you why a column is empty:
   • "Tutte le ricette sono già assegnate" — nothing more to assign
   • "Nessuna ricetta nel sistema" — create at least one recipe first (Maker workflow)
   • "Nessun risultato per il filtro" — clear the search

The assignment audit trail (assigned_by, assigned_at) is stored on the server but not currently shown in the UI.

Edit a Station

1. Click the pencil icon (or the row itself) for the target station
2. Update Nome, Postazione, Note or the Attiva flag
3. Click Salva Modifiche

The Codice field is read-only on edit because the value is contractually bound to the STATION_CODE set on already-deployed tablets. To rename a station you must delete it and create a new one with the new code, then update every affected tablet's .env.

Delete a Station

1. Click the trash icon for the station
2. Confirm in the modal

Deletion cascades to all recipe assignments for that station. Existing measurements collected by tablets at that station are not affected (measurements are linked to recipe versions, not stations).

The ST-DEFAULT station

The first time /api/setup/seed runs, it creates a station called ST-DEFAULT and assigns every demo recipe to it. This is intended for single-tablet demos and dev setups where no per-station segmentation is needed.

In multi-station production deployments you should either:

• Delete ST-DEFAULT once your real stations are configured, or
• Disable it (Attiva off), to prevent a misconfigured tablet from accidentally inheriting the default assignment set.

Tablet deployment cheat sheet

For each new physical tablet:

1. Admin creates the station in the UI (e.g. ST-LINEA-A)
2. Admin assigns the relevant recipes
3. Devops sets STATION_CODE=ST-LINEA-A in the tablet's .env
4. Tablet container starts; the operator opens Measure → Select Recipe and sees the curated list

If step 3 is missed, Select Recipe shows the page "Stazione non configurata" — this is the intentional fail-fast behaviour to prevent a tablet from silently falling back to the wrong recipe set.

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