SimpleLotto Lottery Rules

Manage Lottery Sales

Record lottery ticket sales during the business day.
Support sale entry by game, bin, ticket count, and dollar amount.
Keep running totals for the current shift/day.
Allow correction or void workflows with clear operator confirmation.
Feed sales activity into closing totals so end-of-day balancing is straightforward.

Manage Lottery Inventory

Track active lottery inventory by bin.
Show which game/book is assigned to each bin.
Support inventory receiving, activation, movement, and ending counts.
Keep enough history to explain inventory changes during closing.
Make inventory status visible from the selling workflow so operators can act quickly.
Allow multiple active bundles in the same bin when the workflow requires it.
Treat each bundle as its own inventory object even when several bundles share one bin.

Roles and Login

SimpleLotto has only two possible roles:

Clerk
Manager

Role-based access is always enabled. Do not build a setting to turn role-based access on or off.

First-install setup must require creation of a Manager password before the system can be used. A Manager account is mandatory.

Clerk accounts are optional. The first-install workflow may allow the installer to create a Clerk account, but it must not require one.

A login screen is always shown after setup is complete.
Any valid user can log in.
Logging in starts a new shift for that user.
SimpleLotto is a single-computer, single-active-user application.
Only one user is actively operating the application at a time.
The active user can access the operational workflow needed for their shift.
The active user can close their shift at any time.
Shift closing is primarily financial separation by time, not a hard user handoff.
The same logged-in user may close multiple shifts over time.
Manager access is required for sensitive system settings and user management.
Clerk access, when configured, should support normal sales, bin, inventory, and shift-closing workflows unless a specific action is manager-sensitive.
Settings is Manager-only except Clerk may see a limited Settings page with Scanner and Display tabs.
Additional Clerk-visible Settings information may be added later, but current scope is Scanner and Display only.

First-install workflow:

Create required Manager password.
Optionally create a Clerk user.
Continue into the first login screen.
Successful login starts the first shift.

Shift Model

SimpleLotto closes from shift to shift. There is no separate daily closing model by default.

The shift is the primary accounting boundary:

A shift starts when a valid user logs in.
Sales and inventory movement occur inside the active shift.
The active user can close the shift at any time.
Closing ends the current shift and creates the financial summary for that shift.
After a shift is closed, the same logged-in user may continue into the next shift.
Cash summaries are shift-to-shift only.
Closing reports should be organized around the shift being closed.

If a calendar-day summary is ever shown, it must be clearly secondary and must not replace shift closing.

Future summarization should support partitioning by shift, user, calendar period, or other reporting groups, but the financial summary remains shift-closing to shift-closing.

Reporting and Accounting Separation

Inventory numbers and sales numbers are different accounting concepts and must not be mixed.

Sales reporting answers:

How much was sold?
Which games produced sales?
What cash/payment total should be reconciled for the shift?
What corrections or voids affected the sales total?

Inventory reporting answers:

What inventory was loaded?
What inventory moved between bins?
What ticket/book counts remain?
What activation, receiving, or ending-count changes happened?

Closing may show both inventory overview and sales numbers on the same page, but they must remain visually and mathematically separate. Do not combine inventory counts with sales dollars into one total.

Cash summary rules:

Cash summaries are shift-to-shift only.
Cash summaries are based on sales/payment activity, not inventory counts.
Inventory overview can support reconciliation, but it is not the cash summary.
Any variance should identify whether it belongs to sales/cash or inventory/counts.

Game, Bundle, and Ticket Rules

Settings must let the user define game prices and bundle prices. Game price and bundle price together determine how many tickets are in a bundle.

Default supported game prices should include:

The user must be able to add new game prices, such as $40, from Settings.

Game price rules:

Each game type has a game ID.
Each game type has a display name.
Each game type has an image when available.
Each game type has a price per ticket.
Game ID, game name, game price, and related game metadata are stable once defined and should not change during normal operations.
New game types require the user to set the price before the game can be used operationally.
Auto-fetched game names and images should follow the same state setup mechanism as ../windowsPOS.
Auto-fetch failures must not block manual setup. The user must be able to enter or correct the lotto name and image manually.

Bundle price rules:

Bundle price is configured based on the game price.
Ticket count per bundle is calculated as: bundle price / game price.
Bundle price must produce a whole ticket count. If it does not, the system must reject the value or require correction before saving.
Bundle price options must be editable in Settings.
Bundle price is used for ticket range calculation, sold-out detection, and closing accountability.

Ticket numbering rules:

Settings must allow the user to choose whether the first ticket starts at 000 or 001.
End ticket is calculated from game price, bundle price, and the selected first-ticket mode.
If first ticket is 000, end ticket is ticket_count - 1.
If first ticket is 001, end ticket is ticket_count.
Ticket range calculations must stay consistent across sales, inventory, Rdisplay, and closing.

Bundle completion rules:

A bundle is complete when its sold ticket count/value reaches the configured bundle price.
A bundle can also be treated as sold out during closing if it is expected but not scanned when the user finalizes the shift.
Closing-generated sold-out handling must be recorded separately from normal scanned sales so reports can explain the difference.

