URD: Báo cáo

Module	CORE-11	Phiên bản	v0.4
Trạng thái	In-progress	Ngày	2026-05-29

1. Mục đích

Định nghĩa các yêu cầu hướng người dùng cho báo cáo kinh doanh — các góc nhìn chỉ-đọc mà chủ dùng để điều hành cửa hàng: báo cáo ca thu ngân (X giữa ca / Z đóng ca) với đối soát tiền mặt, tổng hợp doanh số hằng ngày, phân rã sản phẩm và danh mục, và phân tích mua hàng. Báo cáo tổng hợp trên các đơn đã hoàn tất và phiên đã đóng và không bao giờ thay đổi dữ liệu.

2. Phạm vi

Bao gồm	Loại trừ
Báo cáo ca — X (giữa ca) và Z (đóng ca)	Phân tích lãi & lỗ (Planned)
Đối soát tiền mặt (quỹ đầu, doanh số, kỳ vọng vs. thực tế, chênh lệch)	Báo cáo định giá tồn kho (Planned)
Tổng hợp doanh số hằng ngày theo khoảng ngày	Phân tích khách hàng / giữ chân (Planned)
Báo cáo doanh số sản phẩm	Xuất ra PDF / CSV / Excel (Planned)
Doanh số danh mục + đào sâu một danh mục	Báo cáo tự động theo lịch (Planned)
Tổng hợp mua hàng (chi tiêu nhà cung cấp / PO)	Báo cáo kê khai thuế (Thuế & Hóa đơn)
Phân rã phương thức thanh toán	Đặc tả API kỹ thuật (xem tài liệu nhà phát triển)
Giới hạn phạm vi merchant và lọc theo khoảng ngày

3. Định nghĩa

Thuật ngữ	Định nghĩa
Báo cáo X	Một tổng hợp ca giữa kỳ, lấy khi phiên POS vẫn đang mở. Lặp lại được bao nhiêu lần tùy ý.
Báo cáo Z	Báo cáo ca đóng, tạo một lần khi một phiên được đóng. Khóa một bản chụp cuối cùng.
Đối soát tiền mặt	So sánh tiền mặt kỳ vọng (quỹ đầu + doanh số tiền mặt − các khoản chi) với tiền mặt thực đã đếm, ra một chênh lệch.
Tổng hợp hằng ngày	Tổng theo từng ngày (gộp, thuế, chiết khấu, thuần, số đơn) trên một khoảng ngày được chọn.
Tổng hợp mua hàng	Một góc nhìn phía-bán-hàng của các đơn mua hàng, dùng để so sánh chi phí với doanh thu.

4. Mô hình khái niệm

Chỉ mang tính khái niệm — mô hình dữ liệu nằm trong mô hình miền nhà phát triển.

5. Yêu cầu chức năng

