PRD: Stock Count

Module	Inventory	PRD ID	PRD-CNT-001
Status	No item	FEAT	CNT
Epic	—	Plane	—
Date	2026-07-14	Version	v1.0
Packages	@nx/inventory	URD	CNT
Surface	Client · Owner/Mgr
Owner	Phát Nguyễn

What a stock count is

A stock count ticket is the document recording one time a merchant reconciles the books against the real goods on the shelf: how much was counted, how far it is off the books, and why.

The operator opens the ticket for exactly one inventory location on the Client app. The ticket belongs to the merchant currently being worked in; other merchants inside the same organizer never see it. A stock count is one of the nine inventory ticket types and shares the ticket frame's lifecycle: Draft → In progress → Completed, shown in the words of the trade as Draft, Counting, Applied.

The four numbers in stock

Lifted from Stock locations & levels so there is no need to open another PRD. Every item at every location carries four numbers:

Number	What the system calls it	Meaning
On-hand	on-hand	Goods physically sitting in the location
Reserved	reserved	Already promised to another document, no longer sellable to anyone else
Available	available	The part still sellable
Incoming	incoming	Left the source location, not yet arrived at the destination

The invariant, true at every moment:

Available = On-hand - Reserved

A stock count only touches on-hand. The baseline captured when the ticket opens is the on-hand figure, and the variance is added to on-hand at the moment of applying.

Why the tally is never written straight over stock

A merchant cannot close the doors to count. Customers keep coming, orders keep running, deliveries keep arriving. The counter starts at 8am and finishes at 11am, and in those three hours the merchant has sold a few dozen items.

The common approach on the market is to overwrite stock with the tally. That is only correct when the doors are shut. With selling running in parallel, it swallows the legitimately sold goods into the shrinkage figure, or the other way round, it resurrects stock for goods that were just sold. Most software resolves this by telling the user: if there were transactions, count again from scratch.

BANA solves it in software. When the ticket opens, the system captures a baseline of the book figure. Selling carries on against real stock. When the result is applied, the system only applies the variance between the tally and the baseline, on top of current stock.

One count ticket, end to end

An item stands at 100 cartons on the books. Open a count ticket, keep selling while counting, and the counter tallies 80.

What happens	Baseline	On-hand	Tally	Variance
Open a count ticket for location A	100	100	not counted	-
The cashier sells 5 cartons on the POS	100	95	not counted	-
The counter tallies 80 and enters it	100	95	80	-20
Apply the result	100	75	80	applied

• The variance is 80 minus 100, which is -20. Against the baseline, not against current stock.
• The -20 is added to stock as it stands at the moment of applying, which is 95, giving 75.
• The 5 legitimately sold cartons stay sold. Only the 20 cartons of real shrinkage reach the inventory ledger, with the reason the approver picked.
• Writing 80 straight over stock would resurrect the 5 sold cartons in the location, and the shrinkage figure would be wrong by exactly 5.
• This item had transactions between the baseline capture and the moment of applying, so its line carries the "Activity during count" flag for the approver to look at before pressing Apply.

The easiest thing to get wrong

A stock count applies a VARIANCE, it never overwrites the stock figure

The counter's tally is not the new stock figure. It is the quantity that was on the shelf at the moment they counted.

The system takes the tally minus the baseline to get the variance, then adds that variance to stock at the moment of applying. Setting stock straight to the tally erases every transaction that happened during the count.

An applied ticket is final: no edit, no delete. A miscount is fixed by opening a new count ticket, capturing a fresh baseline, and writing a new adjustment row. That is exactly the append-only rule of the inventory ticket frame.

1. Goals & Non-goals

Goals

• Open a count ticket for a location with a selectable scope, and capture a baseline for every item in scope at the moment it opens.
• Run the count ticket on the inventory ticket lifecycle, walking only the part it needs and relabelling what it shows.
• Keep selling, receiving and transferring running normally while a count ticket is open.
• Give the merchant a per-ticket sales-block flag, off by default, for high-value goods.
• Apply the count result as a variance against the baseline, on top of current stock, never as an overwrite.
• Flag items with activity during the count so the approver reviews them before applying.
• Write every variance into the inventory ledger as an adjustment row with a reason, feeding the shrinkage report.
• Support rolling counts by ABC classification group.
• Keep an applied count ticket final, exactly as the ticket frame's append-only rule requires.

Non-goals

