serial numbers

docs/ITEM_TRACKING_PLAN.md

@@ -0,0 +1,242 @@
+# Item Tracking (Serial / Batch / Expiry / Warranty) — ERP-core Plan
+
+**Status**: Implemented 2026-10-07 on branch `ui-bug-fixers` (uncommitted). Migration
+`20261007054513_AddItemTrackingSerialsWarranty` generated and **not yet applied** — `Program.cs` runs
+`MigrateAsync` on startup, so it applies on the next backend start. See §6 for what was built
+differently from the plan and §7 for what is still open.
+**Origin**: adapted from the distribution system's `item_tracking_plan.md`. That plan does **not** map
+1:1 — ERP-core already has most of its foundation (see §1). This plan covers only the gaps.
+
+| Phase | Title | Status |
+|-------|-------|--------|
+| 0 | Decisions (see §3) | ✅ Recommendations D1–D7 adopted as written |
+| 1 | `Serial` entity hardening (status enum, location, provenance) | ✅ |
+| 2 | GRN serial capture + per-serial FIFO layers | ✅ |
+| 3 | Serial-aware / FEFO stock consumption | ✅ |
+| 4 | Sales documents — batch/serial on invoice lines, mandatory on tracked items | ✅ (bundles: see §7) |
+| 5 | Warranty start at sale (`WarrantyRegistration`) | ✅ |
+| 6 | Returns — sales return restock to batch/serial, purchase return of serials | ✅ |
+| 7 | Transfers, adjustments, counts — serial carry-through | ✅ |
+| 8 | Frontend — GRN serial entry, sale pickers, lookups | ✅ (gaps in §7) |
+| 9 | Reports — serial/warranty lookup, batch expiry, stock by batch | ✅ (expiry notifications: §7) |
+| 10 | Migration + tests | ✅ migration generated · ✅ 15 unit tests · ❌ e2e |
+
+---
+
+## 1. What already exists (do not rebuild)
+
+| Area | Where | Notes |
+|---|---|---|
+| Global toggles | `Domain/Entities/ProductConfig.cs` (`SerialNumbersEnabled`, `BatchListsEnabled`, `WarrantyPeriodsEnabled`, `CustomWarrantyPeriodsEnabled`) | Singleton row, enforced on item writes. Replaces the other plan's `SysConfig` keys. |
+| Per-item mode | `Item.TrackingMode` (`None`/`Batch`/`Serial`), `Item.Warranty`, `Item.WarrantyPeriodMonths` | Mutually exclusive mode — an item is batch **or** serial, never both. Expiry lives on `Batch`, so there is no separate expiry flag. |
+| Warranty periods | `WarrantyPeriod` master + `WarrantyPeriods.AllowedMonths` (3/6/12/18) | Months, not days. Validated in `ItemService.ValidateWarrantyPeriod`. |
+| Batches | `Batch` (`BatchNo`, `ExpiryDate`, `Barcode`), unique `(ItemId, BatchNo)` | Created/reused at GRN by `GrnService.ResolveBatchAsync`. |
+| Serials | `Serial` (`SerialNo`, `Status` **string**, `Barcode`), unique `(ItemId, SerialNo)` | Entity exists but **nothing creates rows** (see §2). |
+| Ledger / layers | `StockLedger.BatchId/SerialId`, `StockLayer.BatchId/SerialId` | Columns exist; `SerialId` is always written `null` today. |
+| Expiry block | `FifoCostingService.ConsumeAsync` excludes expired batches, throws `EXPIRED_BATCH_BLOCKED` for an explicit expired batch | |
+| Warranty numbers at GRN | `GrnLineWarrantyNumber` — one per received unit, period snapshotted from item | Unique only per GRN line, not globally. |
+| Sales slip | `SalesSlipLine.BatchId/SerialId`; `SalesPostingService` passes batch to FIFO and flips `Serial.Status = "Sold"` | |
+| Scan lookup | `ItemService` scan resolves item / batch / serial by barcode or number | |
+| Counts | `CountService` snapshots per batch and per serial | Serial branch relies on per-serial layers that never exist. |
+
+## 2. Gaps found (the actual work)
+
+1. **Serials are never received.** `CreateGrnLineInput` has no serial field (frontend `types/grn.ts`
+   documents this as "KNOWN GAP"), `GrnService` never creates `Serial` rows, and
+   `ConfirmAsync` creates one layer per line with `serialId: null`. A `Serial`-mode item can be
+   received with no serials at all.
+2. **FIFO cannot consume a specific serial.** `ConsumeAsync` takes `batchId` only; the slip posting
+   flips the serial to `Sold` without proving that serial's stock was the stock consumed.
+3. **Sales invoices drop batch/serial.** `SalesInvoiceLine` has no `BatchId`/`SerialId`;
+   `PostInvoiceAsync` passes `null, null` (`SalesPostingService.cs:166`). The invoice UI carries
+   them as display-only metadata. Bundle sales also pass `null, null`.
+4. **Tracking is never mandatory on issue.** A batch- or serial-tracked item can be sold, transferred,
+   or adjusted with no batch/serial, so batch balances and serial status drift.
+5. **No FEFO.** Consumption orders by `ReceiptDate`, although `Batch` docs say "expiry drives FEFO".
+6. **Warranty never starts.** `GrnLineWarrantyNumber` records a period, but nothing records the sale
+   date, customer, or expiry date, and there is no lookup.
+7. **Returns lose identity.** `SalesReturnService` restocks via `StockDelta(itemId, null, null, qty)`
+   — no batch, no serial status change, warranty not voided. `PurchaseReturnService` likewise
+   ignores serials.
+8. **Transfers/adjustments** carry `BatchId` only; serial location is never tracked.
+9. **`Serial.Status` is a free string** (`"InStock"`, `"Sold"`) — no enum, no validation.
+
+## 3. Decisions needed before Phase 1 (Phase 0)
+
+| # | Question | Recommendation |
+|---|---|---|
+| D1 | Warranty number vs serial number — for a `Serial` + `Warranty` item, are they the same identifier? | **Yes, use the serial as the warranty identity** and skip `WarrantyNumbers` for serial items. Keep `GrnLineWarrantyNumber` only for warranty items with `TrackingMode = None`. |
+| D2 | Should `Warranty = Warranty` require `TrackingMode = Serial`? | Not forced now (would break existing items); revisit after D1 ships. |
+| D3 | Which document starts warranty? | **Posting of the stock-consuming sale**: slip, invoice and bundle all go through `SalesPostingService.PostAsync`, so one hook covers all three. This settles the other plan's open Phase 13 question. |
+| D4 | One serial per sales line, or many? | **Many**: add a child `…LineSerial` table rather than forcing `Qty = 1` per line (`SalesSlipLine.SerialId` becomes legacy/compat). |
+| D5 | Batch item sold with no batch chosen | **Auto-allocate FEFO** server-side, splitting across batches. Record each allocation on the line. |
+| D6 | Legacy stock of serial items received before Phase 2 (layers with no serial) | Allow issuing serial-less stock **only while** untracked layers remain (`QtyRemaining > 0`, `SerialId IS NULL`); after that, a serial is required. Optionally a one-off "assign serials to existing stock" adjustment. |
+| D7 | Warranty start date: post date or a delivery date? | Post date (no delivery document exists). |
+
+## 4. Phases
+
+### Phase 1 — `Serial` hardening
+- `Domain/Enums/SerialStatus.cs`: `InStock, Reserved, Sold, ReturnedByCustomer, ReturnedToVendor, Damaged, Scrapped`.
+  Map with `HasConversion<string>()` in `BatchSerialConfiguration` — existing `"InStock"`/`"Sold"`
+  values stay valid, so no data migration is needed.
+- Add to `Serial`: `WarehouseId?`, `BinId?` (current location), `GrnLineId?` (provenance),
+  `ReceivedAt`, `CreatedAt`, `UpdatedAt`, `RowVersion`.
+- Index `(ItemId, Status)`, `(WarehouseId, ItemId, Status)`.
+
+### Phase 2 — GRN serial capture
+- `CreateGrnLineInput.SerialNumbers: List<string>?`; `GrnLineDto.Serials`.
+- New `GrnLineSerial` (`GrnLineId`, `SerialNo`), unique `(GrnLineId, SerialNo)` — the draft holds numbers only.
+- `GrnService.CreateAsync` → `ResolveSerialNumbers(item, input, qty)`, the same pattern as
+  `ResolveWarrantyNumbers`: required iff `TrackingMode == Serial`; count must equal `Qty`, and `Qty`
+  must be a whole number; trimmed, distinct within the request, and not already an existing `Serial` for the item;
+  rejected when the mode is not `Serial`. Per D1, a serial+warranty item does not need `WarrantyNumbers`.
+- `ConfirmAsync`: for serial lines create one `Serial` per number (`InStock`, warehouse/bin, `GrnLineId`)
+  and **one layer + one ledger row per serial (qty 1)** via the existing
+  `CreateInboundLayerAsync(..., serialId, ...)` / `PostLedgerAsync(..., serialId, ...)`. Re-check
+  uniqueness inside the transaction (a concurrent GRN could take the number). GL posting is unchanged.
+- Hold/reject: serials on an `OnHold`/`Rejected` line remain `InStock` but non-issuable through the existing layer filter.
+
+### Phase 3 — Serial-aware and FEFO consumption (`FifoCostingService`)
+- `ConsumeAsync(itemId, warehouseId, batchId, qty, ct, allowShortfall, serialIds = null)`: when
+  `serialIds` is given, issue exactly those layers (each must be open, qty 1, issuable) or throw a new
+  `SERIAL_NOT_AVAILABLE` (409).
+- Ordering: for `Batch` items with no batch given, order candidates by `b.ExpiryDate` (nulls last),
+  then `ReceiptDate`, which gives FEFO. `None` items keep pure FIFO.
+- New `AllocateBatchesAsync(itemId, warehouseId, qty)` → `[(batchId, qty)]` for D5 and for UI suggestions.
+- Keep the deliberate "settle shortfall layers before the batch filter" behaviour; add tests around it.
+
+### Phase 4 — Sales documents
+- New `SalesInvoiceLineAllocation` / `SalesSlipLineAllocation` (`LineId`, `BatchId?`, `SerialId?`, `Qty`),
+  following D4/D5. Request DTOs accept `batchId?` and `serialIds?`; existing `SalesSlipLine.SerialId`/`BatchId`
+  are still read for old documents.
+- Validation in `SalesDomainService` (shared by slip/invoice/bundle):
+  `Serial` → serial count equals `Qty + FreeQty`, each `InStock` in the line warehouse (D6 exception);
+  `Batch` → given batch has stock and is not expired, or none given → FEFO allocation on post.
+- `SalesPostingService.PostAsync`: `PostingLine` carries allocations; consume per allocation; one
+  ledger row per serial; serial → `Sold`, location cleared. Replace the current `null, null` for
+  invoices (line 166) and bundles (line 236).
+- Over-stock sale (`allowShortfall`) is not allowed for serial items (a serial cannot go negative).
+
+### Phase 5 — Warranty registration
+- New `WarrantyRegistration`: `ItemId`, `SerialId?`, `GrnLineWarrantyNumberId?`, `CustomerId?`,
+  `SourceDocType`/`SourceDocId`/`LineId`, `StartDate`, `PeriodMonths`, `EndDate`, `Status` (`Active`, `Voided`, `Claimed`).
+- Created in `PostAsync` after consumption for items with `Warranty = Warranty`:
+  `PeriodMonths` = the receipt snapshot (`GrnLineWarrantyNumber.WarrantyPeriodMonths`, or the item's
+  current `WarrantyPeriodMonths` for serial items) and `EndDate = StartDate.AddMonths(PeriodMonths)`.
+- For non-serial warranty items: the sale must name which warranty numbers leave (picker, the same
+  shape as serials), or else D1/D2 is revisited.
+- `GET /api/warranty?serialNo=|warrantyNo=|customerId=` → status and days remaining.
+
+### Phase 6 — Returns
+- `SalesReturnLine` gets `BatchId?` and serial allocations. `StockDelta` (`IStockMutator`) gets an
+  optional `SerialId`; `StockMutator` passes it to layer and ledger.
+- The return reason (existing `ReasonCode`) maps the serial to `InStock` (restock) or `Damaged`;
+  the batch restocks into the **same** batch; the matching `WarrantyRegistration` → `Voided`.
+- A serial can be returned only if it was sold on the referenced invoice line.
+- `PurchaseReturnService`: serial layers being returned → `ReturnedToVendor`.
+
+### Phase 7 — Transfers, adjustments, counts
+- `StockTransferLine` + `StockAdjustmentLine`: serial allocations; transfer moves the per-serial
+  layer and updates `Serial.WarehouseId/BinId`; a negative adjustment of a serial → `Scrapped`/`Damaged`.
+- `CountService` variance posting for serials: found → create layer + `InStock`; missing → consume + `Damaged`
+  (confirm wording with ops). Its existing serial snapshot starts working once Phase 2 writes per-serial layers.
+- Production (`ProductionRunService` blocks tracked finished goods) — **out of scope**, unchanged.
+
+### Phase 8 — Frontend (`Frontend/erp-system`)
+- `receiving/grn/new`: per-line serial entry for `Serial` items (scan field — Enter adds; paste list;
+  auto-generate prefix + start; "n of N" counter; save disabled until complete). Remove the
+  "KNOWN GAP" note in `types/grn.ts` and add rules in `lib/validations/grn.ts`. Hide warranty-number
+  entry for serial items (D1).
+- `receiving/grn/[id]`: show serials per line (collapsible).
+- Sales slip / invoice / bundle: serial picker (scan or search `InStock` serials in the line warehouse)
+  and batch picker with expiry and FEFO suggestion; turn the existing scan metadata into real request fields.
+- Sales return: pick serials and batches from the original invoice line.
+- New `stock/serials` (search by serial → status, location, GRN, sale, warranty) and a warranty lookup.
+
+### Phase 9 — Reports
+- Stock on hand by batch, with expiry; "expiring in N days" (feeds the notification module —
+  `NotificationModuleCatalog`).
+- Serial register / history (from `StockLedger.SerialId`).
+- Warranty register: active, expiring, expired.
+
+### Phase 10 — Migration + tests
+- One EF migration per phase group (1–2, 3–4, 5–7). **This is MySQL/MariaDB**: re-check any CHECK
+  constraints for the quoting issue fixed in `20261005190000_FixCheckConstraintQuotingForMySql`, and
+  note that entity comments still mention PostgreSQL `xmin` for `RowVersion`.
+- Backfill: none required (status values are compatible; legacy layers are handled by D6).
+- Tests (`Testing/`): GRN serial validation and duplicate race; FEFO order with expired/null-expiry
+  batches; serial issue on slip, invoice, and bundle; shortfall blocked for serials; return restores
+  status and voids warranty; transfer moves serial location; count variance for serials.
+
+## 5. Execution order
+
+```
+Phase 0 → 1 → 2 → 3 → 4 → 5 → 6 → 7     (backend, sequential: shared FifoCostingService / SalesPostingService)
+Phase 8 starts per screen once its backend phase lands (GRN after 2, sales after 4, returns after 6)
+Phase 9 after 5 · Phase 10 alongside each group
+```
+
+Smallest shippable slice: **Phases 1 + 2 + GRN UI** (serials can be received correctly). Next:
+**3 + 4 + 5** (sell with serial/batch, warranty starts).
+
+## 6. As built — differences from the plan
+
+| Plan said | Built | Why |
+|---|---|---|
+| One stock-ledger row per serial | Ledger stays **one row per document line** (per batch for FEFO splits); new append-only **`SerialMovement`** table records every serial status/location change | `FifoCostingService.PostLedgerAsync` posts a GL journal per ledger row — per-serial rows would mean one GL call per unit |
+| Warranty period read from the item at sale (serial items) | Snapshotted onto **`Serial.WarrantyPeriodMonths`** at GRN confirm | Same rule as `GrnLineWarrantyNumber` — later item edits don't change stock already received |
+| `SalesInvoiceLineAllocation` / `SalesSlipLineAllocation` | Draft choices in **`SalesInvoiceLineSerial` / `SalesSlipLineSerial`**; what posting actually issued in one polymorphic **`SalesLineAllocation`** (doc type/id/line, batch, serial, qty, cost, qtyReturned) | Invoices, slips and bundles share one posting path; returns read one table |
+| Transfer: serial allocations on the line | **`StockTransferLineSerial`** (+ per-serial cost/batch from dispatch) and new status **`InTransit`** | A serial must be in no warehouse between dispatch and receive |
+| Batch item transfer with no batch | Server **splits the line FEFO into one line per batch at create** | Otherwise the batch is lost when the destination layer is created |
+| Count: missing serial → `Damaged` | Missing → **`Scrapped`**, found → `InStock` | A unit that can't be found isn't "damaged" |
+| Return reason → serial status | `DEF`/`QREJ` ⇒ `Damaged`, else `InStock`; request `markDamaged` overrides | Reason codes are user data — the flag keeps it explicit |
+| — | Pickers live on **`api/v1/tracking`** (base ERP access); registers on `api/v1/serials` (stock), `api/v1/warranties` (sales), `api/v1/stock/batches` | Sales, GRN and stock screens all need the pickers |
+
+**Bugs fixed on the way**: count posting dropped `BatchId` on batch lines; the count's serial snapshot
+wasn't warehouse-scoped; the GRN form never sent a batch expiry date (FEFO had nothing to sort on).
+
+**New error codes**: `SERIAL_DUPLICATE`, `SERIAL_NOT_AVAILABLE`, `TRACKING_REQUIRED`.
+
+**Frontend**: GRN "Serial / warranty numbers" tab (serial items: scan/paste, no auto-generated
+numbers) + batch expiry input; GRN detail shows batch/serials; `LineTrackingPicker` on sales invoice
+(new + edit), transfer and adjustment forms; serial ticking on sales and purchase return forms; new
+pages Stock → Serials, Stock → Batch Expiry, Sales → Warranties (sidebar reuses existing nav codes).
+
+**Auto-generated serial numbers (GRN)**: the serial tab has *Prefix* (default `SKU-`) + *Auto-generate*.
+`GET /tracking/serials/next-numbers?itemId&prefix&count` continues the highest number already used
+under that prefix for the item (received serials and draft-GRN numbers), zero-padded to ≥ 4 digits;
+the form also skips numbers already typed on it and fills **only empty units**, so scanned
+manufacturer serials are never overwritten. Nothing is reserved — the GRN's own uniqueness check
+on save and confirm remains the guard.
+
+## 8. Serial numbers on/off switch
+
+**Products → Configuration → Serial numbers** (`ProductConfig.SerialNumbersEnabled`) now governs
+serial tracking at runtime, not just item creation. Read through `ISerialTrackingService.IsEnabledAsync`
+(backend) and `GET /tracking/settings` + `useTrackingSettings()` (frontend; any logged-in user).
+
+| | On | Off |
+|---|---|---|
+| GRN | one serial per unit required | no serials; sending some → `CONFIG_DISABLED`; serial+warranty items take warranty numbers again |
+| Sales / returns / transfers / adjustments / counts | serials required (D6 exception) | serial items behave as untracked stock; serials refused with `CONFIG_DISABLED` |
+| Stock issue (FIFO) | serial layers only leave by naming the serial | serial layers issued oldest-first like any stock; their serials become **`IssuedUntracked`** (purchase return of a rejected line → `ReturnedToVendor`) |
+| Item edit | — | items already on Serial/Batch can still be edited (only switching *to* a disabled mode is refused) |
+| UI | pickers, GRN serial tab, Serials page | hidden; Serials page (if opened) shows a notice; history kept |
+
+No schema change (`IssuedUntracked` is a new string value). Switching back on resumes tracking for
+stock received from then on; units issued while off are not re-identified.
+
+## 7. Still open
+
+- **Apply the migration** (next backend start, or `dotnet ef database update`) — the dev connection
+  string points at the shared remote MariaDB.
+- **Bundle sales and free issues** have no serial picker: a serial item there can only post from
+  pre-tracking stock, otherwise it fails with `TRACKING_REQUIRED`.
+- **Transfer receive UI** sends qty only: receiving *all* outstanding serials works; a *partial*
+  receive of a serial line needs `serialIds` (API supports it, the screen doesn't).
+- **Non-serial warranty items**: warranty registered per sales line by quantity; choosing which GRN
+  warranty numbers leave (Phase 5 picker) is not built.
+- **Expiring-batch notifications** (`NotificationModuleCatalog`) not wired; the Batch Expiry page covers it manually.
+- **Tests**: FIFO/FEFO and posting paths use MariaDB-only SQL, so they are not unit-tested — needs an
+  e2e/integration pass (Testing/e2e) on a real database: GRN serials → sell → return → transfer → count.
+- Production of tracked finished goods — unchanged (still blocked), out of scope.