Ana içeriğe geç

Workspace DB

Akademi Eğitim Platformu Workspace DB Dökümanı​

1. MariaDB Schema Önerisi (Metadata & Kontrol)​

-- 1. Dosyalar ana tablosu (Workspace Files)
CREATE TABLE workspace_files (
    file_id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    tenant_id BIGINT UNSIGNED NOT NULL,                -- Akademi/organizasyon izolasyonu
    parent_folder_id BIGINT UNSIGNED DEFAULT NULL,     -- Nested folders için self-reference
    uploader_user_id BIGINT UNSIGNED NOT NULL,
    filename VARCHAR(255) NOT NULL,
    original_filename VARCHAR(255) NOT NULL,
    mime_type VARCHAR(100) NOT NULL,                   -- application/pdf, etc.
    file_size BIGINT UNSIGNED NOT NULL,
    storage_path VARCHAR(500) NOT NULL,                -- S3/minio path: tenant_id/uuid.ext
    hash_sha256 CHAR(64) UNIQUE,                       -- Duplicate detection & integrity
    status ENUM('pending', 'processed', 'failed', 'deleted') DEFAULT 'pending',
    version INT UNSIGNED DEFAULT 1,
    tags JSON DEFAULT NULL,                            -- ["sales", "2025", "confidential"]
    metadata JSON DEFAULT NULL,                        -- {"department": "Satış", "publish_date": "2025-01-01"}
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    
    FOREIGN KEY (tenant_id) REFERENCES academies(academy_id) ON DELETE CASCADE,
    FOREIGN KEY (parent_folder_id) REFERENCES workspace_files(file_id) ON DELETE SET NULL,
    INDEX idx_tenant_parent (tenant_id, parent_folder_id),
    INDEX idx_hash (hash_sha256)
);

-- 2. Klasörler (ayrı tabloya gerek yok, files self-reference ile folder olur; is_folder TINYINT ekleyebilirsin)
-- Alternatif: ayrı folders tablosu eğer metadata ayrımı lazımsa

