Kho Hàng Phase 1 In-progress

Tài liệu nghiệp vụ (BA)

UC — Use Case · SRS — Đặc tả yêu cầu · UI — Đặc tả giao diện

Kho Hàng quản lý toàn bộ hàng hoá bán tại sân pickleball - từ dụng cụ thể thao (vợt, bóng, phụ kiện) đến đồ uống và thực phẩm (FNB). Module giữ tồn kho theo thời gian thực, tự trừ kho khi POS bán hàng, cảnh báo khi sắp hết, và ghi lại mọi biến động nhập/xuất để phục vụ báo cáo.

1. Định danh

Thuộc tính	Giá trị
Module ID	OW-04
Hạng	Core
Trạng thái	In-progress
Giai đoạn	P1 (tồn kho, nhập/xuất, kiểm kho, cảnh báo) · P2 (đa chi nhánh, import)
Ưu tiên	HIGH
Người dùng chính	Chủ sân · Quản lý ca · Thu ngân · Xem báo cáo

2. Mục đích & Phạm vi

Bao gồm	Loại trừ
Danh mục sản phẩm: dụng cụ thể thao (vợt/bóng/phụ kiện) + FNB	Bán hàng tại quầy & checkout (→ Bán hàng)
Tồn kho realtime, tự trừ kho khi POS bán	Xử lý thanh toán (→ Thanh toán)
Nhập kho / xuất kho thủ công, kiểm kho điều chỉnh tồn	Tổng hợp doanh thu & lợi nhuận (→ Doanh thu & Báo cáo)
Ngưỡng cảnh báo tồn thấp + push notification	Phát hành hoá đơn nhập/xuất chính thức (→ Hoá đơn & Thuế)
Rollback tồn kho khi huỷ đơn POS	Quản lý nhà cung cấp đầy đủ (Dự kiến P2)
Tồn kho theo chi nhánh + chuyển kho
Lịch sử giao dịch kho & phân tích tiêu thụ

3. Năng lực

Năng lực	Người dùng làm được gì
Danh mục sản phẩm	Thêm/sửa sản phẩm theo 5 danh mục (Vợt & Phụ kiện · Quần áo · Đồ uống · Thực phẩm · Khác) kèm SKU, giá bán, giá vốn, ảnh
Bật/tắt kinh doanh	Ẩn/hiện sản phẩm trên POS mà vẫn giữ được tồn kho
Tồn kho realtime	Xem số lượng tồn hiện tại của từng sản phẩm, badge màu theo mức tồn
Nhập kho thủ công	Tạo phiếu nhập: số lượng, giá nhập, nhà cung cấp, ghi chú
Xuất kho thủ công	Tạo phiếu xuất với lý do (hỏng, tặng, dùng nội bộ)
Kiểm kho	Nhập số thực đếm, hệ thống tính chênh lệch và điều chỉnh tồn
Auto-deduct khi bán	POS chốt đơn → tồn kho tự giảm đồng thời, chống bán âm
Rollback khi huỷ	Huỷ đơn POS → tồn kho tự cộng lại đúng số lượng
Cảnh báo tồn thấp	Cấu hình ngưỡng tối thiểu; push notification khi vượt ngưỡng
Tồn kho theo chi nhánh	Mỗi chi nhánh có kho riêng; chuyển hàng giữa chi nhánh
Lịch sử & phân tích	Xem nhật ký nhập/xuất theo sản phẩm/ngày, sản phẩm bán chạy

4. Phụ thuộc Module

Phụ thuộc vào	Lý do
Xác thực & Phân quyền	Giới hạn thao tác kho theo vai trò và phạm vi chi nhánh (branch scope trong JWT)
Thông báo	Gửi push cảnh báo tồn thấp tới Quản lý ca / Chủ sân

Được phụ thuộc bởi	Lý do
Bán hàng	POS đọc tồn kho, trừ kho khi bán và hoàn kho khi huỷ
Doanh thu & Báo cáo	Lấy giá vốn (Last-in Cost) để tính lợi nhuận gộp, snapshot giá trị tồn
Tổ chức & Chi nhánh	Kho được phân vùng theo từng chi nhánh

5. Backend Packages

Chi tiết triển khai nằm trong tài liệu lập trình viên - mục này chỉ ánh xạ module tới service vận hành nó.

Package	Vai trò	Tài liệu lập trình viên
@nx/inventory	Sở hữu danh mục sản phẩm, tồn kho, phiếu nhập/xuất, kiểm kho, nhật ký giao dịch	inventory

6. Luồng người dùng chính

POS bán hàng → tự trừ tồn kho

Nhập kho thủ công

Kiểm kho & điều chỉnh tồn

7. Vai trò & Phân quyền

Vai trò	Được phép	Không được phép
Chủ sân	Toàn quyền quản lý kho mọi chi nhánh, chuyển kho, xem báo cáo tồn	-
Quản lý ca	Thêm/sửa sản phẩm, nhập/xuất kho, kiểm kho, cấu hình ngưỡng cảnh báo (chi nhánh được phân công)	Quản lý kho ngoài chi nhánh của mình
Thu ngân	Xem tồn kho hiện tại phục vụ POS, xem lịch sử giao dịch kho	Nhập/xuất kho, sửa sản phẩm
Xem báo cáo	Chỉ xem danh sách sản phẩm và tồn kho (read-only)	Mọi thao tác chỉnh sửa

8. Trạng thái & Lộ trình

Giai đoạn	Năng lực
P1	Danh mục sản phẩm, tồn kho realtime, auto-deduct & rollback, nhập/xuất thủ công, kiểm kho, cảnh báo tồn thấp, lịch sử giao dịch
P2	Tồn kho & chuyển kho đa chi nhánh, import Excel/CSV hàng loạt, quản lý nhà cung cấp, đặt hàng tự động, quét barcode/QR
P3	Dự báo nhu cầu theo mùa, giá vốn FIFO chính xác cho kế toán

9. Trang liên quan

• Bán hàng · Doanh thu & Báo cáo · Tổ chức & Chi nhánh
• Tài liệu lập trình viên: Inventory Service