URD: Báo cáo

Module	CORE-11	Phiên bản	v0.5
Trạng thái	In-progress	Ngày	2026-06-04

Tài liệu nghiệp vụ. URD này chính là danh sách tính năng của Báo cáo - mỗi tính năng bên dưới là một Vùng chức năng (<AREA>). Cùng mã <AREA> đó cũng là định danh cho PRD (PRD-<AREA>-NNN) và test (TC-<AREA>-NNN) của tính năng, và mỗi tính năng được liệt kê trong danh mục tính năng Delivery. Xem quy ước Feature Spine.

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ủ cửa hàng 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, 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 ca, doanh số, kỳ vọng so với 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 theo 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 bản 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 đóng ca, tạo một lần khi một phiên được đóng. Khóa lại 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 ca + doanh số tiền mặt − các khoản chi) với tiền mặt thực tế đã đếm, từ đó ra một khoản chênh lệch.
Tổng hợp hằng ngày	Tổng theo từng ngày (doanh thu gộp, thuế, chiết khấu, doanh thu 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 từ phía bán hàng về 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 thực tế nằm trong domain model bên tài liệu nhà phát triển.

5. Danh mục tính năng

Danh sách tính năng của module. Mỗi dòng là một tính năng (một Vùng chức năng). Chi tiết ở §6. Được phản ánh lại trong danh mục tính năng Delivery.

Feature ID	Tính năng	Phase	Trạng thái	Ưu tiên
SHF	Báo cáo ca	P2	In-progress	High
SLS	Báo cáo doanh số	P1	Built	High
ACC	Truy cập & Phạm vi	P1	Built	High
ADV	Phân tích nâng cao	P3	Planned	Low

Trạng thái: live từ Plane nếu có map, còn lại do registry khai báo. Vocabulary đồng nhất với Plane (state-group / phase).

6. Tính năng

Một mục con cho mỗi tính năng, theo thứ tự trong danh mục. Mỗi tính năng gói chung mô tả, yêu cầu và nghiệm thu lại với nhau. Ưu tiên = MoSCoW (Must / Should / Could / Won't).

SHF - Báo cáo ca In-progress

Mã tính năng: reports/SHF · Phase: P2 · PRDs: - · Dev: @nx/sale

Giá trị cho người dùng: thu ngân lấy một bản tổng hợp giữa ca (X) và một báo cáo cuối ca (Z) khi đóng, mỗi báo cáo kèm đối soát tiền mặt và tổng hợp doanh số, cùng phân rã phương thức thanh toán và danh mục tùy chọn.

Yêu cầu

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 ca, doanh số tiền mặt, thu/chi, kỳ vọng so với thực tế, chênh lệch
URD-SHF-004	M	Tổng hợp doanh số trên báo cáo ca: doanh thu gộp, chiết khấu, thuế, doanh 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

Nghiệm thu

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	Xem xét báo cáo đó	Đố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 đều có mặt

SLS - Báo cáo doanh số Built

Mã tính năng: reports/SLS · Phase: P1 · PRDs: - · Dev: @nx/sale

Giá trị cho người dùng: chủ hoặc quản lý xem tổng doanh số hằng ngày trên một khoảng ngày, sản phẩm bán chạy theo doanh thu và số lượng, phân rã theo danh mục kèm đào sâu vào một danh mục, và tổng hợp mua hàng để so sánh chi phí.

Yêu cầu

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 (doanh thu gộp, thuế, chiết khấu, doanh thu 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 theo nhà cung cấp / đơn mua hàng để so sánh chi phí
URD-SLS-006	M	Tổng hợp doanh thu theo chu kỳ: nhóm số liệu doanh thu (gộp, giảm giá, thuế, thuần, số đơn) theo Ngày, Tháng, Năm trên khoảng thời gian lọc

Nghiệm thu

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	Doanh thu gộp, thuế, chiết khấu, doanh thu thuần và số đơn được hiển thị theo từng ngày
Một ngữ cảnh merchant	Cùng yêu cầu đó	Kết quả chỉ giới hạn trong phạm vi merchant đó

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

Cho	Khi	Thì
Các đơn đã hoàn tất với nhiều 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 đó	Đào sâu vào một danh mục	Chi tiết của riêng danh mục đó được hiển thị

AC-SLS-03: Tổng hợp doanh thu theo chu kỳ linh hoạt

Cho	Khi	Thì
Một khoảng thời gian lọc (ví dụ: 1 năm)	Yêu cầu tổng hợp doanh thu nhóm theo Tháng	Trả về tổng cộng của 12 tháng riêng biệt; mỗi tháng hiển thị đúng tổng doanh thu gộp, giảm giá, thuế, thuần và số đơn hoàn tất
Một khoảng thời gian lọc bất kỳ	Thay đổi kiểu nhóm giữa Ngày/Tháng/Năm	Biểu đồ xu hướng và bảng dữ liệu thay đổi số lượng hàng/cột tương ứng chính xác với chu kỳ đã chọn

ACC - Truy cập & Phạm vi Built

Mã tính năng: reports/ACC · Phase: P1 · PRDs: - · Dev: @nx/sale

Giá trị cho người dùng: mọi báo cáo đều bị giới hạn theo quyền truy cập merchant của người dùng, yêu cầu một khoảng ngày, chỉ tính đơn đã hoàn tất, và hiển thị kết quả rỗng một cách mượt mà - nhờ vậy con số luôn đúng và không bao giờ rò rỉ giữa các merchant.

Yêu cầu

ID	P	Yêu cầu
URD-ACC-001	M	Báo cáo giới hạn theo phạm vi quyền truy cập merchant của người dùng; không rò rỉ dữ liệu giữa các 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 mới 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 báo lỗi)

Nghiệm thu

AC-ACC-01: Phạm vi merchant

Cho	Khi	Thì
Một người dùng thuộc Merchant B	Yêu cầu bất kỳ báo cáo nào	Chỉ con số của 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 nào khớp	Báo cáo được yêu cầu	Tổng hiển thị bằng không; không phát sinh lỗi

ADV - Phân tích nâng cao Planned

Mã tính năng: reports/ADV · Phase: P3 · PRDs: - · Dev: @nx/sale

Giá trị cho người dùng: phần mở rộng trong tương lai bổ sung phân tích biên lợi nhuận, định giá tồn kho, phân tích khách hàng, xuất ra các định dạng tệp phổ biến, và tạo báo cáo theo lịch.

Yêu cầu

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

ADV chưa được build. Các yêu cầu này chỉ được ghi lại để phục vụ truy vết lộ trình và chưa có test case cho tới khi bắt đầu build.

Nghiệm thu

AC-ADV-01: Phân tích lợi nhuận (planned)

Cho	Khi	Thì
Các đơn đã hoàn tất có dữ liệu chi phí và doanh thu	Phân tích lợi nhuận được yêu cầu	Biên lợi nhuận giữa chi phí và doanh thu được hiển thị

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 chỉ được tạo một lần cho mỗi phiên (là điểm kết thúc)
C-02	Mọi báo cáo đều giới hạn 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 mới đượ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 trên 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 các vùng 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 vùng (SHF/SLS/ACC/ADV) theo hành vi @nx/sale đã xác minh; đánh dấu phân tích nâng cao là Planned	v0.4
2026-06-04	Claude (AI pair)	Tổ chức lại theo tính năng (Feature Spine); mỗi tính năng tự mang yêu cầu + nghiệm thu của mình	v0.5