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

[smarcetic]

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)

[smarcetic]

Design Summary — Solutions Architect

Branch: design/4-ticket-intake-form
ADR: ADR-0005 — Intake Form Templating

---

Decision

Serve the intake form via Jinja2Templates mounted in api/main.py at GET /. The form submits via vanilla JavaScript fetch() posting application/json to the existing POST /triage endpoint.

Why This Approach

Concern	Decision
HTML rendering	Jinja2 template (api/templates/intake.html) — keeps markup out of Python code
Form submission	fetch() POST with Content-Type: application/json — POST /triage is unchanged
New dependencies	jinja2>=3.1.0 only — no python-multipart, no JS build pipeline
Architecture layer	Transport concern only — lives entirely in api/; domain and application layers untouched

No New Protocol Interfaces Required

The form is a pure transport concern. The Separation of Concerns principle (ADR-0001) holds: the classification pipeline does not know or care how a request arrives. No new application/interfaces.py stubs are needed.

Data Contract — Locked

POST /triage request and response shapes are unchanged from ADR-0001:

• Request: HelpRequest (request_id, submitted_by, date_submitted, subject, description, account_id)
• Response: TriageResult (classification, rationale, confidence, resolution, follow_up_question, meta, ticket_id)

Files Changed by Implementation

pyproject.toml                             ← add jinja2>=3.1.0
src/triage_assistant/api/main.py           ← mount Jinja2Templates + add GET / route
src/triage_assistant/api/templates/        ← new directory
src/triage_assistant/api/templates/intake.html  ← new file

Acceptance Criteria Traceability

AC	Addressed by
AC-1 Happy path	fetch() call + JS renders TriageResult fields on success
AC-2 Client-side validation	HTML5 required attributes + JS pre-submit guard
AC-3 Error path	fetch() catch block renders error message; no stack trace exposed
AC-4 No new build pipeline	Jinja2 (Python-native) + vanilla JS — no npm, no bundler
AC-5 Required fields	Form inputs map 1:1 to HelpRequest fields

---

Handoff to test writer: Please write failing tests for the new GET / route before implementation begins. Tests should cover:

1. GET / returns HTTP 200 with text/html content type
2. The rendered HTML contains all 6 HelpRequest field inputs
3. No regression on existing POST /triage and GET /health routes