feat: FASE 7 - Polish & Testing (security, i18n, test suite, docs)

Security hardening: CORS lockdown, rate limiting middleware con sliding window e eviction IP stale, security headers (CSP, HSTS, X-Frame-Options), session cookie hardening, filename sanitization upload. i18n completion: internazionalizzati barcode.js e csv-export.js con bridge window.BARCODE_I18N/CSV_I18N, aggiornati .po IT/EN con 27 nuove stringhe. Tablet UX: touch target 44px per dispositivi coarse pointer. Test suite: 101 test totali (76 server + 25 client), copertura completa di tutti i router API, autenticazione, ruoli, CRUD, SPC, file upload, security integration. Infrastruttura SQLite async in-memory con fixtures. Fix critici: MissingGreenlet in recipe_service (selectinload eager), route ordering tasks.py, auth_service bcrypt diretto, Measurement.id Integer per SQLite. Documentazione: API.md (riferimento completo 40+ endpoint), DEPLOYMENT.md (guida produzione con Docker/Nginx/SSL), USER_GUIDE.md (manuale utente per ruolo). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-07 17:10:24 +01:00
parent 26e5b9343d
commit dd2ebf863a
46 changed files with 6322 additions and 90 deletions
@@ -0,0 +1,693 @@
+# 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