Sales Report

1. Overview

Property	Value
ID	FEAT-SALE-REPORT
Status	Stable
Owner	sale-team
Depends on	SaleOrder, SaleOrderItem, PurchaseOrder (cross-package read for purchase summary)

SalesReportService exposes read-only aggregations over completed sale orders, intended for dashboards and end-of-day reports. All queries push down to repository SQL methods (no in-memory aggregation).

2. Operations

SalesReportService (sales-report.service.ts — 75 lines, thin wrapper over repos).

Method	Repository SQL	Returns
getDailySummary	SaleOrderRepository.getDailySummary	Daily totals: { date, orderCount, subtotal, tax, discount, total } per day
getProductSales	SaleOrderRepository.getProductSales	Sales by product: { productVariantId, name, qty, total, ... }
getCategorySales	SaleOrderRepository.getCategorySales	Sales by category: { categoryId, name, qty, total, ... }
getCategorySummary	SaleOrderRepository.getCategorySummary	Single-category drill-down
getPurchaseSummary	PurchaseOrderRepository.getDailySummary	Sales-side view of purchase orders for cost-of-goods comparison

3. REST Endpoints

Verb	Path	Auth	Permission	Handler
GET	/reports/sales/summary	JWT/BASIC	SalesReport.dailySummary	getDailySummary
GET	/reports/sales/by-product	JWT/BASIC	SalesReport.byProduct	getProductSales
GET	/reports/sales/by-category	JWT/BASIC	SalesReport.byCategory	getCategorySales
GET	/reports/sales/category/:categoryId	JWT/BASIC	SalesReport.categorySummary	getCategorySummary
GET	/reports/sales/purchase-summary	JWT/BASIC	SalesReport.purchaseSummary	getPurchaseSummary

Common query params (per endpoint, validated by zod):

Param	Type	Description
from	ISO date	Start of range
to	ISO date	End of range
merchantId	string	Required for non-system roles (auto-filtered)
groupBy	enum	day / week / month (where applicable)

Live OpenAPI: /v1/api/sale/doc/openapi.json.

4. Performance Notes

Concern	Handling
Long ranges (>90 days)	Repository SQL uses indexed (merchantId, status, completedAt) to scan only COMPLETED orders
Concurrent dashboard reads	No caching today; repeated calls hit DB. Add Redis cache if pressure observed.
Cross-package PurchaseOrder access	Read via PurchaseOrderRepository which is from @nx/core — same DB, no HTTP roundtrip

5. Events

Outbound: none. Reports are pull-based via REST.

6. Related Pages

• Domain Model — SaleOrder / SaleOrderItem schemas
• API REST — live OpenAPI spec at /doc/openapi.json