Kiến trúc Project và Kế hoạch Triển khai — Trợ lý AI Cơ Xương Khớp Tuổi Bạc

Ngày: 25/09/2026 | Cập nhật: v5.0
Nghiên cứu sinh: Võ Trần Gia Hiếu (thực hiện từ prompt 09_PROMPT_DEEP_RESEARCH_KIEN_TRUC_PROJECT.md v3.0)
Phạm vi: Phân tích toàn bộ thư mục Research/ (10 file, ~560 KB) và Knowledge/ (1 file + 104 chương sách, ~2.1 MB)
Bối cảnh: Đề tài nghiên cứu khoa học (NCKH) | Hạ tầng: IIS + Windows Server 2022 + MSSQL 2022
Trạng thái: Đề xuất — cần review và phê duyệt trước khi triển khai

---

1. Executive Summary

Dự án "Trợ lý AI hỗ trợ người cao tuổi tự chăm sóc hệ vận động" thuộc đề tài nghiên cứu khoa học của công ty Vaga. Dự án đã có nền tảng nghiên cứu rất vững: 1 báo cáo tổng thể ~70 KB với 36 nguồn quốc tế, 1 đề cương 3 phần, 1 kế hoạch 16 tuần chi tiết đến từng ngày, 2 bản triển khai Tuần 1, và ~2 MB tài liệu y khoa đã số hóa (Hướng dẫn BYT + sách ĐHYHN).

Dựa trên kết quả từ báo cáo deep research về Obsidian-Markdown vs RAG, dự án sẽ áp dụng chiến lược 2 giai đoạn để đảm bảo tính khả thi, an toàn và tối ưu nguồn lực.

Chiến lược 2 giai đoạn:

1. Giai đoạn 1 (Sprint 1–8): Obsidian-Markdown thuần
   - KHÔNG có RAG, KHÔNG có vector DB, KHÔNG có embedding.
   - Nạp file trực tiếp vào context window lớn của LLM (Gemini 2.5 Pro/Flash hỗ trợ lên đến 1M tokens).
   - Lý do bỏ RAG cho giai đoạn 1:
   • An toàn y khoa: Không mất ngữ cảnh khi chunking, bảo toàn tính nguyên vẹn của thông tin y tế, đặc biệt là các cờ đỏ (red flag).
   • Đơn giản: 1 Nghiên cứu sinh quản lý được, không cần bảo trì pipeline phức tạp.
   • Context window đủ lớn: Tổng dữ liệu ~2MB < 1M tokens.
   • Minh bạch: Cố vấn y khoa (CVYK) đọc được chính xác những gì AI đọc thông qua giao diện Obsidian trực quan.
2. Giai đoạn 2 (post-MVP): Hybrid
   - Thêm Semantic Router + Context Caching + RAG fallback.
   - Trigger chuyển Hybrid: Dữ liệu > 3MB, traffic > 100 queries/ngày, latency > 10s.

Điểm mạnh đã có:
- Scope y khoa rõ ràng (7 nhóm bệnh/vấn đề MVP)
- Bộ lọc an toàn (safety layer) đã được thiết kế
- Pipeline phân vai AI–con người với 8 vai trò AI
- 4 cổng kiểm soát (quality gate) (Knowledge → Technical → Clinical → Pilot)
- Khung pháp lý và đạo đức đã được khảo sát
- Hạ tầng sẵn có: Windows Server 2022 + IIS + MSSQL 2022

---

2. Deep Research Findings

2.1 Tổng hợp Scope Dự án

Từ file 01 và 02, dự án có 4 giai đoạn:

Deliverable MVP (từ file 02, mục "Đề xuất lộ trình sản phẩm"):
1. Website hỏi đáp có nạp file vào Context + citations
2. Kho tri thức y khoa curated (thẻ tri thức - knowledge card)
3. Red-flag bộ lọc an toàn (safety layer)
4. 300–500 FAQ/cases có gold label
5. Clinician dashboard cơ bản
6. Bộ benchmark test độc lập
7. Báo cáo đề tài (đề cương + nhật ký + kết luận)

2.2 Gap Analysis

ĐÃ CÓ (trong Research/ và Knowledge/)

Đặc biệt quan trọng trong Knowledge/DHYHN/Tap2/:
- 14-viem-khop-dang-thap.md (39 KB)
- 21-thoai-hoa-khop.md (24 KB) ← Trực tiếp cho MVP
- 22-loang-xuong.md (32 KB) ← Trực tiếp cho MVP
- 25-nhiem-khuan-co-xuong-khop.md (30 KB)
- 27-dinh-huong-chan-doan-dau-xuong-khop.md (29 KB) ← Red flag rules
- 28-dau-vung-that-lung.md (52 KB) ← Trực tiếp cho MVP
- 20-benh-gut.md (45 KB) ← Safety corpus
- 35-kham-benh-o-nguoi-cao-tuoi.md trong Tap1 (58 KB) ← Lão khoa

CHƯA CÓ (cần tạo)

2.3 Rủi ro và Ràng buộc

2.4 Đánh giá Tính khả thi

Nguồn lực: 1 Nghiên cứu sinh part-time (~29h/tuần) + AI agent + CVYK part-time

