№ 50
Trợ lý AI cho resort: khách quét QR phòng để hỏi đáp đa ngôn ngữ và đặt dịch vụ tức thì, hệ thống tự tạo yêu cầu và chuyển nhân viên xử lý realtime.
Trợ lý ảo (AI Concierge) đa kênh cho khu nghỉ dưỡng: khách hỏi đáp & đặt dịch vụ bằng ngôn ngữ tự nhiên, nhân viên xử lý yêu cầu realtime, quản trị vận hành tri thức + phân quyền. Repo
C2-App-011, sub-project cohort C2-App-011.
Khu nghỉ dưỡng phục vụ khách quốc tế (Việt/Anh/Nhật/Hàn) với nhiều phòng ban (lễ tân, nhà hàng, spa, buồng phòng…). Quy trình truyền thống bộc lộ nhiều điểm nghẽn:
Xây dựng một AI Concierge giúp:
Monorepo Nx (pnpm) gồm 4 service chính + ứng dụng phụ, ranh giới service nghiêm ngặt:
┌──────────────────────────────┐
Khách (QR) → │ web (Next.js) / mini-app(Zalo)│
Nhân viên → │ Guest · Staff · Admin UI │
└───────┬───────────────┬────────┘
│ auth │ nghiệp vụ
▼ ▼
┌──────────────┐ ┌──────────────────────┐
│ iam (NestJS)│ │ api (NestJS / BFF) │
│ TypeORM │◄─┤ Prisma · Socket.IO │
│ Auth/RBAC │RPC│ Ops · Concierge │
└──────┬───────┘ └─────────┬────────────┘
│ RabbitMQ │ HTTP (internal)
│ ▼
┌──────┴──────┐ ┌──────────────────┐
│ Redis │ │ rag (FastAPI/py) │
│ Postgres │ │ LangGraph · Qdrant│
│ MinIO/S3 │ │ LLM · embeddings │
└─────────────┘ └──────────────────┘
Nguyên tắc ranh giới (bất biến):
@org/iam (auth) và @org/api (mọi nghiệp vụ).@org/rag không public — luồng luôn là FE → API → RAG (proxy qua RagClientService). Không có NEXT_PUBLIC_RAG_*.GET /api/files/:id (stream + Range).| Service | Stack | Vai trò |
|---|---|---|
| web | Next.js 16 · React 19 · Tailwind · Radix · Socket.IO client | UI 3 vùng: Guest portal/chat/requests, Staff dashboard/conversations/KB/analytics, Admin users/roles/audit/rooms |
| api | NestJS 11 · Prisma 7 (Postgres ai191) · Socket.IO · Swagger | BFF + nghiệp vụ: Concierge chat, Service Request, KB, Rooms hierarchy, Files/Storage, Analytics, Audit, Realtime gateway, RAG proxy |
| iam | NestJS 11 · TypeORM (Postgres ai191_iam) · Redis · RabbitMQ | Identity & Access: đăng ký/đăng nhập, OAuth (Google/Microsoft), session cookie + Redis, RBAC MODULE::ACTION, quên/đổi mật khẩu, email |
| rag | FastAPI · LangChain/LangGraph · Qdrant · sentence-transformers · BM25 | Hỏi đáp RAG, agent loop function-calling, ingest tài liệu, phát hiện ngôn ngữ, tool-use nghiệp vụ concierge |
| apps/mini-app | Zalo Mini App | Kênh khách trên Zalo (xác thực Bearer thay vì cookie) |
Building → Floor → Room (audit chuẩn; Room.code unique toàn cục, dùng cho QR ?room=A-12-05).Conversation ↔ Message (role USER/ASSISTANT/STAFF), gắn roomId, hỗ trợ isHandedOver (tiếp quản), resetAt/resetByEmail (reset khi khách mới check-in).ServiceRequest ↔ ServiceRequestStatusLog; gắn Department, roomId, conversationId; state machine NEW → ASSIGNED → IN_PROGRESS → DONE; code compact SR-XXXXX.KnowledgeDocument ↔ KnowledgeChunk; soft-delete + reindex.Department, AuditLog, File, cấu hình SLA/service-type/kb-topic.Hai database trên một Postgres (
localhost:5500):ai191(Prisma/API) vàai191_iam(TypeORM/IAM).
Khách hỏi đáp + đặt dịch vụ (login optional)
GuestSessionGuard resolve room qua /ops/rooms/by-code/:code, lưu {roomId, roomCode, roomLabel}. Thiếu room → /guest/welcome nhập mã thủ công.POST /concierge/conversations/:id/messages; ConciergeService get-or-create 1 hội thoại active/phòng.ServiceRequest, định tuyến phòng ban, broadcast realtime./guest/requests (realtime Socket.IO).attach-on-login backfill email vào SR/Conversation của phòng (idempotent) → đồng bộ lịch sử qua thiết bị.Nhân viên xử lý
/staff hàng đợi realtime (filter dept/status/priority), nhận/xem chi tiết, đổi trạng thái thật, ghi chú nội bộ./staff/conversations tiếp quản hội thoại (takeover persist), trả lời trực tiếp khách.Quản trị
/admin/users + /admin/roles (ma trận quyền IAM thật), /admin/audit-log (CSV), /admin/rooms|floors|buildings (CRUD + reset chat per room), /staff/kb (upload binary qua /files, AI-suggest metadata, reindex), /staff/analytics (KPI + chart từ /ops/analytics)./ws/stream; sự kiện service-request:*, conversation:message/takeover, room:reset.vbim_session_id (Redis); PermissionGuard verify quyền qua RabbitMQ tới IAM (module::action, module::*, *::*). Route khách walk-up (concierge, guest-requests, file stream) cố ý không guard, dùng room-PIN.SessionActorInterceptor ghi đè actor/owner bằng email phiên đăng nhập trên route có @Permissions..env ở root; Makefile + Nx targets.guest_preference + lịch sử để gợi ý dịch vụ chủ động.