Define ApprovalWorkflowService FSM interface and state types
epic-expense-approval-workflow-core-logic-task-001 — Define the Dart abstract interface and sealed state classes for the ApprovalWorkflowService finite state machine. Enumerate all valid claim states (draft, submitted, approved, rejected, exported) and all permitted transition inputs. Establish the ClaimTransitionResult type that callers receive after each operation.
Acceptance Criteria
Technical Requirements
Implementation Notes
Use Dart 3 sealed classes for both ClaimState and ClaimTransitionResult to enable exhaustive pattern matching at all call sites — this is the primary design goal. Place all types in lib/src/approval_workflow/approval_workflow_types.dart. Use freezed or hand-written copyWith/== if immutability is required downstream — prefer hand-written for this low-complexity task to avoid code generation overhead at this stage. The ApprovalWorkflowService abstract class should be in a separate file lib/src/approval_workflow/approval_workflow_service.dart.
Document each state with a brief dartdoc comment explaining which transitions are valid from that state — this serves as the FSM specification for implementers of subsequent tasks.
Testing Requirements
Unit tests (flutter_test): verify pattern matching exhaustiveness — write a switch expression over ClaimState with all 5 subtypes and assert the Dart compiler requires all cases (no default). Verify ClaimTransitionResult can be pattern-matched for success/failure. Verify ClaimTransitionFailureReason enum has exactly the specified values. No mocking required — these are pure type definitions.
The ThresholdEvaluationService is described as shared Dart logic used both client-side and in the Edge Function. Supabase Edge Functions run Deno/TypeScript, not Dart, meaning the threshold logic must be maintained in two languages and can diverge, causing the server to reject legitimate client submissions.
Mitigation & Contingency
Mitigation: Implement the threshold logic as a single TypeScript module in the Edge Function and call it via a thin Dart HTTP client wrapper for client-side preview feedback only. The server is always authoritative; the client version is purely for UX (showing the user whether their claim will auto-approve before they submit).
Contingency: If dual-language maintenance is unavoidable, create a shared golden test file (JSON fixtures with inputs and expected outputs) that is run against both implementations in CI to detect divergence immediately.
A peer mentor could double-tap the submit button or a network retry could trigger a duplicate submission, causing the ApprovalWorkflowService to attempt two concurrent state transitions from draft→submitted for the same claim, potentially resulting in two audit events or conflicting statuses.
Mitigation & Contingency
Mitigation: Implement idempotency in the ApprovalWorkflowService using a database-level unique constraint on (claim_id, from_status, to_status) per transition, combined with a UI-level submission lock (disable button after first tap until response returns).
Contingency: Add a deduplication check at the start of every state transition method that returns the existing state if an identical transition is already in progress or completed within the last 10 seconds.
Claims with multiple expense lines (e.g., mileage + parking) must have their combined total evaluated against the threshold. If individual lines are added asynchronously or the evaluation runs before all lines are persisted, the auto-approval decision may be computed on an incomplete set of expense lines.
Mitigation & Contingency
Mitigation: The Edge Function always fetches all expense lines from the database (not from the client payload) before computing the threshold decision. Define a clear claim submission contract that requires all expense lines to be persisted before the submit action is called.
Contingency: Add a validation step in ApprovalWorkflowService that counts expected vs. persisted expense lines before allowing the transition, returning a validation error if lines are missing.