2.2. Phía ban quản lý

2.3. Luồng AI có xác nhận của người dùng

Hai workflow được model hóa rõ ràng trong AIWorkflow:

• resident_ticket: thu thập unit_id, category, priority, title, description, location và attachment; chỉ tạo ticket sau xác nhận.
• manager_announcement: thu thập title, content, type, priority, expiry, scopes và attachment; tạo draft sau xác nhận, sau đó yêu cầu xác nhận publish riêng.

Agent chỉ đề xuất intent, draft, missing fields và action. Service backend xác thực role, ownership, trạng thái workflow, version, attachment ID và dữ liệu nghiệp vụ trước khi tạo hoặc publish. Thiết kế này giảm nguy cơ LLM gọi hành động có tác động trực tiếp hoặc tạo dữ liệu sai thẩm quyền.

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

3.1. Kiến trúc tổng thể

Hệ thống đang là modular monolith gồm ba phần chính:

Next.js frontend
        |
        | HTTPS / REST + SSE, Bearer JWT
        v
FastAPI modular backend
  |- Auth, RBAC, resident, unit, ticket, conversation
  |- announcement, onboarding, attachment, realtime
  |- AI workflow orchestration và knowledge adapter
        |
        +--> PostgreSQL (Alembic)
        +--> S3 private bucket (presigned URL)
        +--> ChromaDB/Qdrant (RAG vector store)
        +--> LLM provider: OpenAI, Qwen hoặc Groq

Backend tổ chức theo các boundary api -> application -> domain -> infrastructure. Các route FastAPI nhận request và dependency xác thực; application service xử lý nghiệp vụ; domain mô tả enum/lỗi/quy tắc; infrastructure chứa SQLAlchemy, repository, storage và database session.

3.2. Frontend

Frontend nằm trong frontend/, dùng Next.js 15, React 19, TypeScript, TanStack Query, React Hook Form, Zod và Zustand. Có workspace riêng cho cư dân và ban quản lý.

• API client tự gắn access token, thử refresh một lần khi gặp 401, và chuẩn hóa lỗi HTTP để UI hiển thị đúng lỗi quyền, validation hoặc conflict.
• Có chế độ mock chỉ khi NEXT_PUBLIC_USE_MOCKS=true; mặc định dùng backend thật.
• Upload nhận file, gọi POST /attachments/presign, sau đó browser PUT trực tiếp vào S3 để tránh truyền file lớn qua backend.
• SSE được dùng để invalidation/refetch dữ liệu khi có tin nhắn, ticket hoặc announcement mới. REST vẫn là nguồn dữ liệu lịch sử và CRUD.

3.3. Backend, dữ liệu và nghiệp vụ

FastAPI expose API tại /api/v1. Các module API chính gồm auth, chat, tickets, conversations, management, residents, units, announcements, attachments, onboarding, knowledge, realtime, AI workflows và RAG.

Database dùng SQLAlchemy async và Alembic. DATABASE_URL hỗ trợ PostgreSQL qua asyncpg, đồng thời SQLite/aiosqlite cho local và test. Lớp VectorType dùng pgvector khi chạy PostgreSQL, JSON khi chạy SQLite.

Các thực thể nghiệp vụ chính:

• Identity: UserAccount, Resident, ManagementProfile, RefreshSession, token reset password và token/mã xác thực email.
• Vận hành: Unit, ResidentUnit, Ticket, TicketEvent, Conversation, Message, TicketAttachment.
• Thông báo: Announcement, AnnouncementScope, AnnouncementRead, AnnouncementEvent.
• AI và tri thức: AIWorkflow, AIWorkflowAction, KnowledgeDocument, KnowledgeChunk.
• Onboarding: checklist definition/progress theo cư dân.

Ticket có state machine submitted -> approved -> in_progress -> resolved, với các nhánh rejected và cancelled. Announcement có vòng đời draft -> published -> archived. Update/publish announcement, conversation handoff và các thao tác đồng thời dùng optimistic locking/version để phát hiện ghi đè.

3.4. Xác thực và phân quyền