Closing

Closing is the balancing page. It should summarize sales, inventory movement, expected counts, corrections, and end-of-day totals. Closing should guide the operator through a clean final review before committing the day.

Closing must be shift-based. It should show cash summaries, inventory overview, and sales numbers as separate sections. Sales totals and inventory totals must not be mixed for reporting or accounting.

Closing scan rules:

Clicking Shift Closing should open a dedicated scan dialog.
The scan dialog should accept barcode scans and show a live count of scanned barcodes.
The scan dialog should show enough live feedback for the user to know scans are being captured, but it should not finalize reconciliation while the user is still scanning.
The scan dialog should allow the user to finish/close the scanning session.
During the scan dialog, the user scans ticket barcodes only.
During the scan dialog, the user does not scan bin barcodes.
During the scan dialog, the user does not click/select a bin to tell the system where the ticket belongs.
When the scan dialog closes, the system analyzes collected ticket scans against the existing active bundle/bin state.
Closing scan evidence belongs to the shift being closed.
Closing scan evidence represents the current real-world state of all physical bins.
During closing, scanned bundles/tickets are inventory evidence, not normal live sales.
During closing, the user scans the current available ticket from each physical bin/bundle.
Closing scan evidence is treated as the truth of the physical bin state.
If closing scan evidence does not match the system record, the system record must be reconciled to match the closing scan evidence.
The system should associate each scanned ticket to an existing bin by finding the active bundle that owns that ticket.
If a scanned ticket's bundle is active in an existing bin, that scan defines the current active bundle/ticket state for that bin.
If a bin has multiple bundles, the scanned bundle becomes the active/current closing state for that bin and unscanned bundles in that bin are sold out during closing.
If a scanned ticket's bundle is not active in any existing bin, the system must start the manual reconciliation loop to ask where that bundle belongs.
Closing scan collection is not an assignment workflow. Assignment/placement decisions happen only during the post-scan reconciliation loop when the system cannot match scanned evidence to existing active bins.
During closing reconciliation, each resolved bin should have a single current bundle relationship for the closing state.
If the scanned current ticket is forward from the system's expected current ticket, the gap is recorded as sold.
If the scanned current ticket is behind the system's expected current ticket, the system must reconcile the difference in the current shift. Do not edit closed shifts; any fix for previously closed activity must be recorded as a corrective action in the current/later shift.
Closing should not be treated as a free placement/activation workflow.
Closing reconciliation should compare scanned bundle/ticket evidence against the system's existing bin assignments and surface differences before final submit.
Any tickets/bundles that are part of the system's active bin state but are not scanned during closing are closed out when the user finalizes closing.
Any active bundle expected during closing but not scanned is considered sold and should be recorded as gap-fill sold.
Unscanned active bundles do not require per-bundle manual input before final submit.
If closing scan evidence includes a bundle that is not activated yet, the user must reconcile it manually before final submit.
Manual reconciliation for an unactivated bundle must require the user to choose which bin it belongs to.
If the selected bin is not empty, the system must ask what happens to the existing bundle before the new/unactivated bundle can be accepted for that bin.
The occupied-bin question must show the existing bundle's game name, game ID, Bundle ID, and ticket ID/current ticket.
The occupied-bin question must allow the user to identify whether the existing bundle moved to another bin or was taken out of inventory.
If the existing bundle is not sold out, it must either have moved or have been taken out of inventory; there is no third unresolved state.
If the user says the existing bundle moved, they must choose the destination bin.
If that destination bin has another existing bundle, the same occupied-bin question repeats for that displaced bundle.
If the user says the existing bundle was taken out of inventory, the system should close/remove it from active inventory with an auditable reason.
Taken-out-of-inventory reason options are: No sale, Returned, Correction.
Taken-out-of-inventory bundles should go back to open inventory in the future workflow.
This displacement/reconciliation loop applies only to shift closing.
Reconciliation is a closing-only loop and must continue until every displaced, unactivated, missing, or conflicting bundle is resolved.
Reconciliation should iterate until all unactivated bundles, conflicts, missing expected bundles, and bin-state differences are resolved or explicitly confirmed.
The user must confirm that reconciliation is clear before finalizing the shift closing.
In reconciliation context, "game bundle" means Bundle ID.
Every reconciliation interaction must show at minimum: game name, Bundle ID, and game ID.
Reconciliation interactions should also show bundle ID, current/expected bin, scanned ticket/current ticket, price, and status when available.
During closing reconciliation, dormant bundles in a bin that are not represented in the scanned physical state should be considered sold as appropriate for shift-close accountability.
The sold-out fill created by closing must be distinguishable from ordinary scan sales in audit/reporting.
If a bundle reaches its configured bundle price before closing, it is considered complete/sold out.
Closing should make unscanned-bundle sold-out consequences clear before final submit.
Closing scan prompts should use real-time text-to-speech so the operator hears the next action immediately.

Closing Page Bin Status

