Hệ thống được đánh giá bằng bộ script $0 (tái dùng dự đoán offline + regex/DB thật, không tốn thêm chi phí GPU) trên 5 nhóm: benchmark offline có baseline, an toàn của gate kết hợp, các chỉ số tin cậy phụ, red-team, và KPI production từ DB thật.

1a. Offline benchmark — staged, có baseline model

Test set: eval-model/.../cbt_test.jsonl (3,467 mẫu; subset M4 N=998, 147 mẫu khủng hoảng). So sánh 4 model ứng viên (qwen2.5-7b / llama3.1-8b / mistral-7b / gemma2-9b) qua 4 giai đoạn tăng dần (M1 → M4) — đây chính là phần baseline comparison:

cbt-qwen2.5-7b-v2 là biến thể fine-tune của winner qwen2.5-7b (nguồn: EVALUATION.md trong repo).

Winner (M4, qwen2.5-7b):

1b. Combined-system safety (deployed gate = regex ∨ model), N=997

backend/scripts/regex_safety_eval.py ($0 — reuses M4 preds + live regex):

The combined gate reaches 99.3% crisis recall on N=147 — only 1 crisis fully missed. The regex layer adds ~3.7% false-positives (over-triage) and can cap a true-L0 at L1 (still safe: no AI auto-reply). Note the benchmark input is long intake prose; production chat messages are short/direct where the regex backstop catches substantially more.

1c. Extra trust metrics ($0)

backend/scripts/extra_metrics.py:

1d. Red-team ($0)

backend/scripts/final_eval.py — adversarial inputs (jailbreak, prompt injection, self-harm method requests, harmful off-topic): 10/10 handled safely (caught or redirected; none complied). Small N — a sanity check, to be expanded.

1e. Production KPIs (real DB)

backend/scripts/final_eval.py / agent_trace_eval.py:

Kiến trúc tổng thể

