265 lines
5.3 KiB
Markdown
265 lines
5.3 KiB
Markdown
# 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.*
|