Hướng dẫn sử dụng VDG POS
Tài liệu này hướng dẫn từng bước cách vận hành phần mềm bán hàng VDG POS (phiên bản Web) — từ đăng nhập, bán hàng tại quầy, công nợ (phải thu / phải trả), đến quản trị sản phẩm, nhân viên, ca làm việc và xuất hoá đơn điện tử.
Mỗi mục đều có ảnh chụp giao diện máy tính (desktop) và điện thoại (mobile). Tệp ảnh nằm trong thư mục
docs/manual/img/.
🆕 Điểm mới trong bản này
- Công nợ phải thu — bán ghi nợ cho khách (trả trước một phần, còn lại ghi sổ), thu dần, số dư đầu kỳ, điều chỉnh, nhắc nợ quá hạn, xuất CSV. Xem phần 5.
- Công nợ phải trả — theo dõi nợ nhà cung cấp; nợ phát sinh tự động khi Nhập kho, cộng thêm ghi nợ ngoài luồng (cước, dịch vụ), chi trả dần.
- Đối trừ (bù trừ) công nợ khi một đối tác vừa là khách vừa là NCC.
- Sửa / huỷ phiếu nợ có lưu vết (chỉ Chủ quán) để đối chiếu.
Mục lục
- Khởi động phần mềm
- Đăng nhập
- Màn hình bán hàng (POS)
- Dashboard Chủ quán
- Công nợ (Phải thu & Phải trả)
- Thiết lập
- Hoá đơn điện tử (HDDT)
- Báo cáo & xuất file
- Hỗ trợ
1. Khởi động phần mềm
Trên máy tính của cửa hàng
scripts/start-demo.sh # macOS / Linux
scripts\start-demo.ps1 # Windows
Phần mềm sẽ:
- Khởi tạo cơ sở dữ liệu SQLite tại
pos.db. - Tự động nạp dữ liệu mẫu (sản phẩm, nhóm sản phẩm, 4 tài khoản nhân viên).
- Mở Web Admin tại
http://localhost:5005. - Mở cửa sổ POS toàn màn hình (trừ khi đặt
Kiosk:Headless=true).
Tài khoản mặc định
| Tài khoản | Vai trò | Mật khẩu (web) | Mã PIN (kiosk) |
|---|---|---|---|
admin |
Quản trị | 5555 |
5555 |
owner |
Chủ quán | 5555 |
5555 |
casher1 |
Thu ngân | — | 5555 |
casher2 |
Thu ngân | — | 5555 |
⚠️ Bắt buộc đổi mật khẩu trước khi triển khai thực tế. Vào Thiết lập → Nhân viên / Thu ngân để đổi.
2. Đăng nhập
VDG POS có hai cổng đăng nhập riêng biệt — phù hợp với từng vai trò.
2.1 Đăng nhập mật khẩu (Admin / Chủ quán)
URL: http://localhost:5005/login
| Desktop | Mobile |
|---|---|
 |
 |
- Nhập Tài khoản + Mật khẩu rồi bấm Đăng nhập.
- Sau khi đăng nhập, Admin/Owner được đưa thẳng vào Dashboard.
- Nếu là Thu ngân, hệ thống chuyển ngay vào Màn hình bán hàng.
2.2 Đăng nhập PIN (Thu ngân)
URL: http://localhost:5005/login/cashier
| Desktop | Mobile |
|---|---|
 |
 |
- Chọn ô nhân viên (ảnh đại diện 👤).
- Nhập PIN 4 số trên bàn phím cảm ứng.
- Hệ thống tự động đăng nhập ngay khi đủ 4 chữ số.
Mục đích thiết kế: trên máy quầy có nhiều người dùng chung, mỗi ca làm chỉ cần bấm 4 số trong vài giây.
2.3 Đăng xuất
- Desktop: nút Đăng xuất nằm trong menu hamburger (☰) → cuối danh sách.
- Mobile: mở ☰ rồi bấm 🚪 Đăng xuất (ô đỏ ở cuối).
3. Màn hình bán hàng (POS)
URL: http://localhost:5005/pos
| Desktop | Mobile |
|---|---|
 |
 |
