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 |
| **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