# Interview Workflows (AI Interview Module)

Matches the Interview Module: Setup → Persona → Questions → Scheduling handoff.

## Replaces

Ephemeral `POST /interview-preview/*` and `POST …/preview` were **removed**.

Live interview **sessions** are owned by Platform. Gateway final evaluation is mode-aware and persisted:

- `POST /interviews/final-evaluation` — requires `candidate_id` + `interview_id` + `interview_mode` (`interview_type` alias). Text scores answers directly; voice runs STT; video runs video-intelligence (+ transcript). Creates a **processing** row first; marks **completed only after** structured results are saved. Failures stay `failed` (never PDF-ready).
- `GET /interviews/final-evaluation/status?candidate_id=&interview_id=` — poll status / errors; scores only when completed.
- `POST /reports/evaluation-pdf` — **deterministic** PDF from a completed saved evaluation only (no re-score, no invented feedback).

Questions are authored here (`questions/generate` + `questions/batch`). Pass `personaId` on generate so questions match the interviewer persona. Platform selects and saves `mode` (`text` | `voice` | `video`) before the interview starts, then passes the same `interview_mode` into final-evaluation.

**Source of truth:** persisted `workflowId`. Path `{id}` also resolves by `interviewId` for the tenant.

## APIs (`/api/v1`)

| Method | Path | Purpose |
|--------|------|---------|
| POST | `/interview-workflows` | Create draft setup (`mode`: text\|voice\|video) |
| GET | `/interview-workflows/{id}` | Load saved workflow (by `workflowId` or `interviewId`) |
| PATCH | `/interview-workflows/{id}` | Update setup / persona / mode |
| POST | `/interview-workflows/{id}/questions/generate` | AI questions for `personaId`; optional `candidateId`/resume via ResumeService |
| POST | `/interview-workflows/{id}/questions/batch` | Create, update, delete, reorder custom questions |

### Generate body

```json
{
  "personaId": "183f7121-8d2c-4782-95be-5b0d27d9f956",
  "questionCount": 5,
  "questionTypes": ["technical", "scenario"],
  "replaceExisting": true,
  "candidateId": "cand-jane-001"
}
```

`personaId` is required — UUID from `POST /personas` or a built-in id (`technical`, …). Optional `candidateId` / `resumeText` / `resumeStructured` load a shared resume profile (see `docs/RESUME_SERVICE.md`).

### Batch body

```json
{
  "create": [{ "text": "...", "questionType": "short_answer" }],
  "update": [{ "questionId": "q-…", "text": "…" }],
  "delete": ["q-…"],
  "reorder": ["q-…", "q-…"]
}
```

Applied as **delete → update → create → reorder**. At least one section required.

### Modes

| Mode | Meaning |
|------|---------|
| `text` | Written answers |
| `voice` | Transcribed spoken answers (+ audio evidence when supplied) |
| `video` | Transcripts + authorized A/V evidence when available |

Scheduling, invitations, and candidate assignment stay on Platform.

## Tables

- `interview_workflows`
- `interview_workflow_questions`

Alembic: `b2c3d4e5f6a7` · also created via `ensure_schema()`.
