Tài liệu Hệ thống Vkeeper Agent: Trợ lý Quản lý Ra Vào Chung cư Thông minh

1. Bài toán Thực tế Trong các khu chung cư hiện đại, cư dân thường xuyên có nhu cầu cấp quyền ra vào (pass) cho khách như bạn bè, người giao hàng (shipper), hay thợ sửa chữa một cách nhanh chóng và an toàn. Tuy nhiên, quy trình truyền thống hiện nay gặp nhiều bất cập: gọi điện xác minh với bảo vệ, ghi chép sổ tay thủ công, hoặc bắt buộc cư dân đăng ký qua các biểu mẫu (app form) phức tạp trên ứng dụng. Những phương thức này vừa tốn thời gian, dễ gây sai sót, lại làm giảm trải nghiệm sống của cư dân. Mục tiêu của Vkeeper Agent: Hệ thống ra đời nhằm cung cấp một giải pháp tự động hóa thông minh. Thông qua chatbot AI sử dụng ngôn ngữ tự nhiên tiếng Việt, cư dân có thể dễ dàng tạo, quản lý và thu hồi pass ra vào. Lực lượng bảo vệ tại cổng có thể nhanh chóng xác minh khách bằng mã QR hoặc OTP. Đồng thời, hệ thống tự động gửi thông báo chi tiết đến khách ngay khi yêu cầu được phê duyệt. Các nhóm đối tượng sử dụng: Cư dân: Trực tiếp tương tác với trợ lý ảo bằng hội thoại tiếng Việt tự nhiên để tạo mới, điều chỉnh, gia hạn hoặc thu hồi pass. Nhân viên bảo vệ: Sử dụng công cụ quét mã QR hoặc nhập mã OTP trên hệ thống để xác thực khách ra vào tại cổng chung cư. Quản trị viên (Admin): Quản lý danh sách tài khoản cư dân, giám sát và xem các số liệu thống kê lượt ra vào. Tự động gửi thông báo cho khách: Nhận mã OTP và QR code ra vào thông qua Email.

