Phase 7: Hoàn thiện Modular RAG Backend với FastAPI và Đa LLM Provider
This commit is contained in:
264
doc/2.sharepoint-ingestion-playbook.md
Normal file
264
doc/2.sharepoint-ingestion-playbook.md
Normal file
@@ -0,0 +1,264 @@
|
||||
# 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.*
|
||||
Reference in New Issue
Block a user