إدارة المستندات في SaaS: رفع الملفات والإصدارات والوصول المقيد بالمستأجر في Go

إدارة المستندات متطلب أساسي لمعظم منتجات SaaS التجارية. العقود والفواتير والمستندات الامتثالية وملفات الموظفين وسجلات العملاء جميعها تحتاج رفعاً آمناً وتخزيناً متعدد الإصدارات ومراقبة وصول مقيدة بالمستأجر. هذه هي البنية التي نستخدمها لإدارة المستندات في خوادم Go للـ SaaS التي تخدم عملاء الأعمال في لبنان ومنطقة الشرق الأوسط.

البنية الأساسية: الرفع المُسبق التوقيع مع S3

البنية الأكثر كفاءة لرفع المستندات في خادم Go للـ SaaS تستخدم الرفع المباشر من جانب العميل إلى S3 عبر URLs مُسبقة التوقيع، بدلاً من توجيه الملف عبر خادم التطبيق.

التدفق:

1. يطلب العميل URL رفع من الـ API
2. خادم Go يولد URL PUT مُسبقة التوقيع لـ S3 (صالحة 15 دقيقة) ويعيدها للعميل
3. العميل يرفع الملف مباشرة إلى S3 باستخدام URL المُسبقة التوقيع
4. بعد اكتمال الرفع، يستدعي العميل الـ API لتأكيد الرفع
5. خادم Go يتحقق من وجود الملف في S3 وينشئ سجل المستند في PostgreSQL

هذا النهج يبقي خادم التطبيق خارج نقل الملفات تماماً. ملف PDF بحجم 50MB يُرفع من عميل في بيروت مباشرة إلى حاوية S3 في منطقة eu-west-1 أو me-south-1، متجاوزاً خادم التطبيق.

هيكل مفاتيح S3 لتخزين المستندات متعدد المستأجرين

يجب أن يفرض هيكل مفتاح S3 عزل المستأجرين على مستوى التخزين:

tenant-documents/{tenant_id}/{document_id}/{version_id}/{filename}

هذا الهيكل يعني:

• جميع مستندات المستأجر تحت نفس بادئة S3
• كل مستند له UUID مستند مستقر عبر الإصدارات
• كل إصدار له UUID إصدار يسمح للإصدارات المتعددة بالتعايش في التخزين
• اسم الملف الأصلي محفوظ في نهاية المفتاح

نموذج بيانات المستند في PostgreSQL

S3 يحفظ البيانات الثنائية. PostgreSQL يحفظ البيانات الوصفية وسجلات التحكم في الوصول:

CREATE TABLE documents (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    tenant_id UUID NOT NULL,
    name TEXT NOT NULL,
    category TEXT NOT NULL,
    created_at TIMESTAMPTZ DEFAULT NOW(),
    current_version_id UUID
);

CREATE TABLE document_versions (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    document_id UUID REFERENCES documents(id),
    tenant_id UUID NOT NULL,
    version_number INT NOT NULL,
    s3_key TEXT NOT NULL,
    upload_status TEXT NOT NULL DEFAULT 'pending',
    UNIQUE (document_id, version_number)
);

حقل upload_status في document_versions مهم لتدفق الرفع المُسبق التوقيع. إصدار جديد يبدأ في حالة pending عند توليد URL المُسبقة التوقيع. ينتقل إلى uploaded بعد تأكيد العميل وتحقق الخادم من وجود الملف في S3.

التحقق من نوع الملف وفحص الفيروسات

قبول تحميلات ملفات عشوائية من المستخدمين يُدخل مخاطرين: أنواع ملفات ضارة مُخفَّاة بامتدادات بريئة، وبرامج ضارة مرفوعة إلى تخزينك.

للتحقق من نوع الملف في Go، اقرأ أول 512 بايت من الملف المرفوع من S3 بعد اكتمال الرفع واستخدم http.DetectContentType للتحقق من أن نوع المحتوى الفعلي يطابق النوع المُعلَن.

لفحص الفيروسات في نشر SaaS الشرق الأوسط، أكثر النهج العملية هو استخدام ClamAV يعمل كخدمة sidecar، أو AWS GuardDuty Malware Protection لـ S3 (متاح في me-south-1 لنشر الشرق الأوسط).

سجلات الوصول للمستندات للامتثال

عملاء الأعمال في لبنان والخليج كثيراً ما يعملون في إطار تنظيمي يتطلب سجلات تدقيق للوصول إلى المستندات. سجل التدقيق يسجل كل تنزيل ورفع وتغيير صلاحيات وحذف:

CREATE TABLE document_access_log (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    tenant_id UUID NOT NULL,
    document_id UUID NOT NULL,
    user_id UUID NOT NULL,
    action TEXT NOT NULL,
    ip_address INET,
    occurred_at TIMESTAMPTZ DEFAULT NOW()
);

هذا الجدول للإضافة فقط. لا يُحدَّث أو يُحذَف أي سجل في سجل الوصول. لأغراض الامتثال، السجل يجب أن يكون غير قابل للتعديل.

دروس من الإنتاج

لا توجِّه أبداً بيانات الملفات عبر خادم التطبيق. URLs S3 المُسبقة التوقيع تبقي الملفات الكبيرة خارج طبقة التطبيق.

استخدم هيكل مفتاح S3 متسقاً يتضمن tenant ID في المستوى الأول.

تحقق دائماً من وجود الملف في S3 بعد الرفع المُسبق التوقيع قبل تمييز الإصدار على أنه مرفوع. العميل قد يُبلِّغ عن رفع ناجح لم يحدث فعلاً.

طبِّق التحقق من نوع الملف بعد الرفع، وليس قبله. رؤوس content-type من المتصفح غير موثوقة. اقرأ بايتات سحر الملف من S3.

aجعل سجل وصول المستندات للإضافة فقط. سجلات التدقيق الامتثالية التي يمكن تعديلها ليست سجلات تدقيق.