Giới thiệu dự án

Trong bối cảnh chuyển đổi số trong giáo dục và quản trị cơ sở vật chất, mô hình lưu trú "Khách sạn sinh viên" tại các trường đại học đóng vai trò quan trọng trong việc nâng cao chất lượng đời sống sinh viên. Tuy nhiên, theo các khảo sát quản trị ký túc xá đại học tại Việt Nam, hơn 65% đơn vị quản lý vẫn duy trì phương pháp ghi chép thủ công hoặc ứng dụng bảng tính rời rạc (Excel). Thực trạng này dẫn đến tỷ lệ sai sót đối soát số liệu điện nước trung bình 15-20%, độ trễ thông báo công nợ kéo dài 7-10 ngày mỗi kỳ thanh toán, và tiêu tốn hàng chục giờ lao động mỗi tháng của đội ngũ vận hành.

Đề tài "Nghiên cứu xây dựng phần mềm quản lý khách sạn sinh viên (Phân hệ tài chính)" do sinh viên Đào Anh Ngọc thực hiện dưới sự hướng dẫn của Th.S Đỗ Văn Tuyên tại Trường Đại học Quản lý và Công nghệ Hải Phòng giải quyết trực tiếp bài toán tự động hóa quy trình quản trị dòng tiền lưu trú. Hệ thống giải quyết các điểm nghẽn chính:

  • Thao tác ghi nhận và tính toán biểu giá điện, nước theo phòng thủ công dễ nhầm lẫn.
  • Thiếu cơ chế phân quyền kiểm soát dữ liệu đa cấp (Role-Based Access Control - RBAC).
  • Không có hệ thống tự động kết xuất hóa đơn chi tiết và gửi thông báo điện tử đến từng người thuê.
+-----------------------------------------------------------------------------+
|                           MỤC TIÊU DỰ ÁN CỤ THỂ                            |
+-----------------------------------------------------------------------------+
| 1. Số hóa 100% quy trình tính toán tài chính phòng, điện, nước lũy tiến.    |
| 2. Thiết kế kiến trúc JAMstack hiện đại với PostgreSQL và GraphQL Engine.   |
| 3. Tích hợp giải pháp bảo mật, xác thực người dùng tập trung qua Clerk.     |
| 4. Tự động hóa kết xuất hóa đơn và gửi email thông báo chi phí hàng tháng.  |
+-----------------------------------------------------------------------------+

Giải pháp lựa chọn nền tảng web hiện đại với sự kết hợp của ReactJS, Vite, Tailwind CSS ở phía Client, kết nối trực tiếp với PostgreSQL thông qua Hasura GraphQL Engine và Node.js. Lựa chọn này giúp cắt giảm 70% thời gian xây dựng boilerplate backend CRUD, tối ưu hóa băng thông truyền tải dữ liệu và đảm bảo thời gian phản hồi API dưới 150ms.

Phạm vi và giới hạn: Dự án tập trung chuyên sâu vào phân hệ tài chính (quản lý người dùng, phân quyền, cấu hình đơn giá điện nước theo mốc thời gian, chốt chỉ số công tơ, tính toán hóa đơn tự động và gửi email thông báo). Giai đoạn 1 chưa tích hợp cổng thanh toán trực tuyến tự động qua cổng trung gian (Payment Gateway) mà thực hiện đối soát thu chi qua xác nhận chuyển khoản và tiền mặt.

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

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

Khảo sát thực tế tại Khu Khách sạn sinh viên Trường Đại học Quản lý và Công nghệ Hải Phòng cho thấy sự đối lập rõ rệt giữa phương thức quản lý truyền thống và phần mềm chuyên biệt:

Tiêu chí so sánh Quản lý sổ sách / Excel rời rạc Phần mềm Quản lý Tài chính (Đề tài)
Tính chính xác dữ liệu Dễ sai sót khi nhập công tơ, trùng lặp số liệu Ràng buộc toàn vẹn cơ sở dữ liệu, kiểm tra hợp lệ đầu vào
Tốc độ chốt hóa đơn 2 - 3 ngày làm việc cho 100 phòng < 5 phút với thao tác tính toán tự động hàng loạt
Tính minh bạch Sinh viên khó tra cứu chi tiết số điện/nước cũ - mới Hóa đơn điện tử chi tiết chỉ số cũ, mới, đơn giá áp dụng
Phân quyền & Bảo mật File Excel không phân quyền chi tiết, dễ mất mát Xác thực Clerk OAuth/JWT, phân quyền RBAC phân tầng
Thông báo công nợ Dán bảng tin giấy hoặc nhắn tin qua mạng xã hội Gửi Email tự động hóa đơn trực tiếp tới từng sinh viên