Closing page should show all bins, active and inactive.
Unscanned bins should be gray.
Scanned bins should be green.
If the user missed a bin, it is the user's responsibility to scan/fix it before final submit.
Clicking a bin during closing should show expected game ID, Bundle ID, and ticket ID/current ticket.
If the user scans while the closing scan dialog is open, the system matches that ticket to the related active bin/bundle after the dialog closes.
Any other dormant bundle in that bin should be automatically considered sold during closing reconciliation.

Settings

Settings owns configuration and system management. This includes store setup, display setup, scanner/display connectivity, users/permissions if needed later, backup options, and any technical diagnostics.

Settings must include state setup and game setup:

Follow the same state setup pattern as ../windowsPOS.
Use the same auto-fetch mechanism for lotto images where possible.
Use the same auto-fetch mechanism for lotto/game names where possible.
If auto-fetch does not find the lotto name or image, allow manual user entry.

Settings should organize game and bundle configuration into tabs:

Game Prices: shows game ID, image, lotto/game name, and price per game.
Bundle Prices: defines bundle price for each game price and calculates tickets per bundle.
Ticket Numbering: selects whether first ticket starts at 000 or 001.
Displays: handles Rdisplay registration, health, config, and diagnostics.

The Game Prices tab must require a price before a new game type can be used. The Bundle Prices tab must let the user add a new game price/bundle price combination.

Scanner and Runtime Behavior

When a scanner is paired, SimpleLotto must monitor scanner input globally while the application is running.

Scanner rules:

Paired scanner input should be monitored regardless of which page is currently visible.
Scanner input should continue to be monitored when the main window is minimized to the tray.
Scanner routing must respect the current workflow state: normal sale, inventory update, closing scan, setup, or correction.
Scan events should be captured with timestamp, active user, active shift, raw barcode, parsed meaning, page/workflow state, and result.
Scanner monitoring should not depend on keyboard focus inside a specific text field.
If scanner monitoring is unavailable or disconnected, show clear status on Dashboard and Settings.
Scanner status and pairing diagnostics belong under Settings.

Shift-close storage rule:

Shift close creates the immutable financial summary for the shift.
Once a shift is closed, it is closed and should not be edited.
Fixes after shift close happen only in a later shift as corrective actions.
Cash summary data comes from sales/payment activity.
Inventory overview data comes from inventory/count activity.
Reports may display both, but database summaries must keep them separate.

Transaction and consistency rules:

Shift closing finalization must be transactional.
Closing finalization should either complete all sale gap-fill, inventory state changes, report records, and audit rows, or fail without partial finalization.
Report/email sending must not be part of the critical transaction. If email fails, the shift remains closed and the email failure is recorded.
Scan capture can be append-only during the dialog. Reconciliation applies business changes after scan collection.
Closed shifts are immutable; later fixes are corrective actions in a later/current shift.

Reporting and Email Reuse

SimpleLotto should keep the Reporting structure and Email behavior from ../windowsPOS where compatible with the simplified product scope.

Reuse targets from ../windowsPOS:

Closing report generation pattern.
Closing report folder/export structure.
CSV report exports.
PDF closing report export.
Reports repository/query structure.
SMTP/email settings structure.
Closing-report email send flow.
Email status tracking on closings.

Expected closing/report artifacts should follow the ../windowsPOS pattern unless a SimpleLotto-specific reason changes them:

shift_summary.csv
inventory.csv
sales_detail.csv
corrections.csv
anomalies.csv
placement_events.csv
bin_assignments.csv
initialization.csv
closing_audit.csv
closing_report.pdf

SimpleLotto may omit or de-emphasize day-level reporting where it conflicts with shift-to-shift accounting. If a day summary is kept for compatibility, it must be clearly secondary to shift closing and must not become the financial boundary.

Reporting rules:

Reporting is accessed from Closing, not Settings and not a separate top-level menu item.
The user-facing Reporting/Closing history UI should show only the last 7 closings.
Older closing reports may remain stored/exported, but access to older reports is outside the current scope.
Reporting must preserve the separation between sales numbers and inventory numbers.
Reporting must support shift-to-shift financial summaries first.
Future partition summaries may group by shift, user, calendar period, game, or bin.
Partition summaries must not redefine the financial boundary; they are reporting views over closed-shift records.

Audio and Text-to-Speech

SimpleLotto must include text-to-speech for scanner-driven workflows, especially closing.

Text-to-speech rules:

Prompts must be real-time or near-real-time.
Closing prompts such as "start scanning" and "scan next ticket" must play immediately when the workflow state changes.
Do not repeat the delayed audio behavior seen in ../windowsPOS, where closing audio can lag by several seconds.
Prefer pre-initialized Windows speech resources or a queued low-latency audio service so the first prompt is not delayed.
Default speech rate should be faster than normal conversational speech so prompts finish quickly.
Target roughly 170-190 words per minute for standard prompts, assuming healthy adult operators who can understand average human tempo.
Do not make prompts so fast that numbers, bin IDs, game IDs, or correction warnings become ambiguous.
Audio prompts should be short and actionable.
Text-to-speech failure must not block scanning or closing.
Provide a Settings control to enable/disable speech prompts and adjust volume if practical.