feat(app): scan-mode sync, confirmation-gated documents, single-pass product classification

Fixes reported from APK field testing: DO/Product scan mode was inconsistent
between the camera drawer and documents screen (now one shared provider,
with an orange/green color cue); unconfirmed scans leaked into history with
placeholder data before the user tapped confirm (backend now gates
GET /documents on a new `confirmed` column, flipped only by PUT); and
Product Scan ran the GPU classifier twice, once at upload and again on
review (now a single pass at upload, persisted and read directly by the
editor). Also removes the unused "Hubungkan ke PO" field and fabricated
PO/SO/DO placeholder values from the Product Scan flow, closes out the
per-document-polling and save-recovery tasks (6.1/6.3), and splits several
touched files to stay under the repo's 256-line guideline.

Full detail in docs/iteration-log.md and backend/docs/iteration-log.md.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

lib/models/document_model.dart

@@ -14,6 +14,44 @@ class DocumentModel {
   final double? longitude;
   final List<DocumentItem> items;
   final DateTime createdAt;
+  final bool parsed;
+
+  /// 'pending' | 'done' | 'failed', sourced from the backend's `parseStatus`
+  /// (backend task 9.1, `document-mapper.ts`) - only populated by
+  /// `GET /api/v1/documents/:id` (see `pending_documents_provider.dart`'s
+  /// `_pollUntilParsed`, which polls that route instead of scanning the
+  /// whole list). Null for responses that don't include it (e.g. the PUT
+  /// route's own hand-built response, or cached Hive rows).
+  final String? parseStatus;
+
+  /// 'DO' or 'Product', sourced from the backend's persisted `scan_mode`
+  /// column (see backend task 9.1, `document-mapper.ts`'s `docType`) - the
+  /// real replacement for the `orderUntuk == 'PRODUCT SCAN'` sentinel that
+  /// every call site used to check (editing that display field used to
+  /// silently move a document between tabs).
+  final String docType;
+
+  /// True once the user has confirmed this document (`PUT /documents/:id`),
+  /// sourced from the backend's `confirmed` column (backend task 10.1) -
+  /// separates "OCR finished" (`parsed`) from "user confirmed," since a
+  /// document only re-enters `GET /api/v1/documents` (and this field is only
+  /// meaningfully `false`) once confirmed. Defaults to `true` for
+  /// legacy/cached responses that predate the column - see
+  /// docs/api-contract-map.md G11.
+  final bool confirmed;
+
+  /// Top-5 SKU candidates from the single classify+OCR pass the backend runs
+  /// at upload time for Product Scan documents (backend task on gap G3,
+  /// `document-mapper.ts`'s `productScan.possibleMatches`) - lets the product
+  /// editor render immediately instead of re-running the GPU pipeline a
+  /// second time on review. Empty for DO documents, or Product documents
+  /// parsed before this existed (already-confirmed docs also lose it, since
+  /// it's only needed during the initial review).
+  final List<Map<String, dynamic>> productScanMatches;
+
+  /// OCR-extracted expiry date from that same single pass
+  /// (`productScan.extractedExpiryDate`). Empty string when absent/not found.
+  final String productScanExtractedExpiryDate;
 
   DocumentModel({
     required this.id,
@@ -31,6 +69,12 @@ class DocumentModel {
     this.longitude,
     required this.items,
     required this.createdAt,
+    this.parsed = false,
+    this.parseStatus,
+    this.docType = 'DO',
+    this.confirmed = true,
+    this.productScanMatches = const [],
+    this.productScanExtractedExpiryDate = '',
   });
 
   factory DocumentModel.fromJson(Map<String, dynamic> json) {
@@ -56,6 +100,22 @@ class DocumentModel {
       createdAt: json['created_at'] != null
           ? DateTime.parse(json['created_at'].toString())
           : (json['createdAt'] != null ? DateTime.parse(json['createdAt'].toString()) : DateTime.now()),
+      parsed: json['parsed'] as bool? ?? false,
+      parseStatus: json['parseStatus']?.toString(),
+      // Prefer the backend's persisted docType (backend task 9.1). Fall back
+      // to the legacy orderUntuk sentinel for responses/cached rows that
+      // predate that column (e.g. the upload endpoint's fresh-upload stub,
+      // or Hive entries saved before this field existed) - mirrors the same
+      // fallback backend/pfm-web-app/src/utils/document-mapper.ts uses.
+      docType: json['docType']?.toString() ??
+          (shipment['order_untuk'] == 'PRODUCT SCAN' ? 'Product' : 'DO'),
+      confirmed: json['confirmed'] as bool? ?? true,
+      productScanMatches: ((json['productScan'] as Map<String, dynamic>?)?['possibleMatches'] as List?)
+              ?.map((e) => Map<String, dynamic>.from(e as Map))
+              .toList() ??
+          const [],
+      productScanExtractedExpiryDate:
+          (json['productScan'] as Map<String, dynamic>?)?['extractedExpiryDate']?.toString() ?? '',
     );
   }
 
@@ -69,6 +129,8 @@ class DocumentModel {
       'longitude': longitude,
       'nama_driver': namaDriver,
       'nama_penerima': namaPenerima,
+      'parsed': parsed,
+      'docType': docType,
       'header': {
         'tanggal': tanggal,
         'no_po': noPo,
@@ -81,7 +143,7 @@ class DocumentModel {
         'alamat': alamat,
         'plat_truk': platTruk,
       },
-      'items': items.map((e) => {
+      'items': items.map((e) => <String, dynamic>{
         'nomor_sku': e.nomorSku,
         'nama_barang': e.namaBarang,
         'banyak': e.banyak,
@@ -106,7 +168,7 @@ class DocumentModel {
       'namaPenerima': namaPenerima,
       'latitude': latitude,
       'longitude': longitude,
-      'items': items.map((e) => {
+      'items': items.map((e) => <String, dynamic>{
         'nomor_sku': e.nomorSku,
         'nama_barang': e.namaBarang,
         'banyak': e.banyak,