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](./05-orchestration-sla-escalation.md), 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](./07-backend-architecture.md#domain-events).