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, phục vụ dashboard và báo cáo cuối ngày. Mọi truy vấn đều được đẩy xuống method SQL của repository (không tổng hợp trong bộ nhớ).

2. Vận hành

SalesReportService (sales-report.service.ts - 75 dòng, lớp bọc mỏng quanh các repository).

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	Đào sâu một danh mục
getPurchaseSummary	PurchaseOrderRepository.getDailySummary	Góc nhìn từ phía sale về 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 với role không phải system (tự lọc)
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ỉ quét order COMPLETED
Đọc dashboard đồng thời	Hiện chưa cache; mỗi lần gọi đều truy vấn DB. Thêm Redis cache nếu thấy quá tải.
Truy cập PurchaseOrder liên package	Đọc qua PurchaseOrderRepository từ @nx/core - cùng DB, không qua HTTP

5. Sự kiện

Outbound: không có. Báo cáo được lấy chủ độ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