pfm-ocr/docs/feature-list.md

Feature List (Flutter)

Structured log of shipped features, updated by the n/next workflow (see AGENTS.md) whenever a task is marked [DONE]. Organize entries under a heading per module/section, matching plans/next-enhancements.md. Scoped to Flutter only as of 2026-07-08 (see AGENTS.md's "Scope: excludes backend/") — the Backend sections below are a frozen historical record; the active backend feature log now lives at backend/docs/feature-list.md, driven by backend/AGENTS.md Part B.

Format

## <Section / Module Name>

- **<task number>** <feature description> — shipped <date>

---

Existing Features (pre-kit)

Backfilled 2026-07-08 during adoption of this kit — these predate the e/n workflow and have no task numbers; see git log for real dates/history.

Flutter — Auth & Splash

• Login screen with client-side validation; JWT session persisted via Hive; splash auto-navigates based on session state.

Flutter — Camera Capture & Geotagging

• Laplacian-variance blur detection with a pass/fail badge before upload.
• IMU stillness lock (linear/angular thresholds) gating the shutter.
• GPS geotagging on both camera capture and gallery picks.

Flutter — Pending Documents Queue

• In-memory upload queue with per-item status (uploading/processing/success/error), retry (preserving original GPS), delete, and search filter.

Flutter — Document Editor & PDF Receipt

• Header field validation (date, PO/SO number formats), item CRUD validated against the master SKU registry, signature + confirmation submission, local PDF receipt printing.

Backend — Next.js API Gateway

• Upload/parse/documents CRUD routes, GPU status endpoint, vLLM proxy, manual-label review tool.

Backend — OCR Pipeline & Accuracy

• PaddleOCR + vLLM classification pipeline with DB layout caching, table column-shift correction, date normalization, and an accuracy regression harness (backend/pfm-web-app/scripts/accuracy-check.mts) currently at ~89.4% overall (target 95% — see backend/CLAUDE.md).

Backend — Postgres Data Layer

• Schema/init in backend/pfm-web-app/src/db/init.ts, served via the canonical root docker-compose.yml stack.

DevOps — Docker & Dev Tunnel

• Root docker-compose.yml (dev, hot-reload) and docker-compose.demo.yml (production-mode override); start-dev-tunnel.ps1 syncs the host LAN IP into the Flutter app config and starts an ngrok tunnel.

(New features shipped via n/next go below, organized the same way, with task numbers.)

Flutter — Auth & Splash

• 1.3 Added a confirmation dialog before logout when the pending documents queue has unsynced items (CameraDrawer._handleLogout(), lib/features/camera/camera_drawer.dart). Previously, tapping Logout in the drawer called AuthNotifier.logout() unconditionally, which clears the local Hive cache and the in-memory pending queue (localStorage.clearAll() + pendingDocumentsProvider.notifier.clearQueue()) — any document still uploading, awaiting review, or stuck in syncFailed was silently destroyed. Now, if the queue is non-empty, a dialog ("Ada Dokumen Belum Tersinkron", with the pending count) requires an explicit "Ya, Logout" confirmation before proceeding; an empty queue still logs out immediately with no extra tap. Covered by test/camera_drawer_logout_test.dart (3 cases: no pending items, cancel with pending items, confirm with pending items) — shipped 2026-07-10.

Flutter — Product Scan Review Flow

• 7.2 Eliminated the duplicate GPU classification pass (gap G3), sourced from user feedback ("kenapa harus dilakukan dua kali... GPU tidak 2x kerja") after they noticed Product Scan's review screen took visibly longer to open than DO Scan's. Root cause: the backend already classified the photo once at upload time, but the editor's _fetchClassificationAndSkus() re-uploaded the same image and re-ran the entire classify+OCR pipeline a second time via POST /scan-product, purely to get the top-5 candidates and OCR-extracted expiry date the first pass could have produced too. Fixed on the backend (see backend/docs/feature-list.md's 11.1 entry) by having the upload-time parse persist that full result; the editor now reads DocumentModel.productScanMatches/productScanExtractedExpiryDate directly from the already-loaded document — synchronous, no network call — mirroring exactly how EditorScreen._loadDocumentData() reads a DO document's data with no request at all. Keeps one lightweight fallback (GET /master/skus, a plain DB read with no GPU involved) for the rare case where a document has zero stored matches. _loading no longer starts true, so there's no spinner on the happy path. Tests: test/document_product_scan_field_test.dart (3 cases for the new model fields) and test/product_editor_no_double_classify_test.dart (proves a document with stored matches renders immediately with no network call). Verified live against the real backend: a genuinely fresh upload took 9s (one real GPU pass) and the immediate GET /documents/:id already contained 5 real candidate matches and the extracted expiry date, before any editor interaction. Full suite 63/63 pass, flutter analyze clean — shipped 2026-07-10.
• Ad-hoc (Simplify Product Scan form) — Shipped 2026-07-10. Removed the "Hubungkan ke PO Dokumen" field from ProductDropdownCard per user request — the Product Scan review form is now exactly 3 fields (SKU, Pilih Batch, Catatan). Below the SKU dropdown, the matched product's name is now shown as plain informational text (not a form field), mirroring ProductExpiryCard's existing "Tanggal terdeteksi otomatis dari OCR" info row below the batch dropdown. Removed the now-unused _selectedRelatedPo/_doDocs/_loadDoDocs() state from product_editor_data_logic.dart (was Hive-reading local DO documents to populate the removed dropdown); product_editor_submit_logic.dart no longer sets noPo from a manual PO link (now always '' for Product Scan documents — no PO-link concept remains for this doc type). DocumentCard's Product Scan subtitle no longer appends • {noPo} (now just shows the expiry date). Covered by test/product_dropdown_card_test.dart (updated + 1 new case verifying the PO field is gone and the product name info row is shown).
• 7.3 (G7 half) Replaced silently-fabricated data in the Product Scan review flow (ProductEditorScreen) with honest fallback states. Previously: (1) any total classification-fetch failure populated three hardcoded fake SKU matches with fake confidence scores, indistinguishable from a real AI result; (2) whenever OCR found no expiry date, two fabricated future dates were offered as if they were real batches; (3) ProductExpiryCard displayed a literal hardcoded "92.4%" OCR Confidence Score unconditionally — there is no real confidence signal for expiry OCR anywhere in the pipeline, so this number was always fake. Now: a genuinely unrecoverable failure (the SKU master list itself can't load) shows an explicit "Gagal Memuat Klasifikasi Produk" retry screen; a classification-only failure degrades gracefully to manual SKU selection from the real master list, with an honest "Tidak ada rekomendasi otomatis" notice instead of a fake confidence bar; a missing expiry date forces manual entry instead of offering fake batches; and the expiry card now shows an honest "terdeteksi otomatis" / "diinput manual" source label instead of a fabricated percentage. Covered by test/product_dropdown_card_test.dart, test/product_expiry_card_test.dart, test/product_editor_classification_failure_test.dart — shipped 2026-07-10.
• 7.3 (G4 half) Replaced the orderUntuk == 'PRODUCT SCAN' magic-string document-type check with a real docType field on DocumentModel, sourced from the backend's persisted scan_mode column (backend task 9.1, document-mapper.ts's docType) once that shipped. Previously, editing a document's orderUntuk display text (a corrected/OCR'd field) could silently move it between the "DO Scan" and "Product Scan" tabs; now the tab/layout/receipt-format decision reads a dedicated field that isn't user-editable display text. Falls back to the legacy orderUntuk sentinel only for responses/cached data that predate the backend column. Updated call sites: document_card.dart, documents_screen.dart, pdf_service.dart, product_editor_logic.dart. Covered by test/document_doctype_test.dart, including a regression test reproducing the exact old bug trigger — shipped 2026-07-10.
• 7.1 Moved the product editor's classification/SKU-lookup calls off the classic, unauthenticated dev routes (GET /api/skus, POST /api/scan-pfm, reached via a apiBaseUrl.replaceAll('/api/v1', ...) string hack) onto the authenticated v1 surface (GET /api/v1/master/skus, POST /api/v1/scan-product) once backend tasks 9.2/9.3 shipped it — fixes product scanning being broken off-LAN (backend task 4.5 restricts the public tunnel to /api/v1/* only). New endpoint constants in app_config.dart; the auth token is attached automatically by ApiClient's existing interceptor, same as every other v1 call. Also switched the classification request from a base64 JSON body to multipart (FormData/MultipartFile, reusing the pattern already proven for DO uploads) to avoid a multi-MB JSON payload, matching what backend 9.3 was built to prefer. Extracted the v1-envelope-unwrapping logic into a new pure file, lib/features/editor/product_scan_response_parser.dart, mirroring task 6.2's testable-pure-function pattern. Tests: test/product_scan_response_parser_test.dart (6 cases). Verified live against the real backend: a real store account succeeds against both new endpoints with the expected response shapes — shipped 2026-07-10.

