Analysis: Inventory v00

Gap analysis for Inventory v00 (a Modification project). The feature is purely additive — two nullable fields on an existing entity — so there are no behavioral gaps to reconcile; the “gap” is simply that the fields do not yet exist. This document maps every current-code touchpoint the change rides through, with near-exact existing precedents, so the work is mechanical and low-risk. See requirements.md for the target behavior.

Executive Summary

Both fields have direct precedents already in production:

totalInventoryCount (a nullable Quantity) mirrors the existing minQuantity field end to end — persistence, DTO, serializer, and inline grid editing.
lastCountDate (a nullable DateTime) mirrors the Order entity’s deliverBy field on the persistence/DTO side; on the frontend it introduces the first Item date field (list-view date editing and a Detail-panel date-time input).

The most recent comparable change is the manufacturer-field project (Flyway V021), which added a nullable reference to Item; the new migration is V022.

Touchpoint map — operations

Concern	File (repo-relative)	Precedent to copy	Change
Entity + serializer descriptor	`operations/src/main/kotlin/cards/arda/operations/reference/item/business/Item.kt`	`minQuantity`, `manufacturer`	Add both props to the interface + `Entity` data class and add an `element(...)` line for each to the hand-written `ItemSerializer` descriptor
Request/response DTO	`operations/src/main/kotlin/cards/arda/operations/reference/item/api/Model.kt`	`minQuantity: Quantity.Value?`	Add both fields to `ItemInput` and map them in `toItem()`
Persistence table + record	`operations/src/main/kotlin/cards/arda/operations/reference/item/persistence/ItemPersistence.kt`	`min_quantity` quantity component; `Order.deliverBy` datetime component	Add `quantityComponent("total_inventory_count")` and `dateTimeComponent("last_count_date")`; add `var` delegates, the insert lambda, `fromEntity`, and `fillPayload`
DB migration	`operations/src/main/resources/reference/item/database/migrations/V022__inventory_count.sql` (new)	`V003__min_q_subloc.sql`	Add nullable columns: `total_inventory_count_amount`, `total_inventory_count_unit`, `last_count_date_timestamp`, `last_count_date_time_zone`
Value-object precedents	`Quantity.kt`, `DateTime` (common-module)	—	No new value types; reuse `Quantity.Value` and `DateTime`
Unit tests	`operations/src/test/kotlin/cards/arda/operations/reference/item/**`	`ItemDDLTest`, `ItemInputModelTest`, `ItemUniverseTestData`, service/endpoint tests	Extend column assertions, round-trip fixtures, and service/endpoint coverage

Item is bitemporal; the update path is a PUT full-document replace where an omitted field is written as null — no new mechanism is needed for “clear-to-null” (REQ-INV-005). The scalar/value fields pass straight through the update() heal/reconcile logic untouched (that logic only re-derives supply/manufacturer/name-driven slots).

Touchpoint map — arda-frontend-app

Concern	File (repo-relative)	Precedent to copy	Change
Domain type	`arda-frontend-app/src/types/items.ts`	`minQuantity`, `manufacturer`	Add `totalInventoryCount?: Quantity` and `lastCountDate?: string` (ISO)
Backend DTO types	`arda-frontend-app/src/types/arda-api.ts`	`ArdaItemPayload`, `ArdaCreateItemRequest`	Add both fields (count as amount/unit; date as the ARDA `DateTime` shape)
Mappers	`arda-frontend-app/src/lib/mappers/ardaMappers.ts`	`mapArdaItemToItem`, `mapItemToArdaCreateRequest`, `mapItemToArdaUpdateRequest`	Read on the way in; write on create/update; omit-when-empty for clear-to-null
Grid columns	`arda-frontend-app/src/components/table/columnPresets.itemColumns.detail.tsx` (+ `columnPresets.itemColumns.tsx` `buildItemsColumnDefs`)	`Min Qty`/`Min Unit`, `Created` date column	Add count amount + unit columns and a date column, `hide: true`
Column registration	`arda-frontend-app/src/app/items/itemTableConfig.ts`; `arda-frontend-app/src/app/items/sections/ColumnVisibilityMenu.tsx`	existing `VIEW_KEY_TO_FIELD` / `COLUMN_TOGGLES` entries	Register the three columns and their toggles
Inline edit wiring	`arda-frontend-app/src/app/items/gridColumnEnhancers.tsx`	`minQuantityAmount`/`minQuantityUnit` cases	Add `getEditableCellValue` + `applyEditableCellValue` cases (amount default `0`, unit default `"each"`); attach `UnitCellEditor` to the count-unit path and a date cell editor to the date path
Detail View panel	`arda-frontend-app/src/components/items/ItemDetailsPanel.tsx`	flat `ReadOnlyField` list	Introduce a titled “Inventory Count” group at the end with two `ReadOnlyField` rows
Detail View data shape	`arda-frontend-app/src/constants/types.ts` (`ItemCard`); `arda-frontend-app/src/app/items/hooks/itemsPageUtils.ts` (`convertItemToItemCard`)	existing `ItemCard` fields	Add both fields to `ItemCard` and populate them in the converter
Detail Edit panel	`arda-frontend-app/src/components/items/ItemFormPanel.tsx`	”Additional Info” section, `tocSections`, prefill effect, submit builder	Add an “Inventory Count” section after the last section; add to `tocSections`; prefill; emit in the submit builder (empty ⇒ undefined ⇒ cleared)
Edit form state	`arda-frontend-app/src/constants/types.ts` (`ItemFormState`)	existing fields	Add both fields (count amount/unit; date ISO string)
Tests / mocks / e2e	`ItemDetailsPanel.test.tsx`, `ItemFormPanel.test.tsx`, column/renderer tests, `src/mocks/data/mockItems.ts`, `e2e/pages/items.page.ts`, `e2e/specs/items/**`	existing specs	Extend fixtures, component tests, and Playwright specs

The Items grid already inline-edits dimensioned quantities today (Min Qty/Min Unit, Order Qty/Order Unit), so REQ-INV-011/012 reuse an established path rather than adding new edit infrastructure.

Summary Table

Requirement area	Status	Notes
Backend data model & API (REQ-INV-001…008)	gap (additive)	Direct `minQuantity` / `Order.deliverBy` precedents; new migration `V022`
List view columns & inline edit (REQ-INV-010…014)	gap (additive)	Reuses `gridColumnEnhancers` machinery; date editor is new for Item
Detail View/Edit groups (REQ-INV-020…023)	gap (additive)	New titled group in View panel (first of its kind); Edit panel has titled sections already
Documentation (REQ-INV-030)	gap	Update Item current-system functional reference

Prioritized Recommendations

This is additive work with no breaking behaviors or data-integrity risks, so the standard P1/P2/P3 modification priorities collapse to a single completeness pass. Recommended sequencing: operations first (the data contract), then arda-frontend-app (which can develop against mock mode in parallel but integrates against the real field once operations ships), then documentation. See specification.md for the phased plan.