Đánh giá:
- Kế hoạch 16 tuần trong file 04 là tham vọng nhưng có cấu trúc tốt
- File 06 cho thấy Tuần 1 đã được bóc tách rất chi tiết (12 deliverable)
- Rủi ro lớn nhất: CVYK không có đủ thời gian → bottleneck tại clinical review
- Điểm thuận lợi: AI agent có thể đảm nhận ~60% khối lượng (literature search, extraction, structuring, test generation, UI scaffolding). Áp dụng Obsidian-Markdown thuần cho Giai đoạn 1 giúp rút ngắn thời gian và đơn giản hoá việc CVYK review trực tiếp.
- Đề xuất thực tế: Chuyển từ 16 tuần sang 8 sprint (21 tuần), thời lượng mỗi sprint từ 2-3 tuần, có checkpoint giữa mỗi sprint, chấp nhận MVP tối giản hơn kế hoạch gốc.

---

3. Project Architecture — Kiến trúc Folder/File

3.1 Tree Diagram — Kiến trúc Tích hợp (file cũ + file mới)

Nguyên tắc tái cấu trúc:
- File đang có trong Research/ và Knowledge/ được di chuyển vào vị trí nghiệp vụ hợp lý
- Mỗi file cũ giữ nguyên nội dung, chỉ thay đổi vị trí
- Vị trí cũ để redirect stub (file nhỏ chứa link đến vị trí mới) để không gãy tham chiếu
- Ký hiệu: 📦 CŨ = file đã có được di chuyển đến, 🆕 = file mới cần tạo