• How ABC classification is computed (usage value, configurable 80/15/5 thresholds), which belongs to Replenishment. This PRD only uses the groups that feature provides as a scope filter.
• The shared inventory ticket lifecycle, the parent-child shape and the append-only rule at the general level, which belong to Inventory tickets.
• The structure of ledger rows and the reason code set, which belong to the inventory ledger.
• The money value of a variance, which belongs to Inventory valuation.
• Counting with handheld barcode scanners and offline tally entry.
• Counting fixed assets, tools, and anything outside the stock item catalog.

2. Success metrics

Metric	Target / signal
Counting without closing	A merchant finishes a count ticket during opening hours without pausing the POS
Stock is right after applying	Stock after applying equals current stock plus the variance; goods sold during the count never show up in the shrinkage figure
No recounting	Count tickets abandoned mid-way because there were transactions trend to zero
Quality of shrinkage data	Every variance carries a chosen reason; the shrinkage report reads straight off the inventory ledger
Rolling counts	Group A gets counted more often, instead of one whole-location count per year

3. Personas & scenarios

Persona	Goal in this feature
Owner / Manager	Open a count, pick the scope, review the variances, choose a reason for each gap, apply the result
Stock keeper	Walk the aisle with the ticket and enter the tallied quantity on every line
Cashier	Keep selling normally while the count runs, noticing nothing unusual

Core scenario: the manager opens a count for location A scoped to group A → the system captures a baseline for every item in scope → the keeper counts and enters the tallies while the till keeps selling → the manager reopens the ticket, sees a few lines carrying an activity flag, checks them → picks a reason for each gap and hits Apply → stock moves by exactly the variance, and the inventory ledger gets one adjustment row per item with a gap.

4. User stories

#	As a	I want	So that
01	manager	to open a count without pausing sales	the merchant keeps earning while counting
02	manager	the count to record only the real variance	goods I sold during the count are not treated as missing
03	manager	to lock a group of high-value goods while counting	their tally cannot change halfway through
04	manager	to see which items had transactions during the count	I know which lines to look at closely before applying
05	stock keeper	to enter only what I counted	I never have to work out a variance on paper
06	manager	every gap to carry a reason	at month end I know whether goods went to damage, expiry, or a prior miscount
07	manager	to count the important items several times a year	I do not close the location once a year to count everything
08	manager	to know for certain that nobody can edit an applied count	my shrinkage history is never rewritten

5. Functional requirements

