support_backend/docs/04-ticketing-and-problem-management.md

04 — Ticketing & Problem Management

1. Ticket creation timing

The operational ticket/case is created at the very start of the support journey — not after AI fails. This preserves the complete interaction from the first moment: problem, diagnosis, knowledge used, AI messages, tool calls, failed attempts, customer actions, timestamps, evidence, and escalation history.

Example lifecycle

NEW → AI_ANALYZING → AI_TROUBLESHOOTING → AI_VERIFYING
   → AI_RESOLVED
       or
   → HUMAN_ESCALATION

2. Problem is first-class — separate from ticket

Ticket = the operational container tracking the interaction. Problem = the actual thing being solved, which can outlive and span multiple tickets.

Problem contains:

• Problem statement, symptoms, impact
• Product, feature, category, problem type
• Severity, customer impact, business impact
• Environment, evidence, related tickets

Recurring-problem support:

Problem → Ticket A
       → Ticket B
       → Ticket C

This lets SupportHub recognize "this is the same underlying problem occurring again" rather than treating every occurrence as unrelated.

3. Human support flow (post-escalation)

Ticket → Orchestration → Capability → Support Hierarchy → Team
       → Eligible Agents → Assignment → SLA
       → Investigation → Root Cause → Solution → Verification
       → Resolution → Closure

If an agent cannot solve the issue:

Current Support Node → Evaluate escalation rules → Target Support Node
                     → Target Team → Availability → Assignment → Continue SLA

4. Investigation (structured, not free-text notes)

Store:

• Investigator, timestamp
• Findings, evidence, internal notes, references
• Investigation status

Example:

Investigation: Payment service logs checked.
Finding: Webhook was received.
Finding: Payment processing failed.

5. Root cause — separate from investigation

Investigation is what was found. Root cause is why it happened, and is its own record.

Problem:      PDF conversion fails.
Investigation: Layout parser returns error.
Root Cause:   Parser cannot handle a specific table structure.

Root cause types to support: technical cause, configuration cause, external dependency cause, business cause, contributing factor.

6. Solution — proposed vs. implemented

Keep these distinct fields/states, not one blob:

• Proposed solution
• Approved solution
• Implemented solution
• Implementation notes
• Implemented by / implementation timestamp

Proposed:    Enable fallback parser.
Implemented: Fallback parser enabled and conversion retried.

7. Verification — after implementation

Solution → Verification

Verification types: automated, technical test, customer confirmation, agent confirmation.

If verification fails:

Verification → Investigation   (re-open investigation)
   or
Verification → Escalation      (escalate further)

8. Resolution — separate from solution

Solution = what was done. Resolution = the final outcome.

Solution:      Fallback parser enabled.
Verification:  HTML generated successfully.
Resolution:    Customer document successfully converted.

9. Customer confirmation & reopen

Configurable confirmation flow:

RESOLUTION_PENDING_CUSTOMER → Customer confirms → RESOLVED → CLOSED

or

RESOLVED → configured waiting period (auto-close) → CLOSED

Reopen must be supported — a customer or agent can reopen a closed ticket, which should re-enter the appropriate lifecycle stage (and, per 05, repeated reopens are themselves an escalation trigger).

10. Messages

Message types:

Type	Visible to customer?
CUSTOMER_MESSAGE	Yes
AI_MESSAGE	Yes
AGENT_MESSAGE	Yes
INTERNAL_NOTE	No — never
SYSTEM_EVENT	Depends on event (status changes typically yes)
INVESTIGATION_NOTE	No
SOLUTION_NOTE	No

Internal notes must never be shown to customers — enforce this at the API/serialization layer, not just in the UI.

11. Attachments

Supported types: screenshots, PDFs, logs, videos, documents.

Storage: object storage (S3-compatible in production, MinIO for local dev). Never store large binary files in PostgreSQL — store metadata + object storage reference only.

Required capabilities:

• File validation (type/size)
• Size limits (configurable, per product/tenant if needed)
• Malware scanning before the file is considered available
• Secure download via expiring, authorization-checked URLs
• Authorization scoped to the ticket's tenant/user context

12. Domain events emitted by this subsystem

TicketCreated, ProblemCreated, TicketClassified, InvestigationStarted, RootCauseIdentified, SolutionProposed, SolutionImplemented, VerificationCompleted, TicketResolved, TicketClosed, TicketReopened. Full event catalog and consumers are in 07 — Backend Architecture.