CXK/
├── README.md                                    🆕 Giới thiệu dự án, cách cài đặt, link docs
│
│
│ ══════════════════════════════════════════════════
│  TẦNG 1: TÀI LIỆU DỰ ÁN & NGHIÊN CỨU
│ ══════════════════════════════════════════════════
│
├── docs/                                        🆕 Toàn bộ tài liệu dự án
│   │
│   ├── research/                                📦 CŨ ← từ Research/
│   │   ├── 00_MUC_LUC.md                       📦 CŨ Research/00_MUC_LUC.md
│   │   │
│   │   ├── requirements/                        Yêu cầu gốc & phạm vi
│   │   │   └── 01_YEU_CAU_GOC_VA_LICH_SU_NGHIEN_CUU.md
│   │   │                                        📦 CŨ Research/01_*.md
│   │   │
│   │   ├── reports/                             Báo cáo nghiên cứu
│   │   │   ├── 02_BAO_CAO_NGHIEN_CUU_TONG_THE.md
│   │   │   │                                    📦 CŨ Research/02_*.md (70 KB, 36 nguồn)
│   │   │   ├── 03_TOM_TAT_DE_CUONG_NGHIEN_CUU.md
│   │   │   │                                    📦 CŨ Research/03_*.md
│   │   │   └── 08_TOAN_BO_NOI_DUNG_NGHIEN_CUU.md
│   │   │                                        📦 CŨ Research/08_*.md (bản gộp)
│   │   │
│   │   ├── plans/                               Kế hoạch triển khai
│   │   │   ├── 04_KE_HOACH_TRIEN_KHAI_16_TUAN.md
│   │   │   │                                    📦 CŨ Research/04_*.md (79 KB)
│   │   │   ├── 05_TUAN_1_KE_HOACH_VA_DAU_RA_BAN_DAU.md
│   │   │   │                                    📦 CŨ Research/05_*.md
│   │   │   ├── 06_TUAN_1_TASK_CHI_TIET_VA_BIEU_MAU.md
│   │   │   │                                    📦 CŨ Research/06_*.md
│   │   │   ├── 10_KIEN_TRUC_VA_KE_HOACH_TRIEN_KHAI.md
│   │   │   │                                    📦 CŨ Research/10_*.md (file này)
│   │   │   ├── W1/                              🆕 Folder kế hoạch tuần (W1-W16)
│   │   │   └── W1_TASK_BOARD_CHI_TIET.md        🆕 Task board tuần
│   │   │
│   │   ├── references/                          Nguồn tham khảo
│   │   │   └── 07_NGUON_THAM_KHAO_VA_GHI_CHU_XUAT.md
│   │   │                                        📦 CŨ Research/07_*.md (36 nguồn + SHA)
│   │   │
│   │   └── prompts/                             Prompt nghiên cứu
│   │       └── 09_PROMPT_DEEP_RESEARCH_KIEN_TRUC_PROJECT.md
│   │                                            📦 CŨ Research/09_*.md
│   │
│   ├── project/                                 🆕 Tài liệu quản lý dự án
│   │   ├── project_charter.md                   🆕 Hiến chương dự án (từ nội dung file 01+02)
│   │   ├── intended_use.md                      🆕 Phạm vi sử dụng — pháp lý
│   │   ├── risk_register.md                     🆕 Đăng ký rủi ro
│   │   └── stakeholder_map.md                   🆕 Bản đồ các bên liên quan
│   │
│   ├── architecture/                            🆕 Quyết định kiến trúc
│   │   ├── ADR-001_rag_over_finetune.md         🆕 RAG thay vì fine-tune
│   │   ├── ADR-002_safety_first.md              🆕 Safety pre/post check
│   │   ├── ADR-003_voice_first_not_only.md      🆕 Voice-first, không voice-only
│   │   └── system_architecture.md               🆕 Sơ đồ tổng thể (Mermaid)
│   │
│   ├── gates/                                   🆕 Cổng kiểm soát (quality gate)
│   │   ├── gate_a_knowledge.md                  🆕 Gate A: Knowledge
│   │   ├── gate_b_technical.md                  🆕 Gate B: Technical
│   │   ├── gate_c_clinical.md                   🆕 Gate C: Clinical Safety
│   │   └── gate_d_pilot.md                      🆕 Gate D: Pilot/Go-live
│   │
│   ├── diary/                                   🆕 Nhật ký nghiên cứu
│   │   ├── _template.md                         🆕 Mẫu nhật ký
│   │   └── 2026-09-25.md                        🆕 Entry
│   │
│   ├── reports/                                 🆕 Báo cáo tiến độ
│   │   ├── weekly/
│   │   └── final/
│   │
│   ├── presentations/                           🆕 Bài trình bày NCKH
│   │   ├── kickoff/
│   │   │   ├── kickoff_outline.md               🆕 Outline bài trình bày khởi động
│   │   │   └── kickoff_slides.md                🆕 Nội dung slides (md → pptx)
│   │   ├── weekly/
│   │   │   └── weekly_progress_template.md      🆕 Template báo cáo tiến độ tuần
│   │   └── final/
│   │       ├── final_outline.md                 🆕 Outline bài bảo vệ cuối
│   │       └── final_slides.md                  🆕 Nội dung slides bảo vệ
│   │
│   └── legal/                                   🆕 Pháp lý
│       ├── privacy_impact_assessment.md         🆕 Đánh giá tác động quyền riêng tư
│       ├── data_processing_agreement.md         🆕 Thỏa thuận xử lý dữ liệu
│       └── license_audit.md                     🆕 Kiểm tra bản quyền tài liệu
│
│
│ ══════════════════════════════════════════════════
│  TẦNG 2: TRI THỨC Y KHOA (OBSIDIAN VAULT)
│ ══════════════════════════════════════════════════
│
│ ├── knowledge-base/                              🆕 Kho tri thức y khoa có cấu trúc (Obsidian Vault)
│   ├── README.md                                🆕 Quy trình tạo/duyệt thẻ tri thức
│   ├── MOCs/                                    🆕 Map of Content files cho Obsidian
│   │   ├── 00_Trang_chu.md                      🆕 MOC chính
│   │   └── MOC_Thoai_Hoa_Khop.md                🆕 MOC nhóm bệnh
│   │
│   ├── sources/                                 Tài liệu y khoa nguồn (raw)
│   │   │
│   │   ├── guidelines/                          Hướng dẫn chính thống
│   │   │   └── byt-qd361/
│   │   │       └── Huong_Dan_Chan_Doan_Va_Dieu_Tri_Cac_Benh_Co_Xuong_Khop.md
│   │   │                                        📦 CŨ Knowledge/Huong_Dan_*.md (540 KB)
│   │   │
│   │   ├── textbooks/                           Sách giáo khoa y khoa
│   │   │   └── dhyhn/                           Đại học Y Hà Nội
│   │   │       ├── README.md                    🆕 Mô tả nguồn, phiên bản, quyền sử dụng
│   │   │       ├── tap1/                        📦 CŨ Knowledge/DHYHN/Tap1/
│   │   │       │   ├── 02-viem-phe-quan-cap.md  ... (39 chương)
│   │   │       │   ├── 35-kham-benh-o-nguoi-cao-tuoi.md  ← Đặc biệt: Lão khoa
│   │   │       │   └── ...
│   │   │       └── tap2/                        📦 CŨ Knowledge/DHYHN/Tap2/
│   │   │           ├── 14-viem-khop-dang-thap.md
│   │   │           ├── 20-benh-gut.md
│   │   │           ├── 21-thoai-hoa-khop.md     ← Trực tiếp MVP
│   │   │           ├── 22-loang-xuong.md         ← Trực tiếp MVP
│   │   │           ├── 25-nhiem-khuan-co-xuong-khop.md
│   │   │           ├── 27-dinh-huong-chan-doan-dau-xuong-khop.md ← Cờ đỏ (red flag)
│   │   │           ├── 28-dau-vung-that-lung.md  ← Trực tiếp MVP
│   │   │           └── ... (65 chương)
│   │   │
│   │   └── utilities/                           📦 CŨ Scripts OCR/fix
│   │       ├── fix_ocr.py                       📦 CŨ DHYHN/Tap1/fix_ocr.py
│   │       ├── fix_more.py                      📦 CŨ DHYHN/Tap1/fix_more.py
│   │       ├── super_fix.py                     📦 CŨ DHYHN/Tap1/super_fix.py
│   │       ├── ocr_fix.py                       📦 CŨ DHYHN/Tap2/ocr_fix.py
│   │       └── refine.py                        📦 CŨ DHYHN/Tap2/refine.py
│   │
│   ├── taxonomy/                                🆕 Phân loại y khoa (bảng phân loại)
│   │   ├── msk_taxonomy_v1.yaml                 🆕 Phân loại bệnh/vấn đề CXK
│   │   ├── body_regions.yaml                    🆕 Vùng cơ thể
│   │   ├── symptoms.yaml                        🆕 Triệu chứng
│   │   └── risk_factors.yaml                    🆕 Yếu tố nguy cơ
│   │
│   ├── evidence-matrix/                         🆕 Ma trận bằng chứng
│   │   ├── source_registry.csv                  🆕 36+ nguồn (từ file 07)
│   │   └── evidence_pyramid.yaml                🆕 Phân tầng A→E (từ file 02)
│   │
│   ├── knowledge-cards/                         🆕 Thẻ tri thức (có cấu trúc Markdown + YAML)
│   │   ├── _schema.json                         🆕 Schema cho knowledge card (template)
│   │   ├── knee-oa/
│   │   │   ├── KC-OA-001_exercise.md            🆕 Thẻ tri thức mẫu
│   │   │   ├── KC-OA-002_red-flags.md
│   │   │   └── KC-OA-003_self-care.md
│   │   ├── low-back-pain/
│   │   ├── osteoporosis/
│   │   ├── sarcopenia/
│   │   ├── falls-prevention/
│   │   ├── neck-shoulder/
│   │   └── frailty/
│   │
│   ├── faq/                                     🆕 Ngân hàng câu hỏi
│   │   ├── _schema.json                         🆕 Schema cho FAQ
│   │   ├── faq_knee_oa.yaml
│   │   ├── faq_low_back.yaml
│   │   └── faq_general.yaml
│   │
│   └── case-bank/                               🆕 Ngân hàng tình huống lâm sàng
│       ├── _schema.json                         🆕 Schema cho clinical case
│       ├── green/                               Cases an toàn cho self-care
│       ├── amber/                               Cases cần thăm khám
│       └── red/                                 Cases khẩn cấp
│
│
│ ══════════════════════════════════════════════════
│  TẦNG 3: AN TOÀN Y KHOA
│ ══════════════════════════════════════════════════
│
├── safety/                                      🆕 An toàn y khoa
│   ├── README.md
│   ├── W1_D05_SafetyPolicy_v0.1.md              🆕 Chính sách an toàn (thay thế safety_charter)
│   ├── W1_D05_SafetyTests_v0.1.yaml             🆕 Bộ test an toàn (thay thế rules)
│   ├── risk_register.md                         🆕 Đăng ký rủi ro
│   └── disclaimers/
│       ├── vi_general.md                        🆕 Lời khuyên an toàn tiếng Việt
│       └── vi_emergency.md                      🆕 Cảnh báo khẩn cấp
│
│
│ ══════════════════════════════════════════════════
│  TẦNG 4: KỸ THUẬT & SẢN PHẨM
│ ══════════════════════════════════════════════════
│
├── context-loader/                              🆕 Xử lý dữ liệu nạp context (thay thế data-pipeline GĐ1)
│   ├── README.md                                (Ghi chú: Giai đoạn 2 sẽ khôi phục data-pipeline khi cần RAG)
│   ├── requirements.txt
│   ├── scripts/
│   │   ├── 01_extract_knowledge.py              Trích xuất sources/ → structured (không chunk)
│   │   ├── 02_load_files.py                     Đọc file MD từ Vault
│   │   ├── 03_build_prompt.py                   Ghép file thành prompt lớn
│   │   └── utils/
│   │       ├── markdown_parser.py
│   │       ├── frontmatter_reader.py
│   │       └── metadata_extractor.py
│   └── data/                                    (gitignored)
│
├── backend/                                     🆕 Server API
│   ├── README.md
│   ├── requirements.txt
│   ├── app/
│   │   ├── main.py                              FastAPI entry point
│   │   ├── config.py
│   │   ├── routers/
│   │   │   ├── chat.py                          Endpoint hỏi đáp
│   │   │   ├── search.py                        Endpoint tìm kiếm
│   │   │   └── health.py                        Health check
│   │   ├── services/
│   │   │   ├── context_service.py               Gọi context-loader (thay cho retriever)
│   │   │   ├── safety_engine.py                 Bộ lọc an toàn (Safety pre/post check)
│   │   │   ├── citation_engine.py               Truy vết nguồn (provenance)
│   │   │   ├── llm_service.py                   LLM integration (gọi Gemini)
│   │   │   ├── conversation.py                  Quản lý hội thoại
│   │   │   └── triage.py                        phân loại mức độ
│   │   ├── models/
│   │   │   ├── schemas.py                       Pydantic models
│   │   │   └── enums.py                         GREEN/AMBER/RED
│   │   └── middleware/
│   │       ├── logging.py                       Audit log
│   │       └── privacy.py                       PII filter
│   └── tests/
│       ├── test_context.py
│       ├── test_safety.py
│       └── test_citation.py
│
├── frontend/                                    🆕 Website accessibility-first
│   ├── README.md
│   ├── package.json
│   ├── public/
│   │   └── index.html
│   ├── src/
│   │   ├── App.vue
│   │   ├── components/
│   │   │   ├── ChatWindow.vue                   Cửa sổ chat chính
│   │   │   ├── MessageBubble.vue                Bong bóng tin nhắn
│   │   │   ├── VoiceInput.vue                   Nút nói
│   │   │   ├── CitationCard.vue                 Hiển thị nguồn
│   │   │   ├── EmergencyBanner.vue              Banner khẩn cấp
│   │   │   ├── FontSizer.vue                    Điều chỉnh cỡ chữ
│   │   │   └── SafetyDisclaimer.vue             Disclaimer
│   │   ├── styles/
│   │   │   ├── accessibility.css                WCAG 2.2 base
│   │   │   ├── elderly-theme.css                Theme tối giản cho NCT
│   │   │   └── high-contrast.css                Tương phản cao
│   │   └── assets/
│   └── tests/
│
├── voice/                                       🆕 STT/TTS integration
│   ├── README.md
│   ├── stt/
│   │   ├── stt_service.py                       Speech-to-Text wrapper
│   │   ├── transcript_confirmer.py              Xác nhận transcript
│   │   └── vietnamese_postprocess.py            Hậu xử lý tiếng Việt
│   └── tts/
│       ├── tts_service.py                       Text-to-Speech wrapper
│       └── voice_config.yaml                    Cấu hình giọng đọc
│
├── telegram-bot/                                🆕 Tích hợp Telegram
│   ├── README.md
│   ├── bot.py                                   Bot entry point
│   ├── handlers/
│   │   ├── text_handler.py
│   │   ├── voice_handler.py
│   │   └── webapp_handler.py                    Mini App
│   └── config.yaml
│
│
│ ══════════════════════════════════════════════════
│  TẦNG 5: KIỂM THỬ & NGHIÊN CỨU NGƯỜI DÙNG
│ ══════════════════════════════════════════════════
│
├── testing/                                     🆕 Kiểm thử
│   ├── README.md
│   ├── benchmark/
│   │   ├── testset_v1.yaml                      Bộ 100+ test cases
│   │   ├── gold_labels/                         Gold label từ CVYK
│   │   └── scoring_rubric.yaml                  Rubric chấm điểm
│   ├── red-team/
│   │   ├── adversarial_cases.yaml               Tình huống đối kháng
│   │   ├── misinformation_cases.yaml            Thông tin sai
│   │   └── edge_cases.yaml                      Biên case
│   ├── accessibility/
│   │   ├── wcag_checklist.md                    WCAG 2.2 checklist
│   │   └── elderly_usability.md                 Checklist cho NCT
│   ├── scripts/
│   │   ├── run_benchmark.py
│   │   ├── score_results.py
│   │   └── generate_report.py
│   └── results/                                 (gitignored)
│
├── user-research/                               🆕 Nghiên cứu người dùng
│   ├── README.md
│   ├── survey/
│   │   ├── survey_elderly_v1.md                 Bộ khảo sát NCT
│   │   └── survey_caregiver_v1.md               Bộ khảo sát người chăm sóc
│   ├── interview/
│   │   ├── interview_guide_elderly.md           Hướng dẫn PV người cao tuổi
│   │   ├── interview_guide_doctor.md            Hướng dẫn PV bác sĩ
│   │   └── coding_framework.yaml                Khung phân tích
│   ├── personas/
│   │   └── persona_template.yaml
│   ├── insights/
│   │   └── README.md                            Tổng hợp insight
│   └── consent/
│       └── consent_form_vi.md                   Mẫu đồng ý tham gia
│
│
│ ══════════════════════════════════════════════════
│  TẦNG 6: NỘI DUNG & VẬN HÀNH
│ ══════════════════════════════════════════════════
│
├── community/                                   🆕 Giáo dục & cộng đồng
│   ├── README.md
│   ├── education/
│   │   ├── content_matrix.yaml                  Ma trận nội dung (từ file 02)
│   │   ├── articles/                            Bài viết giáo dục
│   │   └── exercises/                           Bài tập đã duyệt
│   └── engagement/
│       ├── challenge_templates.yaml             Thử thách vận động
│       └── checkin_schedule.yaml                Lịch check-in
│
├── deployment/                                  🆕 Triển khai (IIS + Windows Server)
│   ├── iis/
│   │   ├── web.config                           🆕 IIS reverse proxy config
│   │   ├── applicationHost.config               🆕 IIS site binding
│   │   └── setup_iis.ps1                        🆕 Script cấu hình IIS
│   ├── database/
│   │   ├── init_schema.sql                      🆕 MSSQL schema khởi tạo
│   │   ├── migrations/                          🆕 Database migrations
│   │   └── seed_data.sql                        🆕 Dữ liệu khởi tạo
│   ├── .env.example
│   └── monitoring/
│       └── alerts.yaml
│
│
│ ══════════════════════════════════════════════════
│  GỐC: REDIRECT STUBS (giữ tương thích)
│ ══════════════════════════════════════════════════
│
├── Research/                                    ⚠️ REDIRECT STUBS
│   └── _MOVED.md                                Link đến docs/research/
│
├── Knowledge/                                   ⚠️ REDIRECT STUBS
│   └── _MOVED.md                                Link đến knowledge-base/sources/
│
│
│ ══════════════════════════════════════════════════
│  CONFIG
│ ══════════════════════════════════════════════════
│
├── .gitignore
├── pyproject.toml                               Python project config
└── Makefile                                     Lệnh tiện ích