Flutter — API Contract & Sync Integrity (DO flow)

• 6.1 Replaced whole-list polling with per-document polling for pending uploads. Previously, _pollUntilParsed fetched the entire GET /documents list every 2 seconds and inferred "parse done" from the pending item's document appearing in a parsed=true-filtered list via an object-identity check — an ocr_items query per document per poll on the server, growing with history, and no way to distinguish "still parsing" from "parse failed" (a server-side parse failure only ever surfaced as a generic 260-second timeout). Now polls GET /api/v1/documents/:id for just that item's own id (backend task 9.1), reading a real parseStatus (pending/done/failed) instead of guessing from list membership — a failed parse now ends the poll immediately with an explicit error message instead of waiting out the full timeout. The done/failed/pending decision lives in a new pure function, resolvePollOutcome() (lib/features/documents/poll_outcome.dart), unit tested without mocking Dio. Verified live against the running backend stack — a real document's GET /api/v1/documents/:id response matches the shape the new code expects. Covered by test/poll_outcome_test.dart (4 cases) — shipped 2026-07-10.
• 6.2 Fixed a data-integrity bug where DocumentsScreen's server refresh would silently overwrite a driver's corrected-but-unsynced document with the server's stale pre-edit copy (or drop it from the visible list) whenever its PUT /documents/:id save had failed and it sat in the pending queue as syncFailed. Added a pure, unit-tested merge function (mergeDocumentsWithUnsyncedOverrides(), lib/features/documents/document_sync_merge.dart) that lets a matching syncFailed pending item's corrected copy override the server's version (and survive even if the server list omits that document entirely). DocumentCard now shows a "Belum Tersinkron" badge (instead of a hardcoded "Terkonfirmasi") for any document currently overridden this way, so the driver can see at a glance which history entries still need a retry from the pending queue. Covered by test/document_sync_merge_test.dart and test/document_card_unsynced_badge_test.dart — shipped 2026-07-10.
• 6.3 Fixed a data-integrity bug where saving in either editor could PUT to a fabricated client-side ID (a millisecond timestamp) instead of the real server-assigned document id, whenever the editor opened without a resolved server document (e.g. after a process-death restart lost the pendingId route param) — the PUT would target a nonexistent id and the item would loop in syncFailed forever with no way to recover. Now, when no server document is resolved but the pending item's local image is still available, the save flow auto-recovers by re-uploading that image (safe: the backend dedups by file_hash) to get a real id, then PUTs the corrected fields to it; only when neither a server document nor a local image is available does it block with an explicit error instead of guessing an id. The decision logic lives in a new pure function, resolveDocumentSaveAction() (lib/features/editor/document_save_action.dart), unit tested without mocking Dio. Verified live against the running backend: re-uploaded a real test image to get a genuine server id, PUT corrected fields to it, then confirmed via GET that the correction persisted. Covered by test/document_save_action_test.dart (3 cases) — shipped 2026-07-10.

