SmartScanProbeTrack/project_plan.md

# SmartScan Probe Track - Implementation Plan

## Technology Stack
| Component           | Technology             |
|---------------------|------------------------|
| Web Framework       | Flask (Python)         |
| Database            | Supabase (PostgreSQL)  |
| Virtual Environment | uv                     |
| UI Framework        | Bootstrap 5 + Vue.js   |
| Charting            | Chart.js               |
| PDF Generation      | ReportLab + PyPDF2     |

## Database Schema
### Tables
0. **calibration_audit**
   - id (bigserial, PK)
   - calibration_id (uuid, FK → calibrations.id)
   - user_id (uuid, FK → users.id)
   - action (text)
   - old_values (jsonb)
   - new_values (jsonb)
   - timestamp (timestamptz)
   - ip_address (text)

1. **probes**
   - id (uuid, PK, DEFAULT gen_random_uuid())
   - model_id (uuid, FK → probe_models.id)
   - serial_number (text)
   - description (text)
   - created_at (timestamp)
   - retired_at (timestamp)

2. **channels**
   - id (uuid, PK, DEFAULT gen_random_uuid())
   - probe_id (uuid, FK → probes.id)
   - serial_number (varchar(16), regex: [0-9A-F]{16})
   - parameter_id (uuid, FK → parameters.id)
   - created_at (timestamp)

3. **calibrations**
   - id (uuid, PK, DEFAULT gen_random_uuid())
   - channel_id (uuid, FK → channels.id)
   - work_order_id (uuid, FK → work_orders.id)
   - calibrated_by (uuid, FK → users.id)
   - reviewed_by (uuid, FK → users.id)
   - std_used (uuid, FK → standards.id)
   - std_cal_date (date)
   - std_cal_due (date)
   - date (date)
   - scale (float)
   - offset (float)
   - deviation_high (float)
   - deviation_mid (float)
   - deviation_low (float)
   - set_high (float)
   - set_mid (float)
   - set_low (float)
   - passed (boolean)

4. **locations**
   - id (uuid, PK, DEFAULT gen_random_uuid())
   - name (text)
   - address (text)
   - contact_name (text)
   - contact_email (text)
   - contact_phone (text)

5. **probe_locations**
   - id (uuid, PK, DEFAULT gen_random_uuid())
   - probe_id (uuid, FK → probes.id)
   - location_id (uuid, FK → locations.id)
   - start_date (date)
   - end_date (date)

6. **probe_models**
   - id (uuid, PK, DEFAULT gen_random_uuid())
   - model_name (text, unique)
   - specifications (jsonb)

7. **work_orders**
   - id (uuid, PK, DEFAULT gen_random_uuid())
   - order_number (text, unique)
   - customer_id (uuid, FK → customers.id)
   - assigned_to (uuid, FK → users.id)
   - due_date (date)
   - status (text)
   - redmine (integer)
   - cal_type (uuid, FK → calibration_types.id)

8. **users**
   - id (uuid, PK, DEFAULT gen_random_uuid())
   - name (text)
   - email (text, unique)
   - can_calibrate (boolean)
   - can_review (boolean)
   - signature_image (text)

10. **standards**
   - id (uuid, PK, DEFAULT gen_random_uuid())
   - make (text)
   - model (text)
   - description (text)
   - uncertainty (text)
   - calibrated_on (date)
   - calibration_due (date)
   - support_name (text)
   - support_email (text)
   - support_phone (text)
   - support_address (text)

11. **calibration_types**
   - id (uuid, PK, DEFAULT gen_random_uuid())
   - type_name (text)

12. **parameters**
   - id (uuid, PK, DEFAULT gen_random_uuid())
   - parameter_name (text)

### Relationships

