pfm-ocr/docs/api-contract-map.md

Flutter ↔ Backend API Contract Map

Written 2026-07-10 from a full read of both sides of the wire (every Flutter call site in lib/ and every backend route it touches). This is the context document for plans/next-enhancements.md sections 6-7 (Flutter) and backend/plans/next-enhancements.md section 9 (backend counterparts) — read it before picking up any of those tasks. Gap IDs (G1-G10) below are referenced from the task entries so a future session can trace a task back to the evidence.

Endpoint inventory (what the app actually calls)

#	Flutter call site	Method + path	Auth	Backend route
1	auth_provider.dart login()	POST /api/v1/auth/login	none (issues token)	api/v1/auth/login/route.ts
2	auth_provider.dart checkLoginState()	GET /api/v1/auth/me	Bearer	api/v1/auth/me/route.ts
3	pending_documents_provider.dart _uploadAndProcess	POST /api/v1/documents/upload (multipart: image, latitude?, longitude?, scan_mode)	Bearer, 401 enforced	api/v1/documents/upload/route.ts
4	pending_documents_provider.dart _pollUntilParsed (every 2s, ≤130×) and documents_screen.dart _loadDocuments	GET /api/v1/documents	Bearer, 401 enforced	api/v1/documents/route.ts
5	editor_screen.dart save, product_editor_logic.dart _submit, pending_documents_provider.dart retrySync	PUT /api/v1/documents/:id (toPutPayload())	Bearer, 401 + per-store 403	api/v1/documents/[id]/route.ts
6	product_editor_logic.dart _fetchClassificationAndSkus	GET /api/skus — via apiBaseUrl.replaceAll('/api/v1', '/api/skus')	none (classic dev route)	api/skus/route.ts
7	product_editor_logic.dart _fetchClassificationAndSkus	POST /api/scan-pfm (JSON {image_base64}) — same base-URL string hack	none (classic dev route)	api/scan-pfm/route.ts
8	app_config.dart _isBackendReachable (startup probe)	POST /api/v1/auth/login with {}	none	same as #1