-- 3. Chunk metadata (RAG için kritik – ChromaDB'ye sync edilir)
CREATE TABLE file_chunks (
    chunk_id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    file_id BIGINT UNSIGNED NOT NULL,
    chunk_index INT UNSIGNED NOT NULL,                 -- Sıra numarası
    chunk_text TEXT NOT NULL,                          -- Ham chunk (debug için)
    embedding_id VARCHAR(100),                         -- ChromaDB'deki ID
    page_numbers JSON,                                 -- [5,6] veya [10] – PDF için
    hierarchy_level INT DEFAULT 0,                     -- 0: document, 1: section, 2: paragraph, 3: sentence/table
    parent_chunk_id BIGINT UNSIGNED DEFAULT NULL,      -- Hierarchical parent-child
    token_count INT UNSIGNED,
    chunk_strategy ENUM('fixed', 'recursive', 'semantic', 'hierarchical') DEFAULT 'recursive',
    overlap_tokens INT DEFAULT 0,
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    
    UNIQUE KEY uk_file_index (file_id, chunk_index),
    FOREIGN KEY (file_id) REFERENCES workspace_files(file_id) ON DELETE CASCADE,
    FOREIGN KEY (parent_chunk_id) REFERENCES file_chunks(chunk_id) ON DELETE SET NULL
);

-- 4. İzinler (RBAC benzeri)
CREATE TABLE file_permissions (
    permission_id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    file_id BIGINT UNSIGNED NOT NULL,
    user_id BIGINT UNSIGNED DEFAULT NULL,              -- Bireysel
    group_id BIGINT UNSIGNED DEFAULT NULL,             -- Departman/rol
    role ENUM('owner', 'editor', 'viewer', 'commenter') NOT NULL,
    expires_at DATETIME DEFAULT NULL,
    FOREIGN KEY (file_id) REFERENCES workspace_files(file_id) ON DELETE CASCADE
);

-- 5. Audit Log (GDPR/KVKK için) -- security_roles ile çözüyoruz.
CREATE TABLE file_audit_logs (
    log_id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
    file_id BIGINT UNSIGNED NOT NULL,
    user_id BIGINT UNSIGNED NOT NULL,
    action ENUM('upload', 'view', 'edit', 'delete', 'download', 'search') NOT NULL,
    details JSON,                                      -- {"ip": "...", "chunk_ids": [...]}
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP
);

2. ChromaDB Entegrasyonu & Multi-Tenant​

  • Collection Strategy: Tenant başına ayrı collection → client.create_collection(name=f"workspace_{tenant_id}")
    • Avantaj: Tam izolasyon (bir tenant diğerinin verisini göremez), query hızlı.
    • Dezavantaj: Çok tenant'ta yönetim zor (ama senin 2000 domain tecrübenle script'le yönetilir).
  • Alternatif (daha basit): Tek collection + her chunk metadata'sına {"tenant_id": X, "file_id": Y} ekle → filter ile sorgula.
  • Chunk Metadata Örnek (ChromaDB'ye eklerken): 
    {
        "file_id": 123,
        "tenant_id": 456,
        "chunk_index": 5,
        "page": [3,4],
        "hierarchy": "section > paragraph",
        "tags": ["sales_training"]
    }
  • Hybrid Search: ChromaDB destekliyor → where={"tenant_id": tenant_id} + vector query.

3. Chunking Stratejisi Önerisi (Eğitim Belgeleri Odaklı – 2025-2026 Best Practices)​

Eğitim materyalleri (PDF/DOCX/PPTX) için hierarchical + semantic hybrid en iyi sonuç veriyor:

  1. Preprocessing:

    • PDF/DOCX → Unstructured.io veya Docling (IBM) ile parse et → Markdown/JSON'a çevir (başlık, paragraf, tablo, liste ayrımı).
    • Tablo → ayrı chunk yap (tabloyu Markdown table olarak sakla, açıklama ekle).
    • Header/footer duplicate kaldırma.

  2. Chunking Pipeline (Recursive + Semantic):

    • İlk: RecursiveCharacterTextSplitter (LangChain) – separators: ["\n\n", "\n", ". ", " ", ""] → paragraf > cümle > kelime.
    • Sonra: Semantic Chunking (embedding similarity ile merge/split) – küçük chunk'ları anlam bütünlüğü varsa birleştir.
    • Overlap: %15-20 (örn. 512 token chunk → 80-100 token overlap).
    • Boyut: 400-800 token (eğitim için ideal – quiz/explanation bağlamı korur).
    • Hierarchical Metadata: Parent-child ekle (section → paragraph → sentence) → retrieval'da parent chunk'ı da getir.

  3. PDF Özel:

    • Sayfa bazlı değil → heading bazlı (H1 > H2 > paragraph).
    • Tabloyu ayrı chunk + "Bu tabloyu özetle" gibi metadata.

  4. Re-chunk on Update: Dosya değişince hash kontrol → delta chunk (sadece değişen sayfaları re-process).

4. Google Drive / OneDrive Sync​

  • Tablo Ek: external_syncs tablosu ekle: 
    CREATE TABLE external_syncs (
        sync_id BIGINT AUTO_INCREMENT PRIMARY KEY,
        tenant_id BIGINT NOT NULL,
        provider ENUM('google_drive', 'onedrive'),
        folder_id VARCHAR(255),
        last_sync_at DATETIME,
        status ENUM('active', 'paused', 'error'),
        oauth_token JSON  -- encrypted
    );
  • Akış: OAuth → delta API ile değişen dosyaları çek → upload gibi process et.

Son Tavsiyeler & Sorular​

  • MVP için: Recursive + 15% overlap + ChromaDB per-tenant collection ile başla.
  • Gelecek: Semantic chunking + agentic (LLM karar versin) ekle.
  • Test: Eğitim PDF'lerinde retrieval accuracy'yi ölç (RAGAS veya manuel eval).