Dự án áp dụng mô hình phân loại yêu cầu MoSCoW:

  • Must have: Xác thực phân quyền Admin/Manager; Cấu hình đơn giá điện/nước theo thời gian hiệu lực; Nhập và chỉnh sửa chỉ số công tơ tháng; Tính toán hóa đơn tự động; Gửi email thông báo chi tiết.
  • Should have: Tìm kiếm và lọc hóa đơn theo phòng/khu vực/thời gian; Báo cáo doanh thu tổng hợp.
  • Could have: Biểu đồ trực quan hóa mức tiêu thụ năng lượng giữa các tháng.
  • Won't have (v1): Tích hợp Webhook kết nối trực tiếp biến động số dư ngân hàng qua Open Banking API.

Thiết kế hệ thống

Kiến trúc phần mềm được thiết kế theo mô hình 3 lớp phân tán (Decoupled Client-Server Architecture) nhằm đạt hiệu năng cao và khả năng mở rộng linh hoạt:

[ Client Layer: ReactJS 18 + Vite + Tailwind CSS ]
[ Service Layer: Hasura GraphQL Engine v2.35 + Node.js Webhook Services ]
[ Data Layer: PostgreSQL 16 ]            [ Auth Service: Clerk Auth Provider ]

Technology Stack chuẩn hóa:

  • Frontend: ReactJS 18.x, Vite 5.x, Tailwind CSS 3.4.x, Lucide Icons, Axios / Apollo Client.
  • Backend & Middleware: Hasura GraphQL Engine v2.35.x, Node.js 20.x LTS (xử lý logic nghiệp vụ tùy biến và gửi Email qua Nodemailer/SendGrid API).
  • Cơ sở dữ liệu: PostgreSQL 16.x, công cụ quản trị Database4 GUI.
  • Xác thực & Ủy quyền: Clerk Authentication SDK (đồng bộ User ID và gắn Custom Claims vào JWT).
  • Hạ tầng triển khai: Vercel Edge Platform (Frontend & Serverless Functions), Managed Cloud Database.
-- Trích xuất cấu trúc bảng dữ liệu cốt lõi trong hệ thống
CREATE TABLE don_gia_dien (
    id SERIAL PRIMARY KEY,
    don_gia NUMERIC(10, 2) NOT NULL,
    ngay_bat_dau DATE NOT NULL,
    ngay_ket_thuc DATE,
    trang_thai BOOLEAN DEFAULT true,
    created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP
);

CREATE TABLE chi_so_dien_nuoc (
    id SERIAL PRIMARY KEY,
    id_phong INT REFERENCES phong(id) ON DELETE CASCADE,
    thang INT NOT NULL,
    nam INT NOT NULL,
    chi_so_dien_cu INT NOT NULL,
    chi_so_dien_moi INT NOT NULL,
    chi_so_nuoc_cu INT NOT NULL,
    chi_so_nuoc_moi INT NOT NULL,
    CONSTRAINT check_dien CHECK (chi_so_dien_moi >= chi_so_dien_cu),
    CONSTRAINT check_nuoc CHECK (chi_so_nuoc_moi >= chi_so_nuoc_cu)
);

CREATE TABLE hoa_don_thang (
    id SERIAL PRIMARY KEY,
    id_phong INT REFERENCES phong(id),
    id_chi_so INT REFERENCES chi_so_dien_nuoc(id),
    id_don_gia_dien INT REFERENCES don_gia_dien(id),
    id_don_gia_nuoc INT REFERENCES don_gia_nuoc(id),
    tien_phong NUMERIC(12, 2) NOT NULL,
    tien_dien NUMERIC(12, 2) NOT NULL,
    tien_nuoc NUMERIC(12, 2) NOT NULL,
    tong_tien NUMERIC(12, 2) NOT NULL,
    trang_thai_thanh_toan BOOLEAN DEFAULT false,
    da_gui_email BOOLEAN DEFAULT false
);

Methodology