2. Giải pháp Kỹ thuật (Tổng quan Kiến trúc Hệ thống) Hệ thống Vkeeper Agent được thiết kế dựa trên kiến trúc hiện đại, phân rã thành các dịch vụ độc lập hoạt động mượt mà với nhau nhằm đảm bảo tính ổn định, linh hoạt và bảo mật cao. 2.1. Giao diện Người dùng (Frontend - Next.js) Giao diện trực quan được xây dựng trên các công nghệ tiên tiến (Next.js, React, Tailwind CSS), hỗ trợ cả chế độ sáng/tối (dark/light mode) mang lại trải nghiệm tối ưu: Giao diện chat với Trợ lý AI: Hỗ trợ truyền tải tin nhắn phản hồi dạng luồng (streaming SSE) giúp cư dân trò chuyện mượt mà như đang chat với người thật. Quản lý Pass dễ dàng: Hiển thị trực quan mã QR và mã OTP khi pass được khởi tạo thành công; cho phép cư dân xem danh sách, gia hạn thời gian hoặc thu hồi pass ngay tức thì. Công cụ cho bảo vệ: Tích hợp tính năng quét mã QR ngay trên giao diện để bảo vệ quét mã của khách tại cổng kiểm soát. Trang quản trị (Admin Dashboard): Giúp ban quản lý chung cư dễ dàng kiểm soát tài khoản và theo dõi thống kê số liệu. 2.2. Cổng Kết nối Trung tâm (Backend Gateway - FastAPI) Đóng vai trò là bộ não điều phối toàn bộ luồng dữ liệu của hệ thống, xử lý các tác vụ cốt lõi: Xác thực và phân quyền: Cấp phát và xác minh mã khóa bảo mật (JWT) để bảo vệ thông tin cư dân, đảm bảo mọi yêu cầu gửi lên hệ thống đều hợp lệ. Điều phối tin nhắn: Chuyển tiếp (proxy) nội dung chat của cư dân tới dịch vụ AI Agent và lưu trữ lịch sử cuộc hội thoại vào cơ sở dữ liệu. Xác minh lượt ra vào: Tiếp nhận thông tin từ nhân viên bảo vệ để kiểm tra mã QR/OTP có khớp với dữ liệu gốc hay không, sau đó ghi lại nhật ký ra vào chi tiết. 2.3. Dịch vụ Trợ lý AI (AI Agent Service - FastAPI & LangGraph) Trái tim thông minh của hệ thống, vận hành bằng mô hình ngôn ngữ lớn tiên tiến (GPT-4o qua OpenRouter) kết hợp với khung xử lý LangGraph để thực hiện các cuộc hội thoại thông minh và tự động ra quyết định: Tự động xử lý công việc qua hội thoại: AI Agent có thể hiểu ý định của cư dân bằng tiếng Việt để thực hiện các thao tác như: kiểm tra căn hộ, liệt kê các pass đang hoạt động, tạo pass mới, cập nhật thông tin (gia hạn/đổi lượt), thu hồi pass an toàn qua 2 bước xác nhận, và kích hoạt thông báo gửi cho khách. Tra cứu tài liệu thông minh (RAG): Hệ thống tích hợp kho dữ liệu bao gồm luật nhà ở, nội quy và biểu phí của chung cư. Khi cư dân hỏi về quy định, AI Agent sẽ tự động tìm kiếm kết hợp giữa từ khóa truyền thống và không gian vector để trả lời chính xác thông tin. Cơ chế giám sát an toàn: Hệ thống kiểm soát chặt chẽ quyền hạn của AI Agent để tránh lỗi, giới hạn số lần gọi công cụ trong một phiên chat, đồng thời ẩn đi các thông tin nhạy cảm (như OTP hay token QR) khỏi nội dung chat nhằm bảo vệ quyền riêng tư. 2.4. Tự động hóa Thông báo (n8n Workflow Automation) Hệ thống tích hợp công cụ tự động hóa quy trình n8n để đảm bảo việc truyền tải thông tin đến khách diễn ra tức thời: Khi AI Agent hoàn tất việc tạo pass, nó sẽ kích hoạt một lệnh gọi (webhook) tới n8n. Hệ thống n8n tự động biên dịch thông tin (tên khách, căn hộ đăng ký, thời gian hiệu lực, số lượt ra vào), tạo định dạng đẹp mắt và gửi trực tiếp kèm hình ảnh mã QR đến địa chỉ Email của khách hàng. 2.5. Cơ chế Bảo mật Đa lớp Để đảm bảo an toàn tuyệt đối cho một hệ thống quản lý an ninh chung cư, Vkeeper Agent áp dụng các tiêu chuẩn bảo mật khắt khe: Mã hóa truyền tải: Toàn bộ dữ liệu truyền đi giữa các dịch vụ và người dùng đều được mã hóa qua giao thức HTTPS an toàn. Bảo mật thông tin Pass: Mã QR và OTP được lưu dưới dạng mã hóa một chiều (SHA-256) trong cơ sở dữ liệu và chỉ được giải mã an toàn bằng thuật toán Fernet khi cần hiển thị lại cho cư dân, ngăn chặn nguy cơ bị đánh cắp dữ liệu. Cô lập dữ liệu tuyệt đối: Mọi truy vấn thông tin đều được ràng buộc chặt chẽ theo mã định danh của từng cư dân lấy từ mã khóa xác thực, đảm bảo cư dân này không thể xem hoặc sửa đổi thông tin của cư dân khác. An toàn 2 bước: Các hành động nhạy cảm như thu hồi pass bắt buộc phải trải qua 2 bước xác nhận (yêu cầu -> xác nhận thực thi) để tránh thao tác nhầm lẫn.