poc_system/doc/2.sharepoint-ingestion-playbook.md

SharePoint Ingestion – Tài liệu triển khai tuần tự (Reusable)

Mục tiêu tài liệu: Có thể nạp lại bất kỳ lúc nào để tiếp tục đúng hướng. Viết theo kiểu triển khai được ngay, tránh phụ thuộc ngữ cảnh hội thoại.

---

Mục lục

1. Phạm vi & Mục tiêu
2. Nguyên tắc thiết kế
3. Luồng xử lý tổng thể (End-to-End Flow)
4. Sequence Diagram (Mô tả tuần tự)
5. Thiết kế Ingestion Service
6. Delta Sync & State Management
7. Permission Flattening (ACL)
8. Download & File Lifecycle
9. Orchestration, Retry, Idempotency
10. Thiết kế CSDL (Schema)
11. Internal APIs (Spec)
12. Observability & Ops
13. Roadmap thực thi

---

1. Phạm vi & Mục tiêu

• Ingest tài liệu từ SharePoint Online (Microsoft 365) bằng Microsoft Graph API.
• Phát hiện thay đổi bằng Delta Query.
• Thu thập metadata + quyền truy cập.
• Đưa file hợp lệ vào pipeline xử lý (OCR/MarkItDown ở phase sau).
• Đảm bảo permission-aware ngay từ ingestion.

---

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

• App-only authentication (service-to-service).
• Delta-first: không full scan lặp lại.
• Permission-first: flatten ACL khi ingest.
• Idempotent: chạy nhiều lần cho cùng version → kết quả giống nhau.
• File gốc là nguồn chân lý (chỉ lưu bản trích xuất + index).

---

3. Luồng xử lý tổng thể (End-to-End)

[Scheduler]
  ↓
[List Configured Sites]
  ↓
[List Drives / Libraries]
  ↓
[Delta Query Items]
  ↓
[For each Changed Item]
   ├─ Fetch Metadata
   ├─ Fetch Permissions (ACL)
   ├─ Decide Eligibility (whitelist extension/size)
   ├─ Enqueue Processing Job
   └─ Persist State (deltaToken, etag)

---

4. Sequence Diagram (Mô tả tuần tự)

Scheduler
  |
  | trigger
  v
Ingestion Service
  |
  | GET sites/drives
  v
Microsoft Graph
  |
  | 200 OK (sites/drives)
  v
Ingestion Service
  |
  | GET delta(items, token)
  v
Microsoft Graph
  |
  | items[] + deltaToken
  v
Ingestion Service
  |
  | For item changed:
  |   - GET item metadata
  |   - GET item permissions
  |   - Persist ingest record
  |   - Push job to Queue
  v
Queue / Pipeline

---

5. Thiết kế Ingestion Service

5.1 Thành phần

• Auth Module: OAuth2 client-credentials + certificate.
• Site/Drive Scanner: liệt kê phạm vi được cấu hình.
• Delta Engine: quản lý deltaToken.
• Metadata Collector: chuẩn hóa metadata.
• ACL Collector: flatten permission.
• Job Producer: đẩy sự kiện sang pipeline.

5.2 Công nghệ gợi ý

• Backend: Python (FastAPI) hoặc Node.js
• Queue: Azure Service Bus / RabbitMQ / Redis
• Storage state: PostgreSQL hoặc CosmosDB (metadata)

---

6. Delta Sync & State Management

6.1 Delta Token

• Mỗi drive/library có một delta_token riêng.
• Lưu bền vững (DB), không lưu memory.

6.2 Logic

If first_run:
  call delta without token → snapshot + token
Else:
  call delta with token → changes only

6.3 Event Handling

Event	Hành động
Created	Full ingest
Updated	Re-ingest (new version)
Deleted	Soft-delete index

---

7. Permission Flattening (ACL)

7.1 Nguyên tắc

• Thu thập users + groups ngay khi ingest.
• Expand nested groups tại ingestion time.

7.2 Schema ACL

{
  "users": ["aad-user-id"],
  "groups": ["aad-group-id"],
  "inherited": true
}

7.3 Tối ưu

• Cache membership group.
• Refresh định kỳ (daily/weekly).

---

8. Download & File Lifecycle

8.1 Eligibility Rules

• Whitelist: pdf, docx, pptx, image.
• Size limit (ví dụ ≤ 100MB).

8.2 Lifecycle

Download → Process (OCR/MD) → Persist result → Delete local file

---

9. Orchestration, Retry, Idempotency

9.1 Idempotency Key

• (site_id, drive_id, item_id, etag)

9.2 Retry Strategy

Error	Strategy
429	Exponential backoff
Timeout	Retry N lần
Permission denied	Log + skip

---

10. Thiết kế CSDL (Schema)

10.1 Bảng ingest_state

site_id TEXT
drive_id TEXT
delta_token TEXT
updated_at TIMESTAMP
PRIMARY KEY (site_id, drive_id)

10.2 Bảng files

item_id TEXT
site_id TEXT
drive_id TEXT
file_name TEXT
etag TEXT
version TEXT
status TEXT
last_processed_at TIMESTAMP
PRIMARY KEY (item_id)

10.3 Bảng permissions

item_id TEXT
principal_type TEXT  -- user|group
principal_id TEXT

---

11. Internal APIs (Spec)

POST /ingest/run

• Trigger ingestion cycle.

POST /ingest/item

• Input: { site_id, drive_id, item_id }
• Output: job_id

GET /ingest/state

• Trả về deltaToken, health.

---

12. Observability & Ops

Logs (per item)

{ "item_id": "...", "step": "permission", "status": "ok" }

Metrics

• Files/min
• OCR queue length
• Error rate

---

13. Roadmap thực thi

Step 1 (Tuần 1–2)

• Auth + list sites/drives
• Delta sync cơ bản

Step 2 (Tuần 3)

• Metadata + ACL flatten
• Queue integration

Step 3 (Tuần 4)

• Observability
• Hardening & scale

---

Kết thúc tài liệu ingestion. Có thể tiếp tục với Extraction/OCR hoặc Index/Search ở file tiếp theo.