Báo cáo Bán hàng

1. Tổng quan

Thuộc tính	Giá trị
ID	FEAT-SALE-REPORT
Trạng thái	Stable
Owner	sale-team
Phụ thuộc	SaleOrder, SaleOrderItem, PurchaseOrder (đọc liên package cho tổng kết mua hàng)

SalesReportService cung cấp các tổng hợp chỉ đọc trên các sale order đã hoàn tất, dành cho dashboard và báo cáo cuối ngày. Mọi truy vấn được đẩy xuống method SQL của repository (không tổng hợp in-memory).

2. Vận hành

SalesReportService (sales-report.service.ts — 75 dòng, wrapper mỏng trên repos).

Phương thức	Repository SQL	Trả về
getDailySummary	SaleOrderRepository.getDailySummary	Tổng hằng ngày: { date, orderCount, subtotal, tax, discount, total } per ngày
getProductSales	SaleOrderRepository.getProductSales	Doanh số theo sản phẩm: { productVariantId, name, qty, total, ... }
getCategorySales	SaleOrderRepository.getCategorySales	Doanh số theo danh mục: { categoryId, name, qty, total, ... }
getCategorySummary	SaleOrderRepository.getCategorySummary	Drill-down một danh mục
getPurchaseSummary	PurchaseOrderRepository.getDailySummary	Góc nhìn từ phía sale của purchase order để so sánh giá vốn

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

Query params chung (per endpoint, validate bằng zod):

Param	Kiểu	Mô tả
from	ISO date	Bắt đầu khoảng
to	ISO date	Kết thúc khoảng
merchantId	string	Bắt buộc cho role không phải system (auto-filter)
groupBy	enum	day / week / month (nơi áp dụng)

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

4. Lưu ý hiệu năng

Mối quan tâm	Xử lý
Khoảng dài (>90 ngày)	SQL repository dùng index (merchantId, status, completedAt) để chỉ scan order COMPLETED
Đọc dashboard đồng thời	Hiện không cache; gọi lặp lại hit DB. Thêm Redis cache nếu thấy áp lực.
Truy cập PurchaseOrder liên package	Đọc qua PurchaseOrderRepository từ @nx/core — cùng DB, không HTTP roundtrip

5. Sự kiện

Outbound: không có. Báo cáo theo dạng pull qua REST.

6. Trang liên quan

• Mô hình miền — schema SaleOrder / SaleOrderItem
• API REST — OpenAPI spec live tại /doc/openapi.json