pfm-ocr/docs/stock-feature-plan.md

# Stocks Feature — Full-Stack Implementation Plan

Written 2026-07-10 after an extensive grilling/clarification session with the user
(see chat history — not reproduced here). This is the context doc for the Stocks
backlog entries in root [`plans/next-enhancements.md`](../plans/next-enhancements.md)
§9 and [`backend/plans/next-enhancements.md`](../backend/plans/next-enhancements.md)
§12 — read it before picking up any task from either section, same relationship
[`docs/api-contract-map.md`](api-contract-map.md) has to its own gap-fix tasks.

**Status: planned, not yet implemented.** Nothing described below exists in the
codebase yet — this doc is the design record to build from when the tasks below are
picked up via `n`/`next`.

## Context

The app currently tracks Delivery Order (DO) documents and a "Product Scan"
shelf-verification flow, but has **no concept of shelf stock/inventory at all** — no
batch, no expiry-per-batch, no quantity-on-hand. The Product Scan editor already has
a placeholder "batch/expiry" dropdown (`ProductExpiryCard`), but it's fake: it just
echoes the single OCR-extracted expiry-date string from the photo, with no real batch
code, no quantity, no link to what was actually delivered.

The user wants to close this gap: every confirmed DO should feed real, per-store,
per-SKU batch records (batch code + expiry + quantity, split across boxes/packs),
track where each batch came from, and let Product Scan consume from that real batch
pool (matching against it, and decrementing it) instead of operating on fabricated
data.

**Outcome**: a new Postgres schema + `/api/v1/stock/*` endpoints (backend), a new
mandatory-by-default "stock entry" step triggered right after DO confirmation, a new
"Stok" menu (Flutter), a rewired Product Scan batch-matching flow, and a basic
read-only admin web view.

## Confirmed decisions (resolved via one-at-a-time grilling, do not re-litigate)

- **Full-stack, per-store** (`kode_toko`) stock. Batch = unique `(kode_toko, no_sku,
  batch_code, expiry_date)`; repeat deliveries of the same combo **merge** (quantity
  adds), never duplicate.
