Driver Leg Status + BOL/POD QA Matrix

Scope

This matrix validates the trucking driver flow and recent backend/mobile changes for:

• Leg status progression: assigned -> en_route -> loaded -> in_transit -> delivered
• BOL/POD enforcement modes (strict and flexible)
• Override reason capture and exception reporting
• Task auto-complete from media uploads
• BOL/POD history behavior
• Offline queue + replay for failed status transitions

Environments

• Mobile app: attunelogic-mobile
• API: attunelogic-api
• App type: trucking
• Test tenants:
  • Tenant A: tasks.bolPodEnforcement.mode = flexible
  • Tenant B: tasks.bolPodEnforcement.mode = strict

Pre-Test Setup

1. Ensure a driver user exists and is assigned to a job with at least one leg.
2. Ensure test leg begins in assigned.
3. Prepare two task templates on leg flow:
   • BOL-related task (pickup) and POD-related task (delivery)
   • Mark required/signature flags according to test case.
4. Set config variants by tenant:
   • tasks.bolPodEnforcement.mode
   • tasks.bolPodEnforcement.requireOverrideReason
   • tasks.autoCompleteOnMediaUpload.enabled
   • tasks.autoCompleteOnMediaUpload.mappings
5. For offline tests, disable network on test device after opening the leg.

Matrix

ID	Area	Scenario	Steps	Expected Result
Q1	Status Flow	Happy path with docs present	Upload BOL, move to loaded; upload POD, move to delivered	All transitions succeed; success alerts shown; leg status updates correctly
Q2	Status Flow	Verify en_route step exists	From assigned, tap first CTA	Status becomes en_route; next CTA becomes pickup confirmation
Q3	Flexible Policy	Missing BOL at loaded without override	In flexible tenant, do not upload BOL; attempt loaded	API returns conflict requiring override; app prompts for override reason
Q4	Flexible Policy	Missing BOL at loaded with override	Select override reason and continue	Transition succeeds; exception reported; status history includes override metadata
Q5	Flexible Policy	Missing POD at delivered with override	Do not upload POD; proceed with override reason	Transition succeeds; exception entry saved for POD override
Q6	Strict Policy	Missing BOL in strict tenant	Do not upload BOL; attempt loaded	API blocks transition (conflict); no status change
Q7	Strict Policy	Missing POD in strict tenant	Do not upload POD; attempt delivered	API blocks transition (conflict); no status change
Q8	Tasks	Required signature task blocks	Keep required BOL/POD signature task incomplete	App blocks transition and prompts signature capture
Q9	Tasks	Signature capture completes task	Capture signature from prompt	Signature saved; linked task marked complete; transition can proceed
Q10	Auto-Complete	Media upload auto-completes mapped tasks	Enable autoCompleteOnMediaUpload; upload BOL/POD files	Matching tasks complete automatically using mapping aliases
Q11	Auto-Complete	Alias mapping support	Use custom mapping alias in tenant config	Task still auto-completes without default template name
Q12	Media Model	Multi-upload BOL history	Upload BOL twice	bol points to latest; bolHistory contains both in order
Q13	Media Model	Multi-upload POD history	Upload POD multiple times	pod points to latest; podHistory contains all entries
Q14	Exception API	Manual exception reporting endpoint	Call POST /legs/:id/exception with code/reason	200 success; exception appended to leg; timeline/audit entry added
Q15	Offline Retry	Failed transition queued and replayed	Disable network; attempt transition; restore network and reopen leg	Pending update is queued, replayed, then queue entry cleared
Q16	Cache/Refresh	Leg media refresh after signature upload	Upload signature BOL/POD and return to document view	Leg media reflects new document without stale state

API Verification Checklist

• Status update endpoint:
  • GET /api/v1/legs/:id/status?status=<value>
  • Validate behavior for:
    • missing required media (strict/flexible)
    • override flags (missingDocsOverride, overrideReason, overrideSource)
• Completion endpoint:
  • GET /api/v1/legs/:id/complete
  • Validate same enforcement behavior for delivery completion
• Exception endpoint:
  • POST /api/v1/legs/:id/exception
  • Payload example:
    • code: missing_required_document_override
    • reason: selected driver reason
    • status: target status
    • docType: bol or pod

Mobile Verification Checklist

• DriverLoadActions:
  • Correct CTA order and labels by status
  • Override reason prompt shown only when required
  • Correct error handling and retry messaging
• Task interactions:
  • Required signature tasks block correctly
  • Signature capture unblocks progression
• Offline behavior:
  • Queued transition survives app state changes
  • Replay happens when connectivity returns

Regression Checklist

• Existing legs with legacy status aliases still normalize and transition correctly.
• Non-trucking app type behavior remains unchanged.
• Existing task templates continue to function if mappings are not customized.
• Shift/break behavior remains unaffected by leg status and BOL/POD changes.

Exit Criteria

• All matrix cases Q1-Q16 pass in at least one staging run.
• No blocker/critical defects in status transitions or document enforcement.
• Strict and flexible tenant modes both validated and documented.
• Support notes prepared for dispatch/operations on override reason handling.