# 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)

```text
[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ự)

```text
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
```text
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
```json
{
  "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
```text
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`
```sql
site_id TEXT
drive_id TEXT
delta_token TEXT
updated_at TIMESTAMP
PRIMARY KEY (site_id, drive_id)
```

### 10.2 Bảng `files`
```sql
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`
```sql
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)
```json
{ "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.*