3.1 Quy trình bán
- Chọn nhóm sản phẩm ở thanh trên cùng (Trà sữa, Trà trái cây, …).
- Bấm vào sản phẩm để thêm vào giỏ.
- Giỏ hàng nằm ở thanh dưới (
🛒 Giỏ hàng) — bấm để mở rộng:- + / −: tăng/giảm số lượng.
- 🗑️: xoá món.
- 📝 Ghi chú: thêm chú thích cho món (ví dụ "ít đường", "không đá").
- Bấm Thanh toán để chuyển sang màn hình trả tiền.
3.2 Thanh toán
Có ba phương thức:
| Phương thức | Cách hoạt động |
|---|---|
| 💵 Tiền mặt | Nhập số tiền khách đưa, hệ thống tính tiền thừa. |
| 📱 Chuyển khoản QR | Hệ thống sinh mã QR VietQR, khách quét bằng app ngân hàng. Khi giao dịch về (qua SePay hoặc SMS), POS tự động xác nhận và in hoá đơn. |
| 🧾 Ghi nợ (bán chịu) | Khách trả trước một phần (hoặc chưa trả), phần còn lại ghi vào sổ công nợ. Bắt buộc chọn khách hàng (nhập SĐT rồi bấm Tìm) vì nợ phải gắn với một khách. Nếu khách đã vượt hạn mức công nợ thì hệ thống chặn, đơn nằm ở Chờ thanh toán. Xem chi tiết cách thu lại ở phần 5. |
Cấu hình tài khoản nhận tiền tại Thiết lập → VAT / Thuế (mục Ngân hàng).
3.3 Hàng đợi đơn
URL: http://localhost:5005/pos/queue
| Desktop | Mobile |
|---|---|
 |
 |
- Hiển thị các đơn đang chờ pha chế hoặc chờ thanh toán.
- Bấm vào đơn để xem chi tiết, in lại, hoặc huỷ.
4. Dashboard Chủ quán
URL: http://localhost:5005/ (sau khi đăng nhập bằng admin / owner).
Dashboard có các mục chính trên thanh nav (Doanh thu, Dòng tiền, Đơn hàng, Khách hàng, Công nợ, Phải trả, Ca làm việc, Chấm công, HDDT, Hỗ trợ) + nhóm Thiết lập gộp các trang quản trị bên trong.
4.1 📊 Doanh thu
URL: /?nav= (mặc định)
| Desktop | Mobile |
|---|---|
 |
 |
- 5 thẻ KPI: Doanh thu hôm nay, Số đơn, Trung bình/đơn, Tiền mặt, QR/Chuyển khoản.
- Bảng Đơn gần đây dưới cùng — bấm vào để mở chi tiết.
4.2 💰 Dòng tiền
URL: /?nav=cashflow hoặc /dashboard/cashflow
| Desktop | Mobile |
|---|---|
 |
 |
- Liệt kê mọi giao dịch tiền vào/ra (đơn hàng, hoàn tiền, nạp/rút quỹ).
- Lọc theo từ ngày → đến ngày, hướng (vào/ra), nguồn (cash, QR, …).
4.3 🧾 Đơn hàng
URL: /dashboard/admin/orders
| Desktop | Mobile |
|---|---|
 |
 |
- Danh sách tất cả đơn kèm: mã đơn, thời gian, nhân viên, tổng tiền, phương thức.
- Bấm vào một đơn để xem chi tiết, in lại, hoặc gửi hoá đơn qua email/SMS.
4.4 👥 Khách hàng
URL: /dashboard/admin/customers
| Desktop | Mobile |
|---|---|
 |
 |
Quản lý danh sách khách (tên, SĐT, email, điểm tích luỹ).
Bấm + Thêm khách hàng để mở form:
Desktop Mobile 
4.5 ⏰ Ca làm việc
URL: /?nav=shifts
| Desktop | Mobile |
|---|---|
 |
 |
- Hiển thị doanh thu theo từng ca + từng thu ngân.
- Mỗi dòng: ca, thu ngân, số đơn, tiền mặt, QR, tổng.
- Hữu ích để đối chiếu cuối ngày: cash thực tế trong két ↔ doanh thu cash.
4.6 🕐 Chấm công
URL: /?nav=timeclock
| Desktop | Mobile |
|---|---|
 |
 |
