# Shared ResumeService

Central resume fetch, parse, normalize, versioned storage, and profile retrieval.

API entry for resume **inputs** (file / text / candidate_id validation) is
`ResumeInputProcessor` — see [`RESUME_INPUT.md`](./RESUME_INPUT.md).

## Why

Previously each flow re-accepted `resume_text` / `resume_structured` and often
re-ran `structure_resume` (or expected clients to call `/documents/parse` first).
There was no durable profile keyed by `candidate_id`.

## API surface

### Internal

`app.services.screening.resume_service.ResumeService`

- `resolve(...)` — fetch/parse or reuse; optional persist by `candidate_id`
- `get_profile(candidate_id)` — latest stored version

Uses `DocumentsService.parse` **in-process** (never HTTP self-calls).

### HTTP

`POST /api/v1/documents/parse` with `parse_target=resume` + `candidate_id`:

- First call: parse + save profile (`resume_reused=false`)
- Same content again: reuse stored profile (`resume_reused=true`)

Response extras (backward compatible): `candidate_id`, `resume_profile_id`,
`resume_version`, `resume_reused`.

## Versioning

Table `candidate_resume_profiles`:

- Unique `(candidate_id, content_hash)` — same upload/text reuses the row
- `resume_version` increments when content changes for that candidate
- Latest version is current for `get_profile` / resolve-without-media

## Integrated flows

| Flow | Integration |
|------|-------------|
| `/documents/parse` | Resume + `candidate_id` → ResumeService |
| `/resume-match/score` | Resolve by text/media/`candidate_id` |
| `/prep-plans/generate` | Resolve before gap inference |
| `/job-matching/recommend` | Hydrate skills from profile; jobs from Platform `job_catalog` only |
| `/interview-workflows/.../questions/generate` | Optional `candidateId` / resume fields |
| `QuestionsService.generate_from_role` | Resolve before prompt |
| Skill-gap / hiring-fit / profiles (services) | Resolve when resume/candidate present |

## Reuse rules

1. `candidate_id` + same `content_hash` → return stored (no GPT/parse)
2. `candidate_id` + no new media/text → return latest stored
3. New content → parse/normalize → save new version
