URD: Reports

Module	CORE-11	Version	v0.4
Status	In-progress	Date	2026-05-29

1. Purpose

Define user-facing requirements for business reporting — the read-only views an owner uses to run the shop: cashier shift reports (X interim / Z closing) with cash reconciliation, daily sales summaries, product and category breakdowns, and purchase analysis. Reports aggregate over completed orders and closed sessions and never mutate data.

2. Scope

Included	Excluded
Shift reports — X (interim) and Z (closing)	Profit & loss analytics (Planned)
Cash reconciliation (float, sales, expected vs. actual, discrepancy)	Inventory valuation reports (Planned)
Daily sales summary by date range	Customer / retention analytics (Planned)
Product sales report	Export to PDF / CSV / Excel (Planned)
Category sales + single-category drill-down	Scheduled auto-generated reports (Planned)
Purchase summary (supplier / PO spending)	Tax declaration reports (Tax & Invoice)
Payment-method breakdown	Technical API specifications (see developer docs)
Merchant scoping and date-range filtering

3. Definitions

Term	Definition
X report	An interim shift summary, pulled while the POS session is still open. Repeatable any number of times.
Z report	The closing shift report, produced once when a session is closed. Locks a final snapshot.
Cash reconciliation	Comparison of expected cash (opening float + cash sales − pay-outs) against the actual counted cash, yielding a discrepancy.
Daily summary	Per-day totals (gross, tax, discount, net, order count) over a chosen date range.
Purchase summary	A sales-side view of purchase orders, used to compare cost against revenue.

4. Conceptual Model

Conceptual only — the data model lives in the developer domain model.

5. Functional Requirements

One table per functional area. <AREA> codes match the test-case IDs. Priority = MoSCoW (Must / Should / Could / Won't).

5.1 Shift Reports (SHF)

ID	P	Requirement
URD-SHF-001	M	X report (interim): generate from the current open session, repeatable
URD-SHF-002	M	Z report (closing): final report produced once per session at close
URD-SHF-003	M	Cash reconciliation: opening float, cash sales, pay-in/out, expected vs. actual, discrepancy
URD-SHF-004	M	Sales summary on the shift report: gross, discount, tax, net, order count
URD-SHF-005	S	Payment-method breakdown on the shift report (cash / card / e-wallet)
URD-SHF-006	S	Category breakdown on the shift report

5.2 Sales Reports (SLS)

ID	P	Requirement
URD-SLS-001	M	Daily summary: per-day totals (gross, tax, discount, net, order count) over a date range
URD-SLS-002	S	Product sales: top products ranked by revenue and quantity
URD-SLS-003	S	Category sales: totals broken down by product category
URD-SLS-004	S	Category drill-down: detail for a single chosen category
URD-SLS-005	S	Purchase summary: supplier / purchase-order spending for cost comparison

5.3 Access & Scoping (ACC)

ID	P	Requirement
URD-ACC-001	M	Reports are scoped to the user's merchant access; no cross-merchant data leaks
URD-ACC-002	M	Sales reports require a from–to date range
URD-ACC-003	M	Only completed orders count toward sales figures; cancelled / draft orders are excluded
URD-ACC-004	S	Empty result sets render gracefully (zero totals, no error)

5.4 Advanced Analytics (ADV) Planned

ID	P	Requirement
URD-ADV-001	C	Profit analytics: cost vs. revenue margin
URD-ADV-002	C	Inventory valuation: stock value by costing method
URD-ADV-003	C	Customer analytics: retention, lifetime value, segmentation
URD-ADV-004	C	Export to PDF / CSV / Excel
URD-ADV-005	W	Scheduled auto-generated reports

§5.4 is not built. These requirements are documented for roadmap traceability only and have no test cases until build starts.

6. Acceptance Criteria

AC-SHF-01: Shift X / Z reports

Given	When	Then
An open POS session	An X report is requested	Current-shift cash and sales totals are shown; can be repeated
A session being closed	The Z report is generated	Final totals are locked; exactly one Z report exists per session
A Z report	Inspecting it	Cash reconciliation, sales summary, and (where enabled) payment-method and category breakdowns are present

AC-SLS-01: Daily sales summary

Given	When	Then
A from–to date range	The daily summary is requested	Gross, tax, discount, net, and order count are shown per day
A merchant context	The same request	Results are scoped to that merchant only

AC-SLS-02: Product & category breakdown

Given	When	Then
Completed orders with several products	The product sales report is requested	Products are ranked by revenue / quantity
The same data	A category is drilled into	That single category's detail is shown

AC-ACC-01: Merchant scoping

Given	When	Then
A user belonging to Merchant B	Any report is requested	Only Merchant B figures appear; Merchant A data is never returned
A sales report with no matching orders	The report is requested	Totals show zero; no error is raised

7. Constraints & Non-Goals

Constraints

ID	Constraint
C-01	X report is repeatable; the Z report is produced once per session (terminal)
C-02	All reports are scoped by the user's merchant access
C-03	Sales reports require a from–to date range
C-04	Only completed orders are aggregated into sales figures

Non-Goals

• Profit & loss analytics
• Inventory valuation reports
• Customer retention / lifetime-value analytics
• PDF / CSV / Excel export
• Scheduled auto-generated reports
• Real-time dashboard KPI widgets

8. Version History

Date	Author	Description	Ver
2026-02-26	P. Do — Product Owner	Initial user stories	v0.1
2026-04-16	P. Do — Product Owner	Restructured into session + sales report areas	v0.3
2026-05-29	Docs migration	Re-aligned areas (SHF/SLS/ACC/ADV) to verified @nx/sale behavior; marked advanced analytics Planned	v0.4