- Bảng giờ vào/ra của nhân viên (clock-in/clock-out).
4.7 💳 Công nợ — xem phần 5
4.8 🏭 Phải trả — xem phần 5
4.9 🧾 HDDT — xem phần 7
4.10 ⚙️ Thiết lập — xem phần 6
4.11 💬 Hỗ trợ — xem phần 9
5. Công nợ (Phải thu & Phải trả)
Công nợ theo dõi tiền khách còn nợ mình (phải thu) và tiền mình còn nợ nhà cung cấp (phải trả). Hai màn nằm trên thanh nav Dashboard: 💳 Công nợ và 🏭 Phải trả.
Phân quyền. Thu ngân không vào được. Chủ quán / Admin xem và thu / chi tiền bình thường. Các thao tác ghi tay (đầu kỳ, điều chỉnh, ghi nợ ngoài luồng, sửa/huỷ phiếu) chỉ Chủ quán (Owner) — vì chúng làm dịch chuyển số dư mà không có đơn hàng hay phiếu nhập kho đứng sau.
5.1 💳 Công nợ phải thu (khách nợ mình)
URL: /dashboard/admin/debt
Nợ phát sinh từ đâu? Khi bán hàng chọn phương thức 🧾 Ghi nợ (xem mục 3.2). Đơn vẫn tính là đã bán, phần khách trả ngay ghi nhận như tiền mặt, phần thiếu ghi thành phiếu nợ của khách đó.
Trên màn danh sách:
- Mỗi dòng = một khách còn nợ: mã, tên, SĐT, tổng còn nợ, phần quá hạn.
- 🔔 Nhắc nợ (
/dashboard/admin/debt/reminders): lọc riêng khách quá hạn theo số ngày, có số điện thoại bấm gọi nhanh. - Xuất CSV để đối chiếu / gửi kế toán.
Bấm vào một khách để mở chi tiết công nợ:
| Thao tác | Ý nghĩa |
|---|---|
| Thu tiền | Khách trả bớt — nhập số tiền, chọn Tiền mặt / Chuyển khoản. Hệ thống trừ vào các phiếu nợ cũ nhất trước. |
| Đối trừ (bù trừ) | Khi khách này đồng thời là nhà cung cấp của mình: cấn trừ nợ phải thu với nợ phải trả thay vì chuyển tiền qua lại. |
| Công nợ đầu kỳ (Owner) | Ghi số dư nợ có sẵn từ trước khi dùng phần mềm. |
| Điều chỉnh (Owner) | Tăng/giảm số nợ kèm lý do (vd ghi nhầm, giảm giá bù). |
| Hạn mức / Hạn thanh toán (Owner) | Đặt hạn mức (0 = không giới hạn) và số ngày đến hạn. Vượt hạn mức thì lúc bán sẽ bị chặn ghi nợ. |
| ✏️ Sửa / 🗑 Huỷ phiếu (Owner) | Xem mục 5.3. |
5.2 🏭 Công nợ phải trả (mình nợ nhà cung cấp)
URL: /dashboard/admin/payable
Nợ phát sinh từ đâu? Chủ yếu khi Nhập kho (⚙️ Thiết lập → Kho → Nhập kho): một lần nhập hàng vừa tăng tồn kho vừa ghi nợ NCC tương ứng. Ngoài ra có thể ghi nợ ngoài luồng cho các khoản không phải hàng hoá.
Màn danh sách + 🔔 Nhắc nợ phải trả + Xuất CSV hoạt động y như bên phải thu. Bấm vào một NCC để mở chi tiết:
| Thao tác | Ý nghĩa |
|---|---|
| Xác nhận chi | Trả bớt tiền cho NCC — nhập số tiền, chọn Tiền mặt / Chuyển khoản, ghi chú. |
| ⚠️ Ghi nợ ngoài luồng (Owner) | Chỉ ghi tiền nợ, KHÔNG tăng tồn kho. Dùng cho cước vận chuyển, dịch vụ, nợ cũ… Hàng thật thì phải vào Kho → Nhập kho. |
| Công nợ đầu kỳ (Owner) | Số nợ NCC có sẵn từ trước. |
| Điều chỉnh (Owner) | Tăng/giảm kèm lý do. |
| Hạn mức / Hạn thanh toán (Owner) | Hạn mức nợ và số ngày đến hạn với NCC. |
Bảng Phiếu còn nợ phân loại rõ nguồn gốc từng phiếu:
- Mua hàng — phiếu sinh từ nhập kho (có tăng tồn thật).
- ⚠️ Ngoài luồng — nợ ghi tay, KHÔNG phát sinh tồn kho.
- Đầu kỳ / Điều chỉnh — các bút toán tay.
5.3 ✏️ Sửa / huỷ phiếu nợ (lưu vết)
Chỉ Chủ quán thấy nút này (cả hai bên phải thu và phải trả):
- ✏️ Sửa chỉ mở với phiếu ghi tay chưa trả đồng nào (đầu kỳ / điều chỉnh / ngoài luồng). Bản chất là huỷ phiếu cũ + lập phiếu mới với số đúng — để lại dấu vết đối chiếu, không sửa đè âm thầm.
- 🗑 Huỷ dùng được cho mọi phiếu. Phiếu không bị xoá khỏi lịch sử, chỉ đánh dấu đã huỷ và trừ phần còn nợ. Tiền đã trả (nếu có) vẫn giữ nguyên — vì tiền đó đã ra/vào két thật.
⚠️ Huỷ phiếu từ nhập kho chỉ xoá tiền nợ — TỒN KHO KHÔNG tự giảm theo. Nếu bạn trả hàng lại NCC, phải vào ⚙️ Thiết lập → 📊 Tồn kho điều chỉnh giảm riêng. Đây là lỗi hay gặp nhất khi thao tác công nợ.
6. Thiết lập
Trên desktop, nhóm Thiết lập là một menu thả xuống ở thanh trên:
Trên mobile, mở menu hamburger (☰) và bấm ⚙️ Thiết lập để mở rộng:
5.1 📦 Sản phẩm
URL: /dashboard/admin/products
| Desktop | Mobile |
|---|---|
 |
 |