Dự án triển khai theo quy trình Agile Scrum rút gọn với chu kỳ 4 Sprint (mỗi Sprint 2 tuần):

  1. Sprint 1: Khảo sát nghiệp vụ ký túc xá, thiết kế sơ đồ Use Case, ERD và khởi tạo Database PostgreSQL.
  2. Sprint 2: Thiết lập Hasura GraphQL Engine, cấu hình quan hệ bảng (Relationships) và phân quyền Role-Based Access Control (RBAC).
  3. Sprint 3: Xây dựng giao diện ReactJS với Vite, tích hợp xác thực Clerk, màn hình quản lý đơn giá và nhập chỉ số.
  4. Sprint 4: Phát triển module tính toán hóa đơn, tích hợp dịch vụ gửi Email thông báo tự động, viết Unit/Integration Tests và đóng gói triển khai lên Vercel.

Implementation và kết quả

Development process

Quá trình xây dựng hệ thống tập trung vào việc chuẩn hóa luồng dữ liệu GraphQL và xử lý tính toán chính xác số liệu tài chính trước khi xuất hóa đơn.

// Trích đoạn logic xử lý tính toán hóa đơn và gửi dữ liệu qua Hasura GraphQL Client
import { gql } from '@apollo/client';

export const CALCULATE_AND_GENERATE_INVOICE = async (apolloClient, invoicePayload) => {
  const { idPhong, thang, nam, chiSoDienCu, chiSoDienMoi, chiSoNuocCu, chiSoNuocMoi, donGiaDien, donGiaNuoc, giaPhong } = invoicePayload;

  const soDienTieuThu = chiSoDienMoi - chiSoDienCu;
  const soNuocTieuThu = chiSoNuocMoi - chiSoNuocCu;

  const tongTienDien = soDienTieuThu * donGiaDien;
  const tongTienNuoc = soNuocTieuThu * donGiaNuoc;
  const tongThanhToan = giaPhong + tongTienDien + tongTienNuoc;

  const MUTATION_INSERT_INVOICE = gql`
    mutation InsertMonthlyInvoice($object: hoa_don_thang_insert_input!) {
      insert_hoa_don_thang_one(object: $object) {
        id
        tong_tien
        trang_thai_thanh_toan
      }
    }
  `;

  return await apolloClient.mutate({
    mutation: MUTATION_INSERT_INVOICE,
    variables: {
      object: {
        id_phong: idPhong,
        tien_phong: giaPhong,
        tien_dien: tongTienDien,
        tien_nuoc: tongTienNuoc,
        tong_tien: tongThanhToan,
        trang_thai_thanh_toan: false
      }
    }
  });
};

Testing và validation

Quá trình kiểm thử được thực hiện qua 3 cấp độ:

  • Unit Testing: Kiểm tra tính toàn vẹn của logic tính toán tiền phòng, tiền điện, tiền nước với 45 test cases bao gồm các trường hợp biên (chỉ số bằng 0, chỉ số mới bằng chỉ số cũ, số âm bị chặn bởi DB Constraints).
  • Integration Testing: Kiểm tra luồng tương tác giữa Clerk Authentication $\rightarrow$ Hasura Claims Header $\rightarrow$ PostgreSQL Query Execution.
  • Performance Benchmarks:
    • Thời gian build hệ thống với Vite: 2.14 giây.
    • Tốc độ tải trang đầu tiên (FCP): 0.8 giây.
    • Thời gian phản hồi trung bình API GraphQL: 85ms trên mạng băng thông tiêu chuẩn.
    • Điểm hiệu năng Google Lighthouse: 94/100 Performance, 100/100 Best Practices.

Kết quả đạt được

Hệ thống đã hoàn thành 100% các tính năng đề ra theo đề cương nghiên cứu:

Hạng mục chức năng Trạng thái Đánh giá kỹ thuật
Xác thực & Phân quyền Hoàn thành Tích hợp Clerk, phân định rõ ràng quyền Admin và Manager
Quản lý đơn giá điện/nước Hoàn thành Lưu vết lịch sử đơn giá theo ngày hiệu lực, không làm sai lệch hóa đơn cũ
Nhập & Sửa chỉ số tháng Hoàn thành Giao diện bảng tính trực quan, tự động tải chỉ số cũ của tháng liền kề
Tính toán hóa đơn tự động Hoàn thành Xử lý hàng loạt toàn bộ phòng trong khu lưu trú trong < 3 giây
Gửi Email thông báo Hoàn thành Mẫu email HTML chuyên nghiệp, hiển thị chi tiết chỉ số và tổng tiền

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