Một bảng cho mỗi khu vực chức năng. Mã <AREA> khớp với ID của test case. Ưu tiên = MoSCoW (Must / Should / Could / Won't).

5.1 Báo cáo ca (SHF)

ID	P	Yêu cầu
URD-SHF-001	M	Báo cáo X (giữa ca): tạo từ phiên đang mở hiện tại, lặp lại được
URD-SHF-002	M	Báo cáo Z (đóng ca): báo cáo cuối cùng tạo một lần cho mỗi phiên khi đóng
URD-SHF-003	M	Đối soát tiền mặt: quỹ đầu, doanh số tiền mặt, thu/chi, kỳ vọng vs. thực tế, chênh lệch
URD-SHF-004	M	Tổng hợp doanh số trên báo cáo ca: gộp, chiết khấu, thuế, thuần, số đơn
URD-SHF-005	S	Phân rã phương thức thanh toán trên báo cáo ca (tiền mặt / thẻ / ví điện tử)
URD-SHF-006	S	Phân rã danh mục trên báo cáo ca

5.2 Báo cáo doanh số (SLS)

ID	P	Yêu cầu
URD-SLS-001	M	Tổng hợp hằng ngày: tổng theo từng ngày (gộp, thuế, chiết khấu, thuần, số đơn) trên một khoảng ngày
URD-SLS-002	S	Doanh số sản phẩm: sản phẩm bán chạy nhất xếp hạng theo doanh thu và số lượng
URD-SLS-003	S	Doanh số danh mục: tổng phân rã theo danh mục sản phẩm
URD-SLS-004	S	Đào sâu danh mục: chi tiết cho một danh mục được chọn
URD-SLS-005	S	Tổng hợp mua hàng: chi tiêu nhà-cung-cấp / đơn-mua-hàng để so sánh chi phí

5.3 Truy cập & Phạm vi (ACC)

ID	P	Yêu cầu
URD-ACC-001	M	Báo cáo theo phạm vi quyền truy cập merchant của người dùng; không rò rỉ dữ liệu liên-merchant
URD-ACC-002	M	Báo cáo doanh số yêu cầu một khoảng ngày từ–đến
URD-ACC-003	M	Chỉ đơn đã hoàn tất tính vào con số doanh số; đơn đã hủy / nháp bị loại trừ
URD-ACC-004	S	Tập kết quả rỗng hiển thị mượt mà (tổng bằng không, không lỗi)

5.4 Phân tích nâng cao (ADV) Planned

ID	P	Yêu cầu
URD-ADV-001	C	Phân tích lợi nhuận: biên lợi nhuận chi phí vs. doanh thu
URD-ADV-002	C	Định giá tồn kho: giá trị hàng tồn theo phương pháp định giá
URD-ADV-003	C	Phân tích khách hàng: giữ chân, giá trị vòng đời, phân khúc
URD-ADV-004	C	Xuất ra PDF / CSV / Excel
URD-ADV-005	W	Báo cáo tự động theo lịch

§5.4 chưa được build. Các yêu cầu này được tài liệu hóa chỉ để truy vết lộ trình và không có test case cho tới khi bắt đầu build.

6. Tiêu chí chấp nhận

AC-SHF-01: Báo cáo ca X / Z

Cho	Khi	Thì
Một phiên POS đang mở	Một báo cáo X được yêu cầu	Tổng tiền mặt và doanh số của ca hiện tại được hiển thị; có thể lặp lại
Một phiên đang được đóng	Báo cáo Z được tạo	Tổng cuối cùng được khóa; đúng một báo cáo Z tồn tại cho mỗi phiên
Một báo cáo Z	Khảo sát nó	Đối soát tiền mặt, tổng hợp doanh số, và (nơi được bật) phân rã phương thức thanh toán và danh mục có mặt

AC-SLS-01: Tổng hợp doanh số hằng ngày

Cho	Khi	Thì
Một khoảng ngày từ–đến	Tổng hợp hằng ngày được yêu cầu	Gộp, thuế, chiết khấu, thuần, và số đơn được hiển thị theo ngày
Một ngữ cảnh merchant	Cùng yêu cầu	Kết quả chỉ theo phạm vi merchant đó

AC-SLS-02: Phân rã sản phẩm & danh mục

Cho	Khi	Thì
Đơn đã hoàn tất với vài sản phẩm	Báo cáo doanh số sản phẩm được yêu cầu	Sản phẩm được xếp hạng theo doanh thu / số lượng
Cùng dữ liệu	Một danh mục được đào sâu	Chi tiết của riêng danh mục đó được hiển thị

AC-ACC-01: Phạm vi merchant

Cho	Khi	Thì
Một người dùng thuộc Merchant B	Bất kỳ báo cáo nào được yêu cầu	Chỉ con số Merchant B xuất hiện; dữ liệu Merchant A không bao giờ được trả về
Một báo cáo doanh số không có đơn khớp	Báo cáo được yêu cầu	Tổng hiển thị bằng không; không lỗi nào được nêu

7. Ràng buộc & Phi mục tiêu

Ràng buộc

ID	Ràng buộc
C-01	Báo cáo X lặp lại được; báo cáo Z được tạo một lần cho mỗi phiên (cuối cùng)
C-02	Mọi báo cáo theo phạm vi quyền truy cập merchant của người dùng
C-03	Báo cáo doanh số yêu cầu một khoảng ngày từ–đến
C-04	Chỉ đơn đã hoàn tất được tổng hợp vào con số doanh số

Phi mục tiêu

• Phân tích lãi & lỗ
• Báo cáo định giá tồn kho
• Phân tích giữ chân / giá trị vòng đời khách hàng
• Xuất PDF / CSV / Excel
• Báo cáo tự động theo lịch
• Widget KPI dashboard thời gian thực

8. Lịch sử phiên bản

Ngày	Tác giả	Mô tả	Ver
2026-02-26	P. Do — Product Owner	User story ban đầu	v0.1
2026-04-16	P. Do — Product Owner	Tái cấu trúc thành khu vực báo cáo phiên + doanh số	v0.3
2026-05-29	Di trú tài liệu	Căn lại các khu vực (SHF/SLS/ACC/ADV) theo hành vi @nx/sale đã xác minh; đánh dấu phân tích nâng cao Planned	v0.4