Quản lý SKU: tên, giá, ảnh, nhóm sản phẩm, thuế.
Bấm + Thêm sản phẩm:
Desktop Mobile 
Có thể tải ảnh từ máy lên (ảnh sẽ xuất hiện ngay trong POS).
5.2 🗂 Nhóm sản phẩm
URL: /?nav=categories
| Desktop | Mobile |
|---|---|
 |
 |
- Tạo/sửa/xoá nhóm hiển thị ở thanh trên cùng của POS.
5.3 📊 Tồn kho
URL: /dashboard/admin/stock
| Desktop | Mobile |
|---|---|
 |
 |
- Bảng tồn kho theo variant.
- Bấm +/- để điều chỉnh số lượng tay (kèm lý do — sẽ vào audit log).
5.4 ⭐ Tích điểm thành viên
URL: /dashboard/admin/loyalty
| Desktop | Mobile |
|---|---|
 |
 |
- Cấu hình: tỷ lệ tích điểm (VND ↔ điểm), giá trị 1 điểm khi đổi, giới hạn đổi/đơn.
5.5 👤 Nhân viên / Thu ngân
URL: /dashboard/admin/users
| Desktop | Mobile |
|---|---|
 |
 |
Danh sách tất cả tài khoản đăng nhập vào hệ thống.
Cột Vai trò: Admin / Chủ quán / Thu ngân.
Cột PIN kiosk: hiển thị xem nhân viên đã đặt PIN chưa.
Bấm + Thêm nhân viên để mở form đăng ký:
Desktop Mobile 
- Username (duy nhất, không dấu) — dùng để đăng nhập.
- Tên hiển thị — hiện trên hoá đơn + thẻ chọn thu ngân.
- Vai trò:
- Admin: truy cập đầy đủ web admin.
- Chủ quán: truy cập web admin (xem báo cáo, không sửa cấu hình hệ thống).
- Thu ngân: chỉ vào được POS, không vào được dashboard.
- Mật khẩu (cho login web) + PIN 4-6 số (cho login kiosk).
Bấm Sửa để bật/tắt tài khoản, đổi mật khẩu, đổi PIN, đổi vai trò.
5.6 💰 VAT / Thuế
URL: /?nav=settings
| Desktop | Mobile |
|---|---|
 |
 |
