ERP-core/docs/20-FRONTEND.md

# 20 · FRONTEND — Phase 1 (Inventory & Supply Chain)

> **Authoritative for:** frontend user-flows, the rules to follow the existing architecture, and the validation posture.
> **Navigation:** you arrived from `00-CORE.md`. The API contract this UI consumes is in `11-BACKEND-PHASE1.md`; business rules are in `10-BACKEND-PHASE1.md`. Record work in `Frontend/PROGRESS.md`.
> **Note:** the Frontend project is **already initialized** (Next.js, App Router, TypeScript). This document does **not** scaffold structure — it governs how to build within what exists.

---

## 1. Stack & architecture rules

| Concern | Rule |
|---|---|
| Framework | Next.js **App Router** + **TypeScript**. Work within the existing structure; do not restructure or introduce a competing router. |
| Styling / UI | **Tailwind CSS** for all styling — no CSS modules, styled-components, or inline style objects. UI primitives come from **shadcn/ui** (`components/ui/`, built on `@base-ui/react` + `class-variance-authority`); use/extend existing components there before adding a new one, and generate new primitives via the shadcn CLI to keep the pattern consistent. |
| State / forms | **Plain React hooks** (`useState`, `useReducer`, custom hooks). No form/state library. |
| Validation | **Dependency-free** (hand-rolled helpers). See §3. |
| API access | A single **typed fetch client** (`lib/api-client.ts`) against a **same-origin `/api/v1`**; all calls go through it. No scattered `fetch()` in components. |
| Transport | The API is reached through a **Next `rewrites()` proxy** (`next.config.ts`: `/api/*` → `BACKEND_ORIGIN`, default `http://localhost:5224`). Same-origin by construction, so there is no CORS on the backend and none is needed. `BACKEND_ORIGIN` is **server-side only** — deliberately not `NEXT_PUBLIC_*`, since the browser only ever talks to the Next server. |
| Types | TS types in `types/` **mirror the API DTOs** in `11-BACKEND-PHASE1.md`. When the contract changes, update these first. |
| Auth | **httpOnly cookie session — there is no bearer token to store.** `POST /auth/login` sets `erp_at`/`erp_rt`/`XSRF-TOKEN`; the client just sends `credentials: "include"`. JS cannot read `erp_at` by design. `proxy.ts` guards `/dashboard/*` on the cookie's *presence* only (it cannot validate an RS256 JWT at the edge) — **the API remains the authority**. `lib/auth-session.ts` caches the user *profile* in localStorage for display only, because there is no `GET /auth/me`; it is not a credential. |

Principles:
- **The API contract is the source of truth.** The UI adapts to `11-BACKEND-PHASE1.md`, never the reverse.
- **Keep components thin;** put data-fetching and derived state in hooks, request/response shaping in the API client.
- **One typed client method per endpoint**, returning the DTO type from `types/`.

---

## 2. User flows