Điểm đổi mới công nghệ

  1. Kiến trúc Modern GraphQL-as-a-Service: Thay vì xây dựng REST API truyền thống tiêu tốn thời gian viết mã định tuyến và ORM, dự án ứng dụng Hasura GraphQL Engine gắn kết trực tiếp với PostgreSQL. Giải pháp này giúp loại bỏ hoàn toàn các lỗi Over-fetching / Under-fetching dữ liệu ở giao diện người dùng.
  2. Quản lý phiên phi tập trung với Clerk: Tận dụng JWT Claims để truyền dữ liệu định danh trực tiếp tới Hasura qua Request Headers (x-hasura-user-id, x-hasura-role), đảm bảo tính bảo mật cấp doanh nghiệp mà không cần lưu trữ mật khẩu nhạy cảm trên máy chủ ứng dụng.
  3. Cơ chế lưu vết đơn giá theo thời gian (Historical Rate Tracking): Đơn giá điện nước được lưu độc lập với khóa ngoại gắn vào hóa đơn tại thời điểm tạo, đảm bảo khi giá điện/nước nhà nước điều chỉnh, các hóa đơn quá khứ không bị tính toán sai lệch hồi tố.
                    SO SÁNH CÁC GIẢI PHÁP HIỆN HÀNH

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

Kịch bản vận hành thực tế

Hệ thống được thiết kế để phục vụ trực tiếp cho mô hình quản trị tại Khách sạn sinh viên HPU với quy mô 120 phòng và hơn 500 sinh viên lưu trú:

  • Ngày 28-30 hàng tháng: Cán bộ quản lý dùng máy tính bảng hoặc laptop truy cập module "Nhập chỉ số điện nước" để cập nhật số liệu công tơ của từng tầng.
  • Ngày 01 hàng tháng: Hệ thống tự động kích hoạt tiến trình tính toán và xuất bản hóa đơn của toàn bộ các phòng đang có hợp đồng thuê hiệu lực.
  • Sau khi kiểm tra: Người quản trị bấm nút "Gửi thông báo", hệ thống sẽ kích hoạt hàng đợi gửi email hóa đơn điện tử đến hộp thư cá nhân của tất cả sinh viên.

Phân tích hiệu quả kinh tế (ROI)

  • Tiết kiệm thời gian: Giảm từ 24 giờ lao động/tháng xuống còn 1.5 giờ/tháng cho công tác tính toán và phát thông báo cước phí (giảm 93.7% thời gian).
  • Tiết kiệm chi phí văn phòng phẩm: Loại bỏ 100% chi phí in ấn giấy báo tiền phòng hàng tháng, tương đương tiết kiệm hàng triệu đồng mỗi năm học.
  • Hạn chế thất thoát: Triệt tiêu hoàn toàn các sai số tính toán tiền điện lũy tiến và nhầm lẫn đối soát công nợ.

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

Hạn chế kỹ thuật hiện tại

  • Hệ thống phụ thuộc vào kết nối Internet liên tục để tương tác với Cloud Database và Clerk Auth Provider.
  • Chưa trang bị cơ chế Webhook nhận phản hồi trạng thái email (Bounce/Delivered) theo thời gian thực.
  • Việc ghi nhận thanh toán vẫn cần cán bộ quản lý bấm xác nhận thủ công trên giao diện khi nhận tiền mặt hoặc sao kê ngân hàng.

Hướng phát triển trong tương lai

  • Tích hợp VietQR động: Tự động tạo mã QR thanh toán ngân hàng có chứa nội dung chuyển khoản và số tiền chính xác cho từng hóa đơn phòng.
  • Kết nối IoT Smart Meter: Ứng dụng công tơ điện nước thông minh có kết nối WiFi/Zigbee để tự động đồng bộ chỉ số về máy chủ PostgreSQL mà không cần ghi số thủ công.
  • Phát triển Mobile App: Xây dựng ứng dụng di động cho sinh viên bằng React Native để tra cứu lịch sử sử dụng điện nước và nhận thông báo đẩy (Push Notifications).

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

  • Sinh viên lưu trú: Minh bạch hóa các khoản chi phí sinh hoạt hàng tháng, nhận hóa đơn chi tiết qua email kịp thời, loại bỏ tranh chấp về chỉ số công tơ.
  • Đội ngũ quản lý ký túc xá: Giảm thiểu áp lực nhập liệu và tính toán thủ công, kiểm soát chặt chẽ công nợ và tình trạng thanh toán của từng phòng.
  • Ban Giám hiệu nhà trường: Nâng cao hình ảnh chuyên nghiệp, hiện đại của khu khách sạn sinh viên, thúc đẩy chiến lược chuyển đổi số quản trị đại học.
  • Sinh viên ngành CNTT & Lập trình viên: Đề tài là tài liệu tham khảo thực tế về việc áp dụng kiến trúc GraphQL (Hasura) kết hợp ReactJS và Clerk trong phát triển ứng dụng quản lý doanh nghiệp.

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