Flutter — Pending Documents Queue

• 3.1 Persisted the pending documents queue to a new Hive box (lib/core/storage/local_storage.dart) instead of holding it in memory only — an OS-level app kill mid-upload no longer silently loses the document. On next launch, PendingDocumentsNotifier reloads the queue and resumes anything left non-terminal: re-uploads a fresh capture from scratch (safe due to server-side file-hash dedup) or resumes polling for one whose upload already completed. Storage failures degrade gracefully to the old in-memory-only behavior rather than crashing the app — shipped 2026-07-08.

Backend — Postgres Data Layer

• 7.1 Wrapped the ocr_items delete-then-reinsert in /api/parse and /api/v1/documents/[id] PUT inside a DB transaction (withTransaction helper, backend/pfm-web-app/src/db/index.ts) — a mid-loop insert failure now rolls back to the previous item set instead of leaving a document with a correct header but partial/missing items — shipped 2026-07-08.

Flutter — Document Editor & PDF Receipt

• Ad-hoc (Product Scan flow) — Shipped 2026-07-09
  • Implemented mock upload and response flow for Product Scanner review. Created a dedicated ProductEditorScreen with crop preview, AI classification confidence indicator, and dynamic drop-down SKU selector (Fiesta Spicy Chicken Nugget, Akumo Coin, Fiesta Schnitzel).
• Ad-hoc (Fuzzy Batch Expiry Selector) — Shipped 2026-07-09
  • Built dynamic expiry date batch matching dropdown (Batch 1, Batch 2, manual input date picker) based on selected Master SKU product.
• Ad-hoc (Custom Product PDF) — Shipped 2026-07-09
  • Redesigned the printed PDF receipt layout specifically for Product Scan (titles, headers, detail table parameters, store staff signatures) while preserving the same consistent professional layout styling as DO Scan receipt.
• Ad-hoc (PO Document Relationship) — Shipped 2026-07-09
  • Added "Hubungkan ke PO Dokumen" dropdown to select and relate the Product Scan to a confirmed DO Scan document via PO Number (noPo relational field).