Hệ thống có role mức actor: resident, management, system; management profile có admin, manager, staff. Các API nghiệp vụ hiện chủ yếu cấp quyền thao tác quản lý cho admin/manager; staff tồn tại trong enum/schema nhưng chưa được mở rộng thành một bộ quyền vận hành riêng.

Bảo mật đăng nhập gồm:

• Access JWT ngắn hạn và refresh JWT dài hạn.
• Refresh token được hash trong bảng RefreshSession, rotate mỗi lần refresh và có thể revoke theo phiên hoặc toàn bộ phiên.
• Phát hiện refresh token bị dùng lại sẽ revoke tất cả refresh session của account và tăng token_version.
• Đổi/reset password và logout-all làm revoke các phiên liên quan.
• Rate limit cho chat, khóa tạm thời sau nhiều lần đăng nhập sai, kiểm tra email cư dân đã xác thực trước khi login.
• DEV_AUTH_ENABLED mặc định tắt và bị chặn khi APP_ENV=production.

3.5. AI Agent và RAG

src/agents/graph.py là runtime LangGraph-compatible cho agent nghiệp vụ. Agent chọn provider theo cấu hình OpenAI, Qwen rồi Groq; nếu tất cả lỗi hoặc không có API key hợp lệ, code fallback sang xử lý offline mang tính giới hạn. LLM được gọi bằng structured output theo schema AgentStructuredResult, không trả về action tự do.

RAG hiện có ba tầng retrieval, theo thứ tự:

1. Vector retrieval: KnowledgeSearchService gọi src.services.rag.retrieve_context. Tầng này dùng LlamaIndex với ChromaDB hoặc Qdrant; Qdrant được chọn khi VECTOR_STORE_TYPE=qdrant hoặc có QDRANT_URL. Có metadata filter theo building.
2. Local Markdown fallback: chunk handbook theo heading, chuẩn hóa tiếng Việt không dấu, mở rộng một số alias và xếp hạng lexical theo term frequency, phrase và section.
3. Database SQL fallback: tìm KnowledgeChunk có document status indexed bằng ILIKE, rồi xếp hạng theo mật độ từ khóa.

Pipeline ingest nằm trong scripts/ingest_handbook.py, có thể parse tài liệu thành nội dung xử lý, tạo embedding và index vào Chroma/Qdrant. API upload knowledge lưu file và metadata; việc ingest vector hiện là flow script riêng, chưa phải job nền tự động khi upload.

Guardrail xử lý input/output, giới hạn hành động theo role/workflow, gắn citation từ dữ liệu truy xuất và kiểm tra content policy cho announcement. Đây là lớp bảo vệ bổ sung; backend validation mới là cơ chế quyết định cuối cùng.

3.6. Attachment và realtime

Attachment metadata được lưu database; object nằm trong S3 private bucket. Backend tạo object key UUID và presigned upload/download URL, validate MIME type, dung lượng, role, ownership và parent ticket/announcement/workflow/message.

Realtime dùng Server-Sent Events tại GET /realtime/stream. Sau commit, backend phát event tin nhắn, handoff, assignment, ticket status và announcement. Connection manager là asyncio.Queue trong memory, phù hợp MVP một process; browser phải reconnect và refetch khi mất kết nối.

4. Tính khả thi

4.1. Khả thi cho MVP/pilot

Giải pháp phù hợp để chạy pilot cho một hoặc một số tòa nhà vì:

• Nghiệp vụ cốt lõi đã có mô hình dữ liệu, API, frontend và phân quyền thay vì chỉ có demo chatbot.
• Workflow AI có xác nhận của người dùng, giảm rủi ro tạo ticket/announcement sai do suy luận của model.
• Ticket conversation tạo một nguồn lịch sử thống nhất giữa cư dân, chatbot và ban quản lý.
• Announcement audience và read tracking phù hợp với truyền thông theo tòa/căn hộ.
• S3 presigned URL giảm tải cho backend và cho phép bucket riêng tư.
• PostgreSQL, Alembic, Dockerfile, Docker Compose và GitHub Actions tạo nền tảng triển khai có thể lặp lại.

