Add read-only production runtime audit

docs-legacy/ke-hoach-showcase-cai-tien-2-tuan.md

@@ -0,0 +1,229 @@
+# Kế hoạch showcase cải tiến trong 2 tuần
+
+> Khoảng thời gian: **31/07/2026–14/08/2026**  
+> Thời lượng đề xuất: **15 phút trình bày + 5 phút hỏi đáp**  
+> Thông điệp chính: Trong hai tuần, dự án đi từ giao diện mock thành một hệ thống
+> RAG chạy end-to-end, có corpus kiểm soát provenance, retrieval theo cấu trúc,
+> câu trả lời được kiểm chứng và hạ tầng production có quan sát được.
+
+## 1. Mục tiêu của buổi showcase
+
+Sau buổi trình bày, người xem cần hiểu được bốn điều:
+
+1. Hệ thống đã tiến từ prototype sang pipeline chạy thật như thế nào.
+2. Các cải tiến không chỉ là UI hoặc đổi model, mà tập trung vào độ đúng,
+   khả năng kiểm chứng và failure mode an toàn.
+3. Mỗi tuyên bố cải tiến đều có code, test, eval, trace hoặc artifact chứng minh.
+4. Những gì chưa hoàn thành được nói rõ, không gọi bản kỹ thuật đang chạy là
+   một clinical decision support system đã được phê duyệt.
+
+## 2. Câu chuyện trước và sau
+
+| Hạng mục | Đầu kỳ 31/07 | Cuối kỳ 14/08 | Bằng chứng nên chiếu |
+|---|---|---|---|
+| Sản phẩm | Web chat dùng mock | Web gọi FastAPI RAG thật, có citation và evidence panel | Commit `b89a265`, `9e9cef7`; live hoặc video dự phòng |
+| Corpus | PDF chưa thành corpus production | 684 monograph, 15.100 chunk schema v4, có trang in và provenance | Census `chunks.jsonl`, readiness gates |
+| PDF phức tạp | Nguy cơ mất chữ, sai bảng/công thức | Repair chữ vector; bảng/công thức rủi ro được quarantine | Crop PDF và response `VERIFY_PDF` |
+| Retrieval | Dense-only hit@1 = 0,544; riêng chống chỉ định = 0,05 | Exact section routing đạt hit@1 = 1,000 trên 160 routing cases | Bảng eval trước–sau |
+| Generation | Chưa có answer layer chạy thật | Structured claims, citation bắt buộc, numeric grounding và entailment | Một response JSON và test guardrail |
+| Multi-turn | Chưa có luồng hội thoại thật | QueryFrame, kế thừa dữ kiện có điều kiện, clarify và circuit breaker | Demo liều trẻ em nhiều lượt |
+| Tra bệnh → thuốc | Chưa có nhánh grounded hoàn chỉnh | Keyword-first, dense fallback, candidate binding và safety stage 2 | Demo một condition query |
+| UX | Chat cơ bản | Quick replies, citation cards, PDF/evidence panel, abstain message rõ lý do | So sánh ảnh trước–sau |
+| Vận hành | Chạy local | EC2 + Docker Compose + Caddy + CI/CD | Sơ đồ topology và workflow |
+| Quan sát | Log rời rạc | Correlation ID, OpenTelemetry, Prometheus, Tempo và Grafana | Một trace thật theo stage |
+| Public safety | Chưa có lớp bảo vệ đầy đủ | Rate limiting, disclaimer cố định, prompt fencing và granular abstention | API payload + middleware |
+
+## 3. Run-of-show 15 phút
+
+### Phần 1 — Baseline và bài toán, 1 phút
+
+Chiếu giao diện/prototype ngày 31/07 và đặt câu hỏi:
+
+> Làm thế nào biến một PDF Dược thư 1.668 trang thành câu trả lời có thể lần
+> ngược đến đúng trang nguồn, mà không cho LLM tự suy diễn số liệu?
+
+Không đi sâu công nghệ ở phần này. Chỉ chốt baseline: web mock, chưa có corpus
+production, chưa có live RAG và chưa có deployment.
+
+### Phần 2 — PDF thành corpus có thể audit, 3 phút
+
+Chiếu một sơ đồ:
+
+```text
+PDF → spans/page map → repair → monograph/section
+    → chunks + provenance → embedding → Qdrant + manifest
+```
+
+Ba cải tiến cần nhấn mạnh:
+
+1. Không dùng `extract_text()` rồi chia đều; giữ bbox, trang vật lý và trang in.
+2. Khôi phục chữ chỉ tồn tại dưới dạng vector và chạy quality gates trước embed.
+3. Không flatten bảng/công thức chưa đáng tin; quarantine và yêu cầu xem PDF.
+
+Con số nên chiếu:
+
+- 684 monograph;
+- 15.100 chunk;
+- 14.949 prose chunk và 151 block descriptor;
+- 0 chunk vượt trần 800 token trong corpus được ghi nhận;
+- vector Cohere Embed v4, 1.024 chiều.
+
+### Phần 3 — Retrieval chuyển từ “gần nghĩa” sang “đúng mục”, 2 phút
+
+Đây là slide trước–sau quan trọng nhất:
+
+```text
+Dense-only:             hit@1 = 0,544
+Chống chỉ định:         hit@1 = 0,05
+Metadata section route: hit@1 = 1,000 / 160 routing cases
+```
+
+Giải thích logic:
+
+- Khi đã biết `drug_id + section_key`, Qdrant scroll toàn bộ đúng section.
+- Không dùng similarity để đoán giữa “chỉ định” và “chống chỉ định”.
+- Rerank dùng cho câu hỏi tự do; dense search là fallback có giới hạn.
+- Section dài được sắp lại theo `part_index`, không cắt thành một danh sách có
+  vẻ đầy đủ nhưng thực ra thiếu nội dung.
+
+### Phần 4 — LLM chỉ diễn đạt, không quyết định sự thật, 3 phút
+
+Chiếu pipeline:
+
+```text
+evidence → structured claims → numeric/citation check
+         → semantic entailment → completeness repair → response
+```
+
+Cho xem một claim JSON có `text` và `citations`. Sau đó nêu ba cổng:
+
+1. Claim có nội dung phải có citation hợp lệ.
+2. Mọi số phải xuất hiện nguyên văn trong đúng evidence được citation.
+3. LLM judge chỉ so claim với các block mà claim đã trích dẫn.
+
+Nếu một cổng thất bại, hệ thống trả `abstain` với lý do cụ thể; không âm thầm
+đưa raw evidence ra thay cho câu trả lời đã kiểm chứng.
+
+### Phần 5 — Chat thật và luồng nghiệp vụ mới, 3 phút
+
+Demo liên tục ba tình huống:
+
+1. **Tra đúng mục:** “Chống chỉ định của aspirin?” — chứng minh exact section
+   retrieval và citation đúng trang.
+2. **Multi-turn liều trẻ em:** nêu thuốc → “trẻ em” → cung cấp tuổi/cân nặng →
+   chứng minh hệ thống giữ dữ kiện, chỉ hỏi trường còn thiếu và không gán nhầm
+   liều giữa các nhóm.
+3. **Bệnh/chỉ định → thuốc:** câu hỏi condition rõ → danh sách factual candidate,
+   không xếp hạng first-line và không suy ra “an toàn”.
+
+Nếu còn thời gian, thêm case có bảng/công thức để trả `VERIFY_PDF`.
+
+### Phần 6 — Từ local đến production có quan sát, 2 phút
+
+Chiếu topology ngắn:
+
+```text
+Browser → Caddy → Next.js → FastAPI
+                         ↘ Qdrant
+                         ↘ PostgreSQL
+                         ↘ Bedrock
+                         ↘ OTel/Prometheus/Tempo/Grafana
+```
+
+Nêu các cải tiến:
+
+- Docker production và Caddy TLS;
+- GitHub Actions có CI checks và deploy path filter; hai workflow vẫn độc lập;
+- docs-only change không tự redeploy production;
+- correlation/trace ID đi xuyên request;
+- dashboard và stage timing cho receive, understanding, retrieval, generation,
+  grounding, entailment và persistence;
+- Helm/Qdrant snapshot bridge đã được chuẩn bị cho hướng di chuyển cluster,
+  nhưng Kubernetes chưa phải production hiện tại.
+
+### Phần 7 — Kết quả và giới hạn, 1 phút
+
+Kết bằng hai cột.
+
+**Đã chứng minh kỹ thuật:**
+
+- 278 AI-service tests và 277 ingestion tests pass trong lần kiểm kê;
+- corpus và point-count gate nhất quán;
+- section routing cải thiện retrieval đo được;
+- answer có grounding, citation và trace;
+- hệ thống đã chạy end-to-end trên production software stack.
+
+**Chưa được tuyên bố:**
+
+- chưa ingest Part 1 và Part 3;
+- bảng/công thức quarantine chưa được reconstruct đầy đủ;
+- production battery 60 case chưa có record hoàn tất toàn bộ;
+- chưa có authentication và data-governance đầy đủ;
+- chưa có clinical approval, nguồn hiện hành và review chuyên gia đủ để dùng như
+  công cụ quyết định điều trị.
+
+## 4. Kịch bản demo chi tiết
+
+| Demo | Điều cần chứng minh | Dấu hiệu thành công | Phương án dự phòng |
+|---|---|---|---|
+| Tên thuốc đơn | Overview không tải cả monograph | Intro sections, quick replies và citation | Response JSON đã lưu |
+| Chống chỉ định aspirin | Exact metadata routing | Citation có `section_key=chong_chi_dinh` | Test routing + screenshot |
+| Liều trẻ em nhiều lượt | Nhớ đúng context và hỏi đúng field thiếu | Không lặp câu hỏi; tuổi/cân nặng được giữ | Video quay trước |
+| Condition → drug | Candidate bị giới hạn bởi evidence chỉ định | Không có thuốc ngoài candidate set; không claim first-line | Eval JSONL + trace |
+| Bảng/công thức | Fail-closed ở dữ liệu 2D rủi ro | `VERIFY_PDF`, có crop/trang nguồn, không trích số | Crop tĩnh và API payload |
+| Prompt injection hoặc số bịa | Guardrail loại output | `uncited_claim`, `ungrounded_number` hoặc abstain tương ứng | Unit test thay vì live model |
+
+Không dùng live LLM để chứng minh một guardrail adversarial nếu kết quả có thể
+dao động. Với các case này, chạy test xác định hoặc chiếu trace đã lưu đáng tin
+cậy hơn.
+
+## 5. Bộ bằng chứng cần chuẩn bị
+
+### Bắt buộc
+
+- Một ảnh UI ngày đầu và một ảnh UI hiện tại.
+- Sơ đồ hai pipeline offline/online.
+- Census corpus 684/15.100.
+- Bảng retrieval 0,544 → 1,000.
+- Một structured claim và citation đã qua grounding.
+- Một trace end-to-end có correlation ID và stage timing.
+- Kết quả test AI service, ingestion và web build/lint.
+- Một slide limitations.
+
+### Dự phòng
+
+- Video demo 2–3 phút, không phụ thuộc mạng hoặc Bedrock.
+- Response JSON cho từng demo.
+- Screenshot Grafana/Tempo.
+- PDF crop của block quarantine.
+- Commit timeline rút gọn, chỉ giữ 8–10 milestone; không chiếu toàn bộ git log.
+
+## 6. Timeline chuẩn bị showcase
+
+| Thời điểm | Việc cần làm | Đầu ra |
+|---|---|---|
+| T-2 ngày | Chốt claim và số liệu; chạy lại test không tốn cloud | Evidence sheet có ngày chạy |
+| T-2 ngày | Chọn năm request demo và lưu JSON/trace | Demo fixture + trace ID |
+| T-1 ngày | Quay video dự phòng; chụp UI và dashboard | Media offline |
+| T-1 ngày | Dựng tối đa 10 slide theo run-of-show | Deck bản review |
+| T-4 giờ | Smoke test web, API, Qdrant và provider | Checklist xanh/đỏ |
+| T-1 giờ | Không deploy thêm; khóa môi trường demo | Build/version ghi rõ |
+| Sau buổi | Ghi câu hỏi chưa trả lời và claim cần kiểm chứng | Follow-up list |
+
+## 7. Nguyên tắc trình bày
+
+1. Luôn nói “đo được trên bộ eval nào”, không nói “độ chính xác 100%” chung chung.
+2. Tách rõ software production với clinical production approval.
+3. Không mô tả lexical matching hiện tại là BM25 hoặc hybrid RRF production.
+4. Không nói “không tìm thấy tương tác nghĩa là an toàn”.
+5. Không nói Kubernetes/ArgoCD đã production; hiện production vẫn là EC2 Compose.
+6. Ưu tiên một luồng end-to-end có bằng chứng hơn danh sách dài các commit.
+
+## 8. Câu kết đề xuất
+
+> Trong hai tuần, cải tiến lớn nhất không phải là thêm một chatbot vào PDF.
+> Dự án đã tạo được một chuỗi có thể audit từ trang sách đến từng claim trả cho
+> người dùng: dữ liệu có provenance, retrieval bị giới hạn theo cấu trúc, LLM bị
+> ràng buộc bởi evidence, và mọi câu trả lời đều có đường lần ngược qua citation
+> và trace. Phần tiếp theo là biến chất lượng kỹ thuật đó thành chất lượng vận
+> hành và lâm sàng được đánh giá đầy đủ.