Flutter — Pending Documents Queue / History

• Ad-hoc (Custom Tab Switcher) — Shipped 2026-07-09
  • Switched the documents history view to show two tabs (DO Scan and Product Scan) with DO Scan as default, removing the "All" tab.
• Ad-hoc (Document Card Alignment) — Shipped 2026-07-09
  • Styled DO Scan and Product Scan history cards with matched structures:
    • Top category label: Staff Name for DO Scan (Orange), Product Name for Product Scan (Green).
    • Main Title: PO Number for DO Scan (directly without prefix), Batch Number for Product Scan ([Batch Name]).
    • Subtitle Details: [Date] • [Item Count] Item for DO cards, and [Expiry Date] • [PO Number] (without prefix labels) for Product cards.
• Ad-hoc (Active Account Seeding) — Shipped 2026-07-09
  • Seeded 1 initial mock DO Scan document and 1 Product Scan document matching the currently logged-in account/store code if empty.
• Ad-hoc (DO & Product Scan Workflow Realignment) — Shipped 2026-07-09
  • Synced default history view tab (_selectedTab) with the active scanner mode (scanModeProvider) on page load.
  • Realigned category identifiers (orderUntuk) of newly captured product scan documents to 'PRODUCT SCAN' so they appear under the correct tab immediately instead of switching tabs after edit/confirmation.
  • Filtered the pending document queue display by tab category so pending DO documents and pending Product documents are kept separated.
  • Implemented secure store-level data isolation by clearing the local Hive cache boxes on user logout, and delegating document list filtering directly to the backend API (GET /api/v1/documents) which filters Postgres results by the active account's kode_toko. This fixes the issue where DO documents were hidden due to string mismatches in client-side kepadaYth checks.
  • Dynamic store profiling for newly captured mock product documents using SharedPreferences.
  • Modularized DocumentsScreen (bringing it under 256 lines) by extracting widgets into helper components: DocumentsTabSwitcher, DocumentsEmptyState, and DocumentsMockSeeder.

Flutter — Scan Mode UX & Confirmation Gate (§8)

• 8.1 Global scan-mode state + DO/Product color cue — shipped 2026-07-10
  • scanModeProvider is now the single source of truth for the active tab. DocumentsScreen._selectedTab removed; build() reads ref.watch(scanModeProvider); DocumentsTabSwitcher.onTabChanged writes ref.read(scanModeProvider.notifier).state = tab. Eliminates the desync where changing mode in the camera drawer was not reflected in the documents list tab (and vice-versa).
  • AppConfig.doModeColor (Color(0xFFF57C00)) added as a shared constant — formalizes the previously ad-hoc Colors.orange.shade700 used only in document_card.dart.
  • Color cue applied consistently across three call sites:
    • DocumentsTabSwitcher._buildTabItem: active DO tab text → doModeColor (was primaryColor).
    • CameraDrawerModeToggle._buildSegment: active DO segment → doModeColor (was primaryColor).
    • DocumentCard: category label for DO → doModeColor (was inline Colors.orange.shade700).
  • Follow-up (same day): user clarified the icon, not just the text, should carry the mode color — DocumentsTabSwitcher gained Icons.description/ Icons.inventory_2 (matching CameraDrawerModeToggle's existing vocabulary), colored the same as the tab's text (doModeColor/primaryColor active, textSecondary inactive). Deliberately scoped to the mode-toggle controls only — generic/default icons elsewhere (search, print, back, tooltips) were left untouched per explicit instruction.
  • CameraDrawer split into three files to satisfy AGENTS.md §3 (256-line threshold on touched files): camera_drawer.dart (232 lines, structure + logout), camera_drawer_mode_toggle.dart (125 lines, DO/Product pill), camera_drawer_helpers.dart (78 lines, section header, drawer item, dialogs).
• 8.2 Added an optional confirmed field to DocumentModel (default true, same fallback pattern as docType/parseStatus) once backend task 10.1 shipped confirmed on GET /api/v1/documents/:id — the client half of closing gap G11 (documents no longer showing in history before the user taps "Simpan & Konfirmasi"; see backend docs/feature-list.md's 10.1/10.2 entries for the server-side fix). No other Flutter changes were needed: the existing mergeDocumentsWithUnsyncedOverrides() (task 6.2) and the pending queue's "Tertunda & Diproses" section already handled the new server behavior correctly without modification — verified by re-reading both, not assumed. Covered by test/document_confirmed_field_test.dart (3 cases) — shipped 2026-07-10.
  • Tests: 7 new widget tests in test/scan_mode_color_test.dart covering all three color-cue assertions and provider write-through. All 50 suite tests pass.