Phase 7: Hoàn thiện Modular RAG Backend với FastAPI và Đa LLM Provider

doc/6.Operations-Monitoring-Governance-Playbook.md

@@ -0,0 +1,241 @@
+# 6.Operations-Monitoring-Governance-Playbook.md
+
+> Tài liệu này mô tả **cách vận hành, giám sát và kiểm soát** toàn bộ hệ thống SharePoint → Search → RAG Chat trong môi trường doanh nghiệp.
+> Đây là tài liệu **rất quan trọng sau PoC**, đảm bảo hệ thống **bền vững, an toàn, có thể mở rộng và được tin cậy lâu dài**.
+>
+> File được viết để:
+> - IT / Ops / Security đọc là hiểu
+> - AI agent đọc là biết cách triển khai monitoring
+> - Là nền tảng cho **quy trình vận hành & governance nội bộ**
+
+---
+
+## Mục lục
+1. Mục tiêu Operations & Governance
+2. Nguyên tắc vận hành
+3. Tổng quan các tầng cần giám sát
+4. Monitoring chi tiết theo từng tầng
+5. KPI & Quality Metrics
+6. Alerting & Incident Response
+7. Logging & Audit Trail
+8. Data Governance & Compliance
+9. Model / Prompt Governance
+10. User Feedback Loop
+11. Backup, Rollback & Disaster Recovery
+12. Phân quyền vận hành (Ops Roles)
+13. Checklist vận hành định kỳ
+
+---
+
+## 1. Mục tiêu Operations & Governance
+
+Hệ thống không chỉ cần "chạy được", mà phải:
+- ✅ Ổn định
+- ✅ Đúng dữ liệu
+- ✅ Đúng quyền
+- ✅ Truy vết được
+- ✅ Giải thích được
+
+Mục tiêu cuối cùng:
+> **Người dùng tin – IT kiểm soát – Ban lãnh đạo yên tâm**
+
+---
+
+## 2. Nguyên tắc vận hành
+
+1. **Fail rõ ràng, không fail im lặng**
+2. **Mỗi tài liệu đều có lifecycle**
+3. **Mỗi câu trả lời đều có log & nguồn**
+4. **AI không được vượt quyền dữ liệu**
+5. **Có thể rollback bất kỳ tầng nào**
+
+---
+
+## 3. Tổng quan các tầng cần giám sát
+
+```text
+[SharePoint]
+   ↓
+[Ingestion]
+   ↓
+[Extraction / OCR]
+   ↓
+[Index / Search]
+   ↓
+[RAG Chat]
+```
+
+Mỗi tầng phải có:
+- Health check
+- Metric
+- Log
+
+---
+
+## 4. Monitoring chi tiết theo từng tầng
+
+### 4.1 Ingestion Layer
+
+**Theo dõi:**
+- Số file quét / phút
+- Delta sync success rate
+- File fail theo loại lỗi
+
+**Cảnh báo khi:**
+- Delta token không cập nhật > N giờ
+- Lỗi permission tăng đột biến
+
+---
+
+### 4.2 Extraction / OCR Layer
+
+**Theo dõi:**
+- Thời gian OCR / trang
+- OCR failure rate
+- Queue length
+
+**Cảnh báo khi:**
+- OCR latency vượt ngưỡng
+- OCR fail liên tục cùng 1 file type
+
+---
+
+### 4.3 Index / Search Layer
+
+**Theo dõi:**
+- Query latency (p50/p95)
+- Index size
+- Search error rate
+
+**Cảnh báo khi:**
+- Query > SLA
+- Index out-of-sync
+
+---
+
+### 4.4 RAG Chat Layer
+
+**Theo dõi:**
+- Số câu hỏi / ngày
+- % câu trả lời "không tìm thấy dữ liệu"
+- Thời gian phản hồi
+
+**Cảnh báo khi:**
+- Error LLM
+- Citation missing
+
+---
+
+## 5. KPI & Quality Metrics
+
+### 5.1 KPI kỹ thuật
+- Ingestion success rate ≥ 99%
+- OCR success rate ≥ 95%
+- Search latency ≤ 3s
+
+### 5.2 KPI người dùng
+- Query có kết quả hữu ích ≥ X%
+- Click vào tài liệu gốc ≥ Y%
+
+---
+
+## 6. Alerting & Incident Response
+
+### 6.1 Nguyên tắc
+- Alert phải **actionable**
+- Có owner rõ ràng
+
+### 6.2 Incident Flow
+```text
+Detect → Triage → Mitigate → Root cause → Post-mortem
+```
+
+---
+
+## 7. Logging & Audit Trail
+
+### 7.1 Log bắt buộc
+- Ingestion log (file-level)
+- Search log (query-level)
+- Chat log (question, context, answer, citation)
+
+### 7.2 Audit sử dụng khi:
+- Khiếu nại kết quả AI
+- Compliance / kiểm toán
+
+---
+
+## 8. Data Governance & Compliance
+
+### 8.1 Nguyên tắc dữ liệu
+- File gốc không rời SharePoint
+- Không lưu dữ liệu ngoài phạm vi cho phép
+
+### 8.2 Retention
+- Metadata & log theo chính sách công ty
+- Cho phép purge theo yêu cầu
+
+---
+
+## 9. Model / Prompt Governance
+
+### 9.1 Versioning
+- Prompt phải có version
+- Model phải có version
+
+### 9.2 Thay đổi phải:
+- Có test
+- Có rollback plan
+
+---
+
+## 10. User Feedback Loop
+
+### 10.1 Thu thập feedback
+- Nút "Câu trả lời hữu ích / không hữu ích"
+- Comment ngắn
+
+### 10.2 Sử dụng feedback để:
+- Điều chỉnh prompt
+- Điều chỉnh search ranking
+
+---
+
+## 11. Backup, Rollback & DR
+
+- Backup index định kỳ
+- Có thể rebuild index từ Extraction output
+- DR plan cho:
+  - OpenSearch
+  - Metadata DB
+
+---
+
+## 12. Phân quyền vận hành (Ops Roles)
+
+| Role | Trách nhiệm |
+|----|-------------|
+| System Admin | Hạ tầng |
+| Data Admin | Ingestion/Search |
+| AI Admin | Prompt/Model |
+| Auditor | Log/Compliance |
+
+---
+
+## 13. Checklist vận hành định kỳ
+
+### Hàng ngày
+✅ Ingestion health
+✅ OCR queue
+
+### Hàng tuần
+✅ Re-index test
+✅ Permission sync
+
+### Hàng tháng
+✅ Prompt review
+✅ Compliance review
+
+---
+
+*Kết thúc Operations & Governance Playbook. Đây là file hoàn thiện hệ thống ở mức enterprise.*