#	Requirement	Status	URD ref
FR-001	The user creates a stock count ticket for exactly one location on the Client app. • The create form asks for: location (required), ticket name (optional, defaults to the date), scope (required), note (optional). • The scope is set one of three ways: Whole location, By ABC group, Hand-picked list of items. • Saving the ticket generates the count lines, one per item in scope.	🚧	URD-CNT-001 · URD-CNT-011
FR-002	At the moment the ticket is created, the system captures the current on-hand of every item in scope and writes it onto the count line as the baseline. • The baseline carries its capture timestamp and never changes for the life of the ticket. • Every line shows two separate figures: Book figure at capture, and Counted quantity.	🚧	URD-CNT-001
FR-003	Opening a count ticket blocks nothing. • Selling, receiving and transferring all keep running while the count ticket is open. • Sales are only blocked when the merchant deliberately turns on the flag in FR-004.	🚧	URD-CNT-002
FR-004	Every count ticket has its own sales-block flag, shown on the create form and OFF by default. • With the flag on, every item in the ticket's scope is blocked from sale at the POS until the ticket is applied or cancelled. • A cashier tapping a blocked item sees "This item is being counted and is temporarily unavailable". • The flag can only be changed while the ticket is not yet applied.	🚧	URD-CNT-003
FR-005	The counter enters the tallied quantity on every line of the ticket, one line per item. • The tally is entered in the item's base unit and cannot be negative. • A line with no tally entered is marked Not counted and is left out of the variance when the result is applied. • A Variance column shows the tally minus the baseline immediately, so the counter sees which lines are off.	🚧	URD-CNT-004
FR-006	A stock count ticket shares the inventory ticket lifecycle, walking only the part it needs and relabelling what it shows. • Three steps: Draft → In progress → Completed. There is no separate approval step and no state outside the shared lifecycle. • On screen, In progress reads "Counting" and Completed reads "Applied". • Stock only changes at the last step; the two earlier steps never touch it. • Cancelling at any step before the last leaves stock untouched and lifts the sales-block flag.	🚧	URD-CNT-009 · URD-TKT-003 · URD-TKT-004
FR-007	Applying works off the variance against the baseline, never an overwrite of stock with the tally. • A line's variance is the tally minus the baseline captured at ticket creation. • The variance is added to on-hand as it stands at the moment of applying, not as it stood when the baseline was captured. • A line with a variance of 0 moves no stock at all.	🚧	URD-CNT-005
FR-008	Every line with a non-zero variance is written into the inventory ledger as its own adjustment row. • The row records the figure before, the change, the figure after, and points back at the count ticket as the source document. • The approver picks a reason for the gap from the list: Damaged, Expired, Missing, Prior miscount, Other. • Picking Other requires a note.	🚧	URD-CNT-006
FR-009	An item with a sale, a receipt or a transfer between the baseline capture and the moment of applying gets an activity flag. • The flagged line shows an "Activity during count" label right on the ticket. • The approver expands the line to see exactly which transactions happened, to check them before applying. • The activity flag is a warning to look at, never a block on applying.	🚧	URD-CNT-007
FR-010	A count ticket can be scoped to an ABC classification group, supporting rolling counts. • Pick the By ABC group scope and tick one or more of A, B, C. The ticket only generates lines for items in the ticked groups. • The count ticket list shows the last count date per group, so the merchant knows which group is due.	🚧	URD-CNT-008
FR-011	An item appears in several count tickets over time, and each ticket captures its own baseline. • A ticket's baseline never depends on the result of an earlier ticket. • An item already sitting in an unapplied count ticket that is pulled into a second one raises an overlapping-scope warning right at creation, and the user chooses to carry on or drop that item.	🚧	URD-CNT-010 · URD-CNT-012
FR-012	An applied count ticket is final, exactly as the ticket frame's append-only rule requires. • Every field is locked: the tally cannot be re-edited, the reason cannot be re-edited, and there is no delete button. • A miscount is fixed by opening a new count ticket for that item. The new ticket captures a fresh baseline from current stock and writes a new adjustment row into the ledger.	🚧	URD-CNT-014 · URD-TKT-008
FR-013	Count tickets are per-merchant data and can be looked up with filters. • A user only sees and acts on the count tickets of the merchant they are currently working in. • The count ticket list filters by location, ticket status and created-date range.	🚧	URD-CNT-013 · URD-TKT-017

5.1 Acceptance criteria

• Open the Stock count screen on the Client app, hit Create, pick location A and the Whole location scope → the ticket is created with one count line per item at location A, and the Book figure column is pre-filled.
• Create a count ticket with the Hand-picked scope and tick exactly 3 items → the ticket generates exactly 3 count lines, and no other item of the location.
• Create a count ticket leaving the name blank → it still saves, and the name defaults to the creation date.
• Right after creating the ticket, sell 5 units of an item on the POS → stock drops to 95, but the Book figure column on the count line still shows 100.
• With a count ticket open and the sales-block flag OFF, sell an item in scope on the POS → the order goes through with no blocking message.
• Receive a shipment and transfer an item that is in the count's scope → both operations run normally, and the count ticket blocks nothing.
• Create a new count ticket with the sales-block flag ON, then tap an item in scope into the cart on the POS → the message "This item is being counted and is temporarily unavailable" shows and the item does not go into the cart; cancel the count ticket → it sells again straight away.
• Enter a tally of 80 on a line whose Book figure is 100 → the Variance column shows -20 immediately.
• Leave a line's tally blank and apply the result → that line stays Not counted and its stock does not change.
• Open any count ticket → the screen offers Start counting and then Apply result, with no separate approval step and no button outside the inventory ticket lifecycle.
• Open the ticket list → a ticket being counted reads "Counting", and an applied one reads "Applied".
• With the ticket at Counting, check the stock of an item in scope → it has not changed, because the result has not been applied.
• Baseline 100, 5 sold during the count (current stock 95), tally of 80 → apply the result → the item's stock becomes 75, not 80.
• After applying, open that item's inventory ledger → a new adjustment row shows before 95, change -20, after 75, with the chosen reason, pointing back at the count ticket's code.
• Pick the reason Other on a line with a gap, leave the note blank and hit Apply → the system blocks it and asks for a note.
• Sell an item in scope after the ticket opened, then reopen the ticket to review before applying → that item's line shows the "Activity during count" label; expand the line → the transactions since the baseline capture are listed.
• An item with no transaction at all since the baseline capture → its line shows no activity label.
• A line carries an activity flag → the Apply button still works, because the flag does not block.
• Create a count ticket with the By ABC group scope and tick group A → the ticket only generates lines for group A items, with none from B or C.
• On the count ticket list, look at the last-count column per group → the last applied date shows for each of A, B and C.
• Pull an item already sitting in an unapplied count ticket into a second one → an overlapping-scope warning shows with the open ticket's code, offering to carry on or drop that item from the new ticket.
• Choose to carry on → the second ticket captures its own baseline from current stock, independent of the first ticket's baseline.
• Cancel a count ticket while it is Counting → stock for every item in scope is unchanged, the ledger gets no new row, and the sales-block flag is lifted.
• Open an applied count ticket → every field is locked, the tally and the reason cannot be edited, and there is no delete button.
• A miscount turns up after applying → open a new count ticket for that item; it captures a fresh baseline and writes a new adjustment row, while the old ticket stays as it was.
• On the count ticket list, filter by location A, status Counting and this week's date range → only the tickets matching all three conditions show.
• Sign in as a different merchant → none of the first merchant's count tickets are in the list.