4.2. Điều kiện vận hành cần có

Để hệ thống chạy production ổn định, cần cấu hình đầy đủ:

• DATABASE_URL PostgreSQL, JWT_SECRET_KEY riêng có tối thiểu 32 ký tự và APP_ENV=production.
• Credential hoặc IAM role S3, bucket private, bucket CORS cho domain frontend, cùng quyền tối thiểu s3:PutObject, s3:GetObject, s3:DeleteObject theo prefix attachment nếu cần dọn file.
• SMTP cho email verification và reset password.
• Ít nhất một LLM provider/API key và một embedding provider tương thích với vector store.
• Chroma persistence/Chroma server hoặc Qdrant URL/API key; handbook phải được ingest trước khi kỳ vọng semantic RAG.
• CORS_ORIGINS chứa đúng frontend production domain; frontend phải đặt NEXT_PUBLIC_API_BASE_URL và NEXT_PUBLIC_USE_MOCKS=false khi deploy.

4.3. Giới hạn hiện tại

5. Hướng phát triển đề xuất

Giai đoạn 1: Hardening trước pilot mở rộng

1. Tự động hóa ingestion: sau upload, tạo job extract/chunk/embed/index, cập nhật status và hiển thị lỗi rõ ràng cho manager.
2. Thống nhất đánh giá RAG: tập benchmark tiếng Việt theo handbook thật, đo retrieval recall, citation correctness, answer groundedness và latency.
3. Củng cố attachment: lifecycle rule S3, cleanup object mồ côi, log lỗi PUT rõ ràng và kiểm thử browser CORS ở deployment.
4. Đưa frontend lint/typecheck/build/test vào CI; chạy migration và integration test với PostgreSQL trong pipeline.
5. Rà soát role staff: hoặc định nghĩa quyền cụ thể, hoặc không expose các thao tác quản trị cho role này.

Giai đoạn 2: Nâng chất lượng vận hành

1. Notification bền vững: in-app notification, email/push theo sự kiện quan trọng, cấu hình preference và retry có kiểm soát.
2. SLA cho ticket: due date theo loại/priority, nhắc việc, escalation và dashboard quá hạn.
3. Tìm kiếm và phân tích: full-text search ticket/announcement, dashboard xu hướng sự cố, tiện ích thường gặp và workload manager.
4. Cải tiến AI: gợi ý category/priority có confidence, citation rõ ràng, human feedback loop và dữ liệu eval/fine-tune có version.
5. Hoàn thiện resident experience: prefill ticket từ announcement, deep link từ notification vào conversation/ticket tương ứng.

Giai đoạn 3: Mở rộng quy mô và tích hợp

1. Thay in-memory SSE bằng Redis Pub/Sub hoặc message broker; triển khai nhiều backend instance sau khi event được chia sẻ và có cơ chế replay/sync.
2. Dùng outbox pattern/worker cho email, scheduled publish, retry và audit integration khi throughput hoặc độ tin cậy yêu cầu cao hơn.
3. Tách các boundary khi có nhu cầu thực tế: notification, ingestion/embedding và analytics là các ứng viên trước; không cần microservice hóa sớm phần ticket/auth.
4. Tích hợp hệ sinh thái theo nhu cầu xác thực: thanh toán phí, kiểm soát ra vào, IoT, native mobile hoặc kênh nhắn tin ngoài ứng dụng.

6. Kết luận

OnBxrd đã vượt phạm vi chatbot hỏi đáp: codebase có mô hình vận hành cư dân tương đối đầy đủ với auth/RBAC, ticket conversation, announcement theo audience, onboarding, S3 attachment, audit, SSE và workflow AI có human-in-the-loop.

Kiến trúc modular monolith là lựa chọn phù hợp cho MVP vì giảm chi phí vận hành trong khi vẫn giữ boundary rõ ràng để phát triển. Để chuyển từ demo/pilot sang vận hành rộng hơn, ưu tiên đúng là tự động ingestion và đo chất lượng RAG, tăng độ bền realtime/background jobs, đưa frontend vào CI, rồi mới mở rộng tích hợp hoặc scale ngang.