Adopt agents-settings kit, ship Product/SKU scan models, harden auth, verify OCR accuracy
Backend (app-pfm-ocr-v2/backend): - Product/SKU scan feature complete: trained DINOv2 index (118 reference photos, 16 SKU classes) and YOLO classifier (83.3% top-1 val accuracy), fixed scripts/install-pipeline.sh (was missing ultralytics/torch), fully browser-verified end-to-end on /scan-pfm. Mobile m-scan-pfm page cancelled (Flutter app handles mobile; web UI is desktop-only for pipeline testing). - Fixed a real data-loss bug: Save Ground Truth (scan-pfm and the DO-flow's manual-label) was silently writing into the pfm-web-app container's ephemeral filesystem instead of the host, because /sources wasn't bind-mounted in docker-compose.yml. Added the mount, recovered an orphaned entry. - accounts.password is now bcrypt-hashed (bcryptjs, idempotent migration in db/init.ts) instead of plaintext; login route compares hashes. - /api/v1/documents/* (list, PUT, upload) now enforces real 401 auth, matching what the Flutter client already sends. The "classic" routes deliberately stay open — they're dev-only web UI with no login flow and won't exist in production. - OCR accuracy investigated end-to-end: real baseline is 95.10% overall (target met; accuracy_report.md was stale at 75.04%, now flagged). Fixed one genuine parser.ts bug (SO/DO field duplication in the global fallback regex); remaining gaps are OCR/layout-model limitations, not parser bugs. - Adopted a standalone copy of the fhanyuh/agents-settings e/n workflow scoped to backend/ (AGENTS.md Part A/B split, SKILLS.md, plans/, docs/), independent of the root copy which now covers Flutter only. - next-implementation.md deleted; content folded into backend/plans/next-enhancements.md for traceability. Root: - Adopted fhanyuh/agents-settings kit (AGENTS.md, SKILLS.md, plans/, docs/feature-list.md), scoped to the Flutter app only. - Pending documents queue now persists to Hive (lib/core/storage) instead of memory-only, surviving an app kill mid-upload. Removed backend_backup/ (stale Express/Prisma prototype, superseded by pfm-web-app) and the completed plans/next-enhancement-plan.md checklist. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
Rafhan Mazaya FathurrahmanandClaude Sonnet 5 committed
1 parent
3df9f6ec5d
commit
e60ab63154
129 files changed
+8520
-6684
No files matched your search
@@ -1,113 +0,0 @@
|
||||
# PFM OCR App — Quality Engineering & Verification Plan
|
||||
> Auto-managed by Quality Engineering (QE) guidelines. Do not edit task status manually.
|
||||
> Legend: [TODO] = pending | [IN_PROGRESS] = active | [DONE] = completed
|
||||
|
||||
---
|
||||
|
||||
## Section 0: QA Configuration & Permissions Layer [QE]
|
||||
> Verification of OS-level permissions and system dependencies before application execution.
|
||||
|
||||
- 0.1 [DONE] **Android Permission Verification**: Enforce access permissions in `AndroidManifest.xml` (location, camera, internet).
|
||||
- Verify `ACCESS_FINE_LOCATION` and `ACCESS_COARSE_LOCATION` are present.
|
||||
- Verify `CAMERA` and `INTERNET` are declared under `<manifest>` root.
|
||||
- 0.2 [DONE] **iOS Permission Verification**: Enforce privacy descriptors in `Info.plist`.
|
||||
- Verify `NSLocationWhenInUseUsageDescription` and `NSLocationAlwaysUsageDescription` are configured with user-facing Indonesian text.
|
||||
- 0.3 [DONE] **Linting & Code Integrity Check**: Enforce standard Flutter rules.
|
||||
- No compilation warnings or unused imports in the `lib/` directory.
|
||||
- Deprecated UI properties like `.withOpacity` replaced with `.withValues()` to ensure UI rendering performance.
|
||||
|
||||
---
|
||||
|
||||
## Section 1: Authentication & Splash [Splash/Login]
|
||||
> Enforce validation and session security checks.
|
||||
|
||||
- 1.1 [DONE] **Splash Transition**: Verify user session detection.
|
||||
- If token exists and is valid, auto-navigate to `/camera`.
|
||||
- If token does not exist, navigate to `/login`.
|
||||
- 1.2 [DONE] **Login Field Validation**: Ensure strict client-side verification.
|
||||
- Empty username or password triggers inline validation warning.
|
||||
- Password minimum requirement of 6 characters enforced on the input field.
|
||||
- 1.3 [DONE] **Login API & State Integrity**:
|
||||
- Valid credentials store the JWT token securely using Hive/SharedPreferences.
|
||||
- API errors (e.g., 401 Unauthorized, 403 Forbidden) render a red error banner without crashing the application.
|
||||
- Loading indicator overlay blocks user interaction during submission.
|
||||
|
||||
---
|
||||
|
||||
## Section 2: Camera Capture & Geotagging [Camera]
|
||||
> Enforce IMU stillness limits and immediate coordinate capture.
|
||||
|
||||
- 2.1 [DONE] **Stillness Thresholds Check**: Verify IMU stillness analyzer in `camera_screen.dart`.
|
||||
- Linear acceleration limit of `0.3 m/s^2` lock/unlock shutter verified.
|
||||
- Angular rotation limit of `0.15 rad/s` tilts lock/unlock shutter verified.
|
||||
- Warning banner "Tahan posisi HP Anda agar tetap tenang!" displays instantly when motion limits are exceeded.
|
||||
- 2.2 [DONE] **Geotagging Capture (Camera)**: Verify GPS coordination retrieval during image capture.
|
||||
- Calling `LocationService.determinePosition()` begins in parallel with image save.
|
||||
- UI displays "Sedang menangkap gambar & lokasi..." overlay.
|
||||
- Location failure (timeout, permissions denied) falls back gracefully without breaking the camera screen transition.
|
||||
- 2.3 [DONE] **Geotagging Capture (Gallery)**: Verify location retrieval when selecting an image.
|
||||
- Selecting an image from the gallery triggers the location API.
|
||||
- Passes coordinates successfully to the image preview screen.
|
||||
|
||||
---
|
||||
|
||||
## Section 3: Blur Detection & Preview [Preview]
|
||||
> Enforce image sharpness limits and coordinates mapping.
|
||||
|
||||
- 3.1 [DONE] **Sharpness Threshold Audit**:
|
||||
- Sharpness score below 80.0 displays a red "Foto Terdeteksi Blur!" badge.
|
||||
- Sharpness score of 80.0 and above displays a green "Kualitas Foto Baik" badge.
|
||||
- 3.2 [DONE] **Action Control Routing**:
|
||||
- Clicking "Ambil Ulang" pops the screen and returns to the active camera controller.
|
||||
- Clicking "Unggah Dokumen" is disabled when sharpness score is below the threshold.
|
||||
- Successful confirmation dispatches `addDocument` with `latitude` and `longitude` fields populated.
|
||||
|
||||
---
|
||||
|
||||
## Section 4: Pending Queue & Synchronization [List]
|
||||
> Enforce queue integrity, retry state preservation, and metadata filtering.
|
||||
|
||||
- 4.1 [DONE] **Queue State Rendering**:
|
||||
- `uploading` and `processing` states display a progress bar.
|
||||
- `success` state displays a green checkmark and enables the `/editor` navigation list row.
|
||||
- `error` state displays a red error icon and the error string.
|
||||
- 4.2 [DONE] **Context Menu Actions**:
|
||||
- "Delete Document" removes the file and item from memory list state.
|
||||
- "Retry Upload" preserves the original GPS coordinate values (`latitude`, `longitude`) from capture instead of clearing them.
|
||||
- 4.3 [DONE] **Search Filter Matching**:
|
||||
- Search bar query matches: No DO, No PO, No SO, Tanggal, or Customer name (case-insensitive).
|
||||
- 4.4 [DONE] **Confirmed Documents Cards**:
|
||||
- Renders coordinates with `toStringAsFixed(4)` decimals.
|
||||
- "Print Receipt" prints a PDF containing correct details (Items, header metadata, coordinates).
|
||||
|
||||
---
|
||||
|
||||
## Section 5: Document Editor & Verification [Editor]
|
||||
> Enforce strict metadata structure validation and data synchronization.
|
||||
|
||||
- 5.1 [DONE] **Header Field Constraints**:
|
||||
- Date picker formats value as `dd MMMM yyyy`.
|
||||
- PO number validates against format `PO/26/\d{10}`.
|
||||
- SO number validates as digits-only with a length of exactly 10.
|
||||
- 5.2 [DONE] **Item Details CRUD & Master SKU**:
|
||||
- Adding a new item allows typing a SKU.
|
||||
- SKU validation checks against `MasterSku` data registry. Matches display the correct product name; non-matches display "SKU Tidak Terdaftar" and raise a validation error.
|
||||
- 5.3 [DONE] **Signature & Submission**:
|
||||
- "Review Complete" triggers the bottom sheet modal.
|
||||
- Bottom sheet requires recipient's name (non-empty) and the agreement checkbox to be checked.
|
||||
- "Confirm" saves the model locally to Hive and issues a `PUT /api/v1/documents/:id` request to the server with coordinates.
|
||||
|
||||
---
|
||||
|
||||
## Section 6: Backend API contracts [Backend]
|
||||
> Verify route schema validation, file handling, and DB storage integrity.
|
||||
|
||||
- 6.1 [DONE] **POST /api/v1/documents/upload**:
|
||||
- Multipart request parses `image` file and populates body fields `latitude` and `longitude`.
|
||||
- Returns `201 Created` with mapped schema containing parsed coordinates as floats.
|
||||
- 6.2 [DONE] **PUT /api/v1/documents/:id**:
|
||||
- Parses body coordinates and items array.
|
||||
- Updates DB record and deletes old cascade items.
|
||||
- Returns updated entity payload.
|
||||
- 6.3 [DONE] **Auth Middleware Cleanup**:
|
||||
- Unauthorized uploads clean up the multer temporary disk storage before sending responses.
|
||||
@@ -0,0 +1,81 @@
|
||||
# Next Enhancements (Flutter)
|
||||
|
||||
This file is the working backlog driven by the `e`/`enhance` and `n`/`next` triggers
|
||||
defined in [AGENTS.md](../AGENTS.md), which now scopes this kit's automated
|
||||
behaviors to the **Flutter app only** (see AGENTS.md's "Scope: excludes `backend/`").
|
||||
Sections seeded 2026-07-08 from the real module structure of `app-pfm-ocr-v2` (see
|
||||
AGENTS.md's Adaptation Notes); tasks populated the same day via `e`/`enhance`,
|
||||
grounded in a direct read of each module's current code rather than invented work.
|
||||
|
||||
> `backend/` has its own, independent copy of this kit —
|
||||
> [backend/plans/next-enhancements.md](../backend/plans/next-enhancements.md), driven
|
||||
> by `backend/AGENTS.md` Part B. This file no longer tracks backend work at all —
|
||||
> the backend sections that briefly lived here (5-8, from the one backend-scoped `e`
|
||||
> run before the kit split) were removed 2026-07-08 now that the backend copy is the
|
||||
> sole active backlog for that subtree.
|
||||
|
||||
> Note: this repo already has an unrelated, pre-existing `plans/next-enhancement-plan.md`
|
||||
> (singular) — a `[DONE]` QA verification checklist. It is not part of this workflow
|
||||
> and is left as-is; this file (plural) is the one `e`/`n` reads and writes.
|
||||
|
||||
## Format
|
||||
|
||||
Tasks are grouped under a numbered section per module of the application. Each
|
||||
section gets exactly 3 tasks:
|
||||
|
||||
```
|
||||
## 1. <Section / Module Name>
|
||||
|
||||
- **1.1** [TODO] <clear, specific description of the functional change>
|
||||
- **1.2** [TODO] <...>
|
||||
- **1.3** [TODO] <...>
|
||||
```
|
||||
|
||||
When a task is picked up via `n`/`next`, its clarified acceptance criteria (from
|
||||
AGENTS.md §2a) are appended directly under it as a short note, e.g.:
|
||||
|
||||
```
|
||||
- **1.1** [TODO] <description>
|
||||
- Acceptance: <1-3 line resolved scope, from the clarification step>
|
||||
```
|
||||
|
||||
When complete, the status flips to `[DONE]` and the feature is logged in
|
||||
[docs/feature-list.md](../docs/feature-list.md).
|
||||
|
||||
---
|
||||
|
||||
## Sections (seeded from real modules — run `e` / `enhance` to fill in tasks)
|
||||
|
||||
### 1. Flutter — Auth & Splash
|
||||
`lib/features/auth/`, `lib/features/splash/`
|
||||
|
||||
- **1.1** [TODO] Validate the stored token before treating the user as logged in. `AuthNotifier.checkLoginState()` (`lib/features/auth/auth_provider.dart:11-20`) only checks that a token string exists in `SharedPreferences` — it never checks expiry or pings the server — so a stale/revoked token shows the camera screen and only fails later, silently, on the first real API call.
|
||||
- **1.2** [TODO] Add a global 401/403 response interceptor to the Dio client that force-logs-out and redirects to `/login`, so an expired/revoked token surfaces as a clear re-login prompt instead of failing whatever screen happens to make the next API call.
|
||||
- **1.3** [TODO] Warn before logout if the in-memory pending documents queue (`pendingDocumentsProvider`, `lib/features/documents/pending_documents_provider.dart`) has unsynced items. Today `CameraScreen`'s drawer logout (`camera_screen.dart:367-370`) calls `logout()` unconditionally, silently orphaning any in-flight uploads or unsent items.
|
||||
|
||||
### 2. Flutter — Camera Capture & Geotagging
|
||||
`lib/features/camera/`
|
||||
|
||||
- **2.1** [TODO] Surface actionable, user-visible feedback when location can't be determined, instead of only logging it. Every failure path in `LocationService.determinePosition()` (`lib/core/location/location_service.dart`) — services disabled, permission denied, `deniedForever`, or all four GPS-fix strategies failing — only calls `debugPrint` and returns `null`; the driver gets no on-screen prompt (e.g. "enable location" / "open app settings") and the document just uploads without a GPS tag.
|
||||
- **2.2** [TODO] Show a location-fix quality/staleness indicator on the capture screen before the shutter is pressed. `_currentPosition` in `CameraScreen` (`camera_screen.dart:22,37-62`) is used whatever its age or accuracy, with no on-screen warning when no fix has landed yet or the fix is old — a document can silently upload with a poor or missing GPS tag.
|
||||
- **2.3** [TODO] Replace the static "posisikan seluruh halaman dokumen di dalam foto" instructional text with a live document-alignment overlay during capture. `CameraScreen` only launches the OS's native camera app via `ImagePicker(source: ImageSource.camera)` (`camera_screen.dart:69-74`) — there's no in-app camera preview, so the framing guideline is shown once beforehand and then unavailable during the actual shot.
|
||||
|
||||
### 3. Flutter — Pending Documents Queue
|
||||
`lib/features/documents/`
|
||||
|
||||
- **3.1** [DONE] Persisted the pending documents queue to disk via a new Hive box (`LocalStorage.pendingDocumentsBox`/`savePendingDocument`/`removePendingDocument`/`getAllPendingDocuments`, `lib/core/storage/local_storage.dart`). `PendingDocumentsNotifier` now hydrates from disk on construction and resumes anything not yet terminal: a persisted `uploading` item (fresh capture, or a `retryUpload` interrupted mid-flight) re-runs `_uploadAndProcess` from scratch — safe because the upload endpoint dedupes by file hash server-side — and a persisted `processing` item resumes polling via the newly extracted `_pollUntilParsed`/`_resumePolling` instead of re-uploading. `retrySync`'s own transient flip to `uploading` is deliberately kept in-memory-only (`_updateItemInMemory`) so an interrupted sync-retry resumes as "resend the PUT," not "redo the whole upload." Storage failures are caught and swallowed everywhere (`hydrate`, `_persistPendingDocument`, `_removePersistedPendingDocument`) so a Hive error degrades to the old in-memory-only behavior rather than crashing the queue. Verified via `flutter analyze` (clean) and `flutter test` (no new failures vs. the pre-existing 3-test baseline). Completed 2026-07-08.
|
||||
- **3.2** [TODO] Add a persistent "pending/syncing count" badge visible from the camera screen (not just the `/documents` list), reflecting `pendingDocumentsProvider` state — today a driver who navigates away from `/documents` gets no visibility into background uploads still in progress or stuck in `error`/`syncFailed`.
|
||||
- **3.3** [TODO] Add explicit Dio request timeouts to the upload and poll calls in `_uploadAndProcess` (`pending_documents_provider.dart:112-162`). The 2s-interval/130-retry poll loop is intentional and bounded, but the underlying `apiClient.client.post`/`.get` calls themselves have no explicit connect/receive timeout, so a genuinely hung connection (not a slow-but-alive OCR pass) can leave an item stuck in `uploading` indefinitely.
|
||||
|
||||
### 4. Flutter — Document Editor & PDF Receipt
|
||||
`lib/features/editor/`
|
||||
|
||||
- **4.1** [TODO] Add an unsaved-changes guard when navigating away from `EditorScreen` with edited-but-unsaved field values. There is currently no `PopScope`/back-navigation interception, so a back-swipe or system back button silently discards manual corrections to OCR'd header/item fields.
|
||||
- **4.2** [TODO] Block save when a line item's SKU isn't in the master registry, instead of only relabeling it for display. The SKU listener in `_addItem` (`editor_screen.dart:108-115`) sets the item name to "SKU Tidak Terdaftar" for an unrecognized SKU but doesn't stop form submission, so a document with an unregistered/mistyped SKU can still be saved and its receipt printed.
|
||||
- **4.3** [TODO] Include the captured GPS coordinates on the printed PDF receipt. `PdfService.generateAndPrintReceipt` (`pdf_service.dart:36-52`) prints header/shipment/item fields but never includes `document.latitude`/`longitude`, even though the editor captures and displays them (`_latitudeCtrl`/`_longitudeCtrl`) — the geotag exists in the data model but isn't part of the audit-trail document a store keeps.
|
||||
|
||||
---
|
||||
|
||||
*Sections 1-4 (Flutter) are the only sections this file tracks. Backend
|
||||
enhancements (formerly sections 5-8 here, removed 2026-07-08) now live
|
||||
exclusively in [backend/plans/next-enhancements.md](../backend/plans/next-enhancements.md).*
|
||||
Reference in new issue
Block a user