The flow below is the end-to-end Phase-1 journey: replenishment need → procurement → receiving → QC hold → stock available → stock operations, with the reorder loop closing back. Colour = functional role. Roles now drive real sidebar visibility (`GET /auth/me`'s `navCodes`, see docs/10 C.8/docs/11 §2.0.1, admin screens at `/dashboard/settings/roles` and `/dashboard/settings/users`) but **per-endpoint RBAC is still not enforced** — this remains a UI-level filter only.

> **Roles screen (2026-07-18):** `code` is never typed by an operator — it's derived client-side from `name` (uppercased, non-alphanumeric → `_`) and shown read-only, on both create and edit. The Create Role dialog also includes the permission checkbox tree (`components/auth/RolePermissionTree.tsx`, fed by `GET /nav`), so creating a role and assigning its sidebar permissions is one Save action; the detail page (`/dashboard/settings/roles/[id]`) remains for later edits. The Create User dialog's "User type" is a `<Select>` populated from `GET /users/user-types` (proxying AuthHex's `listUserTypes`), defaulting to the sole existing type — operators never type an AuthHex UserType GUID by hand.

```mermaid
flowchart TD
    START([Replenishment need]):::trigger
    ALERT[/Reorder alert raised<br/>available at or below reorder point/]:::system

    START --> REQ[Create Requisition<br/>Procurement officer]:::proc
    ALERT --> REQ
    REQ --> SUBREQ[Submit requisition]:::proc
    SUBREQ --> RFQDEC{RFQ needed?}:::decision
    RFQDEC -->|Yes| RFQ[Create RFQ and send to vendors]:::proc
    RFQ --> QUOTE[Record vendor quotations]:::proc
    QUOTE --> COMPARE[Compare and select vendor]:::proc
    COMPARE --> PO[Create Purchase Order]:::proc
    RFQDEC -->|No| PO

    PO --> APPRDEC{approvalRequired?}:::decision
    APPRDEC -->|No - Phase 1 default| AUTOAPP[[Auto-approved on creation]]:::system
    APPRDEC -->|Yes| PENDING[Pending approval]:::proc
    PENDING --> APPROVE{Approver decision}:::decision
    APPROVE -->|Reject| REJECTED([PO rejected]):::endp
    APPROVE -->|Approve| APPROVED[PO Approved and issued to vendor]:::proc
    AUTOAPP --> APPROVED

    APPROVED --> ARRIVE([Goods arrive from vendor]):::trigger
    ARRIVE --> GRN[Create GRN against PO<br/>Storekeeper]:::wh
    GRN --> ENTER[Enter qty, bin, batch/serial]:::wh
    ENTER --> TOLDEC{Over-receipt beyond tolerance?}:::decision
    TOLDEC -->|Yes| BLOCKREC([Blocked / warn]):::endp
    TOLDEC -->|No| HOLDDEC{Inspection required?}:::decision
    HOLDDEC -->|Yes| RECVHOLD[Receive as OnHold]:::wh
    HOLDDEC -->|No| RECVOK[Receive as Available]:::wh
    RECVHOLD --> CONFIRM[Confirm GRN]:::wh
    RECVOK --> CONFIRM
    CONFIRM --> FIFO[[Create FIFO layer + post stock ledger + update PO qtyReceived]]:::system

    FIFO --> HELDQ{Line on hold?}:::decision
    HELDQ -->|Yes| INSPECT[QC inspection<br/>Inventory controller]:::controller
    INSPECT --> INSPDEC{Pass inspection?}:::decision
    INSPDEC -->|Release| AVAIL
    INSPDEC -->|Reject| PRET[Create Purchase Return]:::proc
    PRET --> RETPOST[[Post outbound ledger]]:::system
    RETPOST --> RETEND([Returned to vendor]):::endp
    HELDQ -->|No| AVAIL([Stock Available]):::stock

    AVAIL --> OPS{Stock operation}:::decision
    OPS -->|Transfer| TR1[Create transfer<br/>source and destination]:::wh
    OPS -->|Adjust| AD1[Create adjustment + reason code<br/>Inventory controller]:::controller
    OPS -->|Count| CN1[Create count - cycle or full<br/>Storekeeper]:::wh

    TR1 --> TRDISP[Dispatch]:::wh
    TRDISP --> TRAVAIL{Available covers qty?}:::decision
    TRAVAIL -->|No| TRBLOCK([Negative-stock block]):::endp
    TRAVAIL -->|Yes| TRIT[[Consume source layers, status In-Transit]]:::system
    TRIT --> TRREC[Receive at destination]:::wh
    TRREC --> TRDONE[[Create destination layer at inherited cost - cost-preserving]]:::system
    TRDONE --> AVAIL

    AD1 --> ADDEC{Decrease exceeds available?}:::decision
    ADDEC -->|Yes| ADBLOCK([Negative-stock block]):::endp
    ADDEC -->|No| ADPOST[[Auto-post: FIFO consume/create + ledger]]:::system
    ADPOST --> AVAIL

    CN1 --> CNSNAP[[Snapshot system qty]]:::system
    CNSNAP --> CNCOUNT[Enter counted qty]:::wh
    CNCOUNT --> CNVAR[[Compute variance]]:::system
    CNVAR --> CNPOST[Post count<br/>Inventory controller]:::controller
    CNPOST --> CNADJ[[Variance adjustment + ledger]]:::system
    CNADJ --> AVAIL

    AVAIL -.->|monitor available vs reorder point| ALERT

    classDef trigger fill:#fff2cc,stroke:#d6b656,color:#333;
    classDef proc fill:#d5e8d4,stroke:#82b366,color:#333;
    classDef wh fill:#ffe6cc,stroke:#d79b00,color:#333;
    classDef controller fill:#e1d5e7,stroke:#9673a6,color:#333;
    classDef system fill:#dae8fc,stroke:#6c8ebf,color:#333;
    classDef stock fill:#d5e8d4,stroke:#2d7d2d,color:#173d17;
    classDef decision fill:#f8f4d0,stroke:#b0a133,color:#333;
    classDef endp fill:#f8cecc,stroke:#b85450,color:#333;
```

### 2.1 Flows → API mapping
Each screen calls the endpoints in `11-BACKEND-PHASE1.md`. System steps (blue) are performed server-side — the UI only triggers them and renders the result.

| Flow | Screens | Key endpoints |
|---|---|---|
| Login | Login | `POST /auth/login` (sets the session cookies), `POST /auth/logout` |
| Replenishment | Reorder alerts | `GET /stock/reorder-alerts`, `POST /stock/reorder-alerts/{itemId}/requisition` |
| Procurement | Requisition, RFQ, PO | `POST /requisitions`, `/rfqs`, `/rfqs/{id}/quotations`, `GET /rfqs/{id}/comparison`, `POST /purchase-orders`, `PUT /purchase-orders/{id}` |
| Receiving | GRN | `POST /grns`, `POST /grns/{id}/confirm`, `POST /grns/{id}/lines/{lineId}/release` |
| Returns | Purchase return | `POST /purchase-returns` |
| Stock enquiry | Stock views | `GET /stock/on-hand`, `/stock/ledger`, `/stock/valuation` |
| Transfer | Transfer | `POST /stock-transfers`, `/dispatch`, `/receive` |
| Adjustment | Adjustment | `POST /stock-adjustments` |
| Count | Count | `POST /stock-counts`, `PUT /stock-counts/{id}/counts`, `POST /stock-counts/{id}/post` |

### 2.2 Master data screens (supporting, outside the core flow)
Vendors, Items, Categories, Subcategories, UOM, Warehouses, Brands, and Item Types are supporting master-data CRUD screens the flow above depends on but doesn't itself route through, so they're intentionally absent from the diagram/table. List screens follow one pagination convention: `page`/`pageSize`/`q`/`sortOrder` params, page size 5, debounced search, Previous/Next controls.

> **2026-07-17 — the frontend is connected to the real API.** `lib/api/mock-data.ts` is **deleted**; every `lib/api/*.ts` module calls the backend. The drift listed here previously has been reconciled — what follows records the decisions so they are not re-litigated.

**Brand** (`app/dashboard/products/brands`), **Item Type** (`app/dashboard/products/item-types`, formerly "Variant Category") and **Subcategory** (`app/dashboard/products/categories/[id]`) are real backend entities (`docs/11 §2.3/2.6/2.7`). The item builder on `/dashboard/products/new` reads the Item Type list live from `GET /item-types`: checking a type (Color, Size, or any custom one added inline from that same page) reveals a value-entry section for it, and one Item is created per combination across however many types are checked, with a client-generated SKU. See `Frontend/PROGRESS.md` for the history.

#### 2.2.1 Resolved contract decisions (backend is authoritative — §1)
- **`variantCategoriesApi` → `itemTypesApi`** (`GET /item-types`); `variantCategoryId` → `itemTypeId`.
- **`Item.itemType` → `stockNature`.** `itemType` now means a Color/Size dimension master — a different concept (`docs/11 §2.7`). The item-detail label reads "Stock nature".
- **Both category FKs travel.** The builder sends `categoryId` **and** `subCategoryId`; the old `subCategoryId ?? categoryId` collapse lost the parent. The server rejects a mismatched pair with 422. Subcategories are their own resource — `Category.parentId` and `?tree=true` are gone.
- **Colour hex-packing stays frontend-only.** There is no value table server-side, so `"Red|#EF4444"` + `encodeColorValue`/`decodeColorValue`/`isColorCategory` have nothing to reconcile against. Kept as-is.
- **SKU generation stays client-side** (`buildVariantSku`) and is the *only* record of which colour/size an item is; the server only uniqueness-checks it. **Nothing can query items by colour** — accepted (`docs/10 Part C.9`).
- **`remove()` → `updateStatus(id, "Inactive")`** everywhere. There are no `DELETE` endpoints on any master (FR-MD-08); the lists show a Status column and Deactivate/Activate.
- **`initialQty` is gone** from the builder — the Item contract has no such field and there is no initial-receipt flow. Stock arrives via a GRN.
- **Sale-price toggle on the builder (2026-07-22).** A "Fixed price / Use stock value" toggle sits on `/dashboard/products/new`. **Use stock value** (default) sends `salePrice: null` on every created item (sold at FIFO value). **Fixed price** reveals a top "fix value" input that pre-fills a per-variant `Sale price` column; each row is editable, and submit is blocked until **every** generated variant has a price `> 0`. The toggle is **frontend-only** — the contract is just the nullable `salePrice` field (`docs/11 §2.1`); it is Sales-only and never affects GRN/costing. The non-transactional create loop still applies — each variant's `salePrice` rides its own `POST /items`.
- **Product Configuration** (`app/dashboard/products/settings`, `GET`/`PUT /product-config`) — only **3** of the original design's ~13 toggles exist. `subcategoriesEnabled`/`brandsEnabled` are server-enforced (`CONFIG_DISABLED`); **`itemTypesEnabled` is advisory** and this app is what honours it (it hides the builder's type section). The UI states that distinction on the screen rather than implying a guarantee.
- **Non-transactional create loop:** the builder's per-row `itemsApi.create()` has no transaction — a `SKU_DUPLICATE` on row 7 of 12 leaves 6 items created. The error message now says how many landed rather than implying nothing happened. A transactional bulk-create endpoint would be the real fix.
- **GRN edit/delete removed** — the API has no `PUT`/`DELETE` for a GRN; receipts are corrected by reversing documents (FR-X-05).
- **GRN off-PO items + inline item create (2026-07-22).** On `/dashboard/receiving/grn/new`, "Add line" is available in **both** PO and direct mode — an added line in PO mode has `poLineId: null` and receives an item not on the PO (editable item/UOM dropdowns, `unitCost` required). A **"New item"** button opens `/dashboard/products/new` in a **new browser tab** (`window.open`, the first such pattern in the app), and a **refresh icon** re-pulls `GET /items?status=Active` so the newly created item is selectable **without** reloading the screen and losing the in-progress GRN. Server treats off-PO lines as direct receipts (no over-receipt check) — `docs/11 §4.1`.
- **RFQ invited-vendors is not persisted** — `POST /rfqs` validates `vendorIds` then discards them, so the list/detail screens show quotations received instead of vendors invited.
- **Known gap — serial numbers:** FR-GRN-04 requires capturing serials on receipt, but `CreateGrnLineInput` has no such field (only `batch`). The UI does not collect them rather than silently discarding them. Needs a backend change to honour the requirement.

---

## 3. Validation posture (read carefully)

**Validate on the client for UX; never trust the client. The server is the authority.** The browser can be bypassed (devtools, direct API calls, replays), so client checks exist only to give fast feedback and reduce round-trips — they are **never** the enforcement point.

### 3.1 Two categories
**Client-side (UX only — safe to check locally):** purely input-level facts the browser already has.
- Required fields present.
- Format: SKU pattern, numeric fields numeric, date format, positive integers.
- Range/bounds: `qty > 0`, `unitPrice >= 0`, `factor > 0`. Item `salePrice` is a client-supplied number — the builder requires `> 0` per variant in fixed mode; the server only checks `>= 0` on a supplied value (`docs/11 §2.1`).
- Simple cross-field input rules: transfer `destWarehouseId != srcWarehouseId`.
- Enum membership via constrained dropdowns (`stockNature` — ex-`itemType`, `trackingMode`, `countType`, `holdStatus`). Note the **Item Type** dropdown is *not* in this category: it's server data (`GET /item-types`), not an enum.

**Server-authoritative (client MUST NOT assume — only the server can judge):** anything depending on current server state.
- **Stock availability / negative-stock block** (depends on live ledger) — `STOCK_NEGATIVE_BLOCKED`.
- **FIFO layer sufficiency** on any issue.
- **Over/under-receipt tolerance** vs PO open quantity — `OVER_RECEIPT_TOLERANCE`.
- **SKU uniqueness** — `SKU_DUPLICATE`.
- **Batch expiry / on-hold issuability** — `EXPIRED_BATCH_BLOCKED`, `ONHOLD_NOT_ISSUABLE`.
- **PO editability** (status-dependent) — `PO_NOT_EDITABLE`.
- **Referential existence/active status** of item/vendor/warehouse/bin.
- **Concurrency** (stale edit) — `CONCURRENCY_CONFLICT` via `ETag`/`If-Match`.
- **Reason code required/valid** — `REASON_CODE_REQUIRED`.

> Rule of thumb: if answering "is this allowed?" requires knowing the **current stock, a document's status, or another user's change**, it is server-authoritative. Do not gate submission on a client-side guess about it, and do not show it as "valid" until the server confirms.

### 3.2 Handling server responses
- Always send the request and handle the outcome; the server response is the truth.
- On `400` `ValidationProblemDetails`, map `errors` to fields.
- On `409` / `422` domain errors, read `code` and show a specific message (e.g. `STOCK_NEGATIVE_BLOCKED` → "Not enough available stock"). Keep a `code → message` map in `lib/` so messages are consistent.
- On `412` (`CONCURRENCY_CONFLICT`), tell the user the record changed and refetch before retrying.
- Never silently swallow a `ProblemDetails`; surface it.

### 3.3 What not to do
- Don't disable the submit button based on a client assumption about stock, availability, or status.
- Don't reimplement FIFO/tolerance/negative-stock logic in the browser — you cannot see the live ledger.
- Don't trust quantities computed client-side for posting; send inputs and let the server compute costed movements.

---

## 4. Error & empty states
- Every list screen handles loading, empty, and error states explicitly.
- Surface the API client's normalized error (from `ProblemDetails`) with the domain `code` message where present.
- For transactional actions (GRN confirm, transfer dispatch/receive, adjustment, count post), show the server's returned side effects (created/consumed layers, ledger refs) as confirmation rather than assuming success.

---

*End of 20-FRONTEND.md. API contract: `11-BACKEND-PHASE1.md`. Record work: `Frontend/PROGRESS.md`.*