6. Non-functional requirements

Aspect	Requirement
Data integrity	The baseline written on a count line is immutable once the ticket exists; applying the whole ticket is one all-or-nothing write - either every line with a gap reaches the ledger, or none does
Correctness under concurrency	Adding the variance to stock runs alongside the sale flow without losing updates: if two flows touch one item, the final figure is the algebraic sum of both, not the value of whichever wrote last
Duplicate protection	Hitting Apply twice on the same ticket still writes the ledger once
Append-only	No business path edits or deletes an applied count ticket
Merchant scoping	Every count ticket and count line is confined to the user's own merchant
Performance / scale	A count ticket holds up to 5,000 lines; capturing the baseline and applying the result both run in batches, never one call per line
Traceability	Every adjustment row in the ledger points back at the count ticket's code, the person who applied it, and the moment of applying
i18n	Ticket status labels, reason labels and the sales-block message are displayed bilingually

7. UX & flows

The lifecycle of a count ticket and where stock actually moves:

Why selling in parallel is not swallowed into shrinkage:

All the stock count screens live in the Client app, in the Inventory area. A list screen filters by location, status and date range. A detail screen is laid out as a table, one line per item, with the columns Item, Base unit, Book figure at capture, Counted quantity, Variance, Reason, plus the activity label where it applies. The Apply button sits at the top of the detail screen and only lights up while the ticket is Counting.

8. Data & domain

Concept	Role
Count ticket	One of the inventory ticket types: one location, one scope, one sales-block flag, three steps of the shared lifecycle
Count line	One item in the ticket, carrying the baseline, the tally, the variance, a reason and the activity flag
Baseline	The item's on-hand at the moment the ticket opened, immutable, used as the comparison point
Variance	The tally minus the baseline; this is the only figure ever applied to stock
Sales-block flag	A ticket attribute, off by default; when on, items in scope are temporarily unavailable for sale
Activity flag	A mark on a count line when the item had transactions since the baseline capture
Adjustment row	The inventory ledger record created on applying, carrying the reason and pointing back at the count ticket
ABC group	An item's importance classification, used as a scope filter for rolling counts

Conceptual level only - the full schema and invariants live in the inventory domain model.

9. Dependencies & assumptions

Depends on

#	Feature	What it depends on
01	TKT Inventory tickets	the shared lifecycle, the per-type status labels and the append-only rule.
02	LOC Inventory locations	a count ticket is always tied to exactly one location.
03	STK Stock items & levels	the source of the on-hand figure at capture, and where the variance is applied.
04	LDG Inventory ledger	where the adjustment rows are written, and the source for detecting activity during the count.
05	RSV Reservation	the sales-block flag acts on the reservation path at the POS.
06	RPL Replenishment	provides the ABC classification groups used as a scope filter.
07	UOM Units of measure & conversion	defines the base unit the counter tallies in.

Assumptions

#	Assumption	What breaks if it is wrong
01	The counter tallies in the item's base unit, converting from pack units themselves before entering the figure.	Type a number of cases into a box expecting cans and the variance is wrong by the whole conversion factor, so one bad count ticket corrupts the stock of the entire location.
02	A variance is real shrinkage or real surplus, not a unit-of-measure mistake. An unusual figure is checked by the approver before applying.	If the approver presses Apply without looking, every data-entry mistake goes straight into the inventory ledger labelled as shrinkage, and the shrinkage report loses all its value.
03	An item should only sit in one unapplied count ticket at a time. The system warns on overlap but does not forbid it.	Two tickets covering one item, both applied, pull stock twice against two different baselines, and nobody can work out which ticket produced the final figure.
04	ABC groups have been computed before a merchant uses the by-group scope.	With no ABC groups computed, the By ABC group scope produces an empty ticket or one missing items, and rolling counts cannot be used at all.