3.2 Bảng Migration — Ánh xạ Cũ → Mới

Bảng này là kế hoạch di chuyển cụ thể. Mỗi file cũ có đường dẫn mới và lý do xếp vào vị trí đó.

Research/ → docs/research/

Knowledge/ → knowledge-base/sources/

3.3 Redirect Stubs

Sau khi di chuyển, tạo file _MOVED.md ở vị trí cũ để tránh gãy tham chiếu:

Research/_MOVED.md:

# ⚠️ Thư mục đã di chuyển

Toàn bộ nội dung Research/ đã được di chuyển đến `docs/research/`.

| Nhóm | Vị trí mới |
|---|---|
| Yêu cầu gốc | `docs/research/requirements/` |
| Báo cáo nghiên cứu | `docs/research/reports/` |
| Kế hoạch triển khai | `docs/research/plans/` |
| Nguồn tham khảo | `docs/research/references/` |
| Prompts | `docs/research/prompts/` |

Knowledge/_MOVED.md:

# ⚠️ Thư mục đã di chuyển

Toàn bộ nội dung Knowledge/ đã được di chuyển đến `knowledge-base/sources/`.

| Nhóm | Vị trí mới |
|---|---|
| Hướng dẫn BYT | `knowledge-base/sources/guidelines/byt-qd361/` |
| Sách ĐHYHN | `knowledge-base/sources/textbooks/dhyhn/` |
| Scripts OCR | `knowledge-base/sources/utilities/` |

