New_REP_SYSTEM/ERP_Distribution
8
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add item tracking and the configuration docs

Browse Source
This commit is contained in:
DeepnaPooja
2026-10-06 13:32:37 +05:30
parent 05d44ab9f0
commit edb5fddc3a
2 changed files with 705 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
Distribution/docs/refactor_docs/item_tracking_config.md
+286
View File
@@ -0,0 +1,286 @@
# [Feature] Item Tracking Configuration — Serial Numbers, Batches, Warranty, Expiry
**Status**: Implemented (see [item_tracking_plan.md](./item_tracking_plan.md) for per-phase status). Open items: apply migration `AddDirectGoodsReceipt`; build the sale/delivery step that starts warranty.
**Touches**: `Item` catalogue, GRN intake, stock ledger (`StockBalance`/`StockMovement`), new
Configuration page (`distribution_fe/app/(dashboard)/configuration`)
---
## Goal
Let specific catalogue items opt into serial-number tracking, batch/lot tracking, and/or expiry-date
tracking, with an optional warranty period (system default or per-item custom override), while:
1. Each feature (serial tracking, batch tracking, expiry-date tracking, warranty) can be turned
**on/off system-wide** from the new Configuration page, independent of any single item.
2. Each **item** can independently track serial numbers, batches, expiry dates, any combination of
the three, or none of them — never forced into a tracking mode it doesn't need. Expiry-date
tracking does not require batch tracking — a perishable item can carry a single expiry date per
goods receipt without ever being assigned a batch number.
3. Items that track none of these continue to work exactly as today — this must be additive, not a
breaking change to the existing stock ledger or GRN flow.
4. Batches and/or expiry-only lots carry an **expiry date**; serials carry a **warranty expiry**,
derived from a period in days that is either the system default or a per-item custom value (only
if the item is flagged to allow a custom override).
---
## Current State (as found in the codebase, before implementation)
- **`Item`** (`Models/Item.cs`) has no tracking-related fields today — just SKU, category, UOM,
pricing, `ReorderLevel` (added in the most recent migration, `20260928101132_AddItemReorderLevel`).
- **Stock ledger** (`Models/StockBalance.cs`, `Models/StockMovement.cs`) is keyed purely on
`FK_ItemId` + `LocationId`/`LocationType`. There is no concept of a batch or a serial unit
anywhere in the ledger — one aggregate quantity per item per location.
- **GRN** (`Features/Grn/GrnService.cs`, `Models/GoodsReceiptItem.cs`) records only
`AcceptedQuantity`/`RejectedQuantity` per PO line. No batch number, expiry, or serial capture
point exists anywhere in intake.
- **No existing entity** anywhere in the backend represents a batch, lot, serial number, or
warranty period — this is a net-new domain concept, not a rename/extension of something existing.
- **`SysConfig`** (`Models/SysConfig.cs`, `Features/SysConfig/*`) is a generic key/value store
already used for one system-wide toggle (`InvoiceCreationMode`, see
`SysConfigService.KeyInvoiceCreationMode`). This is the existing mechanism for global on/off
switches and is the natural home for the new feature toggles — no new entity needed for that part.
---
## Two Layers of Configuration
### 1. Global feature toggles (configuration page) — reuse `SysConfig`
New well-known keys, following the exact pattern `KeyInvoiceCreationMode` already uses
(`SysConfigService.cs:8`, validated in `ValidateValue`):
| Key | Values | Meaning |
|---|---|---|
| `Feature.SerialNumberTracking` | `"true"` / `"false"` | Whether any item is allowed to track serial numbers. |
| `Feature.BatchTracking` | `"true"` / `"false"` | Whether any item is allowed to track batches/lots. |
| `Feature.ExpiryDateTracking` | `"true"` / `"false"` | Whether any item is allowed to require an expiry date at intake — independent of batch tracking. |
| `Feature.WarrantyTracking` | `"true"` / `"false"` | Whether warranty periods apply at all. |
| `Feature.CustomWarrantyOverride` | `"true"` / `"false"` | Whether individual items may override the system default warranty period. |
| `Feature.DefaultWarrantyPeriodDays` | integer string | System-wide default warranty length in days, used when an item has warranty enabled but no custom override. |
`SysConfigService` gains typed getters (`GetSerialTrackingEnabledAsync()`, etc.) mirroring
`GetInvoiceCreationModeAsync()`, plus validation in `ValidateValue` for the boolean/int keys.
`SysConfigController` already exposes generic `GET/PUT /api/sys-config/{key}`, so the
configuration page frontend needs no new backend endpoints for this layer — just calls to the
existing key/value routes.
Turning a global toggle **off** does not delete per-item settings or existing batch/serial data —
it only hides the corresponding controls in the Item Sheet and disables new intake of that kind
(enforced in `ItemService`/`GrnService`, not just the UI).
### 2. Per-item settings — new columns on `Item`
| Column | Type | Notes |
|---|---|---|
| `TracksSerialNumbers` | `bool` | Default `false`. Can only be set `true` if `Feature.SerialNumberTracking` is on. |
| `TracksBatches` | `bool` | Default `false`. Can only be set `true` if `Feature.BatchTracking` is on. |
| `TracksExpiryDate` | `bool` | Default `false`. Can only be set `true` if `Feature.ExpiryDateTracking` is on. Independent of `TracksBatches` — see below. |
| `HasWarranty` | `bool` | Default `false`. Can only be set `true` if `Feature.WarrantyTracking` is on. |
| `WarrantyPeriodDays` | `int?` | Only meaningful if `HasWarranty`. Null = use `Feature.DefaultWarrantyPeriodDays`. |
| `AllowCustomWarrantyPeriod` | `bool` | Default `false`. Gates whether `WarrantyPeriodDays` may be set on this item at all — requires `Feature.CustomWarrantyOverride` on. |
`TracksSerialNumbers`, `TracksBatches`, and `TracksExpiryDate` are independent booleans, so every
combination (none / any one / any two / all three) falls out naturally — no extra enum needed. An
item can have `TracksExpiryDate = true` with `TracksBatches = false`: it gets a per-receipt expiry
date without ever needing a batch number (see `ItemBatch` below, whose `BatchNumber` becomes
optional to support this case).
Validation lives in `ItemService.CreateAsync`/`UpdateAsync`: reject the request if a per-item flag
is `true` while its global feature is off, with a message like *"Serial number tracking is
disabled system-wide."*
---
## New Entities — Batches and Serial Numbers
### `ItemBatch`
| Column | Type | Notes |
|---|---|---|
| Id | Guid | PK |
| FK_ItemId | Guid | FK → Item. Item must have `TracksBatches = true` and/or `TracksExpiryDate = true`. |
| BatchNumber | string? | Supplier/internal lot code. **Required if `TracksBatches`, otherwise null** — an expiry-only item (`TracksExpiryDate` with `TracksBatches = false`) gets a row here purely to carry the expiry date, with no batch number. |
| ManufactureDate | DateTime? | Optional. |
| ExpiryDate | DateTime? | Required if `TracksExpiryDate`. Drives expiry alerts and (later phase) dispatch blocking. |
| IsActive | bool | Standard soft-delete/versioning flag. |
| CreatedAt | DateTime | From `Template`. |
`ItemBatch` is the single mechanism behind both "batch tracking" and "expiry-date tracking" — a
batch is a subdivision of one item's stock, not a new stock-holding location, and quantity for a
batch/lot still lives in the ledger (see below). The row only exists at all when the item tracks
batches or expiry dates (or both); an item that tracks neither never gets `ItemBatch` rows.
### `ItemSerialNumber`
| Column | Type | Notes |
|---|---|---|
| Id | Guid | PK |
| FK_ItemId | Guid | FK → Item. Item must have `TracksSerialNumbers = true`. |
| SerialNumber | string | Unique per item. |
| Status | enum `SerialStatus { InStock, Sold, Returned, Damaged }` | Current lifecycle state. |
| CurrentLocationId / CurrentLocationType | Guid? / `LocationType?` | Mirrors the ledger's location model — where this specific unit currently sits. |
| ReceivedAt | DateTime | When it entered stock (GRN). |
| WarrantyPeriodDaysOverride | int? | Snapshotted at receipt from `Item.WarrantyPeriodDays` when `Item.HasWarranty` and `Item.AllowCustomWarrantyPeriod`; otherwise null (system default applies when the warranty starts). |
| WarrantyExpiresAt | DateTime? | **Set at sale/delivery, not receipt**: sale date + (override ?? `Feature.DefaultWarrantyPeriodDays`). Null while in stock or if `Item.HasWarranty` is false. *(Original design computed this at receipt; changed so warehouse time doesn't consume the customer's warranty.)* |
| IsActive | bool | Standard flag. |
A serial number represents exactly one physical unit — quantity is always 1, so serials are
tracked as rows, not as a quantity column.
---
## Stock Ledger Changes (additive, nullable)
`StockBalance` and `StockMovement` (`Models/StockBalance.cs`, `Models/StockMovement.cs`) each gain:
| Column | Type | Notes |
|---|---|---|
| `FK_ItemBatchId` | Guid? | Null for items that don't track batches — **no behavior change for existing items.** |
| `FK_ItemSerialNumberId` | Guid? | Null for items that don't track serials. |
- Untracked items: both columns stay null, ledger behaves exactly as it does today (one aggregate
row per item+location).
- Batch-tracked items: one `StockBalance` row per (Item, Location, Batch) instead of per (Item,
Location) — the existing `StockRepository.GetBalanceAsync`/`AddBalanceAsync` calls in
`GrnService.CreateAsync` (`Features/Grn/GrnService.cs:106-122`) need a batch-aware overload.
- Serial-tracked items: quantity is always 1 per movement; a `StockMovement` moves one serial from
one location to another and updates `ItemSerialNumber.CurrentLocationId/Type` + `Status` in the
same transaction. A running `StockBalance` row can still exist (count of serials at a location)
for consistency with existing balance-reporting UI, kept in sync alongside the serial's own
status.
---
## GRN Changes (intake is where batches/serials are born)
`GoodsReceiptItem` (`Models/GoodsReceiptItem.cs`) needs a capture point matching the item's
tracking mode:
- **Batch-tracked item**: the GRN line must supply a batch number (+ expiry date if the item also
has `TracksExpiryDate`) instead of a bare accepted quantity. New table `GoodsReceiptItemBatch`
(FK_GoodsReceiptItemId, BatchNumber?, ExpiryDate?, Quantity) — a single PO line can be split across
multiple batches in one receipt.
- **Expiry-only item** (`TracksExpiryDate` without `TracksBatches`): the GRN line must supply an
expiry date but no batch number — same `GoodsReceiptItemBatch` table, `BatchNumber` left null.
- **Serial-tracked item**: the GRN line must supply exactly `AcceptedQuantity` serial numbers. New
table `GoodsReceiptItemSerial` (FK_GoodsReceiptItemId, SerialNumber).
- **None of the above**: unchanged — today's `AcceptedQuantity`/`RejectedQuantity` flow stays as-is.
`GrnService.CreateAsync` (`Features/Grn/GrnService.cs:44`) needs a branch per tracking mode when
writing `StockBalance`/`StockMovement`: create/lookup the `ItemBatch` (or create each
`ItemSerialNumber`) before writing the ledger rows, and validate the request shape matches the
item's `TracksSerialNumbers`/`TracksBatches`/`TracksExpiryDate` flags (e.g. reject a batch number on
an item that doesn't track batches, or a missing expiry date on an item that requires one).
---
## Frontend Changes
- **configuration page** (`distribution_fe/app/(dashboard)/configuration/page.tsx`, currently a
placeholder): add an "Item Tracking" section with toggles for the five `Feature.*` keys and a
number input for the default warranty period, following the same form pattern as
`drivers/compliance/page.tsx` (a single-purpose settings form backed by a GET on load / PUT on
save) but hitting the generic `/api/sys-config/{key}` routes instead of a dedicated controller.
- **Item Sheet** (`catalogue/items/_components/item-sheet.tsx`): add a "Tracking" `FieldGroup` with
`Track serial numbers` / `Track batches` / `Track expiry date` checkboxes, a `Has warranty` checkbox revealing a
warranty-period number input, and (only when `Feature.CustomWarrantyOverride` is on) an
`Allow custom warranty period` checkbox. Checkboxes for a disabled global feature are hidden
entirely, not just disabled, to avoid confusing item editors.
- **GRN entry** — built as two full pages (against a PO: `/procurement/grn/po/new`; direct:
`/procurement/grn/direct/new`). Tracked lines show a status chip that opens a panel for serial
entry (scan / auto-generate / type-paste-edit) or batch rows (batch no. with Auto, expiry, qty).
Save is disabled until every tracked line is complete. Details in the plan, Phases 10–12.
- **configuration page**: a single Products card on `/configuration` holds the switches and warranty
defaults (no separate sub-page). **Item view** shows tracking badges.
---
## Direct Goods Receipt (no purchase order)
A goods receipt may exist without a PO. `GoodsReceipt.FK_PurchaseOrderId` and
`GoodsReceiptItem.FK_PurchaseOrderItemId` are nullable; direct lines carry `FK_ItemId` instead;
an optional `FK_SupplierId` identifies the supplier. `POST /api/goods-receipts/direct` creates one.
Serial/batch/expiry capture, stock balances and movements are identical to a PO receipt (shared
`PostReceiptAsync`); the only differences are that no PO quantity or status is updated and no PO
validation applies. See the plan, Phase 11.
---
## Process — How Item Tracking Works End to End
### 1. Setup (once)
1. **Configuration → Products card**: switch on the capabilities the business needs (serial, batch,
expiry, warranty; optionally per-item custom warranty) and set the default warranty days. Changes
save immediately and are stored in `SysConfig` (`Feature.*` keys).
2. **Catalogue → Items → edit item**: tick `Track serial numbers` / `Track batches` /
`Track expiry date` and, if applicable, `Has warranty` (+ `Use a custom warranty period` and days).
A flag can only be set if its global feature is on. Untracked items are unaffected.
### 2. Receiving goods (where serials / batches are entered)
Entered **only at goods receipt**, never on the item or PO forms.
| Item tracks | GRN line needs | Stored as |
|---|---|---|
| nothing | accepted / rejected qty | one `StockBalance` row per item+warehouse |
| serial numbers | exactly *accepted qty* unique serials | one `ItemSerialNumber` (InStock) + one `StockBalance` (qty 1) + one `StockMovement` per unit |
| batches | batch rows (batch no., [expiry], qty) summing to accepted qty | `ItemBatch` (reused by item + batch no.) + `StockBalance` per (item, warehouse, batch) + `StockMovement` per batch |
| expiry only | lot rows (expiry, qty), **no** batch number | fresh `ItemBatch` per row carrying only the expiry date |
| serial + batch/expiry | serials only (serial wins; batch/expiry not linked — follow-up) | as serial |
Rejected quantity never touches stock. Everything posts in one unit of work and rolls back on any
failure. A serial that already exists for the item, or a mismatch with the item's flags, is rejected.
**Two ways to receive**: *against a PO* (lines come from the PO, PO received-quantities and status
update) or *direct* (no PO; item chosen per line, optional supplier). The UI exposes them as two
pages and both share the same serial/batch entry panel.
### 3. Entering serials / batches in the UI
- Each tracked line shows a chip (amber until complete, green ✓ when complete) → opens the panel.
- **Serials**: scan (Enter adds one), auto-generate (prefix + start number, fills only missing units),
or type/paste one per line; every entry stays editable; duplicates are flagged.
- **Batches**: add rows; batch number can be typed, scanned or auto-generated; expiry date warns if
expired or within 30 days; quantities must add up to the accepted quantity.
- Save is disabled until all tracked lines are complete; the server re-validates.
- Prefer real supplier serials/batch numbers where available — auto-generated values suit internal tags.
### 4. Warranty lifecycle
1. *Receipt*: serial created `InStock`; only the item's custom period (if any) is snapshotted.
2. *Sale/delivery* (**not built yet**): serial → `Sold`; `WarrantyExpiresAt = sale date + (override ??
default days)`.
3. *Claim / return* (future): `WarrantyExpiresAt` decides eligibility; status moves to
`Returned` / `Damaged`.
### 5. Viewing
GRN view shows batches (with expiry) and an expandable serial list per line; the item view shows
tracking badges; the receipts list marks direct receipts.
---
## Explicitly Out of Scope for This Phase
- **Picking/dispatch by batch or serial** (loading sheets, delivery tasks, sales returns) — this
doc only covers catalogue configuration and stock intake (GRN) + ledger schema. Selecting *which*
batch or serial goes out on a given ride/loading sheet is a separate follow-up doc once this
foundation exists.
- **FEFO (first-expiry-first-out) enforcement** at dispatch time.
- **Expired-batch blocking** — whether dispatch should hard-block an expired batch or just warn is
an open question below, deferred to the dispatch-side follow-up doc.
---
## Open Questions
1. Should an expired `ItemBatch` hard-block further dispatch, or just surface a warning? (Decision
deferred to the dispatch follow-up doc, but the `ExpiryDate` column needs to exist now either way.)
2. Is `WarrantyPeriodDays` always in days, or should the Item Sheet offer months/years and convert?
~~Resolved:~~ warranty timing — decided to start at sale, not receipt (see Process §4).
3. Can serial numbers ever be added outside a GRN (e.g. a manual stock adjustment for an
already-tracked item), or is GRN the only entry point in this phase?
4. When batch tracking splits one item's stock into multiple `StockBalance` rows per location, does
the existing Stock Balances page (`stock/_components/stock-balances-client.tsx`) need a
drill-down, or is an aggregated total (sum across batches) sufficient for now?
5. Naming for the migration: proposed `AddItemTrackingConfig`, continuing from the most recent
migration `20260928101132_AddItemReorderLevel`.
Distribution/docs/refactor_docs/item_tracking_plan.md
+419
View File
@@ -0,0 +1,419 @@
# Item Tracking Configuration — Implementation Plan
**Status**: Implemented — serial/batch/expiry capture on both receipt flows (against a PO and direct), config + item UI done. Pending: DB migration `AddDirectGoodsReceipt`, and the sale/delivery step that starts warranty (not built)
**Design doc**: [item_tracking_config.md](./item_tracking_config.md)
| Phase | Title | Status |
|-------|-------|--------|
| 1 | Enums | ✅ Done |
| 2 | Global feature toggles (`SysConfig`) | ✅ Done |
| 3 | `Item` per-item tracking fields | ✅ Done |
| 4 | New entities — `ItemBatch`, `ItemSerialNumber` | ✅ Done |
| 5 | Stock ledger — batch/serial columns | ✅ Done |
| 6 | GRN intake — batch/serial capture | ✅ Done (serial path takes precedence when an item tracks both serials and batches — see `GrnService.ValidateLineShape`). **Warranty is no longer computed here** — see "Warranty timing" below |
| 7 | Migration | ✅ Done — `20261001080630_AddItemTrackingConfig`, applied |
| 8 | configuration page UI | ✅ Done — single Products card on `/configuration` (no separate `/configuration/products` route) |
| 9 | Item Sheet UI | ✅ Done (also fixed pre-existing `reorderLevel` drift in `types/api.ts`/`ItemBody`) |
| 10 | GRN form UI — serial/batch entry | ✅ Done — see Phase 10 |
| 11 | Direct goods receipt (no PO) — backend | ✅ Code done · ⏳ migration `AddDirectGoodsReceipt` generated, **not yet applied** |
| 12 | GRN pages — two routes (against PO / direct) | ✅ Done |
| 13 | Sale/delivery step — start warranty, mark serial `Sold` | ❌ Not built (needs a decision on which document triggers it) |
---
## Scope
Add opt-in serial-number and batch/lot tracking to catalogue items, each independently on/off
system-wide via the new configuration page, with warranty periods (system default or per-item
custom override) and batch expiry dates. Fully additive to the existing schema — items that track
neither must behave exactly as they do today. See the design doc for full rationale, entity shapes,
and open questions; this file only sequences the work.
---
## Execution Order
```
Phase 1 → Phase 2 → Phase 3 → Phase 4 → Phase 5 → Phase 6 → Phase 7 (migration)
→ Phase 8, 9, 10 (frontend, independent of each other, after Phase 7)
```
Backend phases 2–6 touch shared files (`Item.cs`, `AppDBContext.cs`) in sequence and should not be
parallelized. Frontend phases 8–10 have no dependencies on each other.
---
## Phase 1 — Enums
**File**: `Models/Enums.cs`
Add:
```csharp
public enum SerialStatus { InStock, Sold, Returned, Damaged }
```
---
## Phase 2 — Global feature toggles (`SysConfig`)
**Files**: `Features/SysConfig/SysConfigService.cs`, `Features/SysConfig/SysConfigController.cs`
### 2.1 New well-known keys
In `SysConfigService`, alongside `KeyInvoiceCreationMode`:
```csharp
public const string KeySerialNumberTrackingEnabled = "Feature.SerialNumberTracking";
public const string KeyBatchTrackingEnabled = "Feature.BatchTracking";
public const string KeyExpiryDateTrackingEnabled = "Feature.ExpiryDateTracking";
public const string KeyWarrantyTrackingEnabled = "Feature.WarrantyTracking";
public const string KeyCustomWarrantyOverrideEnabled = "Feature.CustomWarrantyOverride";
public const string KeyDefaultWarrantyPeriodDays = "Feature.DefaultWarrantyPeriodDays";
```
### 2.2 Typed getters
Mirror `GetInvoiceCreationModeAsync()`:
```csharp
public async Task<bool> GetSerialNumberTrackingEnabledAsync() => await GetBoolAsync(KeySerialNumberTrackingEnabled);
public async Task<bool> GetBatchTrackingEnabledAsync() => await GetBoolAsync(KeyBatchTrackingEnabled);
public async Task<bool> GetExpiryDateTrackingEnabledAsync() => await GetBoolAsync(KeyExpiryDateTrackingEnabled);
public async Task<bool> GetWarrantyTrackingEnabledAsync() => await GetBoolAsync(KeyWarrantyTrackingEnabled);
public async Task<bool> GetCustomWarrantyOverrideEnabledAsync() => await GetBoolAsync(KeyCustomWarrantyOverrideEnabled);
public async Task<int> GetDefaultWarrantyPeriodDaysAsync()
{
var config = await repo.GetByKeyAsync(KeyDefaultWarrantyPeriodDays);
return config is not null && int.TryParse(config.Value, out var days) ? days : 0;
}
private async Task<bool> GetBoolAsync(string key)
{
var config = await repo.GetByKeyAsync(key);
return config is not null && bool.TryParse(config.Value, out var enabled) && enabled;
}
```
### 2.3 Validation
Extend `ValidateValue` to accept `"true"`/`"false"` for the five boolean keys and a non-negative
integer string for `KeyDefaultWarrantyPeriodDays`.
### 2.4 Controller
No new routes — the existing generic `GET/PUT /api/sys-config/{key}` already covers reading and
setting these keys (same pattern the frontend will already use for `InvoiceCreationMode`).
---
## Phase 3 — `Item` per-item tracking fields
**File**: `Models/Item.cs`
Add after `ReorderLevel`:
```csharp
public bool TracksSerialNumbers { get; set; } = false;
public bool TracksBatches { get; set; } = false;
public bool TracksExpiryDate { get; set; } = false;
public bool HasWarranty { get; set; } = false;
public int? WarrantyPeriodDays { get; set; }
public bool AllowCustomWarrantyPeriod { get; set; } = false;
```
**File**: `Features/Item/ItemDTOs.cs`
Add the same six fields to `CreateItemRequest`, `UpdateItemRequest`, `ItemSummaryResponse`, and
`ItemDetailResponse` (all optional/defaulted, matching how `ReorderLevel` was added).
**File**: `Features/Item/ItemService.cs`
In `CreateAsync`/`UpdateAsync`, before saving, validate each per-item flag against the matching
`SysConfigService` getter from Phase 2 and throw `InvalidOperationException` with a message like
*"Serial number tracking is disabled system-wide."* if a flag is `true` while its feature is off
(same check for `TracksExpiryDate` against `KeyExpiryDateTrackingEnabled`). Same check for
`AllowCustomWarrantyPeriod` against `KeyCustomWarrantyOverrideEnabled`, and for
`WarrantyPeriodDays` requiring `HasWarranty = true`.
---
## Phase 4 — New entities: `ItemBatch`, `ItemSerialNumber`
**New file**: `Models/ItemBatch.cs`
```csharp
public class ItemBatch : Template
{
public Guid FK_ItemId { get; set; }
public Item Item { get; set; }
// Null when the item tracks expiry dates but not batch numbers (TracksExpiryDate without TracksBatches).
public string? BatchNumber { get; set; }
public DateTime? ManufactureDate { get; set; }
public DateTime? ExpiryDate { get; set; }
}
```
This single entity backs both `TracksBatches` and `TracksExpiryDate` — an item can have one, the
other, or both; `ItemBatch` rows only get created at all when at least one of the two is true.
**New file**: `Models/ItemSerialNumber.cs`
```csharp
public class ItemSerialNumber : Template
{
public Guid FK_ItemId { get; set; }
public Item Item { get; set; }
public string SerialNumber { get; set; }
public SerialStatus Status { get; set; } = SerialStatus.InStock;
public Guid? CurrentLocationId { get; set; }
public LocationType? CurrentLocationType { get; set; }
public DateTime ReceivedAt { get; set; }
public int? WarrantyPeriodDaysOverride { get; set; }
public DateTime? WarrantyExpiresAt { get; set; }
}
```
**File**: `Data/AppDBContext.cs` — add `DbSet<ItemBatch> ItemBatches`,
`DbSet<ItemSerialNumber> ItemSerialNumbers`, unique index on `(FK_ItemId, SerialNumber)` for
`ItemSerialNumber`, and index on `(FK_ItemId, BatchNumber)` for `ItemBatch`.
---
## Phase 5 — Stock ledger: batch/serial columns
**Files**: `Models/StockBalance.cs`, `Models/StockMovement.cs`
Add to both:
```csharp
public Guid? FK_ItemBatchId { get; set; }
[ForeignKey("FK_ItemBatchId")]
public ItemBatch? ItemBatch { get; set; }
public Guid? FK_ItemSerialNumberId { get; set; }
[ForeignKey("FK_ItemSerialNumberId")]
public ItemSerialNumber? ItemSerialNumber { get; set; }
```
**Files**: `Features/Stock/IStockRepository.cs`, `Features/Stock/StockRepository.cs`
Add batch-aware overloads: `GetBalanceAsync(itemId, locationId, batchId)` alongside the existing
`GetBalanceAsync(itemId, locationId)`, used only when `Item.TracksBatches` is true so untracked
items keep calling the existing method unchanged.
---
## Phase 6 — GRN intake: batch/serial capture
**New file**: `Models/GoodsReceiptItemBatch.cs`
```csharp
public class GoodsReceiptItemBatch : Template
{
public Guid FK_GoodsReceiptItemId { get; set; }
public GoodsReceiptItem GoodsReceiptItem { get; set; }
public string BatchNumber { get; set; }
public DateTime? ExpiryDate { get; set; }
public int Quantity { get; set; }
}
```
**New file**: `Models/GoodsReceiptItemSerial.cs`
```csharp
public class GoodsReceiptItemSerial : Template
{
public Guid FK_GoodsReceiptItemId { get; set; }
public GoodsReceiptItem GoodsReceiptItem { get; set; }
public string SerialNumber { get; set; }
}
```
**File**: `Features/Grn/GrnDTOs.cs` — extend the create-GRN line request with optional
`List<GrnBatchLineRequest>? Batches` (each carrying `BatchNumber?`, `ExpiryDate?`, `Quantity`) and
`List<string>? SerialNumbers`, validated so exactly one of {bare quantity, batches, serials} is
populated depending on the item's tracking flags.
**File**: `Features/Grn/GrnService.cs`
In `CreateAsync` (`Features/Grn/GrnService.cs:44`), branch per line on
`poItem.Item.TracksSerialNumbers` / `TracksBatches` / `TracksExpiryDate`:
- None of the three: unchanged — today's `AcceptedQuantity`/`RejectedQuantity` path.
- Batches and/or expiry-only: reject if `line.Batches` is null/empty or its quantities don't sum to
`AcceptedQuantity`; reject a populated `BatchNumber` if `TracksBatches` is false, and reject a
missing `ExpiryDate` if `TracksExpiryDate` is true. For each batch entry, create or look up an
`ItemBatch` (by `FK_ItemId` + `BatchNumber` when present, otherwise a fresh expiry-only row),
write one `GoodsReceiptItemBatch`, and write/increment `StockBalance` keyed by
`(ItemId, WarehouseId, BatchId)` plus a `StockMovement` carrying `FK_ItemBatchId`.
- Serials: reject if `line.SerialNumbers.Count != AcceptedQuantity` or any serial number already
exists for the item; create one `ItemSerialNumber` per entry (`Status = InStock`; **no `WarrantyExpiresAt` yet** — see "Warranty timing"), one
`GoodsReceiptItemSerial`, and one `StockMovement` per serial carrying `FK_ItemSerialNumberId`
(quantity always 1).
---
### Warranty timing (changed from the original plan)
The original plan computed `WarrantyExpiresAt = ReceivedAt + period` at GRN. That made stock sitting in
a warehouse consume the customer's warranty, so it was changed: **the warranty clock starts when the
serial is sold/delivered**, not when it is received.
- At GRN, `GrnService` only snapshots the item's custom period onto the serial
(`WarrantyPeriodDaysOverride = Item.WarrantyPeriodDays`, and only when `HasWarranty` and
`AllowCustomWarrantyPeriod`). `WarrantyExpiresAt` stays `null`.
- `GrnService` no longer depends on `SysConfigService`.
- When the sale/delivery step exists (Phase 13), it sets
`WarrantyExpiresAt = saleDate + (WarrantyPeriodDaysOverride ?? Feature.DefaultWarrantyPeriodDays)`
and moves the serial to `SerialStatus.Sold`.
- Caveat: with the default `Feature.DefaultWarrantyPeriodDays = 0` and no per-item period, the
warranty would expire the day it starts — set a default or per-item periods before enabling warranty.
### Shared posting code (refactor done while adding Phase 11)
`GrnService.PostReceiptAsync(goodsReceipt, lines, warehouseId, userId, po?, ct)` now holds the
unit-of-work block: add the receipt, per line write serials / batches / `StockBalance` /
`StockMovement` (type `PurchaseReceipt`), update the PO when present, commit. Both
`CreateAsync` (PO receipt) and `CreateDirectAsync` (no PO) validate their own input and then call
it, so tracking behaviour is identical in both flows.
---
## Phase 7 — Migration
(Applied.) Run `dotnet ef migrations add AddItemTrackingConfig` after Phases 3–6 are code-complete, covering:
`Item` new columns, `ItemBatch`, `ItemSerialNumber`, `GoodsReceiptItemBatch`,
`GoodsReceiptItemSerial` tables, and the new nullable FK columns on `StockBalance`/`StockMovement`.
Review the generated migration for the FK-drop pitfall noted in `refactor_plan.md` Phase 5 before
running `dotnet ef database update`.
---
## Phase 8 — configuration page UI
**Files**: `distribution_fe/app/(dashboard)/configuration/page.tsx`,
`configuration/_components/product-capabilities-card.tsx`
**As built**: `/configuration` shows one **Products** card whose body holds the switches and warranty
defaults directly (each switch saves immediately via `sysConfig.set`, keys in
`ITEM_TRACKING_KEYS`). There is no separate `/configuration/products` page. The original
description follows. Replace the placeholder with a form (pattern: `drivers/compliance/page.tsx`) that on load calls
`GET /api/sys-config` (or the five individual `GET /api/sys-config/{key}` calls) and on save calls
`PUT /api/sys-config/{key}` once per changed key:
- Checkbox — "Enable serial number tracking" (`Feature.SerialNumberTracking`)
- Checkbox — "Enable batch/lot tracking" (`Feature.BatchTracking`)
- Checkbox — "Enable expiry date tracking" (`Feature.ExpiryDateTracking`)
- Checkbox — "Enable warranty periods" (`Feature.WarrantyTracking`)
- Checkbox — "Allow items to set a custom warranty period" (`Feature.CustomWarrantyOverride`), only
shown/enabled when warranty tracking is on
- Number input — "Default warranty period (days)" (`Feature.DefaultWarrantyPeriodDays`), only shown
when warranty tracking is on
Add `sysConfig` helpers to `lib/api/index.ts` (`get(key)`, `set(key, value)`) if not already present.
---
## Phase 9 — Item Sheet UI
**File**: `distribution_fe/app/(dashboard)/catalogue/items/_components/item-sheet.tsx`
Add a "Tracking" `FieldGroup` after the existing fields:
- Checkbox `TracksSerialNumbers` — rendered only if the global serial-tracking toggle is on
- Checkbox `TracksBatches` — rendered only if the global batch-tracking toggle is on
- Checkbox `TracksExpiryDate` — rendered only if the global expiry-date toggle is on; independent
of `TracksBatches`, so it can be checked on its own for perishables with no batch numbering
- Checkbox `HasWarranty` — rendered only if the global warranty toggle is on
- Number input `WarrantyPeriodDays` — shown only when `HasWarranty` is checked
- Checkbox `AllowCustomWarrantyPeriod` — shown only when `HasWarranty` is checked **and** the
global custom-override toggle is on
Fetch the four global toggles once (e.g. via a small `useSysConfig` hook or inline `Promise.all`
next to the existing `categoriesApi`/`brandsApi`/`uomsApi` calls) when the sheet opens, so hidden
fields never get submitted as `true`.
Also update `ItemSummaryResponse`/`ItemDetailResponse` in `distribution_fe/types/api.ts` with the
five new fields (this file was already found to be missing `reorderLevel` from a prior backend
change — fix that drift in the same pass).
---
## Phase 10 — GRN form UI (serial / batch entry)
**Files** (`distribution_fe/app/(dashboard)/procurement/grn/_components/`): `grn-tracking.tsx`
(shared), `grn-view-sheet.tsx`; types in `types/api.ts`, `lib/api/procurement.ts`.
- The form loads each line's item (`items.get`) to read its tracking flags — the PO line response
does not carry them.
- Tracked lines show a **status chip** ("Enter serials · 0/50", amber until complete, green "✓" when
complete). Clicking it opens a panel (`LineTracking`):
- **Serial items**: scan field (Enter adds one serial, duplicates rejected), **auto-generate**
(prefix + start number, fills only the missing units, skips taken values), and an editable
list box (type / paste / edit / clear). Live "n of N entered" count, duplicates listed.
- **Batch / expiry items**: rows of batch number (+ **Auto** button), expiry date, quantity;
"Add batch" pre-fills the remaining quantity; warns "Already expired" / "Expires within 30
days"; live "allocated of accepted" count. Batch-number column hidden if the item does not track
batches; expiry column hidden if it does not track expiry.
- Warranty is a read-only note ("starts at sale") — never an input at GRN.
- `trackingProgress()` drives chip state; **Save is disabled until every tracked line is complete**.
`trackingPayload()` mirrors `GrnService.ValidateLineShape` and builds the request (or an error
toast). Serial tracking takes precedence over batch/expiry, as on the server.
- **GRN view** lists batches per line (batch no., qty, expiry) and serials in an expandable
"n serial numbers" row. **Item view sheet** shows tracking badges (Serial / Batch / Expiry /
Warranty period).
---
## Phase 11 — Direct goods receipt (no purchase order)
Goods can now be received without a PO. Both flows work independently and share the posting code.
**Models / migration `AddDirectGoodsReceipt`** (generated; **apply with `dotnet ef database update`**):
- `GoodsReceipt.FK_PurchaseOrderId` → nullable; new optional `FK_SupplierId` (+ `Supplier` nav).
- `GoodsReceiptItem.FK_PurchaseOrderItemId` → nullable; new `FK_ItemId` (+ `Item` nav) set on
direct lines. Existing PO lines resolve their item through `PurchaseOrderItem` (`MapItem`:
`i.Item ?? i.PurchaseOrderItem!.Item`).
**DTOs** (`GrnDTOs.cs`): `GrnItemRequest.PurchaseOrderItemId` is now `Guid?`, plus
`Guid? ItemId = null` for direct lines; new `CreateDirectGrnRequest(WarehouseId, Items, SupplierId?,
ReceivedByUserId?)`; `GrnResponse` gains `SupplierId`/`SupplierName` and a nullable
`PurchaseOrderId`; `GrnItemResponse.PurchaseOrderItemId` is nullable.
**Endpoint**: `POST /api/goods-receipts/direct` (`GrnController.CreateDirect`).
`GrnService.CreateDirectAsync` validates: at least one line; supplier (if given) exists and is
active; each line has an `ItemId` of an active item; quantities non-negative and not both zero;
`ValidateLineShape`; serials not already in stock and not repeated across lines of the same
request. It then calls `PostReceiptAsync` with no PO — no PO quantities or status change.
**Not included (by choice)**: unit cost on direct lines; a received-date input (the server stamps
`DateTime.Now` — also true of the PO flow).
---
## Phase 12 — GRN pages (two routes)
| Route | Purpose |
|---|---|
| `/procurement/grn` | Receipts list. "Receipt Against PO" and "Direct Receipt" buttons navigate to the pages below. PO column shows "Direct receipt" when there is no PO. |
| `/procurement/grn/po/new` | Pick an issued / partially received PO, warehouse, date, user; PO lines pre-filled with remaining quantity; serial/batch chips on tracked lines. |
| `/procurement/grn/direct/new` | Warehouse, optional supplier, user, then "Add item" rows (item + accepted / rejected + serial/batch chip). |
Both are full pages (not dialogs), using the shared `grn-tracking.tsx`. The old popup components
`grn-sheet.tsx` / `direct-grn-sheet.tsx` were removed. The GRN view remains a dialog.
---
## Phase 13 — Sale/delivery step (not built)
Needed to complete warranty: on sale/delivery of a serial, set `Status = Sold`,
`WarrantyExpiresAt`, and (for batch items) consume batch balances (FEFO suggestion). Also still
missing: stock screen drill-down by batch/serial and any warranty-status lookup UI. Requires a
decision on which document (invoice vs delivery) triggers it.