- Batches track **both** outer qty (boxes/karung, matches DO's `banyak`) and inner
  qty (packs/pieces, matches DO's `jumlah`) — both **manually typed**, seeded from
  the DO item's already-user-corrected quantities (physical verification already
  happens in the existing DO editor before confirmation; no re-verification here).
- **Every quantity change is logged** in an append-only movement table
  (`intake`/`decrement`/`adjustment`/`manual_seed`), referencing the causing
  document where applicable.
- **DO confirm trigger**: right after `PUT /api/v1/documents/:id` succeeds in the DO
  editor (`editor_logic.dart`), auto-navigate to a stock-entry screen. Each item
  **starts with 1 pre-filled batch** (full confirmed quantity); user can split into
  more via "+ Tambah Batch". An explicit **"Isi Nanti"** (finish later) exits without
  hard-blocking, leaving that DO resumable/visible from the Stocks menu.
- Batch code is **always manually typed** (no OCR/camera in stock-entry — plain form
  only).
- **Stocks menu** ("Stok" in the drawer): two-level SKU list → batch detail, sorted
  soonest-expiry-first, expired batches flagged red (visual only, no write-off
  workflow this pass). Batches are manually editable after creation (logged as
  `adjustment`). Manual "add batch" with no DO link is supported (seeds pre-existing
  inventory, logged as `manual_seed`).
- **Product Scan integration**: SKU candidates restricted to in-stock (qty > 0)
  SKUs only. Batch dropdown shows all of that SKU's in-stock batches (no cap);
  closest-to-OCR-extracted-expiry batch is auto-selected. Depleted/negative batches
  still selectable with a warning. Confirming decrements the selected batch's
  **inner qty by exactly 1**, allowed to go **negative**, logged. **If the selected
  batch id is invalid/cross-store, the whole document confirm fails (400)** — never
  a silent skip.
- **Admin web**: read-only "Stock" tab in the existing `admin/master-data` surface,
  all-stores view (admin bypasses `kode_toko` scoping).
- Backend work tracked in `backend/plans/next-enhancements.md` (new section);
  Flutter work tracked in root `plans/next-enhancements.md` (new section) — both as
  ad-hoc-originated backlog per `AGENTS.md` §7, not a fresh `e`/`enhance` pass.

## Backend design

### 1. Schema — new `backend/pfm-web-app/src/db/init-stock.ts`

```sql
CREATE TABLE IF NOT EXISTS stock_batches (
    id SERIAL PRIMARY KEY,
    kode_toko VARCHAR(255) NOT NULL REFERENCES store_master(kode_toko),
    no_sku VARCHAR(255) NOT NULL REFERENCES sku_master(no_sku),
    batch_code VARCHAR(255) NOT NULL,
    expiry_date DATE NOT NULL,
    outer_qty INTEGER NOT NULL DEFAULT 0,
    inner_qty INTEGER NOT NULL DEFAULT 0,
    created_at TIMESTAMP NOT NULL DEFAULT NOW(),
    updated_at TIMESTAMP NOT NULL DEFAULT NOW(),
    UNIQUE (kode_toko, no_sku, batch_code, expiry_date)
);
CREATE INDEX IF NOT EXISTS idx_stock_batches_store_sku ON stock_batches(kode_toko, no_sku);

CREATE TABLE IF NOT EXISTS stock_movements (
    id SERIAL PRIMARY KEY,
    batch_id INTEGER NOT NULL REFERENCES stock_batches(id) ON DELETE RESTRICT,
    document_id INTEGER REFERENCES documents(id) ON DELETE SET NULL,
    movement_type VARCHAR(20) NOT NULL CHECK (movement_type IN ('intake','decrement','adjustment','manual_seed')),
    outer_delta INTEGER NOT NULL DEFAULT 0,
    inner_delta INTEGER NOT NULL DEFAULT 0,
    note VARCHAR(500),
    created_by_account_id INTEGER REFERENCES accounts(id),
    created_at TIMESTAMP NOT NULL DEFAULT NOW()
);
CREATE INDEX IF NOT EXISTS idx_stock_movements_batch ON stock_movements(batch_id);
CREATE INDEX IF NOT EXISTS idx_stock_movements_document ON stock_movements(document_id);
```

No soft-delete/DELETE route — batches are edit-only, matching "manually editable,
never removed." No `CHECK (qty >= 0)` — decrements must go negative. Wrap in
`try/catch` + `console.error`, matching `init.ts`'s existing idiom for every other
table. Wire into `init.ts`: `import { initStockSchema } from "./init-stock"; await
initStockSchema(pool);` right after the accounts table's plaintext-password
migration block (~line 209, before the `arena_runs` table), since `stock_batches`
FKs both `store_master` and `sku_master`, both of which must already exist. This is
itself the AGENTS.md §3-compliant "split" — new logic lives in a fresh sub-256-line
file rather than growing the already-over-budget `init.ts` (562 lines) further.

### 2. New utils

- **`src/utils/stock-mapper.ts`** — `mapStockSummaryRow`, `mapStockBatchRow`,
  mirroring `document-mapper.ts`'s typed-row → response-shape pattern.
- **`src/utils/stock-movement.ts`** — `recordStockMovement(client, {batchId,
  documentId, movementType, outerDelta, innerDelta, note})` (single INSERT);
  `decrementBatchForProductScan(client, {batchId, kodeToko, documentId})` —
  `SELECT ... FOR UPDATE`, store-isolation check, `inner_qty = inner_qty - 1` (no
  floor), logs a `decrement` movement, returns `{ok:true}` or `{ok:false, reason}`.
- **`src/utils/stock-lookup.ts`** — `getInStockSkuSet(kodeToko)` (SKUs with
  `SUM(inner_qty) > 0`); `filterMatchesByStock(matches, inStock)` for the classifier
  candidate filter.

### 3. New routes under `src/app/api/v1/stock/`

- **`stock/route.ts`** — `GET` (summary per SKU: total outer/inner qty, batch
  count, nearest expiry, `has_expired` flag; non-admin forced to own `kode_toko`,
  admin sees all stores via optional `?kode_toko=`); `POST` (create/merge a batch —
  `{kode_toko?, no_sku, batch_code, expiry_date, outer_qty, inner_qty,
  document_id?}`, `withTransaction`: `INSERT ... ON CONFLICT
  (kode_toko,no_sku,batch_code,expiry_date) DO UPDATE SET outer_qty = outer_qty +
  EXCLUDED.outer_qty, inner_qty = inner_qty + EXCLUDED.inner_qty` then
  `recordStockMovement` with type `intake` if `document_id` present else
  `manual_seed`).
- **`stock/[noSku]/route.ts`** — `GET` batch list for one SKU (store-scoped),
  sorted by `expiry_date ASC`.
- **`stock/batches/[id]/route.ts`** — `PUT` edit a batch (`{batch_code?,
  expiry_date?, outer_qty?, inner_qty?, note?}`), `FOR UPDATE`, computes deltas,
  updates, logs `adjustment`; 403 on cross-store, 409 on unique collision.

All follow existing conventions: `getAccountFromAuthHeader`, inline
`NextResponse.json({status:"success", data:...})` (no `successResponse` helper
exists in this codebase — don't invent one), `errorResponse()` from
`utils/api-error.ts`.

### 4. Decrement integration — `documents/[id]/route.ts`

- Extend the existing `checkRes` SELECT to also fetch `scan_mode`.
- Accept new top-level PUT body field `stock_batch_id: number | null`.
- Inside the **existing** `withTransaction` block (reuse it — don't open a second
  transaction), after the `ocr_items` rewrite: if `doc.scan_mode === 'Product' &&
  stock_batch_id`, call `decrementBatchForProductScan`; on `{ok:false}`, `throw` a
  tagged error so the transaction rolls back, and the route's catch returns **400**
  (not the current 500) for this specific case.
- Net effect: document confirm and stock decrement are atomic — per the confirmed
  "fail the whole confirm on bad batch id" decision.

### 5. Product Scan candidate filtering

- `api/parse/route.ts`'s Product branch and `api/v1/scan-product/route.ts`: after
  calling `classifyAndMatchProduct()`, filter `possibleMatches` through
  `filterMatchesByStock(matches, await getInStockSkuSet(kodeToko))`. **Do not
  change `classifyAndMatchProduct`'s signature** — it's shared with the anonymous,
  store-agnostic desktop dev route; filter at the two authenticated call sites
  instead.

### 6. Admin web view

- Split `admin/master-data/page.tsx` (419 lines, already over threshold) into
  `page.tsx` (shell + login + tabs) + extracted `StoreManager.tsx` +
  `SkuManager.tsx` (pure extraction, no behavior change) + new `StockManager.tsx`
  (read-only: fetches `GET /api/v1/stock` with no `kode_toko` param as admin →
  all-store table; row click expands a batch sub-table via `GET
  /api/v1/stock/:noSku?kode_toko=...`).

## Flutter design

### 7. Data layer (new `lib/features/stock/`)

- `lib/models/stock_model.dart` — `StockBatch` (id, noSku, batchCode, expiryDate,
  outerQty, innerQty, `isExpired`/`isDepleted` getters), `StockItem` (summary row:
  noSku, namaItem, kodeToko?, totals, batchCount, nearestExpiryDate, hasExpired).
- `stock_response_parser.dart` — pure envelope unwrap (`{status,data}` → typed
  lists), mirroring `product_scan_response_parser.dart`.
- `stock_batch_sort.dart` — pure `sortBatchesForDisplay()` (expired-first, then
  soonest-expiry) and `pickClosestBatch(batches, extractedExpiry)`.
- `quantity_parse.dart` — pure `parseLeadingQty(String)` for `"10 KRG"` → `10`
  style extraction, used to seed the stock-entry screen's default pre-filled
  quantities from `DocumentItem.banyak`/`.jumlah`.
- `stock_provider.dart` — `StockNotifier extends StateNotifier<List<StockItem>>` +
  `stockProvider`, matching `pending_documents_provider.dart`'s conventions
  (network via `ref.read(apiClientProvider)`, no premature caching abstractions).
- `app_config.dart` — add `stockEndpoint = '/stock'`.
- `local_storage.dart` — new `stockEntryBoxName` Hive box (draft persistence for
  "Isi Nanti" resume), registered in `init()`, wiped in `clearAll()`.

### 8. Stock-entry screen (new `lib/features/stock/`)

`part of` + mixin split (matching both existing editor screens' convention):
- `stock_entry_screen.dart` — shell, receives `DocumentModel` via `state.extra`.
- `stock_entry_logic.dart` (`part of`) — per-item batch-draft state, Hive draft
  load/resume, `batchesSumMatches()` validation (pure function, own test file).
- `stock_entry_submit_logic.dart` (`part of`) — per-item submit
  (`stockProvider.createOrMergeBatch(..., documentId: document.id)`, idempotency
  via a `submitted` flag per batch draft so resume never double-POSTs), "Isi Nanti"
  (persist + pop), "Selesai" (clear draft + pop).
- `widgets/stock_entry_item_card.dart`, `widgets/stock_entry_batch_form.dart` (also
  reused by the Stocks menu's manual-add/edit).

**`editor_logic.dart`** — on `syncedToServer == true`, replace `context.pop(true)`
with `context.pushReplacement('/stock-entry', extra: finalDoc)`; extract the branch
into a new pure `lib/features/editor/document_submit_navigation.dart`
(`resolveDocumentSubmitNavigation({required bool syncedToServer})`), matching the
`resolveDocumentSaveAction`/`resolvePollOutcome` pattern already used twice in this
codebase. Keeps `editor_logic.dart` under 256 lines and testable without widget
mocking.

**`app_router.dart`** — add `/stock-entry` (`extra: DocumentModel`), `/stocks`,
`/stock-detail` (`extra: StockItem`).

### 9. Stocks menu (new `lib/features/stock/`)

- `stocks_screen.dart` — "Perlu diisi" banner (from Hive drafts, tap-to-resume),
  searchable SKU list.
- `stock_detail_screen.dart` — batch list via `sortBatchesForDisplay`, expired-red
  flag, tap-to-edit (bottom sheet, reuses `stock_entry_batch_form.dart`), FAB "+
  Tambah Batch Manual" (`documentId: null` → `manual_seed`).
- `camera_drawer.dart` — new `buildDrawerItem(icon: Icons.inventory_2_outlined,
  title: 'Stok', onTap: () { Navigator.pop(context); context.push('/stocks'); })`
  right after "History".

### 10. Product Scan rewrite

- `product_editor_data_logic.dart` — `_skuBatches` becomes `Map<String,
  List<StockBatch>>`; classifier-matched-SKU branch additionally fetches real batch
  data per candidate (`stockProvider.fetchBatchDetail`); fallback branch switches
  from `masterSkusEndpoint` to `stockEndpoint` (filtered to qty > 0) — this
  **removes** a code path rather than adding one, and removes the manual-date-entry
  fallback entirely (no longer a valid state once candidates are stock-guaranteed to
  have ≥1 batch).
- `product_editor_submit_logic.dart` — add `selectedStockBatchId` to
  `finalDoc`/`toPutPayload()` as `stock_batch_id`.
- `product_expiry_card.dart` — rewritten props (`List<StockBatch> batches`,
  `StockBatch? selectedBatch`), depleted-batch warning row. Update
  `test/product_expiry_card_test.dart` for the new shape (breaking change, not
  additive).
- `document_model.dart` — add `selectedStockBatchId` field.

## Sequencing (7 chunks, backend → Flutter → admin)

1. Backend schema + core CRUD (`init-stock.ts`, `stock-mapper.ts`,
   `stock-movement.ts`'s `recordStockMovement`, all 3 stock routes). Verify live:
   merge-add, 409 on collision, correct movement rows.
2. Backend decrement hook + in-stock filter (`decrementBatchForProductScan`,
   `documents/[id]/route.ts` wiring, `stock-lookup.ts`, `parse/route.ts` +
   `scan-product/route.ts` filtering). Verify live: decrement to negative, 400 on
   bad batch id, filtered candidates.
3. Flutter data layer (models, parser, sort/qty pure functions, provider, Hive
   box, config). Unit tests only.
4. Flutter stock-entry screen + DO-confirm integration (`editor_logic.dart`,
   `document_submit_navigation.dart`, router). Live-verify: DO confirm →
   stock-entry → submit → Postgres rows; "Isi Nanti" resumability.
5. Flutter Stocks menu (list/detail screens, drawer, manual add/edit).
   Live-verify search, expiry sort/flag, manual seed, edit.
6. Flutter Product Scan rewrite (`product_editor_data_logic.dart`,
   `product_editor_submit_logic.dart`, `product_expiry_card.dart`, updated test).
   Live-verify: depleted SKU disappears from candidates, closest-expiry auto-pick,
   decrement (including going negative).
7. Admin web (`page.tsx` split + `StoreManager.tsx`/`SkuManager.tsx` extraction +
   new `StockManager.tsx`). Live-verify cross-store view.

Backend chunks (1-2, 7's backend half) are tracked as backend/plans
`§12`; Flutter chunks (3-6) are tracked as root plans `§9`. Each task flips
`[TODO]` → `[DONE]` and gets logged in the relevant `docs/feature-list.md` as it
ships, per the normal `n`/`next` workflow.

## Testing plan

**Dart unit tests** (pure functions, no Dio mocking — this repo's established
convention): `stock_response_parser_test.dart`, `stock_batch_sort_test.dart`
(ordering + `pickClosestBatch`), `quantity_parse_test.dart`,
`document_submit_navigation_test.dart`, `stock_entry_sum_validation_test.dart`.
Update `product_expiry_card_test.dart` for the new prop shape.

**Backend**: no existing route-test harness — this repo relies on live
verification against the running Docker stack (per established practice). For
each chunk: `docker compose up -d --build`, curl every new endpoint as both a
store account and admin, confirm merge/409/movement-row correctness, then a real
end-to-end pass through the actual Flutter app (DO scan → confirm → stock-entry →
submit; Product Scan → depleted-SKU exclusion → decrement) with Postgres row
checks, matching how prior tasks (6.1–8.2, 9.x, 10.x, 11.1) were verified in this
repo's iteration logs.

## Open implementation-time decisions (flagged during planning, not yet re-confirmed)

- Whether an invalid/cross-store `stock_batch_id` should ever be *allowed* to skip
  silently instead of failing the whole confirm — resolved: **fail the whole
  confirm (400)**, per user answer during grilling.
- Stock-entry screen default state (ask batch count upfront vs. start with 1
  pre-filled batch) — resolved: **start with 1 pre-filled, "+ Tambah Batch" to
  split**, per user answer during grilling.