1.4 Bốn nguyên tắc trải nghiệm chi phối thiết kế

Khi các quyết định thiết kế mâu thuẫn nhau, thứ tự ưu tiên sau quyết định lựa chọn nào thắng:

1. Thà nói không biết còn hơn hướng dẫn sai — thủ tục hành chính sai khiến cư dân phải đi lại lần hai; trợ lý phải từ chối khi không có căn cứ, và cơ chế từ chối nằm trong code, không phải chỉ dặn dò trong prompt.
2. Minh bạch nguồn, kể cả khi nguồn là dữ liệu mô phỏng — mỗi câu trả lời hiện nhãn phân loại nguồn; dữ liệu nhóm tự dựng cho demo mang nhãn "Quy trình mô phỏng (dữ liệu demo)", không giấu.
3. Gỡ sự mơ hồ trước, tạo động lực sau — người dùng ngại làm thủ tục vì thiếu thông tin (mang gì, mất bao lâu, đi đâu), không phải vì thiếu động lực; phần thưởng/gamification đứng sau, không thay thế ba câu trả lời cốt lõi này.
4. Không hứa thay mặt Ban quản lý — phần thưởng chỉ là thứ sản phẩm tự trao được (huy hiệu, cột mốc); không hứa ưu đãi tiền, vì đó là quyền của BQL.

2. Giải pháp kỹ thuật

2.1 Kiến trúc tổng quan

MoveInMate là một web app dạng PWA (Progressive Web App), gồm ba tầng triển khai độc lập:

graph TB
    subgraph Vercel
        UI["Next.js 16 PWA — giao diện cư dân & BQL"]
    end
    subgraph Railway
        API["FastAPI — 23 endpoint REST"]
        SVC["Services: rule engine checklist · vectorstore · ingest"]
        AGENT["LangGraph Agent — chat_graph"]
        CHROMA[("ChromaDB — chạy in-process")]
    end
    subgraph "Dịch vụ quản lý"
        SUPA[("Supabase — Postgres + Auth")]
        OPENAI["OpenAI gpt-4o-mini + Google gemini-embedding-001"]
    end
    VOL["Railway Volume — persist vector store"]

    UI -->|"HTTPS + JWT"| API
    UI -->|"đăng nhập"| SUPA
    API --> SVC
    API --> AGENT
    SVC --> CHROMA
    SVC --> SUPA
    AGENT --> SVC
    AGENT --> OPENAI
    CHROMA -.->|"persist"| VOL

Quyết định kiến trúc trung tâm: hai năng lực cốt lõi được xử lý bằng hai cơ chế khác nhau, có chủ đích:

• Checklist cá nhân hoá → rule engine tất định, không dùng LLM.
• Hỏi đáp thủ tục → LangGraph agent kết hợp RAG (Retrieval-Augmented Generation).

Lý do tách bạch: phân loại cư dân theo hồ sơ (chủ hộ/người thuê, có xe, gói tiện ích) là bài toán trên tập thuộc tính hữu hạn, thu qua form có cấu trúc — dùng LLM ở đây vừa tốn kém vừa kém tin cậy hơn một quy tắc so khớp đơn giản. Ngược lại, trả lời câu hỏi tự do bằng ngôn ngữ tự nhiên là bài toán thực sự cần mô hình ngôn ngữ.

2.2 Rule engine — checklist cá nhân hoá

Nằm ở tầng service thuần (src/services/checklist.py), không phụ thuộc DB hay LangGraph, không phải một node trong graph (tránh việc bọc một hàm thuần thành node LangGraph một cách thừa thãi):

def matches(profile: dict, conditions: dict) -> bool:
    """Item hiển thị nếu MỌI cặp key:value trong conditions khớp profile.
    conditions rỗng ({}) → luôn khớp."""

def generate_checklist(profile: dict, items: list) -> list:
    """Lọc danh sách item theo profile cư dân."""