Base URL: AppConfig.apiBaseUrl resolved once at startup (LAN first, ngrok fallback), frozen into the singleton Dio client (api_client.dart:13). Timeouts: connectTimeout 10s, receiveTimeout 240s (sized for upload's synchronous 210s-worst-case parse; every other call inherits it).

Response envelopes

• v1 success: { status: "success", message?, data: ... } — Flutter reads response.data['data'].
• v1 error: { status: "error", error: { statusCode, code, message } } (utils/api-error.ts → lib/http-status.ts), mirrored by lib/core/network/api_exception.dart (ApiException.fromDioException). These two are deliberately kept in sync — keep it that way.
• Classic routes: ad-hoc shapes — GET /api/skus returns { skus: [...] }, POST /api/scan-pfm returns a flat { classification, ocr, possibleMatches, layoutParsingResult }. No envelope, no auth, CORS-open.

The DO document lifecycle (happy path, as implemented)

1. Capture → blur check → addDocument() persists a PendingDocument to Hive (uploading) → multipart POST to /documents/upload with scan_mode ('DO' or 'Product' from scanModeProvider).
2. Upload route: dedups by file_hash+kode_toko; inserts documents row (parsed=false); synchronously calls internal /api/parse (210s abort); parse writes metadata JSONB + ocr_items rows and sets parsed=true. Response data is a stub DocumentModel (real id, empty header/items).
3. Client flips item to processing and polls GET /documents every 2s, looking for its id in the full list with parsed==true (the list endpoint filters WHERE parsed = true, so "appears in list" is the parse-done signal).
4. On success the pending card routes to /editor (or /product-editor when scanMode == 'Product') with pendingId passed as state.extra.
5. Editor save: builds DocumentModel (id = _document?.id ?? pendingId ?? now-ms), saves to Hive documentBox, PUT /documents/:id; on success removes the pending item, on failure marks it syncFailed (retry = re-PUT via retrySync).
6. documents_screen._loadDocuments: shows Hive cache, then fetches the server list, clears the whole Hive box, and re-saves only server rows.

The PUT route writes metadata in both shapes (legacy web keys noPO/ customerInfo/… and mobile header/shipment sub-objects); the GET list maps whichever exists. DocumentModel.fromJson/toPutPayload match this contract.

Gaps found (G1-G10)

G1 — No GET /api/v1/documents/:id, and no parse status in the contract. api/v1/documents/[id]/route.ts only has PUT. The poller must fetch the entire list every 2s (server side: one documents query + one ocr_items query per document per poll — N+1 that grows with history size). Because the list filters parsed=true, the client cannot distinguish "still parsing" / "parse failed" / "not mine": a server-side parse failure (upload route swallows it, upload/route.ts:134) surfaces only as the client's generic 260s timeout ("Gagal mengekstrak data (Timeout)"). Match detection also relies on a Dart object identity trick (found != doc, pending_documents_provider.dart:133).

G2 — Product flow calls unauthenticated dev routes via URL string-hacking. product_editor_logic.dart:57,69 rewrites the base URL with .replaceAll('/api/v1', '/api/skus' | '/api/scan-pfm'). Those classic routes are documented (backend/CLAUDE.md) as dev-only, never-authed, and not part of the production surface; backend task 4.5 (shipped) restricts the public ngrok tunnel to /api/v1/*, so both calls are expected to fail off-LAN. The existing v1 alternative GET /api/v1/master/skus is admin-only (403 for store accounts) and uses a different envelope ({status,data} vs {skus}), so the client can't just switch paths.

G3 — RESOLVED 2026-07-10 (root task 7.2 / backend task 11.1). Double classification per product scan. Upload with scan_mode=Product already ran the classifier inside /api/parse and stored only the top-1 SKU as the document's single item. The product editor then re-read the image file, base64-encoded it (~MBs through Dio JSON), and re-ran the whole classify+OCR pipeline via /api/scan-pfm — ignoring the stored parse result except as a lat/lng fallback. Two GPU passes per photo; the reviewed result could disagree with the stored one. Fixed by having /api/parse's Product branch call the same shared classifyAndMatchProduct() used by POST /api/v1/scan-product (task 9.3) and persist the full result (top-5 possibleMatches + OCR extractedExpiryDate) in documents.metadata.productScan, surfaced by document-mapper.ts. The editor now reads this directly from the document instead of re-classifying — one GPU pass per photo, editor opens instantly like DO Scan's does.

G4 — Product documents are typed by magic strings, scan_mode is never persisted. The backend fabricates placeholder metadata for product scans (PO-PRODUCT-001, noSO 1002003004, DO-PRODUCT-999, plat B 1234 PFM, order_untuk: "PRODUCT SCAN" — parse/route.ts:107-135) and the Flutter side detects "is a product doc" by orderUntuk == 'PRODUCT SCAN' (documents_screen.dart:110, product_editor_logic.dart:36). scan_mode is sent at upload and forwarded to parse but never stored in documents nor returned by GET, and DocumentModel has no doc-type field. Editing orderUntuk silently moves a doc between tabs.

G5 — PUT to a client-generated ID can never succeed. Both editors fall back to finalDoc.id = widget.pendingId ?? now-ms when _document is null (e.g. pendingId no longer found in the provider — the orElse stub at product_editor_logic.dart:26 makes this reachable). The PUT then targets /documents/<13-digit ms timestamp>; the backend parseInts it into a value that can't match (or even fit) the int4 documents.id → 404/500 → the item is stuck in syncFailed and every retry re-fails identically.

G6 — Server refresh wipes locally-saved-but-unsynced documents. After a failed PUT the editors keep the corrected doc in Hive (saveDocument(finalDoc)) and mark the pending item syncFailed — but documents_screen._loadDocuments (documents_screen.dart:55) does documentBox.clear() and refills from the server list, deleting the local-only copy from history. Recovery survives only via the pending item's embedded document; the history list lies in between.

G7 — Mock data presented as real data in the product editor. Offline/error fallback fabricates three hardcoded SKU "matches" with fake confidences (product_editor_logic.dart:116-126) and fake batch/expiry dates ('15/12/2026','20/04/2027' — also used whenever OCR extracted no expiry date, line 103). A reviewer cannot tell mock from model output. AGENTS.md §5 wants mock data behind an explicit Demo/Live switch, not silently inlined in the live path.

G8 — Route params ride on state.extra. /editor and /product-editor receive pendingId via GoRoute state.extra (app_router.dart:34,41), which does not survive process death/state restoration and can't be deep-linked; a restored editor gets pendingId == null and renders empty (feeding G5).

G9 — checkLoginState error handling is string-typed and fail-open. auth_provider.dart:30 detects 401 by e.toString().contains('401') instead of ApiException.from(e).statusCode, and any other failure (timeout, 500, dead tunnel) silently keeps the user "logged in" with a possibly-stale profile in SharedPreferences. Plan task 1.1's original claim ("never pings the server") is stale — /auth/me is called now; the residual gap is this fragile detection.

G10 — Dedup response is a second, emptier stub. A duplicate upload returns the original document's id with empty header/items and no parsed flag (upload/route.ts:75-96); the client treats it as fresh and re-polls. Works if the original parsed; if the original's parse failed (G1), the second client also burns the full 260s timeout. Low severity on its own — folds into G1's fix.

G11 — No draft/confirmed distinction — parsed triggers list visibility, not user confirmation. GET /api/v1/documents filters WHERE parsed = true. parsed is set the instant the backend's OCR pass finishes (api/parse/route.ts), which happens synchronously right after upload — before the mobile user ever taps "Simpan & Konfirmasi" in the editor (that action only happens on PUT /api/v1/documents/:id). A scan the user captured, previewed, and then backed out of (without confirming) is already sitting in the server's document list with blank/placeholder fields — visible both to the store account and to admin. Fix: separate "OCR finished" (parsed) from "user confirmed" (confirmed) as two distinct booleans, gate list visibility on the latter. Root cause of the document_card.dart:25 fallback to the placeholder string "Staff Toko" (empty namaPenerima on an unconfirmed DO document). Task: backend §10.1 (adds column + gates list) → Flutter §8.2 (adds confirmed field to DocumentModel). Added 2026-07-10 from user APK testing feedback.

G12 — Product Scan documents carry fabricated PO/SO/DO placeholder values with no real-world referent. api/parse/route.ts Product-scan branch (lines ~107-118) stamps every Product Scan upload with noPO: "PO-PRODUCT-001", noSO: "1002003004", noDO: "DO-PRODUCT-999" — concepts that don't apply to a product verification scan. Not user-facing: pdf_service.dart's Product receipt branch never prints them (shows "Nomor Batch"/expiry instead), and product_editor_submit_logic.dart's _submit() never reads them (it builds noPo/noSo/noDo itself from the user's PO-link dropdown/batch selection). Only visible in raw debug logs. Same class of issue as the already-fixed G7 (fabricated SKU matches/dates) — dishonest raw data, low risk to remove since nothing meaningful depends on the values. Task: backend §10.2 (bundled with §10.1, same file). Added 2026-07-10 from user APK testing feedback.

Ownership

• Flutter-side fixes: root plans/next-enhancements.md §6 (G1 client half, G5, G6) and §7 (G2 client half, G3, G4 client half, G7) and §8 (G11 client half). G8/G9 are folded into existing §1/§4-adjacent tasks as noted there.
• Backend counterparts: backend/plans/next-enhancements.md §9 (G1/G10 server half: GET-by-id + parse status; G2: non-admin v1 SKU read + v1 scan endpoint; G4 server half: persist and return scan_mode) and §10 (G11 server half: confirmed column + list filter + PUT flip; G12: remove fabricated PO/SO/DO).
• Cross-cutting sequencing: backend §9 ships first; Flutter §6/§7 consume it. Backend §10 ships first; Flutter §8.2 consumes it. Flutter §8.1 is independent.