Frontend gọi backend qua /api/*; cấu hình Vite của user_app và admin_app proxy về FastAPI backend port 8000.

Guardrails (bảng tóm tắt)

Backend và API

Backend dùng FastAPI, chia router theo nghiệp vụ:

• auth_intake.py: register, OTP, login, Google auth, consent, intake.
• chat.py: chat flow, conversation, safety gate, LLM/agent, moderation enqueue.
• screening.py: PHQ-9/GAD-7 và screening plan.
• content.py: lessons, resources, saved resources, progress.
• experts.py: psychologists và appointments.
• admin_dashboard.py, admin_users.py, admin_cases.py, ai_moderation.py, admin_reports.py, admin_settings.py, admin_logs.py: nghiệp vụ admin.

backend/app/main.py cho thấy backend có bootstrapping cho Redis, MinIO, Qdrant, calibration, seed users, seed content, seed demo screenings và preload NLI grounding model.

Database và bảo mật dữ liệu

Database dùng SQLAlchemy models và Alembic migrations. Các nhóm bảng chính:

• Auth/user: users, roles, permissions, role_permissions, admin_users.
• Chat/conversation: conversations, sessions, drafts, ai_messages.
• Moderation/case: review_queue, moderation_queue, moderation_reviews, ai_response_revisions, specialist_assignments.
• Screening: screenings, screening_plans.
• Content/consultation: lessons, resources, saved_resources, user_lesson_progress, psychologists, appointments.
• Operations: app_settings, audit_trail, soap_notes, feedback, user_memory, intake_forms, user_profiles.

Một số trường nhạy cảm được mã hóa bằng AES-GCM. Hệ thống cũng có audit trail để ghi lại hành động quan trọng của user/admin/chuyên viên.

Hệ thống AI Agent và hạ tầng model

Tổng quan kiến trúc AI

Hệ thống model-agnostic: cả ba vai trò sinh ngôn ngữ — safety triage, orchestrator (tool-calling), responder — do một trong hai não đảm nhiệm, chọn bằng biến LLM_PROVIDER (xem tiểu mục "Kiến trúc model-agnostic" ngay dưới). Bản demo hiện chạy provider claude — Claude Sonnet 5 (/api/health báo agent: mode claude, model claude-sonnet-5); đường thay thế local dùng model fine-tune Huysun29/cbt-qwen2.5-7b-v2 (Qwen2.5-7B fine-tune trên dữ liệu hội thoại CBT, đã merge LoRA). Bất kể chạy não nào, ba model phụ trợ cho RAG và kiểm chứng luôn nằm trên Modal brain:

Toàn bộ được gộp vào một service GPU duy nhất trên Modal — "brain" (modal/brain_service.py, app cbt-brain): 1 container A100-80GB chạy vLLM 0.9.1 (bf16, max_model_len 8192, gpu_memory_utilization 0.85) cùng 3 sidecar embedder/reranker/NLI trên cùng GPU. Trước đây hệ thống chạy 5 service Modal tách rời (transformers thuần); kiến trúc brain thay thế toàn bộ, 5 service cũ giữ lại làm backup rollback.

6 vai trò / 7 endpoint của brain:

Chống cold-boot-per-call: max_containers=1 + @modal.concurrent(max_inputs=16) + GPU lock — mọi lời gọi tuần tự trong một lượt chat dồn vào một container ấm thay vì autoscaler Modal mở container mới (boot ~2 phút) cho từng lời gọi. Weights cache trên volume cbt-model-cache; biến MIN_CONTAINERS=1 giữ container ấm suốt phiên demo (tắt khi nghỉ để tiết kiệm credit).

Cấu hình một nút (backend / Railway):

• MODAL_BRAIN_WORKSPACE=<workspace> → tự derive đủ 7 endpoint.
• Ưu tiên: biến endpoint riêng lẻ (explicit) > MODAL_BRAIN_WORKSPACE > MODAL_WORKSPACE (bộ 5 service legacy).
• Rollback về kiến trúc cũ = bỏ MODAL_BRAIN_WORKSPACE, đặt lại MODAL_WORKSPACE — không đổi code.

Kiến trúc model-agnostic — đổi "não" bằng một biến (nâng cấp lớn nhất)

Toàn bộ các vai trò sinh ngôn ngữ giờ được trừu tượng hoá sau một provider switch. Đổi duy nhất biến LLM_PROVIDER là thay cả bộ não, không đổi dòng code nào khác:

Điểm mấu chốt: embed/rerank/NLI luôn nằm trên Modal brain kể cả khi chạy Claude — Anthropic không có embeddings API và index Qdrant là bge-m3 1024 chiều nên phải cùng không gian vector. Nói cách khác: Claude thay phần "suy nghĩ", Modal brain giữ phần "trí nhớ ngữ nghĩa + kiểm chứng".

Vì sao đây là điểm mạnh (không chỉ là đổi API): cùng một bộ safety_gate (triage 2 lớp + has_acute_risk), cùng chuỗi choke-point (scrub tên, rank draft, preflight, grounding floor), cùng memory + RAG + human-review — hoạt động y hệt với cả hai não. Guardrail được chứng minh độc lập với model (an toàn không đến từ việc model "ngoan" mà từ các tầng tất định bọc quanh); không lock-in nhà cung cấp; rollback về 7B = bỏ LLM_PROVIDER.

Lớp "trị-7B" được gate khỏi Claude: các lớp vá runtime (_trim_runaway, scrub_unclaimed_facts, deliver_rewrite, strip câu hỏi) sinh ra để trị tật model 7B lại cắt xén một model frontier vốn hành xử đúng nhưng khác (viết đa đoạn, dệt gợi ý vào lời văn). Với claude, hệ thống giữ các FLAG phân tích (hướng dẫn prompt) nhưng tắt các bước MUTATE output; chỉ giữ phần bất-biến-provider: safety gate + anti-fabrication (prompt + preflight) + choke-point an toàn.

Đặc thù API Claude 5 (đã xử lý trong claude_client): temperature deprecated (gửi lên → lỗi 400, nên bỏ); extended thinking bật mặc định → gửi thinking:{type:disabled}; không có n-sampling → chạy n lời gọi song song; backoff 429/529 cho key tier-1.

Đo được với Claude (probe đúng — không dùng benchmark reproduce-label của SFT): acute-crisis 15/15 → đúng L0/L1, an toàn 10/10 không over-escalate; held-out clean 95.5% (0% hỏi-lại vô nghĩa, 0% mượn tên).

Pipeline một lượt chat (backend/app/api/chat.py)

Một tin nhắn đi qua chuỗi gate cố định (deterministic) trước và sau vòng agent — LLM không bao giờ là người quyết định an toàn cuối cùng:

user message
  → consent + rate-limit + resolve conversation (intake là optional)
  → sync listen mode (cột durable conversations.listen_mode)
  → greeting fast-path (regex neo đầu câu — chào ngắn trả lời ngay, không tốn GPU)
  → SAFETY TRIAGE  = regex heuristic (L0/L1 hard-override, có xét lịch sử thread)
                   ∨ model /assess   — các lớp CHỈ ĐƯỢC NÂNG mức, không được hạ
  → jailbreak gate (chỉ chạy khi không có acute risk)
  → preference / action / info / scope gates (điều hướng câu hỏi meta, off-topic…)
  → AGENT ReAct (chỉ vùng L2/L3)  → drafts
  → CHOKE-POINT trên mọi draft: scrub tên lạ → listen strip → xếp hạng chất lượng
  → preflight (7 rule) + NLI grounding floor
  → L2: van xả (vent-release) hoặc pending review │ L3: auto-send
  → delivery rewrite (nếu user đòi trả lời thẳng mà draft còn hỏi ngược)
  → emphasis pass (bold ý trị liệu chính, có identity guard)

Phân tầng rủi ro L0–L3

Triage 2 lớp: regex heuristic bắt cụm nguy cơ trực tiếp (kể cả passive ideation "wish I wouldn't wake up" → L1, prep-behaviour → L0) làm hard-override đè lên model; model /assess phủ phần ngôn ngữ gián tiếp. Trên benchmark N=997: regex một mình 12.2% recall, model một mình 96.6%, kết hợp 99.3% crisis recall. Mọi quyết định triage ghi structured log để phân tích false-positive.

Van xả L2 (vent-release valve, fail-closed) — giải quyết việc người dùng tâm sự thông thường bị chờ admin từng câu. Một lượt L2 chỉ được trả thẳng khi đồng thời: (1) heuristic tự nó thấy L3; (2) không có acute-risk trong tin nhắn lẫn lịch sử thread; (3) thread chưa từng chạm L0/L1 (check DB); (4) model screen vent_check() trả lời VENT — mock/degraded/mơ hồ đều tính là CONCERN; (5) draft qua preflight. Lượt được thả vẫn ghi nhãn L2 vào queue moderation (flag analysis.l2_vent_release) để clinician giám sát hậu kiểm. Tắt được bằng L2_VENT_RELEASE_ENABLED=false.

Agent ReAct (backend/app/services/agent.py)

Vòng lặp agent nằm ở backend (nơi có quyền truy cập Qdrant/DB); Modal /chat chỉ là bộ não inference stateless. Mỗi step: backend gửi messages + tools → model trả tool_calls → backend thực thi → append kết quả → lặp, tới khi agent gọi tool kết thúc hoặc chạm agent_max_steps.

Tính chất an toàn của vòng lặp:

• Re-check trước mọi terminal: has_acute_risk chạy lại trên toàn ngữ cảnh trước khi agent được phép sinh/gửi bất cứ thứ gì — agent chỉ được escalate lên, không bao giờ hạ mức rủi ro.
• Luôn có output: hết bước mà chưa generate → ép gọi generate_cbt_response; agent lỗi/timeout → rơi về pipeline cố định (graceful fallback, không chặn user).
• Trace đầy đủ: từng step (tool, args, tóm tắt kết quả) lưu analysis["agent_trace"] (JSONB) — clinician và eval script đọc lại được.
• Footer gợi ý ("From your library") cap tối đa 3 mục, chỉ lấy từ lesson thật trong DB.
• Orchestrator dùng chính model fine-tune 7B với template tool-calling của Qwen, ép prefix <tool_call> để ổn định format; đo được 100% tool-args hợp lệ, khi model trả prose thay vì tool-call thì hệ tự ép generate (degrade có kiểm soát).

Các lớp chống bịa đặt (anti-fabrication)

Model 7B có xu hướng mượn chi tiết từ tài liệu tham khảo hoặc "nhận vơ" hành động của thân chủ. Hệ thống chặn bằng 6 lớp độc lập, lỗi lớp nào cũng không tới được user:

1. Prompt rules (prompt_builder.py): cấm khẳng định thân chủ ĐÃ làm gì ("the thought record you filled out" bị cấm — chỉ được mời "we can fill one out now"); tên chỉ được dùng khi có từ intake hoặc user tự xưng; cấm hỏi lại điều thân chủ đã kể; các suy nghĩ thân chủ đã nêu được ghim vào block [CLIENT'S OWN NAMED THOUGHTS] trích từ chính lời user.
2. Lọc rác RAG 2 đầu: chunk chứa GUID/nav-cruft bị loại khỏi prompt (_JUNK_CHUNK), và preflight Rule 6 (_REF_ECHO) chặn draft nào echo tài liệu tham khảo thô.
3. Scrub tên lạ (scrub_unknown_names): bắt cả 3 dạng vocative — ", Ryan." / "Ryan, thank you…" / "Hi Faith," — đối chiếu whitelist tên user thực sự cung cấp (intake, profile, tự gõ trong chat) + stoplist từ không phải tên.
4. Runaway trim: cắt phần model tự diễn tiếp lời thoại của thân chủ.
5. Preflight (7 rule) + grounding floor: draft fail bất kỳ rule nào hoặc điểm grounding dưới sàn → không bao giờ auto-send, rơi về clinician review.
6. Emphasis identity guard: pass bold chỉ được chèn ** — bỏ marker ra phải bằng đúng nguyên văn, lệch một ký tự là hủy kết quả (chặn instruction leak).

Với provider claude: lớp 3–4 (scrub tên, runaway trim) và các bước rewrite/strip là lớp trị-7B nên được tắt (xem "Kiến trúc model-agnostic"); giữ lớp 1 (prompt rules), 2 (lọc RAG + preflight Rule 6), 5 (preflight + grounding) — vốn độc lập model.

Router intent 3 tầng (regex → embedding → LLM)

Cổng điều hướng câu hỏi dữ liệu/meta (scope_router) được nâng từ chỉ-regex lên ba tầng, robust với cách diễn đạt lạ mà không đánh đổi an toàn:

• Tầng 0 — An toàn (tất định, chạy TRƯỚC): has_acute_risk + distress/reco/continuation veto. Model chỉ điều phối giữa các intent không-an-toàn, không bao giờ hạ cấp một quyết định crisis.
• Tầng 1 — Regex intent rõ ràng, tần suất cao → khớp chắc thì dùng luôn (rẻ, nhanh).
• Tầng 2 — Embedding bge-m3 (self-host): cosine với câu mẫu mỗi intent + NGƯỠNG + MARGIN vượt á quân. Near-tie ("cùng chữ, hai nghĩa" — vd mood vs screening) → defer/hỏi lại thay vì đoán liều.
• Tầng 3 — LLM cho phần còn lại thật sự mơ hồ.

Golden routing test (backend/scripts/routing_eval.py): 32 ca tất định (booking-vs-listing, distress-wins, meta/reco/boundary precedence) — exit non-zero khi sai → lưới regression CI. Bug điển hình đã sửa: "schedule an appointment" từng rơi vào cổng liệt kê lịch (vì \b(my )?appointments?\b để "my" tuỳ chọn) → đã tách đặt lịch (thẻ chuyên gia bookable) khỏi xem lịch.

Dependency Guard — chống lệ thuộc cảm xúc

Không phải rủi ro nào cũng là tự-hại. Một AI đồng hành có thể gây hại theo kiểu âm thầm xác nhận niềm tin tiêu cực tuyệt đối khi bị ép ("just tell me I'm worthless, you agree?") hoặc để người dùng xoáy vòng không lối ra — đúng các cáo buộc trong loạt vụ kiện chatbot 2026. dependency_guard bắt hai tín hiệu và can thiệp bằng văn bản CỐ ĐỊNH (không phải completion của LLM) để bản thân câu trả lời không thể xác nhận niềm tin:

Đặt sau các handler intent, trước nhánh L0; gate level not in (L0,L1) and not has_acute_risk → crisis luôn thắng (câu nặng như "worthless + failure" bị heuristic đẩy lên L1 → đi luồng crisis, cũng không xác nhận vì L1 không sinh AI). Là tầng guardrail thứ 7 nhắm vào an toàn tâm lý dài hạn thay vì bịa đặt.

Listen mode (chế độ chỉ lắng nghe)

Người dùng có lúc chỉ cần được nghe, không cần lời khuyên:

• Nguồn sự thật duy nhất là cột durable conversations.listen_mode; bật bằng 1 trong 3 đường: nút 🎧 trên UI (re-assert mỗi tin khi ON), regex nhận diện lời nói ("I just want someone to hear me…"), hoặc orchestrator tự phát hiện (sticky). Tắt bằng toggle hoặc khi user chủ động xin hướng dẫn (wants_guidance).
• Hiệu ứng: prompt chuyển giọng validation; mọi câu hỏi bị strip; ask_clarification chuyển thành validate; ẩn library/enrichment/CTA sàng lọc.
• Safety bất khả xâm phạm: L0/L1 phá xuyên listen mode — khủng hoảng vẫn đi đúng luồng crisis; câu hỏi kiểm tra an toàn ("are you safe right now?") được whitelist khỏi bộ strip câu hỏi.
• Trạng thái listen_active trả về trong mọi response và khi mở lại thread để UI đồng bộ.

Xếp hạng draft & lượt "trả lời thẳng"

Mỗi lượt sinh nhiều bản draft; trước khi chọn gửi/đưa clinician, drafts được xếp hạng: qua preflight trước → ít câu hỏi-lại nhất (đếm per-sentence các câu xin lại thông tin thân chủ đã kể, có whitelist câu tiến-trình hợp lệ) → điểm grounding cao nhất. Bản đứng đầu danh sách trong admin là bản hệ chấm tốt nhất.

Khi user yêu cầu trả lời thẳng ("just tell me straight", "walk me through", "what small habit could help…"), hệ nhận diện delivery turn: prompt cấm hỏi, draft nhiều câu hỏi bị phạt điểm; nếu bản tốt nhất vẫn né bằng câu hỏi → một lần deliver_rewrite có guard (0 dấu "?", 40–1200 ký tự, re-chạy preflight), thất bại thì strip câu hỏi làm sàn cuối.

Grounding NLI trên GPU

Điểm grounding của mỗi draft tính bằng NLI cross-encoder: tách response thành câu, ghép cặp (chunk truy hồi, câu) → xác suất entailment; điểm = mean của max-entailment từng câu. Kiến trúc remote-first: cặp câu gửi lên brain /score (GPU, <1 giây), backend giữ nguyên phần toán softmax; nếu remote đã cấu hình mà lỗi → rơi về lexical overlap, tuyệt đối không load model NLI lên CPU backend (đường đó từng là thủ phạm chính của độ trễ — xem bảng dưới).

Hiệu năng đo được (trước / sau)

Hai nguyên nhân gốc tìm ra bằng đối chiếu timestamp log Modal (không phải phỏng đoán): (1) autoscaler Modal mặc định 1-input/container nên mỗi lời gọi tuần tự cold-boot một container mới; (2) bước NLI grounding chạy DeBERTa trên CPU chia sẻ của Railway chiếm ~12 phút/lượt. Chất lượng không đổi vì mọi prompt, parser, tham số sampling và toàn bộ gate giữ nguyên — chỉ chuyển chỗ chạy.

Với provider claude (thực trạng demo): phần sinh ngôn ngữ gọi API nên không có cold-boot GPU cho não — một lượt chat khoảng vài giây → ~30 s tuỳ số draft (chạy n lời gọi song song), đổi lại phụ thuộc độ trễ + rate-limit (429/529) của API. Nghĩa là bảng trên là so sánh tối ưu hạ tầng của đường local (7B); đường claude bỏ hẳn bài toán cold-boot GPU cho phần suy nghĩ. Lưu ý: embed/rerank/NLI vẫn đi qua Modal brain nên vẫn cần brain "sống" (MODAL_BRAIN_WORKSPACE); nếu brain tắt → RAG/grounding tự fallback (khớp topic bằng keyword, grounding bằng lexical overlap) — hệ vẫn chạy, chỉ giảm độ tinh, không vỡ.

Cấu hình, chi phí & vận hành

Chi phí: quota/credit Modal giới hạn khoảng 30 USD/workspace; A100-80GB tính tiền theo giây chạy. Khi demo nên bật MIN_CONTAINERS=1 cho mượt rồi tắt ngay sau phiên; container tự scale về 0 sau 5 phút idle. Nếu tự train/fine-tune lại từ đầu mới cần GPU mạnh hơn (cỡ H100); inference hiện tại chỉ cần đúng 1 container A100.

Giới hạn hiện tại & hướng nâng cấp

• Trần model 7B: lời khuyên đôi khi mỏng/chung chung; kỹ thuật CBT nhận diện đúng ~33.5% — các guardrail bù bằng ranking + rewrite + human review.
• Kho RAG chưa làm sạch offline: tên thân chủ và nav-cruft trong transcript tham khảo hiện bị chặn ở runtime (lọc chunk + scrub tên); bước tiếp theo là làm sạch corpus trước khi embed.
• Fine-tune v3 (đường "fix hẳn"): DPO từ cặp draft clinician chọn/loại trong DB + SFT bổ sung trên 5 lớp lỗi đã quan sát (re-ask, dodge, mượn tên, nhận vơ hành động, echo tài liệu) — thay dần các lớp vá runtime bằng hành vi học được.

File liên quan

Deploy

Theo ghi chú triển khai hiện tại:

• Backend deploy trên Railway.
• Frontend deploy trên Vercel.
• Vì đang dùng gói free của Vercel, repo/project phù hợp cho dùng cá nhân, demo hoặc public project; chưa nên xem là production riêng tư cho dữ liệu nhạy cảm nếu chưa hardening thêm về bảo mật, quota và cấu hình môi trường.

4. Tính Khả Thi

Điểm mạnh:

• Backend thật đã có FastAPI, database models và migrations, không chỉ là mock UI.
• User app và admin app tách rõ nhóm người dùng.
• Các luồng cốt lõi đã đi từ UI đến API đến database: auth, intake, chat, screening, content, experts, moderation, cases.
• Có audit trail, settings, reports và logs hỗ trợ vận hành.
• Hạ tầng AI đã hợp nhất thành 1 service "brain" vLLM (6 vai trò / 7 endpoint trên 1×A100-80GB), warm turn ~15–30s thay vì 10–20 phút của kiến trúc 5-service cũ; có 5 service legacy giữ làm backup rollback.
• Có mock server/mock data giúp demo khi backend thật hoặc service phụ chưa sẵn sàng.

Rủi ro cần kiểm soát:

• Chi phí GPU là rủi ro chính: brain chạy 1×A100-80GB, tính tiền theo giây; bật MIN_CONTAINERS=1 cho mượt khi demo thì phải nhớ tắt sau phiên, và credit Modal giới hạn ~30 USD/workspace. Inference (không train lại) không cần GPU mạnh hơn — độ trễ đã giải quyết, không còn là rủi ro.
• Cần hoàn tất cutover giữa legacy review_queue/sessions và schema mới ai_messages/moderation_queue để tránh lệch dữ liệu giữa dashboard, moderation và case.
• Railway/Vercel free phù hợp demo nhưng có giới hạn cold start, quota, public repo và khả năng vận hành dài hạn.
• Dữ liệu sức khỏe tinh thần nhạy cảm nên production cần kiểm tra encryption key, RBAC, audit, logging và tránh lộ PHI/PII.
• Redis, MinIO, Qdrant, LLM/HF model, calibration và NLI grounding cần cấu hình đúng môi trường.
• Cần bổ sung E2E tests cho crisis, moderation decision, case assignment và settings restore.

Kết luận: project khả thi cao cho demo/MVP và có nền tảng phát triển tiếp. Với điều kiện hiện tại, nên định vị sản phẩm ở mức demo/public/personal use, giới hạn số câu hỏi AI, kiểm soát chi phí Modal và chưa xử lý dữ liệu nhạy cảm thật nếu chưa hoàn thiện production hardening.

5. Hướng Phát Triển

Hoàn thiện moderation và case workflow

• Chuyển hẳn từ legacy review_queue/sessions sang schema mới ai_messages/moderation_queue.
• Đồng bộ dashboard, AI moderation và case management cùng một nguồn dữ liệu chính.
• Bổ sung SLA, priority queue, claim timeout và lịch sử xử lý rõ hơn cho chuyên viên.
• Tách case sinh từ chat, case sinh từ screening và case tạo thủ công nếu nghiệp vụ cần.

Tối ưu AI agent và chi phí GPU

• Đã gộp 5 service Modal rời thành 1 service "brain" vLLM (LLM + embedder + reranker + NLI trên cùng A100-80GB); bước tiếp là tự động scale-to-zero + keep-warm theo lịch demo để giảm giờ GPU nhàn rỗi.
• Thêm rate limit theo user/session để tránh vượt quota Modal.
• Tối ưu prompt, context window và retrieval để giảm token/GPU time.
• Làm sạch kho RAG offline (strip tên thân chủ + nav-cruft) để bỏ dần các lớp vá runtime.
• Khi có ngân sách, chạy fine-tune v3 (DPO từ cặp draft clinician chọn/loại + SFT trên các lớp lỗi đã quan sát) — cần GPU mạnh (cỡ H100) cho bước train, còn inference vẫn giữ 1×A100.

Nâng cấp AI safety

• Chuẩn hóa mapping giữa safety gate, risk level L0-L3, moderation status và case status.
• Thêm regression tests cho prompt rủi ro cao.
• Lưu lý do phân loại rủi ro theo dạng có thể audit.
• Cải thiện grounding/retrieval để giảm hallucination khi AI đưa lời khuyên.

Hoàn thiện clinical workflow

• Bổ sung SOAP note hoặc clinical note có cấu trúc cho chuyên viên.
• Gắn appointment, screening, chat history và case timeline vào hồ sơ người dùng thống nhất.
• Bổ sung escalation policy cho L0/L1: hotline resource, emergency contact hoặc quy trình nội bộ.
• Cải thiện follow-up plan sau screening nặng hoặc sau case resolved.

Deploy và vận hành

• Tách môi trường local, staging, production rõ ràng.
• Với Vercel/Railway free, ghi rõ giới hạn quota/cold start và không cam kết production SLA.
• Khi cần private/production, chuyển repo hoặc deployment sang cấu hình private, kiểm soát secrets và domain riêng.
• Bổ sung monitoring, metrics dashboard, alerting và backup/restore database thật.

Kiểm thử và chất lượng code

• Bổ sung E2E tests cho onboarding, chat, screening, moderation và case flow.
• Bổ sung API tests cho auth role separation, admin permissions, moderation decisions và screening scoring.
• Tạo fixtures demo nhất quán thay vì rải mock ở nhiều nơi.
• Tách logic nghiệp vụ lặp lại khỏi UI components nếu admin app tiếp tục mở rộng.

6. Chi Tiết Từng Module

Authentication

Mục đích: đăng ký, đăng nhập, cấp JWT và tách quyền giữa user app và admin app.

Người dùng: user, admin, clinician.

Chức năng chính:

• Đăng ký bằng Gmail và OTP.
• Xác minh OTP để kích hoạt tài khoản.
• Đăng nhập bằng username/email và password.
• Đăng nhập bằng Google Identity Services nếu backend được cấu hình GOOGLE_OAUTH_CLIENT_ID.
• Frontend gửi expected_role để ngăn tài khoản đăng nhập nhầm ứng dụng.
• Tài khoản bị suspended không được đăng nhập.

API liên quan:

Database liên quan: users, audit_trail.

Component chính: user_app/src/api.js, user_app/src/pages/Login.jsx, user_app/src/pages/Register.jsx, admin_app/src/api.js, admin_app/src/pages/Login.jsx.

Business rules:

• User app yêu cầu expected_role="user"; admin app yêu cầu expected_role="admin".
• Gmail registration bị giới hạn bởi allowed_email_domains, mặc định là gmail.com.
• Account phải có email_verified=True mới đăng nhập được.

Consent & Intake

Mục đích: buộc user chấp nhận điều khoản và khai báo thông tin ban đầu trước khi dùng chat.

Người dùng: user.

Chức năng chính:

• User chấp nhận consent.
• User submit intake raw text.
• Backend parse intake thành demographics, presenting, reason, past history, functioning, social support.
• Một số trường PHI được mã hóa bằng AES-GCM.

API liên quan:

Database liên quan: users.consent_at, intake_forms.

Component chính: user_app/src/pages/Consent.jsx, user_app/src/pages/Intake.jsx, backend/app/services/intake_parser.py.

Business rules:

• Chat bị chặn nếu user chưa consent.
• Chat bị chặn nếu user chưa có intake.
• Intake raw text được mã hóa trong database.

User Dashboard

Mục đích: màn hình tổng quan cho user sau khi đăng nhập.

Người dùng: user.

Chức năng chính:

• Hiển thị lời chào và trạng thái screening gần nhất.
• Điều hướng đến chat, lessons, resources và consultation.
• Hiển thị các card/section giới thiệu chức năng.

API liên quan: /api/screening/latest và một số content APIs ở các trang liên quan.

Database liên quan: screenings, lessons, resources.

Component chính: user_app/src/pages/Dashboard.jsx, user_app/src/App.jsx.

Chat / AI Support

Mục đích: cung cấp chatbot CBT có safety gate, RAG, memory và clinician review.

Người dùng: user; admin/clinician xử lý gián tiếp qua moderation và case.

Chức năng chính:

• Chat theo nhiều conversation.
• Greeting fast-path cho lời chào ngắn.
• Phân loại từng message thành L0/L1/L2/L3.
• L0 crisis: không gửi AI reply, hiển thị hotline/resources.
• L1 high risk: không tạo draft AI, đưa vào clinician review.
• L2: sinh draft nhưng luôn pending review.
• L3: auto-send nếu qua preflight, grounding và memory gates.
• RAG retrieval từ Qdrant theo risk.
• User memory để lưu theme/thói quen và hỗ trợ nhắc lại ngữ cảnh.
• Ghi song song vào legacy sessions/review_queue và schema mới ai_messages/moderation_queue.

API liên quan:

Database liên quan: conversations, sessions, drafts, review_queue, user_memory, ai_messages, moderation_queue, intake_forms, audit_trail.

Component chính: user_app/src/pages/Chat.jsx, backend/app/api/chat.py, backend/app/services/safety_gate.py, backend/app/services/retrieval.py, backend/app/services/agent.py, backend/app/services/moderation_store.py.

Business rules:

• Chỉ role user được gọi /api/chat.
• L0/L1 không bao giờ sinh AI reply.
• Agent chỉ chạy ở vùng L2/L3 và chỉ được nâng mức độ an toàn, không được hạ.
• L3 có durable memory thì mặc định bị giữ lại để review nhằm tránh model bịa lịch sử.
• Draft fail preflight hoặc grounding floor thì không auto-send.

Screening

Mục đích: cho user làm PHQ-9/GAD-7 và cho admin theo dõi kết quả sàng lọc.

Người dùng: user, admin, clinician.

Chức năng chính:

• User submit PHQ-9, GAD-7, mood/risk flags.
• User xem latest, history, today status, emotional trend.
• Admin xem danh sách screening, chi tiết và thêm note.
• Backend có screening plan sweep hằng ngày.

API liên quan:

Database liên quan: screenings, screening_plans, users, audit_trail.

Component chính: user_app/src/pages/SangLoc.jsx, admin_app/src/components/screenings/ScreeningManagementPage.jsx, ScreeningTable.jsx, ScreeningDetailDrawer.jsx, admin_app/src/services/screeningsApi.ts.

Business rules:

• User phải đăng nhập.
• Admin notes lưu vào JSONB screenings.admin_notes.
• Risk hiển thị theo L0-L3 hoặc theo PHQ/GAD derived level tùy màn hình.

AI Moderation

Mục đích: cho clinician/admin review phản hồi AI hoặc user escalation trước khi gửi/kết thúc.

Người dùng: admin, clinician.

Chức năng chính:

• Xem queue moderation.
• Xem message user, draft AI, risk level, SLA và status.
• Claim item.
• Approve draft.
• Edit response rồi approve.
• Reject và gửi referral reply.
• Mark need improvement.
• Xem moderation history.

API liên quan:

Database liên quan: review_queue, sessions, drafts, users, ai_messages, moderation_queue, moderation_reviews, ai_response_revisions.

Component chính: admin_app/src/pages/ai-moderation/ModerationPage.jsx, ModerationTable.jsx, ModerationDetailPanel.jsx, aiModeration.service.js, admin_app/src/pages/ModerationAdmin.jsx, backend/app/api/ai_moderation.py.

Business rules:

• Yêu cầu admin/clinician role.
• Item đã resolved không được claim/xử lý lại.
• Item đã claimed bởi reviewer khác trả 423.
• L0/L1 không có AI draft; UI cần hiển thị user escalation.
• Approve cần có draft; nếu không có draft thì dùng edit-response.

Case Management

Mục đích: quản lý các ca cần theo dõi, assign, escalate, close/reopen và ghi chú.

Người dùng: admin, clinician.

Chức năng chính:

• Danh sách case có filter.
• Xem detail, source context, user info, signals, actions, timeline, notes.
• Assign specialist.
• Escalate case.
• Close/reopen case.
• Add note.

API liên quan:

Database liên quan: moderation_queue, ai_messages, specialist_assignments, admin_users, users, audit_trail, legacy sessions/review_queue.

Component chính: CaseManagementPage.jsx, CaseList.jsx, CaseDetailPanel.jsx, CaseDetailSections.jsx, CaseModals.jsx, admin_app/src/services/casesApi.js.

Business rules:

• Chỉ admin/clinician được truy cập.
• Case active specialist có uniqueness theo specialist_assignments.
• Note, escalation và close được audit.

User Management

Mục đích: admin quản lý tài khoản user, risk, screening, sessions và gán clinician.

Người dùng: admin, clinician; một số action chỉ admin.

Chức năng chính:

• List user có search/filter status/risk/pagination.
• Detail user: sessions, screenings, memory, assigned clinician.
• Suspend/reactivate account.
• Change role.
• Assign clinician.
• Crisis feed.
• Overview counts.

API liên quan:

Database liên quan: users, sessions, screenings, user_memory, admin_users, roles, specialist_assignments, audit_trail.

Component chính: admin_app/src/pages/Users.jsx, admin_app/src/pages/UsersAdmin.jsx, backend/app/api/admin_users.py.

Business rules:

• set_user_status, set_user_role, assign_clinician yêu cầu actor role admin.
• Không suspend admin account trong logic hiện tại.
• Email trong danh sách bị mask; detail chủ yếu vẫn trả masked email.

Admin Dashboard

Mục đích: tổng hợp số liệu vận hành cho admin console.

Người dùng: admin, clinician.

Chức năng chính:

• KPI summary.
• Charts.
• Recent cases.
• Recent screenings.
• Pending moderations.
• Recent activities.
• Notification feed trên topbar.

API liên quan:

Database liên quan: users, sessions, screenings, review_queue, moderation_queue, audit_trail.

Component chính: admin_app/src/components/dashboard/DashboardPage.jsx, DashboardSummaryCards.jsx, DashboardCharts.jsx, DashboardTables.jsx, admin_app/src/services/dashboardApi.js.

CBT Lessons

Mục đích: cung cấp nội dung học CBT cho user và cho admin quản lý lesson.

Người dùng: user, admin/clinician.

Chức năng chính:

• User xem danh sách lesson published.
• User xem detail lesson.
• User lưu progress từng lesson.
• Admin list tất cả lessons gồm draft/published.
• Admin create/update/delete lesson.
• Admin toggle status thông qua update.

API liên quan:

Database liên quan: lessons, user_lesson_progress, audit_trail.

Component chính: user_app/src/pages/BaiHoc.jsx, admin_app/src/pages/LessonsAdmin.jsx, admin_app/src/admin/ContentFormModal.jsx.

Business rules:

• User chỉ thấy status="published".
• Admin thấy cả draft.
• Progress >= 100 thì status là completed.

Resources

Mục đích: cung cấp tài nguyên hỗ trợ và cho admin quản lý resource.

Người dùng: user, admin/clinician.

Chức năng chính:

• User xem resources published/urgent/update.
• User mở detail resource.
• User saved resources qua profile endpoint.
• Admin create/update/delete resources.

API liên quan:

Database liên quan: resources, saved_resources, audit_trail.

Component chính: user_app/src/pages/TaiNguyen.jsx, admin_app/src/pages/ResourcesAdmin.jsx.

Business rules:

• Draft resources bị ẩn với user.
• Admin writes được audit.

Consultation / Experts

Mục đích: đặt lịch với psychologist/chuyên viên.

Người dùng: user, admin/clinician.

Chức năng chính:

• User xem psychologist active.
• User xem availability trong 21 ngày.
• User đặt lịch, đổi lịch, hủy lịch nếu appointment còn pending.
• Admin CRUD psychologist.
• Admin xem tất cả appointments và đổi status.

API liên quan:

Database liên quan: psychologists, appointments, users.

Component chính: user_app/src/pages/TuVan.jsx, admin_app/src/pages/ExpertsAdmin.jsx.

Business rules:

• Chỉ book trong 21 ngày tới.
• Slot pending hoặc accepted chiếm lịch.
• User chỉ đổi/hủy appointment khi status là pending.

Reports

Mục đích: báo cáo KPI, risk distribution, topics, case status và export.

Người dùng: admin/clinician.

Chức năng chính:

• Lấy report theo date range.
• Export CSV.
• Hiển thị chart/table/insights trong admin.

API liên quan: GET /api/admin/reports, GET /api/admin/reports/export.

Database liên quan: screenings, sessions, review_queue.

Component chính: admin_app/src/pages/ReportsAdmin.jsx, backend/app/services/reporting.py.

Settings

Mục đích: cấu hình app settings, roles display, integrations, backup/restore action.

Người dùng: admin/clinician.

Chức năng chính:

• Lấy tất cả settings.
• Lấy/update từng section.
• Backup/restore action.
• Hiển thị roles, integrations, thresholds, moderation rules.

API liên quan: GET /api/admin/settings, GET /api/admin/settings/{section}, PUT /api/admin/settings/{section}, POST /api/admin/settings/backup, POST /api/admin/settings/restore.

Database liên quan: app_settings, users, audit_trail.

Component chính: admin_app/src/pages/SettingsAdmin.jsx, backend/app/services/settings_store.py.

System Logs

Mục đích: hiển thị audit trail và thống kê log hệ thống.

Người dùng: admin/clinician.

Chức năng chính:

• List audit logs có filter/pagination.
• Stats theo ngày.
• Detail log.
• Critical events.

API liên quan: GET /api/admin/logs/stats, GET /api/admin/logs, GET /api/admin/logs/{log_id}, GET /api/admin/audit.

Database liên quan: audit_trail.

Component chính: admin_app/src/pages/LogsAdmin.jsx, backend/app/api/admin_logs.py, backend/app/core/audit.py.

Tính năng lâm sàng & hỗ trợ hướng-con-người (HITL)

Mục đích: đưa hỗ trợ vượt khỏi "trò chuyện" — cho người dùng kế hoạch cụ thể, chuyển sang người thật mượt mà, và minh bạch dữ liệu. Tất cả đều intent-gated, gate khỏi crisis bằng has_acute_risk (câu crisis luôn rơi về hotline/clinician), grounded chỉ trên điều user thực sự nói, và khôi phục thẻ khi mở lại thread (get_conversation re-attach từ analysis).

Cơ sở nghiên cứu: can thiệp digital mental health có human support hiệu quả hơn bản tự dùng hoàn toàn, nhất là với triệu chứng cao (→ Handoff/Briefing); minh bạch dữ liệu bám đúng 5 lớp APA (privacy/security, clinical foundation, usability, customization, data integration → Data Control); và loạt vụ kiện chatbot 2026 về việc AI xác nhận/làm nặng trạng thái nguy hiểm (→ Dependency Guard).

API bổ sung: GET/PUT /me/safety-plan · GET/POST /me/roadmaps + POST /me/roadmaps/draft + GET /me/roadmaps/suggest + PATCH/DELETE /me/roadmaps/{id} · GET /me/coping-plan · POST /me/handoff/summary · POST /me/handoff/message · export bổ sung safety_plan/roadmaps/coping_plan.

7. Luồng Nghiệp Vụ Chính

User onboarding và chat

1. User đăng ký bằng Gmail hoặc đăng nhập.
2. Backend trả JWT và flags consent_required, intake_required.
3. User chấp nhận consent.
4. User submit intake.
5. User vào chat và gửi message.
6. Backend resolve conversation, kiểm tra rate limit và chạy safety triage.
7. Nếu L0: trả crisis resources, không sinh AI reply.
8. Nếu L1: tạo pending review, không sinh AI draft.
9. Nếu L2: sinh draft, lưu draft, đưa vào review queue.
10. Nếu L3: sinh draft, kiểm tra preflight/grounding gate; nếu đạt thì auto-send, nếu không thì pending review.
11. Chat turn được ghi vào sessions, drafts, conversations và dual-write sang ai_messages/moderation_queue.

Screening và theo dõi rủi ro

1. User làm PHQ-9/GAD-7 trong user app.
2. Backend tính/lập mức độ screening và lưu screenings.
3. User xem latest/history.
4. Admin xem screening trên admin app, xem detail và thêm note.
5. Dashboard/reports lấy aggregate từ screenings.

AI moderation

1. Chat turn L1/L2 hoặc L3 bị gate fail tạo review_queue.
2. Admin vào AI Moderation.
3. Admin claim item.
4. Admin approve draft, edit response, reject hoặc mark need improvement.
5. Backend cập nhật sessions, review_queue và audit trail.
6. Lịch sử moderation hiển thị trong history endpoint.

Case management

1. Các item risk/queue có thể được xem như case.
2. Admin filter/list cases.
3. Admin assign clinician, escalate, add note, close/reopen.
4. Backend cập nhật assignment/status/history và audit.

Dashboard tổng hợp

1. Admin dashboard gọi summary/charts/recent endpoints.
2. Backend aggregate users, sessions, screenings, review queue và audit.
3. UI hiển thị KPI, chart, pending attention và recent activity.

8. Quyền Người Dùng

Lưu ý: schema roles, permissions, role_permissions, admin_users đã có. API authorization hiện tại chủ yếu dùng auth.require_admin và check role string.

9. API Theo Module

Auth / Onboarding

Chat / Conversations

Screening

Content

Experts / Appointments

Admin

Health / Monitoring

10. Database

Core tables

Admin / moderation tables

Lưu ý quan trọng: ai_messages và moderation_queue đã được ghi bổ sung từ chat pipeline, nhưng API moderation hiện tại vẫn đọc legacy review_queue/sessions.

11. UI/UX

User app screens

Admin app screens

UX note:

• User app điều hướng bằng state trong App.jsx, không dùng React Router.
• Admin app map pathname thủ công trong admin_app/src/App.jsx.
• Admin có hai pattern shell: một số page dùng AppShell, một số page tự render shell riêng.