Bản lưu kiến trúc v6.1 trước tích hợp camera
Lưu ngày 26/09/2026. Chỉ dùng truy vết, không dùng để triển khai.
Xem kiến trúc hiện hành.
Nội dung bên dưới được giữ nguyên trong khối mã; đường dẫn thuộc vị trí file cũ.
# Kiến trúc Dự án — Trợ lý AI Cơ Xương Khớp Tuổi Bạc (CXK)
> **Ngày:** 26/09/2026 | **Phiên bản:** v6.1
> **NCS1:** Võ Trần Gia Hiếu — Core MVP | **NCS2:** Đỗ Đoàn Anh Tuấn — Camera POC
> **CVYK:** Lương y Vũ Thế Sỹ | **GVHD:** Nguyễn Đảm
> **Hạ tầng:** IIS 10 + Windows Server 2022 + MSSQL 2022 + GPU
> **Trạng thái:** Đề xuất — cần GVHD duyệt
### Tài liệu liên quan
| File | Nội dung |
|---|---|
| **[ROADMAP.md](../ROADMAP.html)** | Roadmap triển khai chi tiết 8 sprint + Camera C1–C3 |
| **[PHAN_TICH_DU_AN.md](../PHAN_TICH_DU_AN.html)** | Gap analysis, rủi ro, đánh giá tính khả thi, Quick Wins |
| [CAMERA_MODULE_TASK_BOARD.md](../CAMERA_MODULE_TASK_BOARD.html) | Task board camera NCS2 |
| [DE_CUONG_NGHIEN_CUU.md](../../reports/DE_CUONG_NGHIEN_CUU.html) | Đề cương nghiên cứu |
| [NGUON_THAM_KHAO.md](../../references/NGUON_THAM_KHAO.html) | Nguồn tham khảo (61 nguồn) |
| [DEEP_RESEARCH_CAMERA.md](../../reports/DEEP_RESEARCH_CAMERA.html) | Nghiên cứu khả thi camera |
| [CHIEN_LUOC_BAO_VE_PL8.md](../../reports/CHIEN_LUOC_BAO_VE_PL8.html) | Chiến lược bảo vệ PL8 |
---
## 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 + GPU
### Mở rộng: Module Camera Quan sát Cử động (v6.0)
> **Phán quyết:** GO CÓ ĐIỀU KIỆN (65.1/100) | **Phương án:** P2 — POC | **Phụ trách:** NCS2
Dự án đã nghiên cứu khả thi bổ sung chức năng quan sát cử động (movement observation) bằng camera. Kết quả:
- Camera chỉ quan sát được 25-30% cờ đỏ y khoa (triệu chứng vận động).
- MediaPipe BlazePose chạy trên trình duyệt, xử lý tại thiết bị (on-device), không lưu video.
- NCS2 (Đỗ Đoàn Anh Tuấn) triển khai độc lập, không ảnh hưởng tiến độ MVP của NCS1.
- CVYK đã chấp nhận ngưỡng TUG/5STS quốc tế làm tham chiếu.
- Xem chi tiết: [Báo cáo nghiên cứu 12](../../reports/DEEP_RESEARCH_CAMERA.html) | [Task board camera](../CAMERA_MODULE_TASK_BOARD.html)
---
## 2. Phân tích Dự án
> Phần phân tích gap, rủi ro, đánh giá tính khả thi, và Quick Wins đã chuyển sang → **[PHAN_TICH_DU_AN.md](../PHAN_TICH_DU_AN.html)**
---
## 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
│ │ │ └── YEU_CAU_GOC.md
│ │ │ 📦 CŨ Research/01_*.md
│ │ │
│ │ ├── reports/ Báo cáo nghiên cứu
│ │ │ ├── BAO_CAO_NGHIEN_CUU_TONG_THE.md
│ │ │ │ 📦 CŨ Research/02_*.md (70 KB, 36 nguồn)
│ │ │ ├── DE_CUONG_NGHIEN_CUU.md
│ │ │ │ 📦 CŨ Research/03_*.md
│ │ │ └── TONG_HOP_NGHIEN_CUU_ARCHIVE.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
│ │ │ ├── KIEN_TRUC_DU_AN.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
│ │ │ └── NGUON_THAM_KHAO.md
│ │ │ 📦 CŨ Research/07_*.md (36 nguồn + SHA)
│ │ │
│ │ └── prompts/ Prompt nghiên cứu
│ │ └── 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/
| File cũ | Vị trí mới | Lý do |
|---|---|---|
| `Research/00_MUC_LUC.md` | `docs/research/00_MUC_LUC.md` | Mục lục bộ nghiên cứu → giữ nguyên tên, đặt ở gốc research |
| `Research/01_YEU_CAU_GOC_*.md` | `docs/research/requirements/01_*.md` | Yêu cầu và phạm vi dự án → nhóm requirements |
| `Research/02_BAO_CAO_*.md` | `docs/research/reports/02_*.md` | Báo cáo nghiên cứu tổng thể → nhóm reports |
| `Research/03_TOM_TAT_*.md` | `docs/research/reports/03_*.md` | Đề cương nghiên cứu → nhóm reports |
| `Research/04_KE_HOACH_*.md` | `docs/research/plans/04_*.md` | Kế hoạch 16 tuần → nhóm plans |
| `Research/05_TUAN_1_*.md` | `docs/research/plans/05_*.md` | Kế hoạch tuần 1 v1 → nhóm plans |
| `Research/06_TUAN_1_*.md` | `docs/research/plans/06_*.md` | Kế hoạch tuần 1 v2 → nhóm plans |
| `Research/07_NGUON_*.md` | `docs/research/references/07_*.md` | Danh mục nguồn → nhóm references |
| `Research/08_TOAN_BO_*.md` | `docs/research/reports/08_*.md` | Bản gộp → nhóm reports |
| `Research/09_PROMPT_*.md` | `docs/research/prompts/09_*.md` | Prompt deep research → nhóm prompts |
| `Research/10_KIEN_TRUC_*.md` | `docs/research/plans/10_*.md` | Kiến trúc & kế hoạch → nhóm plans |
#### Knowledge/ → knowledge-base/sources/
| File/Thư mục cũ | Vị trí mới | Lý do |
|---|---|---|
| `Knowledge/Huong_Dan_Chan_Doan_*.md` | `knowledge-base/sources/guidelines/byt-qd361/` | Hướng dẫn chính thống BYT → nhóm guidelines |
| `Knowledge/DHYHN/Tap1/*.md` | `knowledge-base/sources/textbooks/dhyhn/tap1/` | Sách giáo khoa → nhóm textbooks |
| `Knowledge/DHYHN/Tap2/*.md` | `knowledge-base/sources/textbooks/dhyhn/tap2/` | Sách giáo khoa → nhóm textbooks |
| `Knowledge/DHYHN/Tap1/*.py` | `knowledge-base/sources/utilities/` | Scripts OCR → gom chung utilities |
| `Knowledge/DHYHN/Tap2/*.py` | `knowledge-base/sources/utilities/` | Scripts OCR → gom chung utilities |
| `Knowledge/DHYHN/Tap1/.progress/` | `knowledge-base/sources/textbooks/dhyhn/tap1/.progress/` | Metadata tiến độ OCR → giữ cùng sách |
| `Knowledge/DHYHN/Tap2/.progress/` | `knowledge-base/sources/textbooks/dhyhn/tap2/.progress/` | Metadata tiến độ OCR → giữ cùng sách |
### 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`:**
```markdown
# ⚠️ 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`:**
```markdown
# ⚠️ 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
| Loại | Quy ước | Ví dụ |
|---|---|---|
| Thư mục | `kebab-case` | `knowledge-base`, `context-loader` |
| File Python | `snake_case.py` | `safety_engine.py` |
| File YAML/JSON | `snake_case.yaml` | `source_registry.csv` |
| Knowledge Card | `KC-{NHÓM}-{SỐ}_{mô_tả}.md` | `KC-OA-001_exercise.md` |
| Test Case | `TC-{NHÓM}-{SỐ}.yaml` | `TC-RED-015.yaml` |
| FAQ | `faq_{nhóm}.yaml` | `faq_knee_oa.yaml` |
| Clinical Case | `CASE-{MÀU}-{SỐ}.yaml` | `CASE-RED-003.yaml` |
| Diary entry | `YYYY-MM-DD.md` | `2026-09-23.md` |
| Research file | Giữ tên gốc `NN_TEN_*.md` | `BAO_CAO_NGHIEN_CUU_TONG_THE.md` |
| Source file | Giữ tên gốc từ OCR | `21-thoai-hoa-khop.md` |
---
## 4. Implementation Roadmap
### 4.1 Tech Stack Recommendation (So sánh 2 giai đoạn)
| Component | Giai đoạn 1: Obsidian-Markdown | Giai đoạn 2: Hybrid |
|---|---|---|
| Knowledge Mgmt | Obsidian vault (local-first) | Obsidian (source of truth) |
| Retrieval | Context Loader (đọc file MD → nạp prompt) | Semantic Router + Context Cache + RAG fallback |
| Vector DB | **Không có** | ChromaDB/Qdrant |
| Embedding | **Không có** | text-embedding-004 |
| LLM | Gemini 2.5 Pro/Flash (1M context) | Gemini 2.5 Pro + Context Caching |
| Backend | Python + FastAPI behind IIS | Giữ nguyên |
| Frontend | Vue 3 (IIS serve static) | Giữ nguyên |
| Database | MSSQL 2022 | Giữ nguyên |
| Server | IIS 10 / Windows Server 2022 | Giữ nguyên |
| Voice | Google Cloud STT/TTS | Giữ nguyên |
| Telegram | python-telegram-bot | Giữ nguyên |
| Monitoring | Langfuse + IIS logs + MSSQL audit | Giữ nguyên |
#### 4.2 Sơ đồ Hạ tầng Giai đoạn 1 (KHÔNG có ChromaDB)
```mermaid
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)
```mermaid
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"]
```
> Sprint Plan chi tiết (8 Sprint + Camera C1–C3) đã chuyển sang → **[ROADMAP.md](../ROADMAP.html)**
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).
---
> Quick Wins và trạng thái thực hiện đã chuyển sang → **[PHAN_TICH_DU_AN.md](../PHAN_TICH_DU_AN.html)** (Section 5)
---
## 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.
### 7.5 ADR-005: Camera là công cụ quan sát, không phải công cụ chẩn đoán
- **Context:** Luật KCB 15/2023/QH15 — chỉ người có chứng chỉ hành nghề mới được chẩn đoán. Phần mềm đo vận động có nguy cơ bị xếp là trang thiết bị y tế nếu đưa kết luận bệnh.
- **Decision:** Camera chỉ "quan sát", "ghi nhận dấu hiệu", "gợi ý đi khám". Tuyệt đối không dùng từ "chẩn đoán", "xác định bệnh", "loại trừ", "bình thường hoàn toàn".
- **Consequences:** Tránh vi phạm Luật KCB; giảm rủi ro RSK-CAM-005. Hạn chế: kết quả có thể kém "ấn tượng" so với chẩn đoán trực tiếp.
- **Trigger:** Áp dụng ngay khi viết bất kỳ ngôn ngữ trả kết quả nào cho module camera.
### 7.6 ADR-006: Xử lý tại thiết bị, chỉ lưu chỉ số, không lưu video
- **Context:** Luật BVDLCN 91/2025/QH15 — video/hình ảnh là dữ liệu cá nhân, khung xương số có thể là dữ liệu sinh trắc (biometric data) nhạy cảm. >800.000 camera VN bị rò rỉ 2024.
- **Decision:** Dùng MediaPipe WASM xử lý trên trình duyệt. Video bị huỷ ngay sau khi tính chỉ số. Chỉ gửi chỉ số số học về server. Tỷ lệ video lưu = 0%.
- **Consequences:** Triệt tiêu rủi ro RSK-CAM-006 (rò rỉ hình ảnh). Hạn chế: không thể review lại video khi cần kiểm tra sai số.
- **Trigger:** Áp dụng cho mọi phiên bản module camera (POC và sau).
### 7.7 ADR-007: Camera triển khai POC song song MVP, do NCS2 phụ trách
- **Context:** Phán quyết GO CÓ ĐIỀU KIỆN (65.1/100). NCS2 (Đỗ Đoàn Anh Tuấn) chuyên trách camera, không ảnh hưởng tiến độ MVP của NCS1.
- **Decision:** NCS2 triển khai POC (P2) song song với MVP core. Tích hợp vào sản phẩm chỉ khi MVP core ≥80% deliverables.
- **Consequences:** Tận dụng nguồn lực NCS2 mà không kích hoạt RSK-014 (scope creep). NCS2 báo cáo tiến độ cùng phiên với NCS1.
- **Trigger kích hoạt tích hợp:** MVP ≥80% + CVYK ký ≥3 ngưỡng + POC camera đạt Camera Gate A.
---
## 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
| Chỉ số (Metric) | Ngưỡng Giai đoạn 1 | Ngưỡng kích hoạt GĐ 2 (Hybrid) | Phân tích tác động |
|---|---|---|---|
| **Dung lượng Vault** | < 3 MB (~750K tokens) | **> 3 MB** | Vượt mức này dễ gây tràn context, tăng độ trễ và chi phí. Cần định tuyến để chỉ nạp file cần thiết. |
| **Lưu lượng truy vấn (Traffic)** | < 100 queries/ngày | **> 100 queries/ngày** | Cost API sẽ tăng mạnh nếu nhồi toàn bộ context mỗi lần gọi. Cần RAG hoặc Context Cache để giảm chi phí. |
| **Độ trễ (Latency)** | < 5s text, < 8s voice | **Liên tục > 10s** | Việc gửi và xử lý > 500K tokens bắt đầu làm chậm hệ thống, gây UX kém cho NCT. |
| **Đa miền (Multi-domain)** | Chỉ 7 nhóm CXK | **Mở rộng sang tim mạch, hô hấp** | Khi có nhiều miền kiến thức khác nhau, việc nạp tài liệu không liên quan vào prompt làm nhiễu AI. |
### 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.