PRD: Báo cáo doanh số & quyền truy cập
| Module | Báo cáo (CORE-11) | PRD ID | PRD-SLS-001 |
| Status | Shipped | Owner | Reports squad |
| Date | 2026-05-28 | Version | v1.0 |
| Packages | @nx/sale · @nx/commerce · @nx/finance · apps/client | URD | SLS · ACC |
TL;DR
Cung cấp cho chủ merchant các góc nhìn chỉ đọc về những gì đã thực sự bán ra: mỗi ngày bán bao nhiêu, sản phẩm và danh mục nào tạo ra doanh thu, và chi tiêu mua hàng so sánh thế nào với doanh thu. Mọi báo cáo đều giới hạn trong phạm vi merchant của người dùng, yêu cầu một khoảng ngày, và chỉ tính các đơn đã hoàn tất - nên những con số chủ cửa hàng dùng để điều hành luôn chính xác và không bao giờ rò rỉ giữa các merchant.
1. Context & Problem
Chủ merchant cần các góc nhìn chỉ đọc đáng tin cậy về hoạt động kinh doanh: doanh số hằng ngày, sản phẩm và danh mục bán chạy, và chi tiêu mua hàng so với doanh thu. Đơn hàng và đơn mua hàng đã tồn tại dưới dạng bản ghi giao dịch, nhưng chưa có lớp đọc tổng hợp trên chúng - chủ cửa hàng không thể trả lời "hôm qua tôi bán được bao nhiêu", "mặt hàng nào bán chạy nhất", hay "chi phí so với doanh thu thế nào" mà không phải đếm thủ công.
Phần tăng trưởng này xây lớp đọc báo cáo doanh số dựa trên các đơn bán và đơn mua đã hoàn tất, giới hạn mọi phép tổng hợp trong phạm vi merchant của người dùng đang yêu cầu, và đưa nó ra qua các màn hình báo cáo doanh thu trong client. Việc tổng hợp được đẩy xuống tầng database trên các đơn đã hoàn tất; báo cáo không bao giờ thay đổi dữ liệu.
2. Goals & Non-Goals
Goals
- Tổng hợp doanh số hằng ngày - gross, tax, discount, net, và số lượng đơn theo từng ngày trong một khoảng ngày từ-đến.
- Báo cáo doanh số sản phẩm - các sản phẩm hàng đầu xếp hạng theo doanh thu và số lượng.
- Báo cáo doanh số danh mục với khả năng đi sâu vào một danh mục.
- Tổng hợp mua hàng - chi tiêu theo nhà cung cấp / đơn mua hàng để so sánh chi phí.
- Giới hạn phạm vi nghiêm ngặt - mọi báo cáo giới hạn trong phạm vi merchant của người dùng, yêu cầu một khoảng ngày, chỉ tính các đơn đã hoàn tất, và tập kết quả rỗng hiển thị thành tổng bằng không thay vì báo lỗi.
Non-Goals
- Báo cáo ca X / Z và đối soát tiền mặt - thuộc về feature
SHFriêng (URD-SHF), vẫn đang triển khai. - Phân tích lãi/lỗ / biên lợi nhuận, định giá tồn kho, phân tích giữ chân khách hàng - thuộc về
ADV(URD-ADV). - Xuất ra PDF / CSV / Excel và báo cáo tự sinh theo lịch.
- Báo cáo kê khai thuế (thuộc về Thuế & Hóa đơn).
3. Success Metrics
| Metric | Mục tiêu / tín hiệu |
|---|---|
| Cách ly đa-tenant | 0 dòng chéo merchant trong bất kỳ phản hồi báo cáo nào; mọi query khóa theo merchantId |
| Độ chính xác con số | Tổng hằng ngày khớp với các đơn đã hoàn tất trong khoảng; ngày kết thúc nằm trong cửa sổ |
| Chính xác chỉ-hoàn-tất | Đơn đã hủy / nháp không bao giờ đóng góp vào con số doanh số |
| Bền vững trạng thái rỗng | Một khoảng không có đơn nào khớp trả về tổng bằng không, không bao giờ báo lỗi |
4. Personas & Use Cases
| Persona | Mục tiêu trong feature này |
|---|---|
| Owner | Xem doanh số hằng ngày, mặt hàng bán chạy, cơ cấu danh mục, và chi phí-so-với-doanh thu trên merchant |
| Manager | Xem các báo cáo doanh số / sản phẩm / danh mục / mua hàng của merchant |
Core scenarios: chọn một khoảng ngày từ-đến → xem tổng hợp doanh số hằng ngày → xếp hạng sản phẩm theo doanh thu và số lượng → phân rã theo danh mục và đi sâu vào một danh mục → xem chi tiêu mua hàng để so sánh chi phí - tất cả đều giới hạn trong phạm vi merchant của người dùng.
5. User Stories
- Là một owner, tôi muốn có tổng hợp doanh số hằng ngày trên một khoảng ngày, để tôi thấy được gross, tax, discount, net, và số lượng đơn theo từng ngày.
- Là một manager, tôi muốn các sản phẩm hàng đầu xếp hạng theo doanh thu và số lượng, để tôi biết mặt hàng nào bán chạy nhất.
- Là một manager, tôi muốn doanh số được phân rã theo danh mục, để tôi so sánh hiệu quả giữa các danh mục.
- Là một manager, tôi muốn đi sâu vào một danh mục, để tôi xem chi tiết của nó.
- Là một owner, tôi muốn một tổng hợp mua hàng theo nhà cung cấp / đơn mua hàng, để tôi so sánh chi phí với doanh thu.
- Là một owner, tôi muốn mọi báo cáo giới hạn trong phạm vi merchant của mình và chỉ tính các đơn đã hoàn tất, để các con số luôn chính xác và không bao giờ rò rỉ giữa các merchant.
6. Functional Requirements
| # | Yêu cầu | URD ref |
|---|---|---|
| FR-1 | Tổng hợp doanh số hằng ngày: gross / tax / discount / net / số lượng đơn theo từng ngày trên một khoảng từ-đến | URD-SLS-001 |
| FR-2 | Doanh số sản phẩm: các sản phẩm hàng đầu xếp hạng theo doanh thu và số lượng | URD-SLS-002 |
| FR-3 | Doanh số danh mục: tổng được phân rã theo danh mục sản phẩm | URD-SLS-003 |
| FR-4 | Đi sâu danh mục: chi tiết cho một danh mục được chọn | URD-SLS-004 |
| FR-5 | Tổng hợp mua hàng: chi tiêu theo nhà cung cấp / đơn mua hàng để so sánh chi phí | URD-SLS-005 |
| FR-6 | Mọi query giới hạn trong phạm vi merchant của người dùng; không rò rỉ chéo merchant | URD-ACC-001 |
| FR-7 | Báo cáo doanh số yêu cầu một khoảng ngày từ-đến; ngày kết thúc nằm trong cửa sổ | URD-ACC-002 |
| FR-8 | Chỉ các đơn bán / đơn mua đã hoàn tất được tổng hợp; đơn đã hủy / nháp bị loại trừ | URD-ACC-003 |
| FR-9 | Tập kết quả rỗng hiển thị nhẹ nhàng thành tổng bằng không, không phải lỗi | URD-ACC-004 |
Toàn văn yêu cầu và tiêu chí nghiệm thu nằm trong URD Báo cáo. PRD này tham chiếu đến chúng thay vì lặp lại.
7. Non-Functional Requirements
| Lĩnh vực | Yêu cầu |
|---|---|
| Chỉ đọc | Báo cáo tổng hợp trên các đơn đã hoàn tất và không bao giờ thay đổi dữ liệu |
| Tenancy & authz | Mọi phép tổng hợp khóa theo merchantId; giới hạn trong phạm vi merchant của người dùng; không có dòng chéo merchant |
| Ngữ nghĩa ngày | Bắt buộc một khoảng từ-đến; cửa sổ bao gồm cả ngày kết thúc |
| Performance / scale | Việc tổng hợp được đẩy xuống SQL có index trên các đơn đã hoàn tất thay vì vòng lặp trong bộ nhớ |
| Bền vững | Tập kết quả rỗng phân giải thành tổng bằng không, không phải lỗi |
| i18n | Nhãn hướng tới người dùng song ngữ ({ en, vi }) |
8. UX & Flows
Các màn hình chính (trong apps/client): dashboard báo cáo doanh thu với biểu đồ và các bộ lọc báo cáo (khoảng ngày, trạng thái reset), trên route báo cáo riêng của nó.
9. Data & Domain
| Entity | Vai trò |
|---|---|
SalesReportService | Service backend điều phối các phép tổng hợp doanh số / sản phẩm / danh mục / mua hàng |
SalesSummaryRepository | Tổng hợp gross / tax / discount / net / số lượng đơn theo từng ngày trên các đơn bán đã hoàn tất |
SalesProductRepository | Xếp hạng sản phẩm theo doanh thu và số lượng (đọc dữ liệu sản phẩm của commerce) |
SalesCategoryRepository | Phân rã danh mục và đi sâu vào một danh mục (đọc dữ liệu danh mục của commerce) |
PurchaseSummaryRepository | Tổng hợp chi tiêu theo nhà cung cấp / đơn mua hàng để so sánh chi phí |
Chỉ ở mức khái niệm - schema đầy đủ và chi tiết query nằm trong domain model của sale.
10. Dependencies & Assumptions
Phụ thuộc vào
- Orders (
@nx/sale) - các đơn bán đã hoàn tất là nguồn của mọi con số doanh số. - Dữ liệu sản phẩm / danh mục (
@nx/commerce) - tên sản phẩm và danh mục dẫn dắt phân rã sản phẩm / danh mục. - Tổng đơn của finance (
@nx/finance) - tổng tiền của đơn cung cấp cho các bản tổng hợp. - Đơn mua hàng của inventory - các đơn mua hàng đã hoàn tất cung cấp cho tổng hợp mua hàng.
Giả định
- Người dùng đang yêu cầu có một phạm vi merchant phân giải được.
- Các đơn đã hoàn tất mang theo các trường tiền tệ (gross, tax, discount, net) mà các bản tổng hợp tổng hợp.
11. Risks & Open Questions
| Rủi ro / câu hỏi | Giảm thiểu / trạng thái |
|---|---|
| Rò rỉ chéo merchant trong tổng hợp | Mọi query khóa theo merchantId; phạm vi được áp trên đường đọc |
| Lệch một-đơn-vị ở cửa sổ ngày | Cửa sổ bao gồm cả ngày kết thúc cho các đơn bán và đơn mua đã hoàn tất |
| Khoảng ngày lớn quét nhiều đơn | Việc tổng hợp được đẩy xuống SQL có index thay vì vòng lặp trong bộ nhớ |
| Lọc trạng thái không nhất quán giữa các loại báo cáo | Chỉ các đơn đã hoàn tất được tính đồng nhất trên cả báo cáo doanh số và mua hàng |
12. Release Plan & Launch Criteria
| Khía cạnh | Kế hoạch |
|---|---|
| Phase | P1 - xem danh mục feature trong URD (SLS và ACC đã Built) |
| Rollout | Tất cả merchant; không feature flag |
| Migration | Không (tổng hợp chỉ-đọc trên các đơn hiện có) |
| Launch criteria | Báo cáo hằng ngày / sản phẩm / danh mục / mua hàng trả về tổng đúng; phạm vi merchant đã kiểm chứng; khoảng rỗng trả về tổng bằng không; ngày kết thúc được bao gồm |
| Monitoring | Lượng yêu cầu báo cáo, độ trễ query trên khoảng lớn, kiểm tra cách ly chéo merchant |
13. FAQ
Những đơn nào được tính vào con số doanh số? Chỉ các đơn đã hoàn tất - đơn đã hủy và đơn nháp bị loại trừ khỏi mọi báo cáo doanh số.
Khoảng ngày có tùy chọn không? Không - báo cáo doanh số yêu cầu một khoảng từ-đến, và cửa sổ bao gồm cả ngày kết thúc.
Tôi có thể xem con số của merchant khác không? Không - mọi báo cáo giới hạn trong phạm vi merchant của người dùng; dữ liệu chéo merchant không bao giờ được trả về.
Điều gì xảy ra khi không có đơn nào khớp? Báo cáo trả về tổng bằng không thay vì báo lỗi.
Báo cáo ca X / Z ở đâu? Chúng thuộc về feature SHF Shift Reports riêng, không thuộc phần tăng trưởng này.
References
- URD: Báo cáo - Sales Reports · Access & Scoping
- Liên quan: Shift Reports · Advanced Analytics
- Module: Báo cáo - tổng quan + truy vết
- Developer: @nx/sale · Sales Report