Driver Fee
Data Entity
Description
Stores the honorarium amount awarded to a peer mentor for providing transportation in a driver assignment. The fee amount is linked to organization-specific rate guidance and must be explicitly confirmed by the driver. Driver fees flow into the Xledger accounting export pipeline for Blindeforbundet reimbursement processing.
Data Structure
| Name | Type | Description | Constraints |
|---|---|---|---|
id |
uuid |
Unique identifier for the driver fee record, generated on creation. | PKrequiredunique |
driver_assignment_id |
uuid |
Foreign key reference to the driver_assignment record this fee belongs to. Enforces the one-to-one relationship: exactly one fee per assignment. | requiredunique |
organization_id |
uuid |
Foreign key to the organization that owns this fee record. Used for RLS scoping and Xledger export pipeline routing. | required |
amount |
decimal |
The honorarium amount in Norwegian kroner (NOK) awarded to the peer mentor driver. Stored with two decimal places. Must be positive and within the organization's configured rate guidance range. | required |
currency |
string |
ISO 4217 currency code for the honorarium amount. Defaults to 'NOK' for all Blindeforbundet operations. | required |
rate_basis |
enum |
Describes the basis on which the honorarium rate is calculated. Drives rate guidance display in the driver honorarium form. | required |
rate_guidance_reference |
string |
Human-readable reference to the organization rate guidance document or policy that anchors the amount (e.g., 'Blindeforbundet Sjåfærhonorar 2025'). Stored for audit transparency. | - |
acknowledged_by_user_id |
uuid |
User ID of the peer mentor driver who explicitly confirmed the fee amount. Required before the fee can be submitted to the accounting export pipeline. | - |
acknowledged_at |
datetime |
UTC timestamp of when the driver explicitly acknowledged the fee amount. Null until acknowledgement. After this is set, the fee is locked for accounting export. | - |
export_status |
enum |
Tracks the Xledger accounting export lifecycle for this fee record. | required |
export_run_id |
uuid |
Reference to the accounting export run that included this fee. Null until the fee has been successfully exported to Xledger. | - |
exported_at |
datetime |
UTC timestamp when this fee was successfully exported to Xledger. Null until export completes. | - |
notes |
text |
Optional coordinator-supplied notes about this specific fee record (e.g., explanation for a custom rate deviation). | - |
created_by_user_id |
uuid |
User ID of the coordinator who created this fee record. Used for audit trail. | required |
created_at |
datetime |
UTC timestamp when the fee record was created. Set automatically on insert, immutable thereafter. | required |
updated_at |
datetime |
UTC timestamp of the last modification to this record. Updated automatically on every write. | required |
Database Indexes
idx_driver_fee_driver_assignment_id
Columns: driver_assignment_id
idx_driver_fee_organization_id
Columns: organization_id
idx_driver_fee_export_status
Columns: export_status
idx_driver_fee_organization_acknowledged
Columns: organization_id, acknowledged_at
idx_driver_fee_export_run_id
Columns: export_run_id
Validation Rules
amount_must_be_positive
error
Validation failed
driver_assignment_id_must_exist
error
Validation failed
acknowledged_at_after_created_at
error
Validation failed
currency_must_be_nok
error
Validation failed
rate_basis_enum_valid
error
Validation failed
custom_rate_basis_requires_notes
error
Validation failed
export_status_transition_valid
error
Validation failed
acknowledged_by_must_be_driver
error
Validation failed
Business Rules
one_fee_per_assignment
Each driver_assignment record may have exactly one associated driver_fee record. Creating a second fee for the same assignment must be rejected at the database level via the unique constraint on driver_assignment_id.
acknowledgement_required_before_export
A driver fee record with a null acknowledged_at must never be included in an Xledger accounting export run. The export_status must be 'pending_export' (i.e., acknowledgement complete) before the fee is eligible for export.
amount_locked_after_acknowledgement
Once the driver has acknowledged the fee (acknowledged_at is set), the amount and rate_basis fields become immutable. Any attempt to update these fields after acknowledgement must be rejected.
driver_feature_flag_required
Driver fee records may only be created for organizations with the driver feature flag enabled. The UI guard (driver-feature-flag-guard) prevents form access, and the service layer validates the flag before any write operation.
amount_within_org_rate_guidance
The fee amount must fall within the organization's configured honorarium rate guidance range. A custom rate_basis value requires coordinator notes to justify the deviation.
export_idempotency
A fee record with export_status 'exported' must never appear in a subsequent export run. The double-export-guard filters exported fees before building each export payload.
cascade_delete_with_assignment
When the parent driver_assignment record is soft-deleted or hard-deleted, the associated driver_fee record must be deleted or soft-deleted accordingly, provided it has not already been exported to Xledger.
organization_rls_scoping
All queries against driver_fee must be scoped to the requesting user's organization_id via Supabase Row-Level Security. Cross-organization fee access is prohibited.
CRUD Operations
Storage Configuration
Entity Relationships
Each driver assignment has exactly one fee record storing the agreed honorarium amount and acknowledgement status