# 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.