feat: Backend OCR manual proxy endpoint (#129) #135

New Issue

egullickson · 2026-02-11T03:04:59Z

egullickson commented

2026-02-11 03:04:59 +00:00

Relates to #129

Milestone 6: Backend OCR Manual Proxy Endpoint

Add backend proxy endpoint for manual extraction that triggers async Gemini processing.

Files

backend/src/features/ocr/domain/ocr.types.ts
backend/src/features/ocr/external/ocr-client.ts
backend/src/features/ocr/domain/ocr.service.ts
backend/src/features/ocr/api/ocr.controller.ts
backend/src/features/ocr/api/ocr.routes.ts

Requirements

Add ManualExtractionResponse and ManualJobResponse types matching Python API response
Add OcrClient.submitManualJob() method that POSTs to Python /extract/manual
Add ocrService.submitManualJob() with file validation (200MB max, PDF only)
Add OcrController.extractManual() handler for async job submission
Add POST /api/ocr/extract/manual route with auth + tier guard for document.scanMaintenanceSchedule
Reuse existing GET /api/ocr/jobs/:jobId for manual job polling

Acceptance Criteria

POST /api/ocr/extract/manual with PDF returns 202 with jobId
Non-Pro users get 403 TIER_REQUIRED response
POST with non-PDF file returns 400
POST with file > 200MB returns 413
GET /api/ocr/jobs/:jobId returns manual job progress and result when completed
Completed result includes maintenanceSchedules array

Tests

Test files: backend/src/features/ocr/tests/unit/ocr-manual.test.ts (NEW)
Test type: unit (mock OcrClient)
Scenarios:
- Normal: PDF submission returns 202 with jobId
- Normal: Job poll returns completed result with schedules
- Edge: Tier gating blocks free users
- Error: Non-PDF file, oversized file, empty file

Relates to #129 ## Milestone 6: Backend OCR Manual Proxy Endpoint Add backend proxy endpoint for manual extraction that triggers async Gemini processing. ### Files - `backend/src/features/ocr/domain/ocr.types.ts` - `backend/src/features/ocr/external/ocr-client.ts` - `backend/src/features/ocr/domain/ocr.service.ts` - `backend/src/features/ocr/api/ocr.controller.ts` - `backend/src/features/ocr/api/ocr.routes.ts` ### Requirements - Add `ManualExtractionResponse` and `ManualJobResponse` types matching Python API response - Add `OcrClient.submitManualJob()` method that POSTs to Python `/extract/manual` - Add `ocrService.submitManualJob()` with file validation (200MB max, PDF only) - Add `OcrController.extractManual()` handler for async job submission - Add `POST /api/ocr/extract/manual` route with auth + tier guard for `document.scanMaintenanceSchedule` - Reuse existing `GET /api/ocr/jobs/:jobId` for manual job polling ### Acceptance Criteria - [ ] POST /api/ocr/extract/manual with PDF returns 202 with jobId - [ ] Non-Pro users get 403 TIER_REQUIRED response - [ ] POST with non-PDF file returns 400 - [ ] POST with file > 200MB returns 413 - [ ] GET /api/ocr/jobs/:jobId returns manual job progress and result when completed - [ ] Completed result includes maintenanceSchedules array ### Tests - **Test files**: `backend/src/features/ocr/tests/unit/ocr-manual.test.ts` (NEW) - **Test type**: unit (mock OcrClient) - **Scenarios**: - Normal: PDF submission returns 202 with jobId - Normal: Job poll returns completed result with schedules - Edge: Tier gating blocks free users - Error: Non-PDF file, oversized file, empty file

egullickson added the

labels 2026-02-11 03:12:41 +00:00

egullickson added

and removed

labels 2026-02-11 16:32:47 +00:00

egullickson commented

2026-02-11 16:37:34 +00:00

Milestone: Backend OCR Manual Proxy Endpoint

Phase: Execution | Agent: Developer | Status: PASS

Changes Made

Types (ocr.types.ts):

Added ManualJobSubmitRequest, ManualVehicleInfo, MaintenanceScheduleItem, ManualExtractionResult, ManualJobResponse types matching Python API response format

Client (ocr-client.ts):

Added OcrClient.submitManualJob() method that POSTs to Python /extract/manual with PDF file + optional vehicle_id

Service (ocr.service.ts):

Added OcrService.submitManualJob() with PDF-only validation (400) and 200MB file size limit (413)

Controller (ocr.controller.ts):

Added OcrController.extractManual() handler with file reading, empty file check, content type validation, and 202 async response

Routes (ocr.routes.ts):

Added POST /api/ocr/extract/manual with requireAuth + requireTier({ featureKey: 'document.scanMaintenanceSchedule' })
Existing GET /api/ocr/jobs/:jobId reused for manual job polling

Tests (ocr-manual.test.ts):

10 unit tests: PDF submission, vehicleId passing, completed result with maintenanceSchedules, non-PDF rejection (JPEG/PNG/text), oversized file, 200MB boundary, OCR error propagation

Quality Checks

Lint: 0 errors (existing warnings only)
Type-check: PASS
Tests: 10/10 PASS (new) + 9/9 PASS (existing receipt tests)

Verdict: PASS | Commit: a281cea

## Milestone: Backend OCR Manual Proxy Endpoint **Phase**: Execution | **Agent**: Developer | **Status**: PASS ### Changes Made **Types** (`ocr.types.ts`): - Added `ManualJobSubmitRequest`, `ManualVehicleInfo`, `MaintenanceScheduleItem`, `ManualExtractionResult`, `ManualJobResponse` types matching Python API response format **Client** (`ocr-client.ts`): - Added `OcrClient.submitManualJob()` method that POSTs to Python `/extract/manual` with PDF file + optional `vehicle_id` **Service** (`ocr.service.ts`): - Added `OcrService.submitManualJob()` with PDF-only validation (400) and 200MB file size limit (413) **Controller** (`ocr.controller.ts`): - Added `OcrController.extractManual()` handler with file reading, empty file check, content type validation, and 202 async response **Routes** (`ocr.routes.ts`): - Added `POST /api/ocr/extract/manual` with `requireAuth` + `requireTier({ featureKey: 'document.scanMaintenanceSchedule' })` - Existing `GET /api/ocr/jobs/:jobId` reused for manual job polling **Tests** (`ocr-manual.test.ts`): - 10 unit tests: PDF submission, vehicleId passing, completed result with maintenanceSchedules, non-PDF rejection (JPEG/PNG/text), oversized file, 200MB boundary, OCR error propagation ### Quality Checks - Lint: 0 errors (existing warnings only) - Type-check: PASS - Tests: 10/10 PASS (new) + 9/9 PASS (existing receipt tests) *Verdict*: PASS | *Commit*: `a281cea`

egullickson referenced this issue from a commit

2026-02-11 21:27:47 +00:00

feat: add backend OCR manual proxy endpoint (refs #135)

egullickson referenced a pull request that will close this issue

2026-02-11 21:28:11 +00:00

feat: Expand OCR with fuel receipt scanning and maintenance extraction (#129) #147

egullickson closed this issue

2026-02-13 02:25:56 +00:00

Sign in to join this conversation.