Giới thiệu dự án

Ngành xây dựng Việt Nam ghi nhận tốc độ tăng trưởng trung bình 7.2 - 8.5%/năm trong giai đoạn phát triển hạ tầng và đô thị hóa. Tuy nhiên, theo khảo sát thực tế tại các doanh nghiệp và đại lý bán lẻ vật liệu xây dựng (tiêu biểu như cơ sở Tôn Liêm Lan, Cư M'gar, Đắk Lắk), hơn 75% cửa hàng quy mô vừa và nhỏ (SMEs) vẫn vận hành qua sổ sách giấy truyền thống hoặc phần mềm rời rạc.

+-------------------------------------------------------------------------+
|                  THỰC TRẠNG QUẢN LÝ VẬT LIỆU XÂY DỰNG                   |
|                                                                         |
|  [ Sổ sách giấy / Excel ]  --->  Tra cứu nợ: 15 - 30 phút / giao dịch   |
|  [ Đơn vị tính phức tạp ]  --->  Quy đổi thủ công (Kg <-> Mét <-> Tấm)   |
|  [ Thất thoát tồn kho ]    --->  Chênh lệch thực tế 5 - 12% / quý        |
|  [ Rủi ro dòng tiền ]      --->  Sai lệch công nợ, khó kiểm soát nợ xấu  |
+-------------------------------------------------------------------------+

Vấn đề cốt lõi phát sinh từ các điểm nghẽn đặc thù của ngành:

  • Quy cách sản phẩm đa dạng: Hàng hóa có nhiều đơn vị quy đổi (sắt thép tính theo kg/cây/cuộn, tôn tính theo mét/tấm/cuộn, xi măng tính theo bao/tấn) gây sai số lớn khi tính giá và trừ kho.
  • Công nợ dây dưa phức tạp: Khách hàng công trình thường thanh toán gối đầu theo tiến độ, việc tra cứu thủ công tốn 15–30 phút/giao dịch và dễ thất lạc chứng từ gốc.
  • Tính toán thuế và lãi lỗ thiếu chuẩn xác: Nhầm lẫn giữa phương pháp tính thuế GTGT trực tiếp và khấu trừ theo quy định của Bộ Tài chính.

Đề tài khóa luận tốt nghiệp kỹ sư Công nghệ thông tin chuyên ngành Công nghệ phần mềm tại Trường Đại học Sư phạm Kỹ thuật TP.HCM (HCMUTE) do nhóm sinh viên Nguyễn Trung Kiên, Trần Đức Long, Nguyễn Như Sâm thực hiện dưới sự hướng dẫn của PGS. Hoàng Văn Dũng đã giải quyết bài toán trên thông qua việc phát triển: "Phần mềm Quản lý Vật liệu Xây dựng – Máy POS".

Mục tiêu của dự án

  1. Xây dựng hệ thống quản lý bán hàng (POS) và quản trị tập trung (MCS - Management Control System) đa nền tảng (Web & Mobile).
  2. Tự động hóa công cụ quy đổi đa đơn vị tính và tính toán diện tích/quy cách theo thời gian thực.
  3. Tích hợp phân hệ theo dõi công nợ hai chiều (nhà cung cấp - khách hàng) chuẩn xác 100%.
  4. Chuẩn hóa quy trình nhập - xuất - kiểm kê kho (FIFO, cân bằng kho) và xuất báo cáo tài chính/thuế GTGT.

Phạm vi và giới hạn: Đề tài tập trung triển khai chuyên sâu cho các đại lý, cửa hàng phân phối vật liệu xây dựng, nhà máy tôn thép; chưa tích hợp trực tiếp cổng kết nối Hóa đơn điện tử có mã của Cơ quan Thuế theo Nghị định 123/2020/NĐ-CP (được xếp vào lộ trình nâng cấp).

Phân tích và thiết kế giải pháp

Phân tích hiện trạng

Khảo sát và đối sánh thực tế với các giải pháp phổ biến trên thị trường:

Tiêu chí kỹ thuật / Nghiệp vụ Sổ sách thủ công Sapo POS KiotViet POS Hệ thống VLXD POS đề xuất
Quy đổi đa đơn vị tính Tính nhẩm / Excel Hỗ trợ cơ bản Hỗ trợ cơ bản Chuyên sâu đa cấp ($kg \leftrightarrow m \leftrightarrow tấm$)
Tính quy cách động (Dài $\times$ Rộng $\times$ Hệ số) Không có Cần plugin Cần cấu hình phụ Tích hợp sẵn tại giao diện POS
Quản lý công nợ hai chiều Ghi sổ rời rạc Tốt Tốt Tự động gắn bill & khấu trừ đối ứng
Chi phí triển khai / duy trì Thấp (rủi ro cao) Thuê bao tháng cao Thuê bao tháng Tự chủ server, tối ưu TCO cho SME
Khả năng hoạt động ngoại tuyến (Offline) Không áp dụng Phụ thuộc Internet Hỗ trợ Offline Hybrid Cache & Đồng bộ đa nền tảng

Ma trận ưu tiên yêu cầu người dùng (MoSCoW)

  • Must-have: Bán hàng POS đa đơn vị; Quản lý kho (IQC, FIFO, cân bằng kho); Quản lý công nợ khách hàng/nhà cung cấp; Lập phiếu thu/chi; Phân quyền RBAC.
  • Should-have: Tính năng cắt tôn/tính diện tích theo quy cách động; Xuất báo cáo PDF/Excel với đa bộ lọc; Upload ảnh chứng từ lên AWS S3.
  • Could-have: Quản lý combo sản phẩm - dịch vụ vận chuyển; Thống kê biểu đồ trực quan hóa doanh thu theo thời gian thực.
  • Won't-have (giai đoạn này): Tự động điều phối xe tải logistics qua GPS; Kết nối trực tiếp máy POS ngân hàng qua giao thức thanh toán SmartPOS.

Thiết kế hệ thống

Kiến trúc tổng thể (3-Tier Clean Architecture)

+-------------------------------------------------------------------------------+
|                             PRESENTATION TIER                                 |
|   +-------------------------------+       +-------------------------------+   |
|   | Flutter Mobile Client (Dart)  |       |  Web POS / MCS Dashboard      |   |
|   | (Android / iOS)               |       |  (Static Web Hosted on S3)    |   |
|   +---------------+---------------+       +---------------+---------------+   |
+-------------------|---------------------------------------|-------------------+
                    | HTTPS / JSON                          | HTTPS / REST API  
+-------------------|---------------------------------------|-------------------+
|                   v                                       v                   |
|                                REVERSE PROXY                                  |
|                          +----------------------+                             |
|                          |     Nginx Server     |                             |
|                          +----------+-----------+                             |
|                                     |                                         |
|                               APPLICATION TIER                                |
|                          +----------v-----------+                             |
|                          | RESTful API Services |                             |
|                          | Node.js / Express.js |                             |
|                          +----+-----------+-----+                             |
+-------------------------------|-----------|-----------------------------------+
                                |           | SQL Queries / ORM
+-------------------------------|-----------|-----------------------------------+
|                               v           v                                   |
|                                DATA TIER                                      |
|    +------------------------------+   +----------------------------------+    |
|    | Amazon S3 Bucket             |   | Relational Database Server       |    |
|    | (Hình ảnh vật liệu, hóa đơn) |   | (PostgreSQL / MySQL Schema)      |    |
|    +------------------------------+   +----------------------------------+    |
+-------------------------------------------------------------------------------+

Công nghệ và phiên bản (Technology Stack)

  • Frontend & POS Client: Web App (HTML5/CSS3/JavaScript SPA), Flutter Framework (v3.19.x) & Dart SDK (v3.3.x) cho Mobile App.
  • Backend & Middleware: Node.js runtime (v20.x LTS), Express.js framework, Nginx Reverse Proxy (v1.24.x).
  • Database: Relational Database Engine (PostgreSQL v15 / MySQL v8.0) với mô hình Entity-Relationship chuẩn hóa (3NF).
  • Cloud & Storage: AWS S3 Bucket (Lưu trữ media/ảnh chứng từ), VPS Linux Server (Ubuntu 22.04 LTS).

Thiết kế Cơ sở dữ liệu (Database Schema Entities)

Hệ thống chuẩn hóa hơn 30 thực thể quan hệ, tiêu biểu:

  • products: Lưu thông tin chung (id, name, category_id, brand_id, base_unit_id, cost_price, selling_price, stock_quantity).
  • product_units: Bảng quy đổi (id, product_id, unit_id, conversion_rate, price).
  • specifications & size_units: Quy cách động (id, product_id, length, width, height, factor).
  • orders & order_items: Đơn bán hàng và chi tiết (order_id, customer_id, total_amount, tax_id, debt_amount, status_id).
  • debts: Quản lý nợ (id, target_type [CUSTOMER/SUPPLIER], target_id, total_debt, paid_amount, remaining_debt).
-- DDL trích xuất cấu trúc quan hệ quy đổi đơn vị tính và quy cách tôn/thép
CREATE TABLE product_units (
    id SERIAL PRIMARY KEY,
    product_id INT NOT NULL REFERENCES products(id) ON DELETE CASCADE,
    unit_name VARCHAR(50) NOT NULL,
    conversion_rate NUMERIC(10, 4) NOT NULL, -- Tỷ lệ quy đổi so với đơn vị cơ sở
    selling_price NUMERIC(15, 2) NOT NULL,
    is_base_unit BOOLEAN DEFAULT FALSE,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE specifications (
    id SERIAL PRIMARY KEY,
    product_id INT NOT NULL REFERENCES products(id),
    length NUMERIC(8, 2),   -- Chiều dài (mét)
    width NUMERIC(8, 2),    -- Chiều rộng (mét)
    thickness NUMERIC(8, 2),-- Độ dày (mm/dem)
    factor NUMERIC(8, 4) DEFAULT 1.0, -- Hệ số quy đổi diện tích/khối lượng
    unit_code VARCHAR(20)
);

Thiết kế RESTful API Endpoints tiêu chuẩn

Phương thức Endpoint Mô tả nghiệp vụ Dữ liệu trả về / Mã trạng thái
POST /api/v1/auth/login Xác thực người dùng (Admin, Nhân viên, Khách) JWT Token, User Profile (200 OK)
GET /api/v1/products/{id}/units Lấy danh mục đơn vị quy đổi theo sản phẩm List ProductUnitDTO (200 OK)
POST /api/v1/orders/create Tạo hóa đơn POS & tính trừ tồn kho tự động OrderReceiptDTO (201 Created)
POST /api/v1/inventory/adjust Cân bằng kho thực tế sau kiểm kê StockAdjustmentResult (200 OK)
GET /api/v1/debts/customers/{id} Truy xuất lịch sử giao dịch và dư nợ khách DebtSummaryDTO (200 OK)

Implementation và kết quả

Development Process & Key Algorithms

Dự án được xây dựng theo mô hình Agile/Scrum với 9 cột mốc thực hiện liên tục từ 05/07/2023 đến 15/06/2024:

[07/2023] Khảo sát thực tế Tôn Liêm Lan & Đối soát KiotViet/Sapo
   ↓
[09/2023] Phân tích đặc tả 42 Use Cases & Thiết kế ERD / Figma UI
   ↓
[12/2023] Hoàn thiện Web MCS Core & Hệ thống RESTful API
   ↓
[03/2024] Xây dựng Mobile POS (Flutter) & Xử lý nghiệp vụ cắt tôn/đa đơn vị
   ↓
[05/2024] Kiểm thử tích hợp (Integration Test) & Tối ưu hóa trên VPS/AWS
   ↓
[06/2024] Nghiệm thu thực tế & Hoàn thiện luận văn tốt nghiệp

Thuật toán quy đổi đơn vị tính & tính quy cách cắt tôn động

/**
 * Thuật toán tính toán số lượng xuất kho và thành tiền theo quy cách tấm
 * @param length Chiều dài đặt cắt (mét)
 * @param quantity Số tấm khách đặt
 * @param unitPrice Giá niêm yết theo mét tới (VND)
 * @param conversionRate Tỷ lệ quy đổi từ mét ra đơn vị lưu kho cơ sở (kg)
 */
function calculateRoofingOrderItem(
  length: number,
  quantity: number,
  unitPrice: number,
  conversionRate: number
) {
  // 1. Tính tổng mét tới
  const totalLengthMeters = length * quantity;
  
  // 2. Tính thành tiền đơn hàng
  const itemTotalPrice = totalLengthMeters * unitPrice;
  
  // 3. Quy đổi khối lượng trừ kho cơ sở (Kg)
  const inventoryDeductionKg = totalLengthMeters * conversionRate;
  
  return {
    totalMeters: Number(totalLengthMeters.toFixed(2)),
    totalPrice: Math.round(itemTotalPrice),
    deductStockQuantity: Number(inventoryDeductionKg.toFixed(3))
  };
}

Testing và Validation

+----------------------------------------------------------------------------+
|                       KẾT QUẢ KIỂM THỬ HỆ THỐNG                            |
|                                                                            |
|   [ Unit Tests ]          Coverage: 88.4% (Pass: 142/142 test cases)       |
|   [ Integration Tests ]   API Response Time: Avg 135ms (< 200ms target)    |
|   [ Performance ]         PDF Report Generation: 1.1s cho 10,000 dòng      |
|   [ System Uptime ]       99.9% trên VPS Production                        |
+----------------------------------------------------------------------------+
  1. Kiểm thử đơn vị (Unit Testing): Đạt tỷ lệ bao phủ (Coverage) 88.4% trên toàn bộ các module tính toán logic: công nợ, khấu trừ thuế GTGT, cân bằng kho.
  2. Kiểm thử hiệu năng (Performance Benchmarks):
    • Thời gian phản hồi API trung bình: 135ms trên hạ tầng máy chủ VPS tiêu chuẩn (2 vCPU, 4GB RAM).
    • Tốc độ xuất báo cáo tài chính PDF lọc động (Dynamic PDF Engine): 1.1 giây đối với tập dữ liệu 10,000 bản ghi đơn hàng.
  3. Kiểm thử chấp nhận người dùng (UAT): Thử nghiệm trực tiếp tại Cửa hàng Tôn Liêm Lan với hơn 350 giao dịch thực tế không phát sinh lỗi sai lệch tồn kho hay nhầm lẫn số liệu sổ quỹ.

Đổi mới và đóng góp

+-----------------------------------------------------------------------------+
|                     HIỆU QUẢ CẢI TIẾN ĐƯỢC ĐO LƯỜNG                         |
|                                                                             |
|  Thời gian tra cứu công nợ:      Giảm 80% (từ 15 phút -> < 5 giây)          |
|  Thời gian lập bill & cắt tôn:   Giảm 65% (từ 7 phút -> 2.5 phút)           |
|  Tỷ lệ sai lệch kiểm kê kho:     Giảm từ 8.5% xuống < 0.2%                  |
|  Hiệu suất quyết toán sổ quỹ:    Tăng 90% (kết xuất tức thì)                |
+-----------------------------------------------------------------------------+
  • Công cụ tính toán quy cách linh hoạt: Loại bỏ hoàn toàn phương pháp bấm máy tính cầm tay để quy đổi tôn thép từ mét/diện tích sang kg, hạn chế 100% rủi ro tính nhầm giá cho khách hàng công trình.
  • Module quản lý công nợ hai chiều tự động: Tự động liên kết phiếu thu/chi với từng hóa đơn nhập/xuất cụ thể. Giảm 80% thời gian tra cứu hồ sơ nợ cũ (từ 15 phút tìm sổ sách xuống dưới 5 giây tra cứu trên máy POS).
  • Quy trình cân bằng kho khoa học: Cho phép lập phiếu kiểm kê định kỳ, phân tích nguyên nhân hao hụt (mất mát, cắt vụn phế liệu, sai số cân) và tự động tạo bút toán điều chỉnh tồn kho.

Ứng dụng thực tế và triển khai

Kịch bản ứng dụng thực tế

  1. Đại lý kinh doanh sắt thép - tôn cuộn: Tiếp nhận đơn hàng yêu cầu cắt tôn theo kích thước công trình, hệ thống tự tính mét tới, tổng tiền và trừ kho theo cuộn thép chính xác.
  2. Cửa hàng bán lẻ gạch men - xi măng: Bán theo thùng, m2 hoặc viên; tự động tính đơn giá chiết khấu theo số lượng và phân loại khách hàng (Thợ thầu, Đại lý cấp 2, Khách lẻ).
+-----------------------------------------------------------------------------+
|                    QUY TRÌNH DEPLOY HỆ THỐNG TRÊN VPS                       |
|                                                                             |
|   [ Git Repo ]  --->  [ Build Dist & Flutter APK/Bundle ]                   |
|                              |                                              |
|         +--------------------+--------------------+                         |
|         |                                         |                         |
|         v                                         v                         |
|  [ AWS S3 Static Bucket ]              [ Nginx Reverse Proxy ]              |
|  - Web POS Client Static Files         - SSL Termination (Let's Encrypt)    |
|  - Product & Receipt Images            - Upstream Node.js API (Port 5000)   |
+-----------------------------------------------------------------------------+

Hướng dẫn triển khai hạ tầng

# 1. Cấu hình Reverse Proxy Nginx cho Backend API
server {
    listen 80;
    server_name api.vlxd-pos.vn;

    location / {
        proxy_pass http://localhost:5000;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection 'upgrade';
        proxy_set_header Host $host;
        proxy_cache_bypass $http_upgrade;
    }
}

# 2. Đồng bộ giao diện Web POS lên AWS S3 Bucket
aws s3 sync ./dist/ s3://vlxd-pos-web-bucket/ --acl public-read

Phân tích hiệu quả đầu tư (ROI Analysis)

Đối với một cửa hàng VLXD quy mô trung bình (doanh thu 800 triệu - 1.5 tỷ VND/tháng):

  • Tiết kiệm chi phí nhân sự kiểm kê: Cắt giảm 1 nhân sự chuyên ghi sổ kế toán (~84 triệu VND/năm).
  • Hạn chế thất thoát vật tư: Tiết kiệm trung bình 1.5 - 2.5% giá trị hàng tồn kho bị sai lệch (~30 - 50 triệu VND/năm).
  • Thời gian hoàn vốn (ROI): Ước tính từ 3 đến 5 tháng sau khi đưa vào vận hành thực tế.

Hạn chế và hướng phát triển

  • Hạn chế: Hệ thống hiện phụ thuộc vào đường truyền mạng để đồng bộ dữ liệu tập trung giữa các chi nhánh; chưa hỗ trợ công nghệ OCR tự động quét hóa đơn đầu vào từ nhà cung cấp dạng ảnh chụp.
  • Hướng phát triển:
    1. Tích hợp AI dự báo nhu cầu nhập hàng theo mùa xây dựng dựa trên thuật toán Time Series Forecasting (ARIMA/LSTM).
    2. Tích hợp API xuất hóa đơn điện tử theo chuẩn Tổng cục Thuế Việt Nam.
    3. Mở rộng tính năng điều phối vận tải logistics, theo dõi lộ trình xe tải giao hàng đến công trường.

Đối tượng hưởng lợi

  • Sinh viên & Nghiên cứu sinh: Nguồn tài liệu tham khảo hoàn chỉnh về kiến trúc ứng dụng bán hàng POS, mô hình ERD chuẩn hóa cho ngành bán lẻ đặc thù và đặc tả 42 use cases chi tiết.
  • Lập trình viên (Developers): Cung cấp mã nguồn mẫu về tích hợp Flutter Mobile với Node.js REST API, kỹ thuật triển khai AWS S3 kết hợp Nginx Reverse Proxy.
  • Chủ doanh nghiệp / Cửa hàng VLXD: Sở hữu giải pháp chuyển đổi số toàn diện giúp ngăn chặn thất thoát hàng hóa, tự động hóa dòng tiền và gia tăng 35% tốc độ phục vụ khách hàng.

Câu hỏi thường gặp

1. Cấu hình máy chủ tối thiểu để triển khai hệ thống là gì?

Máy chủ VPS cần tối thiểu 1 vCPU, 2GB RAM và 25GB SSD (hệ điều hành Ubuntu 20.04/22.04 LTS). Đối với client, máy POS hoặc máy tính bàn chỉ cần trình duyệt web hiện đại (Chrome, Edge) và điện thoại Android/iOS cấu hình cơ bản.

2. Hệ thống xử lý thế nào khi mất kết nối Internet đột ngột tại quầy thu ngân?

Client POS hỗ trợ cơ chế lưu trữ cục bộ (Local Storage/IndexedDB trên Web và SQLite trên Mobile App), cho phép thu ngân tiếp tục lập đơn và in hóa đơn tạm thời. Khi có kết nối trở lại, hệ thống tự động đẩy dữ liệu đồng bộ lên Database chính.

3. Phần mềm có thể kết nối với các thiết bị phần cứng ngoại vi nào?

Hệ thống tương thích hoàn toàn với các dòng máy in hóa đơn nhiệt qua cổng USB/LAN (khổ K80, K57), máy quét mã vạch Barcode/QR Code 1D/2D và ngăn kéo đựng tiền tự động (Cash Drawer).

4. Quy trình bảo trì và sao lưu (Backup) dữ liệu được thực hiện ra sao?

Cơ sở dữ liệu được cấu hình tự động backup định kỳ hàng ngày (Daily Cronjob) và đẩy bản nén mã hóa lưu trữ sang Amazon S3 Glacier nhằm đảm bảo an toàn dữ liệu tuyệt đối trước sự cố phần cứng.

5. Chi phí duy trì vận hành hệ thống hàng tháng là bao nhiêu?

Chi phí vận hành rất tiết kiệm đối với cửa hàng SME: VPS cơ bản (~150,000 - 300,000 VND/tháng), tên miền (~250,000 VND/năm) và chi phí lưu trữ AWS S3 (~20,000 - 50,000 VND/tháng tùy lượng ảnh), giúp tiết kiệm hơn 70% so với giải pháp thuê bao SaaS dài hạn.

Kết luận

Đồ án tốt nghiệp "Xây dựng phần mềm Quản lý Vật liệu Xây dựng – Máy POS" của nhóm sinh viên Trường Đại học Sư phạm Kỹ thuật TP.HCM đã giải quyết triệt để bài toán quản lý đặc thù của ngành vật liệu xây dựng. Bằng việc kết hợp kiến trúc phần mềm hiện đại, thuật toán quy đổi đơn vị linh hoạt và phân hệ quản lý công nợ chuyên sâu, dự án không chỉ hoàn thành xuất sắc yêu cầu học thuật mà còn chứng minh giá trị thực tiễn vượt trội khi áp dụng vào doanh nghiệp thực tế. Đây là nền tảng vững chắc để tiếp tục mở rộng thành hệ sinh thái quản trị chuỗi cung ứng vật tư xây dựng thông minh trong tương lai.