US-012 · Ticket Intake Form — Field Contractor Support Submission #4

User Story

Persona: Field Contractor
Bounded Context: Incident Management / Support Triage

As a field contractor, I need a web form to submit a help request so that my issue is triaged and a ticket is created without me needing to call an API directly.

Background

The triage engine (POST /triage) was built to classify and route support tickets, but there is no user-facing intake surface. Field contractors currently have no way to submit a help request without calling the raw API. This violates the explicit challenge requirement:

"Determine how the request is first received (HTTP POST, Teams chat, Power BI form, email, file, etc.)"

This story closes that gap with a minimal web form served by the existing FastAPI application.

Acceptance Criteria

AC-1 — Happy path
Given a field contractor fills in all required fields and submits, then they see the triage classification, confidence score, resolution path, and their ticket ID on screen.

AC-2 — Client-side validation
Given a contractor leaves a required field blank and submits, then the form prevents submission and highlights the missing field before any API call is made.

AC-3 — Error path
Given the triage service returns an error (5xx), then the contractor sees a meaningful error message — not a blank page or raw stack trace.

AC-4 — No new dependencies
The form is served by the existing FastAPI application using Python-native templating. No separate JS build pipeline, no new service.

AC-5 — Required fields
The form captures exactly the fields defined in HelpRequest:

• request_id
• submitted_by
• date_submitted
• subject
• description
• account_id

Out of Scope

• Authentication / login
• File attachments
• Saved drafts
• Multi-step wizard

Definition of Ready Checklist

• User story follows INVEST
• Persona identified (Field Contractor)
• Bounded context identified (Support Triage → Incident Management)
• Acceptance criteria: happy path, boundary, error path
• Out of scope defined
• No ambiguous field names (maps directly to HelpRequest domain model)