```mermaid
erDiagram
    probes ||--o{ channels : has
    probes }|--|| probe_models : model
    channels }|--|| parameters : parameter
    channels ||--o{ calibrations : has
    calibrations }|--|| standards : standard
    work_orders ||--o{ calibrations : contains
    work_orders }|--|| calibration_types : type
    work_orders }|--|| users : assigned_to
    probes ||--o{ probe_locations : assigned
    locations ||--o{ probe_locations : location
    customers ||--o{ work_orders : requested
    users ||--o{ calibrations : calibrated
    users ||--o{ calibrations : reviewed

Application Structure

SmartScanProbeTrack3/
├── app/
│   ├── __init__.py
│   ├── routes/
│   │   ├── auth.py
│   │   ├── probes.py
│   │   ├── channels.py
│   │   ├── calibrations.py
│   │   ├── locations.py
│   │   └── work_orders.py
│   ├── templates/
│   │   ├── auth/
│   │   │   └── login.html
│   │   ├── base.html
│   │   ├── index.html
│   │   ├── probe_list.html
│   │   ├── probe_form.html
│   │   ├── probe_view.html
│   │   ├── channel_view.html
│   │   ├── calibration_form.html
│   │   ├── calibration_view.html
│   │   ├── calibration_review.html
│   │   ├── location_timeline.html
│   │   ├── work_order_list.html
│   │   ├── work_order_form.html
│   │   └── work_order_view.html
│   ├── models.py
│   ├── supabase_client.py
│   └── utils/
│       └── pdf_utils.py
├── sql/
│   ├── create_tables.sql
│   ├── create_auth_audit_table.sql
│   ├── create_calibration_audit_table.sql
│   └── create_execute_sql_function.sql
├── tests/
├── requirements.txt
├── main.py
├── create_audit_tables.py
├── test_supabase.py
└── .env

Core Features

1. Probe Management

• Probe List: View all probes (probe_list.html)
• Probe Creation: Form to create new probes with channels (probe_form.html)
• Probe View: Detailed view showing:
  • Probe details
  • Associated channels (linking to channel_view.html)
  • Location history (linking to location_timeline.html)
• Channel Management:
  • Each probe has multiple channels
  • Channel view shows calibration history (channel_view.html)
• Location Assignment: Track probe deployment history

2. Calibration Workflow

1. Work Order Management:

   • List view (work_order_list.html)
   • Creation form (work_order_form.html)
   • Detailed view (work_order_view.html)

2. Calibration Process:

   • Entry Form: Multi-channel calibration entry (calibration_form.html)
   • Review Interface: For supervisor approval (calibration_review.html)
   • View Details: Shows full calibration history (calibration_view.html)

3. Workflow:

   • Create work order → Add calibrations → Submit for review → Approve
   • Audit trail maintained via SQL audit tables
   • Electronic signatures captured during review

4. Certificate Generation:

   • Automatic PDF generation after approval
   • Includes all calibration metrics and standards data

3. Reporting

• Probe history:

  • Show location assignment timeline (from probe_locations)
  • Include calibration history with deviation/set point values

• Location inventory:

  • Current probe assignments with dates
  • Contact information for each location

• Work order tracking:

  • Status indicators (pending, in progress, completed)
  • Filter by calibration type

4. User Management

• Role-based access control
• Electronic signatures
• Audit trails

Setup Instructions

Use uv for all relevant virtual environment and package management. For example, use 'uv add' rather than 'uv pip'. Use 'uv run' to run the app.

# Create virtual environment
uv venv venv
.\venv\Scripts\activate

# Install dependencies
uv pip install flask supabase python-dotenv reportlab pypdf2

# Environment variables (.env)
SUPABASE_URL=https://yelyqstoffujrlddboai.supabase.co
SUPABASE_KEY=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6InllbHlxc3RvZmZ1anJsZGRib2FpIiwicm9sZSI6ImFub24iLCJpYXQiOjE3NTM2Mjg3OTIsImV4cCI6MjA2OTIwNDc5Mn0.IAwOaydZXvklT9atJoJix9Abf7pMPr1q1WZMI2JJUCc
SECRET_KEY=5e8f8d7e-5e8f-4a3d-9e8f-5e8f8d7e5e8f
DATABASE_URL=postgresql://postgres:FRWLUJ5xTpcLJ136Xqob06HNWfaUXlqf@yelyqstoffujrlddboai.supabase.co:5432/postgres

Implementation Roadmap

Phase 1: Foundation

1. Flask application scaffold
2. Supabase connection setup
3. User authentication system
   • web app will be hosted internally on a closed network so authentication is only needed to identify users for calibration and review purposes
   • no passwords are required at this time, though that may change in the future
   • login page can be as simple as a drop-down to select from a list of existing users
4. Basic probe management

Phase 2: Core Functionality

1. Work order management system
   • Implement calibration type selection
   • Customer association
2. Batch calibration interface
   • Form fields for new deviation/set point values
   • Real-time validation for serial numbers
3. Review workflow (Completed)
   • Electronic signature capture (Implemented)
   • Audit trail implementation (Created calibration_audit table)

Phase 3: Reporting & Output

1. Location history tracking
   • Timeline visualization for probe locations
2. Probe history reports
   • Tabular display of calibration data
   • Deviation trend graphs
3. PDF certificate generation
   • Template design with new calibration fields
   • Automatic inclusion of standard equipment details

Phase 4: Analytics (Future)

1. Probe lifespan prediction
2. Calibration trend analysis
3. Maintenance scheduling

UI/UX Guidelines

• Form validation:

  • Channel serial numbers: Enforce [0-9A-F]{16} pattern
  • Date fields: Prevent future dates for calibration
  • Numeric fields: Range validation for deviation/set points
  • Never allow duplicate channel serial numbers
  • Never allow duplicate probe serial numbers

• Status indicators:

  • Color-coded work order status (red/yellow/green)
  • Pass/fail badges for calibrations

• Data visualization:

  • Trend graphs for deviation values over time
  • Location assignment timelines

Code Guidelines

• include clear and industry-standard comments throughout code, compliant with all relevant python PIP regulations
• include unit tests throughout
• always keep project_plan.md and todo.md in mind when considering what to do next and to maintain an understanding of where in the development process we are