3.4 Quy ước Đặt tên

---

4. Implementation Roadmap

4.1 Tech Stack Recommendation (So sánh 2 giai đoạn)

4.2 Sơ đồ Hạ tầng Giai đoạn 1 (KHÔNG có ChromaDB)

graph LR
    subgraph WS["Windows Server 2022"]
        IIS["IIS 10
Reverse Proxy
SSL + Static"]
        FastAPI["FastAPI
:8000
Context Loading + Safety"]
        MSSQL[("MSSQL 2022
Metadata
Audit Log")]
        TG["Telegram Bot
Service"]
        Vault["Obsidian Vault
(Synced Files)"]
    end
    User -->|HTTPS| IIS
    IIS -->|Proxy /api| FastAPI
    IIS -->|Static /| Frontend["Vue 3 Build"]
    FastAPI -->|Read Files| Vault
    FastAPI --> MSSQL
    FastAPI -->|API| LLM["Gemini 2.5
1M Context"]
    TG --> FastAPI

4.3 Sơ đồ Giai đoạn 2 (Thêm Router + Cache + RAG)

graph LR
    subgraph WS["Windows Server 2022"]
        IIS["IIS 10"]
        FastAPI["FastAPI :8000"]
        Router["Semantic Router"]
        Cache["Context Cache"]
        VDB["ChromaDB/Qdrant"]
        MSSQL[("MSSQL 2022")]
        Vault["Obsidian Vault"]
    end
    User --> IIS --> FastAPI
    FastAPI --> Router
    Router -->|"Đủ nhỏ"| Cache -->|"Nạp file"| Vault
    Router -->|"Đa domain"| VDB
    FastAPI --> MSSQL
    FastAPI --> LLM["Gemini 2.5"]

4.4 Sprint Plan (8 Sprint × 21 Tuần)

gantt
    title Lộ trình 21 tuần - 8 Sprint (Giai đoạn 1)
    dateFormat YYYY-MM-DD
    axisFormat %d/%m

    section Sprint 1 (2w)
    M0: Tái cấu trúc & Kickoff: s1, 2026-09-25, 14d
    section Sprint 2 (3w)
    M1: Vault & Taxonomy (Thoái hoá khớp): s2, after s1, 21d
    section Sprint 3 (3w)
    Knowledge (Đau lưng): s3, after s2, 21d
    section Sprint 4 (3w)
    M2: Gate A pass & Context Loader: s4, after s3, 21d
    section Sprint 5 (3w)
    M3 & M4: Safety, Backend & Gate B: s5, after s4, 21d
    section Sprint 6 (2w)
    M5 & M6: Frontend, Voice & Gate C: s6, after s5, 14d
    section Sprint 7 (3w)
    M7: Pilot 20-30 NCT: s7, after s6, 21d
    section Sprint 8 (2w)
    M8: Báo cáo cuối & Gate D: s8, after s7, 14d

Sprint 1: S1 (Tuần 1-2)

Workload summary: NCS: 36.2h/46h (78.7%) | CVYK: 2.4h/6.4h (37.5%)

Sprint 2: S2 (Tuần 3-5)

Workload summary: NCS: 24.4h/69h (35.4%) | CVYK: 9.0h/9.6h (93.8%)

Sprint 3: S3 (Tuần 6-8)

Workload summary: NCS: 20.8h/47h (44.3%) | CVYK: 9.6h/9.6h (100.0%)

Sprint 4: S4 (Tuần 9-11)

Workload summary: NCS: 25.4h/69h (36.8%) | CVYK: 8.5h/9.6h (88.5%)

Sprint 5: S5 (Tuần 12-14)

Workload summary: NCS: 24.4h/69h (35.4%) | CVYK: 4.8h/9.6h (50.0%)

Sprint 6: S6 (Tuần 15-16)

Workload summary: NCS: 26.6h/46h (57.8%) | CVYK: 1.2h/6.4h (18.7%)

Sprint 7: S7 (Tuần 17-19)

Workload summary: NCS: 47.8h/69h (69.3%) | CVYK: 1.2h/9.6h (12.5%)

Sprint 8: S8 (Tuần 20-21)

Workload summary: NCS: 44.0h/46h (95.7%) | CVYK: 4.8h/6.4h (75.0%)

4.5 Milestones & Critical Path

• M0 (Tuần 2): Project Kickoff
• M1 (Tuần 5): Obsidian Vault & Taxonomy hoàn chỉnh
• M2 (Tuần 11): ≥80 KC approved + Cổng kiểm soát A pass
• M3 (Tuần 14): Context Loader + Safety Engine hoạt động
• M4 (Tuần 14): Backend MVP + Cổng kiểm soát B pass
• M5 (Tuần 16): Frontend + Voice MVP
• M6 (Tuần 16): Cổng kiểm soát C (Clinical Safety) pass
• M7 (Tuần 19): Pilot hoàn thành
• M8 (Tuần 21): Báo cáo cuối + Cổng kiểm soát D

---

5. Academic Presentations (Deliverable NCKH)

Dự án này là một đề tài NCKH, cần các bài trình bày chuẩn mực.

5.1 Kickoff Meeting (Đầu Sprint 1)

• Mục tiêu: Thống nhất scope, phê duyệt kiến trúc và pipeline an toàn.
• Outline (10-15 slides):
  1. Đặt vấn đề: Nhu cầu tự chăm sóc CXK ở NCT.
  2. Mục tiêu nghiên cứu & Phạm vi.
  3. Phương pháp nghiên cứu y khoa (Evidence Pyramid).
  4. Kiến trúc hệ thống Giai đoạn 1 (FastAPI + IIS + MSSQL).
  5. Quy trình duyệt tri thức với Obsidian Vault.
  6. Context Engineering + Obsidian + Safety (điểm sáng tạo).
  7. Pipeline bảo vệ 3 lớp (Pre-check, Post-check, Provenance).
  8. Lộ trình 8 Sprint.

5.2 Weekly Progress (Mỗi thứ 6)

• Mục tiêu: Cập nhật tiến độ cho hội đồng / CVYK.
• Format (1 pager / 3 slides): Done tuần qua, Cần làm tuần tới, Blocker/Rủi ro.

5.3 Final Defense (Cuối Sprint 8)

• Mục tiêu: Bảo vệ kết quả nghiên cứu.
• Outline (20 slides):
  1. Tóm tắt vấn đề & Giải pháp đã thực hiện.
  2. Cơ sở khoa học & Quản trị rủi ro y khoa.
  3. Quá trình thu thập và số hóa tri thức.
  4. Quá trình xây dựng bộ lọc cờ đỏ (red flag).
  5. Đánh giá chất lượng qua 100 test cases (điểm benchmark).
  6. Cập nhật phương pháp (Tại sao dùng Obsidian-Markdown cho MVP).
  7. Kết quả thử nghiệm pilot.
  8. Bàn luận & Hạn chế.
  9. Hướng phát triển Giai đoạn 2 (Hybrid, RAG, mở rộng dữ liệu).

---

6. Quick Wins (Việc cần làm ngay trong Tuần 1)

Thay vì đi thẳng vào code phức tạp, hãy tạo đà bằng các Quick Wins do AI thực hiện:

1. QW-1: Dựng toàn bộ 6 tầng thư mục + 11 file REDIRECT STUBS (Script tự động).
2. QW-2: Chuyển 07_NGUON_THAM_KHAO thành source_registry.csv.
3. QW-3: Chuyển 7 nhóm bệnh từ file 02 thành msk_taxonomy_v1.yaml.
4. QW-4: Soạn safety_charter.md từ nội dung file 04.
5. QW-5: Soạn project_charter.md từ file 01, 02.
6. QW-6: Tạo file nhật ký 2026-09-25.md đầu tiên.
7. QW-7: Viết file kickoff_outline.md.
8. QW-8: Tạo evidence_pyramid.yaml.
9. QW-9: Trích xuất 3 thẻ tri thức (knowledge cards) đầu tiên cho Thoái hóa khớp (từ file ĐHYHN Tap2/21) làm mẫu để CVYK duyệt định dạng.
10. QW-10: Setup Obsidian vault + sync + MSSQL schema + IIS config.
11. QW-11: Tạo Obsidian templates (KC, FAQ, Case, MOC).

Next Steps sau khi duyệt kiến trúc này:
- Gọi tool triển khai script tạo Folder.
- Gọi AI Agent trích xuất CSV và YAML ban đầu.
- Cài Obsidian cho CVYK và thiết lập thư mục Vault.

---

7. Phụ lục: Architecture Decision Records (ADRs)

7.1 ADR-001: RAG (Context Loading) over Fine-tuning

• Context: Dự án cần AI cung cấp thông tin y khoa chính xác, không ảo giác, và phải trích dẫn được nguồn gốc. Dữ liệu y khoa (guidelines) thay đổi liên tục.
• Decision: Sử dụng kỹ thuật cấp ngữ cảnh trực tiếp (Context Loading) kết hợp truy vết nguồn (provenance), không fine-tune mô hình ngôn ngữ.
• Consequences: Đảm bảo được tính minh bạch và an toàn y khoa. Giảm chi phí huấn luyện. Đòi hỏi nỗ lực trong việc thiết kế kho tri thức và prompt.

7.2 ADR-002: Safety-First Architecture (Bộ lọc an toàn)

• Context: Dự án y tế có nguy cơ rất cao nếu AI đưa ra lời khuyên sai lầm, bỏ qua các cờ đỏ (red flags) cần cấp cứu.
• Decision: Bắt buộc áp dụng bộ lọc an toàn 3 lớp (Safety Layer): (1) Bộ lọc trước (Pre-check) nhận diện cờ đỏ, (2) Prompt cứng quy định giới hạn hệ thống, (3) Bộ lọc sau (Post-check) chặn các câu trả lời tự ý kê đơn hoặc chẩn đoán.
• Consequences: Có thể làm tăng độ trễ (latency). Cần nguồn lực để viết các quy tắc red_flag_rules.yaml. Cổng kiểm soát (quality gate) lâm sàng trở thành bắt buộc trước khi go-live.

7.3 ADR-003: Voice-First but Not Voice-Only

• Context: Đối tượng là người cao tuổi (NCT) thường thao tác gõ phím kém, cần giao diện dễ sử dụng. Tuy nhiên, nếu chỉ dùng voice, NCT có thể quên lời khuyên hoặc không kiểm chứng được transcript khi có lỗi nhận dạng giọng nói.
• Decision: Giao diện đặt nút Voice to và ở trung tâm, nhưng luôn hiển thị văn bản, yêu cầu người dùng xác nhận văn bản trước khi gửi, và trả kết quả bằng cả Text lớn lẫn Voice.
• Consequences: Tăng khối lượng công việc Frontend và tích hợp STT/TTS. Cần bộ kiểm tra transcript để xử lý tiếng Việt y khoa. Đảm bảo chuẩn tiếp cận WCAG.

7.4 ADR-004: Obsidian-Markdown thuần cho Giai đoạn 1, Hybrid cho Giai đoạn 2

• Context: Dự án CXK có khối lượng dữ liệu MVP nhỏ (~2MB), context window của LLM đã lên đến 1M tokens, nguồn lực chỉ có 1 NCS, và yêu cầu an toàn y khoa cao nhất (tránh đứt gãy ngữ cảnh khi chunk).
• Decision: Dùng Obsidian-Markdown thuần cho MVP (Nạp toàn bộ file vào prompt). Chuyển sang mô hình Hybrid khi dự án scale lên mức độ lớn hơn.
• Consequences:
• Đơn giản hóa Sprint 3 (không cần cài ChromaDB hay lập trình chunking/embedding pipeline).
• Tối ưu được thời gian review cho CVYK nhờ đọc file nguyên bản qua Obsidian graph.
• Phụ thuộc nhiều vào context window của Gemini, có thể tăng token cost nếu traffic lớn.
• Trigger chuyển giai đoạn: Dữ liệu > 3MB, traffic > 100 queries/ngày, latency > 10s, multi-domain.

---

8. Trigger chuyển Giai đoạn (Từ Obsidian-Markdown sang Hybrid RAG)

Khi MVP hoàn thành và nền tảng bước vào giai đoạn mở rộng, việc giữ nguyên 100% tài liệu trong context window cho mọi câu hỏi sẽ không còn tối ưu. Dưới đây là các ngưỡng và checklist để quyết định thời điểm bật Hybrid (Semantic Router + Context Cache + RAG fallback).

8.1 Bảng Trigger Conditions

8.2 Checklist chuyển giai đoạn (Pre-Hybrid Checklist)

Trước khi thực thi chuyển từ Obsidian thuần sang Hybrid, phải hoàn thành các bước sau:
- [ ] Phân tích log từ Giai đoạn 1: Liệt kê top 20% thẻ tri thức được truy xuất nhiều nhất để lên kế hoạch Caching.
- [ ] Khôi phục data-pipeline (viết script chunking và embedding).
- [ ] Thiết lập ChromaDB hoặc Qdrant trên Windows Server.
- [ ] Phát triển Semantic Router: Lấy câu hỏi user phân loại để quyết định có cần gọi RAG hay chỉ lấy 1 file Markdown.
- [ ] Chạy lại bộ benchmark test 100 cases. Đảm bảo điểm số an toàn lâm sàng (clinical safety) không giảm (≥ 95%).
- [ ] Duy trì quy trình duyệt nội dung qua Obsidian: CVYK vẫn làm việc trên Obsidian, các file duyệt xong sẽ kích hoạt trigger đẩy vào RAG.

8.3 Timeline dự kiến cho việc chuyển đổi

Việc chuyển từ Giai đoạn 1 sang Giai đoạn 2 dự kiến sẽ diễn ra vào Giai đoạn Thử nghiệm cộng đồng (sau Sprint 8), tùy thuộc vào kết quả thu thập từ Pilot và báo cáo đánh giá cuối kỳ. Quá trình chuyển đổi có thể mất thêm 1-2 Sprint để tích hợp an toàn mà không làm gián đoạn hệ thống.