# Kiến trúc và định hướng xây dựng hệ thống tra cứu tài liệu scan SharePoint

## 1. Mục tiêu tổng thể
Hệ thống nhằm giải quyết ba vấn đề cốt lõi trong doanh nghiệp:
1. **Biến kho tài liệu scan trên SharePoint thành dữ liệu có thể tìm kiếm theo ngữ nghĩa**.
2. **Tìm nhanh → đúng tài liệu → đúng vị trí trong tài liệu**.
3. **Giữ nguyên tính kiểm soát, phân quyền và tuân thủ (compliance)** của Microsoft 365.

Hệ thống không thay thế SharePoint, mà **tăng cường khả năng tra cứu và hiểu nội dung**.

---

## 2. Nguyên tắc thiết kế

### 2.1. Không lock-in
- Ưu tiên **Open Source** cho lõi xử lý.
- Có thể thay OCR / embedding / LLM trong tương lai.

### 2.2. File gốc là "nguồn chân lý"
- File **luôn ở SharePoint**.
- Hệ thống chỉ lưu **nội dung trích xuất + metadata + index**.

### 2.3. Permission-aware từ đầu
- Không index kiểu "public rồi filter sau".
- Mỗi kết quả search phải map được tới **ACL tương ứng trên SharePoint**.

---

## 3. Kiến trúc tổng thể (Logical Architecture)

```
SharePoint (Files, PDFs scan)
   │
   ▼
Ingestion & Sync Layer (tự viết – vibecode)
   │
   ├── Fetch file
   ├── Fetch metadata & permissions
   └── Versioning
   ▼
Extraction Layer
   │
   ├── OCR (scan PDF)
   └── MarkItDown (→ Markdown)
   ▼
Normalization & Enrichment
   │
   ├── Chunking
   ├── Metadata mapping
   └── Page / section anchoring
   ▼
Index Layer (OpenSearch)
   │
   ├── Full-text index
   ├── Vector index
   └── Metadata filter
   ▼
Search / Chat UI
   └── Click → mở đúng file SharePoint
```

---

## 4. Thành phần chi tiết và trách nhiệm

### 4.1. Ingestion Layer (then chốt nhất)

**Nhiệm vụ**:
- Kết nối SharePoint bằng Microsoft Graph API.
- Theo dõi thay đổi file (delta query / webhook).
- Tải file + metadata.

**Metadata bắt buộc**:
- site_id
- drive_id / library
- file_id
- file_name
- file_url (mở trực tiếp trên SharePoint)
- created_by, modified_by
- created_at, modified_at
- permission_groups / users

> Lưu ý: permission cần map thành dạng filter-friendly (list group/user IDs).

---

### 4.2. Extraction Layer

#### OCR
- Scan PDF thường là image → cần OCR.
- Định hướng:
  - Tesseract / PaddleOCR cho local.
  - Có thể thay bằng model mới sau.

#### MarkItDown
- Chuyển output OCR → Markdown sạch.
- Ưu điểm:
  - Giữ cấu trúc
  - Thuận lợi cho chunk & embedding

Output cần lưu:
```json
{
  "file_id": "...",
  "page": 12,
  "content_md": "## Điều 3...",
  "bbox_hint": "page=12"
}
```

---

### 4.3. Normalization & Chunking

**Mục tiêu**: mỗi đơn vị index phải vừa đủ nhỏ để search chính xác, vừa đủ lớn để có ngữ cảnh.

Chiến lược chunk:
- Ưu tiên theo:
  1. Heading (##, ###)
  2. Trang (page)
  3. Đoạn văn

Mỗi chunk gồm:
- chunk_id
- text
- file_id
- page_from / page_to
- sharepoint_url_with_anchor

---

### 4.4. Index Layer (OpenSearch)

**Hai loại index song song**:

1. **Full-text index**
- Phục vụ search truyền thống
- Có highlight

2. **Vector index**
- Phục vụ semantic search
- Dùng embedding OSS (bge, e5, etc.)

**Schema gợi ý**:

```json
{
  "chunk_id": "...",
  "text": "...",
  "embedding": [ ... ],
  "file_id": "...",
  "file_name": "...",
  "sharepoint_url": "...",
  "page_from": 10,
  "page_to": 11,
  "site_id": "...",
  "permissions": ["groupA", "userB"],
  "updated_at": "..."
}
```

---

## 5. Search & UX định hướng

### 5.1. Search mode
- Keyword search
- Semantic search
- Hybrid (khuyên dùng)

### 5.2. Kết quả search bắt buộc có
- Trích đoạn nội dung
- Tên file
- Thư mục / site
- Trang (page)
- Link mở đúng file

### 5.3. UX nguyên tắc
- Tìm ≤ 3s
- Click ≤ 1 lần để mở file
- Người dùng **không cần biết file nằm ở đâu**

---

## 6. Vibecode: nên tập trung viết gì?

✅ NÊN tự viết:
- SharePoint ingestion & sync
- Permission mapping
- Metadata chuẩn hóa
- UI search phù hợp nghiệp vụ

❌ KHÔNG nên tự viết:
- OCR engine
- Search engine
- Vector index

---

## 7. Lộ trình triển khai thực tế

### Phase 1 – PoC (2–4 tuần)
- Lấy 1 site SharePoint
- OCR + MarkItDown
- Full-text search

### Phase 2 – Semantic search
- Chunking
- Embedding
- Vector search

### Phase 3 – Permission & scale
- ACL filtering
- Delta sync
- Monitoring

---

## 8. Tương tác AI agent trong tương lai

Hệ thống này có thể:
- Gắn Chat UI (RAG)
- Tóm tắt tài liệu
- So sánh nhiều file
- Trả lời câu hỏi trích dẫn rõ nguồn

---

## 9. Kết luận

Bài toán của bạn **không mới nhưng rất ít hệ thống làm đúng**.

Việc kết hợp:
- SharePoint (nguồn tin cậy)
- MarkItDown (chuẩn hóa nội dung)
- OpenSearch (index & search)
- Vibecode (điều phối thông minh)

là **hướng kiến trúc bền vững, mở rộng được nhiều năm**.

---

*Tài liệu này được thiết kế để AI agent hoặc dev khác có thể đọc và triển khai tiếp mà không cần giải thích lại.*