URD: Reports

Module	CORE-11	Version	v0.5
Status	In-progress	Date	2026-06-04

Business documentation. This URD is Reports' feature list - each feature below is one Functional Area (<AREA>). The same <AREA> keys the feature's PRDs (PRD-<AREA>-NNN) and tests (TC-<AREA>-NNN), and each feature is listed in the Delivery feature catalog. See the Feature Spine convention.

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. Feature Catalog

The feature list of this module. Each row is one feature (a Functional Area). Detail in §6. Mirrored in the Delivery feature catalog.

Feature ID	Feature	Phase	Status	Priority
SHF	Shift Reports	P2	In-progress	High
SLS	Sales Reports	P1	Built	High
ACC	Access & Scoping	P1	Built	High
ADV	Advanced Analytics	P3	Planned	Low

Status: live from Plane where mapped, otherwise registry-declared. Vocabulary mirrors Plane (state-group / phase).

6. Features

One sub-section per feature, in catalog order. Each feature keeps its description, requirements, and acceptance together. Priority = MoSCoW (Must / Should / Could / Won't).

SHF - Shift Reports In-progress

Feature ID: reports/SHF · Phase: P2 · PRDs: - · Dev: @nx/sale

What it does for users: a cashier pulls an interim (X) summary mid-shift and a final (Z) report at close, each with cash reconciliation and a sales summary, plus optional payment-method and category breakdowns.

Requirements

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

Acceptance

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

SLS - Sales Reports Built

Feature ID: reports/SLS · Phase: P1 · PRDs: - · Dev: @nx/sale

What it does for users: an owner or manager sees daily sales totals over a date range, top products by revenue and quantity, category breakdowns with single-category drill-down, and a purchase summary for cost comparison.

Requirements

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
URD-SLS-006	M	Periodic sales summary: group revenue totals (gross, discount, tax, net, order count) by Day, Month, or Year over the chosen date range

Acceptance

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-SLS-03: Flexible periodic revenue aggregation

Given	When	Then
A filtered time range (e.g. 1 year)	The revenue report is requested grouped by Month	Totals of 12 distinct months are returned; each month shows correct gross revenue, discounts, tax, net revenue, and completed order counts
Any filtered time range	The grouping interval is toggled between Day/Month/Year	The trend chart and data table update their rows/intervals to match the selected grouping precisely

ACC - Access & Scoping Built

Feature ID: reports/ACC · Phase: P1 · PRDs: - · Dev: @nx/sale

What it does for users: every report is confined to the user's merchant access, requires a date range, counts only completed orders, and renders empty results gracefully - so figures are always correct and never leak across merchants.

Requirements

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)

Acceptance

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

ADV - Advanced Analytics Planned

Feature ID: reports/ADV · Phase: P3 · PRDs: - · Dev: @nx/sale

What it does for users: a future expansion adding profit margin analysis, inventory valuation, customer analytics, export to common file formats, and scheduled report generation.

Requirements

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

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

Acceptance

AC-ADV-01: Profit analytics (planned)

Given	When	Then
Completed orders with cost and revenue data	Profit analytics is requested	Cost-vs-revenue margin is shown

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
2026-06-04	Claude (AI pair)	Reorganize by feature (Feature Spine); each feature carries its own requirements + acceptance	v0.5