E-Signature Integration for Forms

This document explains how the e-signature integration works with entity forms and how to configure it.

Overview

The form system now supports e-signature verification for save and submit operations. When enabled, users must verify their identity before form data is saved or submitted.

Features Implemented

1. Draft Mode Removal

• The "Save Draft" button is automatically removed from the action bar once a form is saved
• For forms that are already saved, the draft button won't appear in subsequent edit sessions

2. E-Signature Verification

• Configurable signature verification for save operations (requiresVerificationForSave)
• Configurable signature verification for submit operations (requiresVerificationForSubmit)
• Integration with the existing CompanyAuth e-signature dialog
• Graceful fallback when signature verification is not available

3. Form State Management

• Tracks whether a draft has been saved to update UI accordingly
• Maintains signature verification state throughout the form lifecycle
• Handles signature verification context properly

Configuration

Enable E-Signature for Entity Forms

final formDescriptor = EntityFormDescriptor<MyEntity>(
  form: myEntityForm,
  transformer: myEntityTransformer,
  allowDrafts: true,                    // Enable draft mode (default: false)
  requiresVerificationForSave: true,    // Require signature for draft saves
  requiresVerificationForSubmit: true,  // Require signature for final submit
);

Initialize E-Signature Integration

In your app initialization (typically in main.dart or app startup):

import 'package:company_auth/signature_integration.dart';

void main() {
  // ... other initialization code
  
  // Register the e-signature dialog with the entity system
  SignatureIntegration.registerSignatureDialog();
  
  // ... rest of app initialization
}

How It Works

1. Form Loading: EntityFormPage loads with Update/Create button (and optionally Save Draft if allowDrafts: true)
2. Draft Save (only if allowDrafts: true): When user clicks "Save Draft":
   • If requiresVerificationForSave is true, signature dialog is shown
   • After successful signature verification, form data is saved
   • Draft button is hidden from the action bar
3. Form Submit: When user clicks "Update/Create":
   • If requiresVerificationForSubmit is true, signature dialog is shown
   • After successful signature verification, form is validated and submitted
4. Signature Tracking: Signature metadata (signer identity, timestamp) is captured during verification

Draft Mode Behavior

• Default: Draft mode is disabled (allowDrafts: false)
• When enabled: Save Draft button appears alongside Update/Create button
• After saving: Draft button disappears to prevent redundant saves
• Security: Draft saves can require signature verification independently from submits

Technical Architecture

Components

• EntityFormController: Handles signature verification logic and form operations
• FormSignatureHelper: Utility class for signature dialog integration
• SignatureIntegration: Bridge between CompanyAuth and EntitySystem
• EntityFormPage: UI with conditional action bar buttons

Flow

EntityFormPage → EntityFormController → FormSignatureHelper → CompanyAuth E-Signature Dialog
     ↓                    ↓                     ↓                        ↓
   UI State           Form Logic           Dialog Provider           User Verification

Signature Verification Process

1. User clicks save/submit button
2. Controller checks if signature verification is required
3. If required, FormSignatureHelper shows signature dialog
4. User verifies identity (email/password)
5. On successful verification, callback executes actual save/submit
6. Form state is updated and user is notified

Benefits

• Security: Critical form operations require user verification
• Audit Trail: Signature events are logged with user identity and timestamp
• User Experience: Seamless integration with existing form workflows
• Flexibility: Configurable per entity type and operation type
• Fallback: Works gracefully when signature verification is not available