10. Release plan & criteria

Aspect	Plan
Phase	P2 (Inventory v2) - see the URD feature catalog
Rollout	All merchants; no feature flag. The sales-block flag is a per-ticket choice, not a merchant-level setting
Migration	There is no legacy count data to move; each merchant's first count ticket captures its baseline from current stock
Release criteria	The count ticket walks the three steps of the inventory ticket lifecycle with the right wording; the baseline 100 - sell 5 - tally 80 - stock 75 scenario behaves correctly; the sales-block flag works at the POS both ways; every variance carries a reason and a ledger row; an applied ticket cannot be edited; a 5,000-line ticket can be created and applied
Monitoring	Count tickets completed per month, share of lines carrying an activity flag, total variance value by reason, tickets cancelled mid-way

References

• URD: Stock count
• Related: Inventory tickets · Stock items & levels · Inventory ledger · Stock transfer · Replenishment
• Module: Inventory - URD
• Developer: @nx/inventory · domain model

Risks & open questions

#	Risk / question	Mitigation / status
01	Overwriting stock with the tally would swallow goods sold during the count into false shrinkage	Applying works off the variance against the baseline, on top of current stock (FR-007)
02	The approver applies without knowing an item just had transactions	The activity flag shows right on the line and expands to list the transactions (FR-009)
03	A count ticket left open too long makes the variance harder to explain as more transactions pile in	Open: consider a warning when a ticket has been open beyond a configurable number of days, or a nudge to finish it the same day
04	The sales-block flag is left on and the merchant cannot sell	Cancelling or applying lifts the flag immediately (FR-006); the list screen shows plainly which tickets are blocking sales
05	Two count tickets covering one item could apply the same variance twice	The overlapping-scope warning fires at creation (FR-011); each ticket still works off its own baseline so the variance never doubles, but this is a case the user has to confirm
06	An item with the oversell flag can go negative, so the tally never matches the baseline	The variance is computed as usual; the negative figure is pulled back to the counted number once the result is applied
07	The money value of a variance is not shown on the ticket	Open: decide whether to show the shrinkage value at cost on the count ticket itself, or leave it to the shrinkage report

FAQ

#	Question	Answer
01	Does the merchant have to stop selling during a count?	No. Opening a count blocks nothing: the till keeps selling, deliveries keep arriving, transfers keep running. Sales are only blocked when the merchant deliberately turns on the sales-block flag on the ticket, and that flag is off by default.
02	Then what is the baseline for, if not to freeze stock?	The baseline is a comparison point. The counter's tally reflects the shelf at the moment they counted, while stock in the system keeps moving. With a baseline, the system can separate real shrinkage from goods that were legitimately sold.
03	I counted 80, why is stock 75 after applying?	Because the book figure was 100 when the ticket opened, and 5 units were sold during the count. The variance is 80 minus 100, which is -20: that is the shrinkage. Current stock at the moment of applying was 95, minus 20, leaving 75. Setting stock straight to 80 would resurrect the 5 units that were already sold.
04	Is a stock count an inventory ticket?	Yes. It uses the inventory ticket lifecycle, walking three of its steps and relabelling them for the trade: In progress reads "Counting" and Completed reads "Applied". There is no lifecycle of its own.
05	When should I turn on the sales-block flag?	When counting high-value goods whose tally must not move halfway through, such as a spirits cabinet or electronics. For fast movers, leave it off: blocking sales costs revenue.
06	What does rolling counts by ABC group mean?	Instead of closing the location once a year to count everything, the merchant counts group A (the most important items) often, group B less often, and group C rarely. A count ticket can be scoped to a group, so each pass only covers part of the location.
07	Does the "Activity during count" flag stop me applying?	No. It is a nudge to look closely at that line, because its figure was affected by transactions. Expanding the line shows exactly which ones ran.
08	I applied the result and then found a miscount, what now?	An applied ticket is final: no edits, no deletes. Fix it by opening a new count ticket for that item. The new ticket captures a fresh baseline, and the new variance is written as its own adjustment row in the ledger. That is exactly the append-only rule of the whole inventory module.