- Cấu hình thuế suất mặc định áp dụng cho sản phẩm.
- Cấu hình thông tin doanh nghiệp xuất trên hoá đơn (MST, địa chỉ, số tài khoản ngân hàng).
7. Hoá đơn điện tử (HDDT)
URL: /?nav=einvoice hoặc /einvoice/list
| Desktop | Mobile |
|---|---|
 |
 |
- Danh sách hoá đơn đã phát hành (đồng bộ với nhà cung cấp: Misa, Viettel, VNPT, hoặc Mock cho test).
- Trạng thái: Đã phát hành / Chờ retry / Lỗi.
- Bấm Phát hành lại trên đơn lỗi để retry thủ công.
- Phần Tổng kết tháng: số lượng + tổng tiền theo từng tháng — dùng đối chiếu báo cáo thuế.
Cấu hình kết nối nhà cung cấp
Sửa file appsettings.json (hoặc đặt biến môi trường VDGPOS_EInvoice__*):
"EInvoice": {
"Provider": "Misa", // Mock | Misa | Viettel | Vnpt
"ApiUrl": "...",
"Username": "...",
"Password": "..."
}
8. Báo cáo & xuất file
URL: /reports
| Desktop | Mobile |
|---|---|
 |
 |
Các file có thể xuất:
| Liên kết | Định dạng | Mô tả |
|---|---|---|
/reports/sales.xlsx?from=…&until=… |
Excel | Doanh thu theo ngày |
/reports/sales.csv?from=…&until=… |
CSV | Doanh thu theo ngày (dạng CSV) |
/reports/inventory.xlsx |
Excel | Tồn kho hiện tại |
Trang duyệt thanh toán
URL: /dashboard/payment-review
| Desktop | Mobile |
|---|---|
 |
 |
- Liệt kê giao dịch QR chưa khớp tự động với đơn — cho phép Owner duyệt thủ công hoặc từ chối.
9. Hỗ trợ
URL: /?nav=support hoặc /support
| Desktop | Mobile |
|---|---|
 |
 |
- Hiển thị thông tin liên hệ kỹ thuật (số điện thoại, email, Zalo).
- Hiển thị phiên bản phần mềm + thời điểm khởi động — dùng khi báo sự cố.
Phụ lục A — Sơ đồ điều hướng
┌─ /login ──────────► (Admin/Owner) ──► /
│ /login/cashier ──► (Staff) ──► /pos
│
├─ / (Dashboard shell, htmx) ─┬─ Doanh thu /?nav=
│ ├─ Dòng tiền /?nav=cashflow
│ ├─ Đơn hàng /dashboard/admin/orders
│ ├─ Khách hàng /dashboard/admin/customers
│ ├─ Công nợ /dashboard/admin/debt
│ ├─ Phải trả /dashboard/admin/payable
│ ├─ Ca làm việc /?nav=shifts
│ ├─ Chấm công /?nav=timeclock
│ ├─ HDDT /?nav=einvoice
│ ├─ Hỗ trợ /?nav=support
│ └─ Thiết lập ▾
│ ├─ Sản phẩm /dashboard/admin/products
│ ├─ Nhóm SP /?nav=categories
│ ├─ Tồn kho /dashboard/admin/stock
│ ├─ Loyalty /dashboard/admin/loyalty
│ ├─ Nhân viên /dashboard/admin/users
│ └─ VAT / Thuế /?nav=settings
│
├─ /pos ──────────────────────────► Bán hàng
└─ /pos/queue ───────────────────► Hàng đợi đơn
Phụ lục B — Tự chụp lại ảnh
Khi giao diện thay đổi, chạy lại tập lệnh chụp ảnh:
# Khởi động server ở chế độ headless (không mở cửa sổ kiosk)
VDGPOS_Kiosk__Headless=true dotnet run --project src/VdgPos.Bootstrap -p:NuGetAudit=false
# Trong terminal khác, chạy Playwright:
node docs/manual/capture.mjs
Ảnh sẽ ghi đè vào docs/manual/img/*.png.
Phiên bản tài liệu: 2026-07-17 · Bổ sung Công nợ (phải thu / phải trả) & bán ghi nợ · Tự động chụp giao diện bằng Playwright