• So khớp kiểu AND, exact-match trên trường conditions (JSONB). Với thuộc tính multi-select (amenity_packages), một giá trị đơn được hiểu là "nằm trong danh sách đã chọn".
• Không hỗ trợ OR hay so sánh khoảng — đây là giới hạn được chấp nhận có ý thức; khi phát sinh nhu cầu OR thì thêm dòng dữ liệu thay vì làm engine phức tạp hơn.
• Lọc trực tiếp tại thời điểm truy vấn, không chốt cứng checklist lúc onboarding. Mỗi lần gọi GET /checklist, hệ thống lọc lại CHECKLIST_ITEMS theo hồ sơ hiện tại rồi join với bảng chỉ lưu các mục đã hoàn thành. Cách này mang lại ba lợi ích: BQL cập nhật thủ tục thì cư dân cũ thấy ngay lập tức; cư dân sửa hồ sơ (ví dụ mua xe sau khi dọn vào) thì checklist tự cập nhật mà không cần logic gộp dễ sai; và không phát sinh câu hỏi khó "mục đã tick nhưng không còn khớp điều kiện thì xử lý sao".
• Mỗi mục checklist còn mang nhãn item_type (bql_actionable hoặc third_party_info) quyết định cách hiển thị, có cho phép nộp hồ sơ online hay không, và nguồn trích dẫn — đây là cơ chế hiện thực hoá ràng buộc "không mạo nhận quy trình bên thứ ba là của BQL" nêu ở mục 1.3.

2.3 AI Agent — LangGraph + RAG cho hỏi đáp thủ tục

Toàn hệ thống chỉ có một graph (chat_graph), với luồng thực tế đang chạy:

graph LR
    S0(["START"]) --> RW["rewrite_query"]
    RW --> R1["rag_retrieve"]
    R1 --> G1["generate"]
    G1 --> E1(["END"])

Hai bảo đảm kỹ thuật là xương sống của giải pháp:

1. sources[] là output tất định của bước truy xuất, không phải do LLM tự liệt kê. Yêu cầu "trả lời có trích nguồn" của đề bài vì vậy là một bảo đảm ở tầng code, không phụ thuộc việc LLM có tuân thủ prompt hay không — đây là điểm mà phần lớn hệ thống RAG khác thất bại (LLM tự bịa tên tài liệu, sai định dạng trích dẫn).
2. Guard chống bịa thông tin nằm trong code. Khi không tìm được đoạn tài liệu nào vượt ngưỡng liên quan, node generate không gọi LLM mà trả thẳng câu từ chối kèm hướng dẫn liên hệ BQL. Đây không phải một chỉ dẫn "hãy trung thực" trong system prompt — model không có cơ hội bịa vì đường gọi tới nó bị chặn từ trước.

Nhận diện nguồn tài liệu: mỗi đoạn văn bản trong ChromaDB mang metadata source_type với bốn giá trị — bql_internal (tài liệu nội bộ BQL), public_regulation (văn bản pháp quy còn hiệu lực), unofficial_web (trang tham khảo chưa xác minh), và synthetic_demo (quy trình nhóm tự dựng cho mục đích trình diễn, luôn hiển thị nhãn "Quy trình mô phỏng" ở giao diện). Cơ chế này cho phép câu trả lời phân biệt rạch ròi giữa "quy trình chính thức của BQL" và "hướng dẫn tham khảo", đúng ràng buộc bảo mật/chính xác của đề bài.

2.4 Dữ liệu và mô hình lưu trữ

Vector store ChromaDB được lưu bền trên Railway Volume (không phải filesystem tạm thời của container), tránh việc mỗi lần triển khai lại phải nhúng toàn bộ kho tri thức từ đầu — vừa tốn chi phí gọi API vừa mất thời gian.

2.5 Xác thực, phân quyền và bảo mật

Đề bài đặt ràng buộc tường minh "bảo mật giấy tờ & thông tin cá nhân cư dân mới". Các cơ chế sau phục vụ trực tiếp ràng buộc đó:

• Xác thực: Supabase Auth là nguồn xác thực duy nhất, ký token chuẩn ES256 kèm xác minh qua JWKS; hệ thống không tự lưu mật khẩu.
• Phân quyền: mọi route /admin/* kiểm tra vai trò admin ngay phía server, không tin dữ liệu phía client.
• Cách ly dữ liệu cá nhân: mọi truy vấn dữ liệu riêng tư (lịch sử chat, tiến độ checklist, hồ sơ) lọc theo user_id ngay trong câu truy vấn — không lấy toàn bộ rồi lọc ở tầng ứng dụng.
• Không đưa dữ liệu cá nhân vào vector store — đây là quy tắc kiến trúc cứng, vì ChromaDB không có cơ chế phân quyền theo người dùng: bất kỳ ai hỏi đúng câu cũng truy xuất được nội dung đã nhúng.
• Che thông tin cá nhân (PII masking) trước khi ghi vào lịch sử chat — cư dân có thể gõ số CCCD, số điện thoại vào ô chat.
• Giới hạn tần suất (rate limiting) riêng cho các endpoint tốn tiền (gọi LLM, gọi embedding, tải tệp) — chặn việc một client gọi liên tục làm cạn hạn mức API trả phí, trong khi các endpoint chỉ đọc không bị giới hạn.

2.6 Vận hành và độ tin cậy

2.7 Tech stack

3. Tính khả thi

3.1 Đã chạy thật, không phải mô hình trên giấy

Hệ thống đã được triển khai và truy cập công khai — không phải bản mô phỏng cục bộ:

• Ứng dụng: đã deploy trên Vercel, có thể truy cập và thao tác end-to-end.
• API: đã deploy trên Railway với 23 endpoint REST đang hoạt động, phủ đủ các luồng chính: đăng nhập, onboarding, checklist, hỏi đáp, nộp hồ sơ, quản trị BQL.
• Kho tri thức: đã nhúng vector cho gần 400 đoạn tài liệu, đủ để trả lời các câu hỏi thủ tục thực tế thay vì dữ liệu giả lập rỗng.
• Đánh giá chất lượng tự động: bộ 35 câu hỏi chuẩn hoá, kết quả 32/35 (91%) trả lời đúng loại — có bằng chứng đo lường thay vì chỉ khẳng định định tính.

3.2 Cơ chế đảm bảo chất lượng nằm trong code, không phụ thuộc prompt

Đây là luận điểm khả thi quan trọng nhất: hai yêu cầu khó nhất của đề bài — "cá nhân hoá đúng hoàn cảnh" và "trích nguồn, không bịa" — đều được hiện thực bằng cơ chế tất định (rule engine so khớp thuộc tính, và bước truy xuất tách rời khỏi bước sinh văn bản), không phải bằng cách hy vọng LLM tuân thủ hướng dẫn. Điều này khiến hành vi hệ thống dự đoán được và kiểm thử được bằng unit test thông thường, thay vì chỉ có thể đánh giá bằng cách đọc qua nhiều câu trả lời mẫu.

3.3 Rủi ro kỹ thuật đã nhận diện và cách xử lý

Nhóm đã tự rà soát và ghi nhận minh bạch các điểm yếu, thay vì che giấu — đây là một chỉ dấu khả thi vận hành quan trọng vì nó cho thấy nhóm hiểu rõ giới hạn hệ thống của chính mình:

3.4 Giới hạn vận hành đã biết và được chấp nhận có chủ đích

• Hệ thống hiện chạy một instance duy nhất vì vector store nhúng trực tiếp trong tiến trình backend — mở rộng theo chiều ngang (auto-scale) sẽ khiến mỗi bản sao có kho tri thức riêng biệt, không đồng bộ. Đây là đánh đổi được chấp nhận có ý thức ở quy mô một dự án chung cư, không phải một thiếu sót bị bỏ sót.
• Cố tình không đặt trần tổng số request/ngày trên toàn hệ thống — vì một trần như vậy, nếu chạm ngưỡng giữa lúc đang trình diễn hoặc vận hành thật, sẽ khiến trợ lý im lặng với toàn bộ người dùng, tự tạo ra đúng sự cố mà nó được thiết kế để tránh. Rủi ro hạn mức API dùng chung được theo dõi thủ công thay vì chặn cứng bằng code.
• Hội thoại hỗ trợ nhiều lượt (multi-turn) trong phạm vi một cuộc trò chuyện, nhưng cơ chế viết lại câu hỏi mơ hồ chỉ dùng vài lượt gần nhất — không phải bộ nhớ dài hạn xuyên suốt mọi lần đăng nhập.

3.5 Kết luận về tính khả thi

Ba yếu tố cùng chỉ về một hướng: hệ thống không chỉ là ý tưởng khả thi trên lý thuyết mà đã chứng minh được bằng vận hành thật (deploy công khai, có số liệu đo lường), các rủi ro lớn nhất đã được chủ động xử lý thay vì bị bỏ ngỏ, và những giới hạn còn lại đều đã được nhận diện rõ ràng kèm mức độ ưu tiên — không có "điểm mù" chưa được biết đến. Đây là mức độ khả thi phù hợp cho một sản phẩm giai đoạn đầu (MVP) chuẩn bị mở rộng, chưa phải một hệ thống sẵn sàng phục vụ quy mô lớn không giám sát.

4. Hướng phát triển

4.1 Hoàn thiện các hạng mục còn dang dở của Phase 1

4.2 Phase 2 — năng lực nâng cao

4.3 Củng cố nền tảng vận hành trước khi mở rộng quy mô

Đây là các hạng mục không tạo tính năng mới cho người dùng cuối, nhưng là điều kiện cần trước khi hệ thống phục vụ nhiều dự án hoặc nhiều BQL cùng lúc:

• Theo dõi chi tiết vệt xử lý (tracing) từng câu hỏi — hiện đã khai báo trong kiến trúc nhưng chưa bật; chi phí khắc phục thấp, chỉ cần cấu hình biến môi trường.
• Theo dõi chi phí/token theo từng lượt gọi — cần thiết để đặt ngân sách vận hành và phát hiện lượt sử dụng bất thường (ví dụ bị lạm dụng hoặc rơi vào vòng lặp).
• Bắt lỗi tập trung — hiện lỗi hệ thống (mã 500) không được ghi lại có cấu trúc ở đâu ngoài log runtime của nền tảng hạ tầng.
• Hiệu chỉnh lại ngưỡng nhận diện "không có căn cứ trả lời" dựa trên bộ dữ liệu đo lường lớn hơn — đây là điểm yếu kỹ thuật quan trọng nhất còn tồn đọng (mục 3.3).
• Phòng chống prompt injection — rủi ro còn thấp khi hệ thống chỉ đọc dữ liệu, nhưng cần thiết trước khi agent có khả năng thực hiện hành động ghi dữ liệu thay người dùng (ví dụ tự động nộp hồ sơ ở Phase 2).

4.4 Cố ý nằm ngoài phạm vi hiện tại

Các hạng mục sau đã được nhóm chủ động loại khỏi phạm vi, không phải bị bỏ quên: hỗ trợ đa ngôn ngữ; OCR xác thực giấy tờ tự động; thông báo qua email/SMS/Zalo; phân tích dữ liệu (analytics) nâng cao; đồng bộ dữ liệu offline (PWA hiện chỉ là vỏ cài đặt được, không hoạt động khi mất mạng); mở rộng đa khu/đa dự án cùng lúc; tự động mở rộng theo chiều ngang (auto-scale).

4.5 Hướng mở rộng dài hạn (gợi ý tham khảo, chưa nằm trong kế hoạch chính thức)

Các điểm dưới đây không nằm trong tài liệu quyết định chính thức của nhóm — nêu ra như những hướng hợp lý để cân nhắc khi sản phẩm đã chứng minh giá trị ở quy mô một dự án:

• Mở rộng sang các khu đô thị/chung cư khác ngoài Vinhomes Smart City, với kho tri thức và bộ quy tắc checklist cấu hình riêng cho từng khu thay vì hard-code cho một khu duy nhất.
• Tích hợp hoặc liên thông với ứng dụng cư dân đã ổn định (như Vinhomes Resident), để hành trình của một cư dân từ "mới nhận nhà" sang "đã ổn định" liền mạch thay vì hai ứng dụng tách biệt.
• Mở rộng năng lực agent từ "chỉ đọc và tư vấn" sang "hành động thay mặt cư dân trong giới hạn được uỷ quyền" (ví dụ tự động điền một phần hồ sơ dựa trên thông tin đã có), đi kèm các lớp bảo vệ chống prompt injection và kiểm soát quyền chặt chẽ hơn hiện tại.