1. Yêu cầu cấu hình phần cứng và môi trường để triển khai hệ thống là gì?

Hệ thống được xây dựng theo kiến trúc Cloud-native, do đó môi trường vận hành không yêu cầu máy chủ cục bộ đắt tiền. Yêu cầu gồm có:

  • Client: Mọi thiết bị có trình duyệt web hiện đại (Chrome, Edge, Safari, Firefox) trên PC, Tablet hoặc Smartphone.
  • Hosting & Database: Node.js runtime $\ge$ v18.x, PostgreSQL $\ge$ 14.x, Hasura GraphQL Engine instance kết nối qua cổng tiêu chuẩn, tài khoản dịch vụ Clerk Auth và nền tảng Vercel để triển khai Frontend.

2. Hệ thống có khả năng mở rộng (Scalability) phục vụ nhiều cơ sở ký túc xá cùng lúc không?

Hoàn toàn có thể. Do sử dụng Hasura GraphQL Engine biên dịch các truy vấn GraphQL thành câu lệnh SQL thuần thực thi trực tiếp trên PostgreSQL, hệ thống có thể xử lý hàng nghìn kết nối đồng thời với mức tiêu thụ tài nguyên máy chủ rất thấp. Cấu trúc CSDL đã hỗ trợ bảng danh mục khu_vuc cho phép mở rộng quản lý đa tòa nhà, đa chi nhánh.

3. Có thể tích hợp hệ thống vào cổng thông tin đào tạo sẵn có của nhà trường không?

Được. Thông qua cơ chế REST Endpoints hoặc GraphQL API của Hasura kết hợp với Clerk SSO (Single Sign-On), hệ thống có thể dễ dàng đồng bộ dữ liệu sinh viên từ hệ thống quản lý đào tạo (SIS/ERP) của trường đại học vào bảng nguoi_thue và hop_dong_thue.

4. Chi phí duy trì hệ thống hàng tháng là bao nhiêu?

Với quy mô một trường đại học quy mô vừa và nhỏ (dưới 1,000 phòng lưu trú), hệ thống hoàn toàn có thể vận hành ổn định trong giới hạn gói miễn phí (Free-tier) của Vercel, Supabase/Neon PostgreSQL và Clerk, giúp chi phí bản quyền và duy trì hạ tầng tiệm cận mức 0 VNĐ/tháng.

5. Trường hợp chỉ số công tơ bị nhập sai thì quy trình xử lý điều chỉnh hóa đơn như thế nào?

Hệ thống cung cấp Use Case "Sửa chỉ số điện, nước tháng". Người quản lý có thẩm quyền có thể chỉnh sửa lại chỉ số đúng; hệ thống sẽ tự động kích hoạt tính toán lại hoa_don_thang tương ứng và cập nhật trạng thái trước khi gửi lại email đính chính cho người thuê phòng.

Kết luận

Đồ án tốt nghiệp "Xây dựng ứng dụng nền tảng web quản lý tài chính khu khách sạn sinh viên" của sinh viên Đào Anh Ngọc đã giải quyết trọn vẹn và hiệu quả bài toán quản trị tài chính lưu trú tại Trường Đại học Quản lý và Công nghệ Hải Phòng. Bằng việc kết hợp sáng tạo các công nghệ web tiên tiến như ReactJS, Vite, Tailwind CSS, PostgreSQL, Hasura GraphQL và Clerk, hệ thống không chỉ chứng minh tính khả thi cao về mặt kỹ thuật mà còn mang lại giá trị kinh tế - xã hội rõ rệt trong việc tối ưu hóa năng suất vận hành và minh bạch hóa dòng tiền. Đây là tiền đề vững chắc để tiếp tục mở rộng tích hợp thanh toán số và công nghệ đo đếm thông minh trong các giai đoạn phát triển tiếp theo.