106 lines
4.4 KiB
Markdown
106 lines
4.4 KiB
Markdown
# OCR Review Workflow Specification
|
|
|
|
## Purpose
|
|
|
|
Define authenticated review, atomic correction, activation, and retention.
|
|
|
|
## Requirements
|
|
|
|
### Requirement: Mandatory Authenticated Review
|
|
|
|
OCR versions MUST remain `review_required` and non-retrievable until approved. Status, review, images, approval, and rejection MUST require the administrator token.
|
|
|
|
#### Scenario: Reviewer inspects a candidate
|
|
|
|
- GIVEN all documents passed the version gate
|
|
- WHEN an authorized reviewer opens review
|
|
- THEN it MUST show image, native text, raw OCR, boxes, confidence, differences, and risks
|
|
|
|
#### Scenario: Unauthorized or premature access
|
|
|
|
- GIVEN credentials fail or the version is not reviewable
|
|
- WHEN review or decision is requested
|
|
- THEN it MUST reject the request without exposing artifacts or changing state
|
|
|
|
### Requirement: Atomic Optimistic Corrections
|
|
|
|
Approval MUST validate `candidateSha256`, unique line identities, and every `expectedLineSha256` before changes. Reviewed text SHALL be immutable.
|
|
|
|
#### Scenario: Valid corrections commit together
|
|
|
|
- GIVEN hashes are current and correction targets are unique
|
|
- WHEN approval is submitted
|
|
- THEN all replacements MUST commit together with reviewer, time, and resulting hashes
|
|
|
|
#### Scenario: Stale or conflicting correction
|
|
|
|
- GIVEN any candidate, line, identity, or box is stale or duplicated
|
|
- WHEN approval is submitted
|
|
- THEN the system MUST return `409` without corrections or state transition
|
|
|
|
### Requirement: Approval and Activation Gate
|
|
|
|
Approval MUST cover the version, derive final hashes, and move `review_required` to `indexing` before chunking. Activation SHALL use Point 2 verification and the expected active version.
|
|
|
|
#### Scenario: Approved content becomes active
|
|
|
|
- GIVEN corrections are valid and the expected active version is current
|
|
- WHEN indexing and point verification succeed
|
|
- THEN the new version MUST become active atomically and the previous one superseded
|
|
- AND only reviewed content MAY be retrieved
|
|
|
|
#### Scenario: Active version changes during review
|
|
|
|
- GIVEN another version activates during review
|
|
- WHEN approved indexing completes
|
|
- THEN the candidate MUST remain `ready`, return `409 ACTIVE_VERSION_CHANGED`, and not replace it
|
|
|
|
#### Scenario: Reusable content already exists
|
|
|
|
- GIVEN final content, fingerprint, and metadata match a reusable version
|
|
- WHEN approval checks the active-version precondition
|
|
- THEN the candidate MUST be `rejected` with `DUPLICATE_REUSABLE_VERSION`
|
|
- AND only the existing version MAY be activated
|
|
|
|
### Requirement: Rejection and Failure Isolation
|
|
|
|
Rejection MUST produce `rejected`, preserve temporary audit evidence, and generate no embeddings. Failed or rejected candidates SHALL never alter the active version.
|
|
|
|
#### Scenario: Reviewer rejects candidate
|
|
|
|
- GIVEN a version is `review_required`
|
|
- WHEN an authorized reviewer rejects it
|
|
- THEN it MUST become `rejected` with audit data and no indexing
|
|
|
|
### Requirement: Retention Safety
|
|
|
|
Private artifacts MUST use `0600` permissions and verifiable hashes. The system MUST retain review 30 days, failed/rejected artifacts 7 days, review images 7 days post-decision, OCR copies until transfer or 24 hours, and active artifacts until 30 days after supersession. Cleanup MUST be idempotent and never delete active versions.
|
|
|
|
#### Scenario: Review expires
|
|
|
|
- GIVEN a version remains `review_required` for 30 days
|
|
- WHEN daily retention runs exclusively
|
|
- THEN it MUST become `rejected` with `REVIEW_EXPIRED` before removal
|
|
|
|
#### Scenario: Active artifacts are protected
|
|
|
|
- GIVEN an active version is past a TTL
|
|
- WHEN retention runs concurrently with review or purge
|
|
- THEN its original, reviewed text, raw OCR, and manifest MUST remain
|
|
- AND cleanup MUST not escape the version directory or expose a public URL
|
|
|
|
#### Scenario: Interrupted cleanup resumes
|
|
|
|
- GIVEN deletion stopped after retention entered its deleting state
|
|
- WHEN cleanup runs again
|
|
- THEN deletion MUST resume safely and finish in the deleted state without affecting other versions
|
|
|
|
### Requirement: Human-Approved Production Acceptance
|
|
|
|
The release MUST prove corrected content after approval; confidence SHALL NOT authorize activation.
|
|
|
|
#### Scenario: FacturaTech acceptance succeeds
|
|
|
|
- GIVEN the real FacturaTech PDF has been reviewed and its 34 entries approved
|
|
- WHEN the version becomes active and retrieval is queried
|
|
- THEN all 34 entries and `CBG04a`, `FAT07`, `DSAU08`, and `NSAV06` MUST be returned exactly
|