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, đế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/.

Mục lục

1. Khởi động phần mềm
2. Đăng nhập
3. Màn hình bán hàng (POS)
4. Dashboard Chủ quán
5. Thiết lập
6. Hoá đơn điện tử (HDDT)
7. Báo cáo & xuất file
8. 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ẽ:

1. Khởi tạo cơ sở dữ liệu SQLite tại pos.db.
2. 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).
3. Mở Web Admin tại http://localhost:5005.
4. Mở cửa sổ POS toàn màn hình (trừ khi đặt Kiosk:Headless=true).

Tài khoản mặc định

⚠️ 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

1. Chọn nhóm sản phẩm ở thanh trên cùng (Trà sữa, Trà trái cây, …).
2. Bấm vào sản phẩm để thêm vào giỏ.
3. 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 đá").
4. Bấm Thanh toán để chuyển sang màn hình trả tiền.

3.2 Thanh toán

Có hai phương thức:

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ó 8 mục chính trên thanh nav + 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 🧾 HDDT — xem phần 6

4.8 ⚙️ Thiết lập — xem phần 5

4.9 💬 Hỗ trợ — xem phần 8

5. 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).

6. 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": "..."
}

7. Báo cáo & xuất file

URL: /reports

Desktop	Mobile

Các file có thể xuất:

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.

8. 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
│                              ├─ 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-05-19 · Tự động chụp giao diện bằng Playwright