التخزين

توفّر HeroMate تخزين ملفات مدعوماً بـ Cloudflare R2 (متوافق مع S3). يمكن لكل مشروع إنشاء حاويات متعددة لتنظيم الملفات، بوصول عام أو خاص. يذهب الرفع مباشرة إلى R2 باستخدام عناوين URL موقّعة مسبقاً، وتُقدَّم الملفات الخاصة عبر عناوين URL موقّعة من خلال Cloudflare Worker.

المفاهيم الأساسية

• Buckets — حاويات عليا لتنظيم الملفات. كل حاوية إما عامة (تُقدَّم عبر CDN دون مصادقة) أو خاصة (تتطلب عنوان URL موقّعاً).
• Presigned Uploads — يحصل SDK على عنوان URL موقّع مسبقاً من المحرك، ثم يرفع الملف مباشرة إلى R2. لا تمر بيانات الملف عبر خادمك.
• Signed URLs — عناوين URL محدودة زمنياً لتنزيل الملفات الخاصة، يتحقق منها Cloudflare Worker.
• File paths — تُنظَّم الملفات حسب معرّف الكيان والمجلد، مثلاً {entity_id}/image/avatars/photo.jpg.

الحاويات

تُخزَّن الحاويات في جدول storage.buckets. لكل حاوية:

يمكنك إنشاء الحاويات من قسم Storage في لوحة تحكم مشروعك.

تدفق الرفع

تستخدم HeroMate رفعاً من 3 مراحل يرسل الملفات مباشرة إلى Cloudflare R2، فيُبقي خادمك خفيفاً:

1. SIGN    → Client requests a presigned upload URL from the engine
2. UPLOAD  → Client uploads the file directly to R2 using the presigned URL
3. VERIFY  → Client confirms the upload, engine records metadata in the database

باستخدام SDK

تمر كل عمليات الملفات عبر endpoints الخاصة بك، التي تستخدم عقدة dypai_storage في الخلفية:

const { data, error } = await dypai.api.upload('storage_files', file, {
  params: {
    operation: 'upload',
    file_path: `invoices/${file.name}`,
  },
  onProgress: (pct) => console.log(`Upload: ${pct}%`),
});

if (data) {
  console.log('Storage path:', data.storage_path);
}

يتولى SDK تدفق المراحل الثلاث بالكامل تلقائياً. يوفّر رد النداء onProgress تقدّم الرفع في الوقت الفعلي لأن الملف يذهب مباشرة من المتصفح إلى R2.

باستخدام خطاف React

import { useUpload } from '@dypai-ai/client-sdk/react';

function FileUploader() {
  const { upload, progress, isUploading } = useUpload('storage_files');

  const handleFile = async (e: React.ChangeEvent<HTMLInputElement>) => {
    const file = e.target.files?.[0];
    if (!file) return;
    const { data, error } = await upload(file, {
      operation: 'upload',
      file_path: `avatars/${file.name}`,
    });
  };

  return (
    <div>
      <input type="file" onChange={handleFile} disabled={isUploading} />
      {isUploading && <p>Uploading: {progress}%</p>}
    </div>
  );
}

مهم: استخدم storage_path

أثناء الرفع قد يُلحق الخلفية UUID أو يُطبّع اسم الملف. احفظ storage_path في قاعدة بياناتك، لا file_path الأصلي.

تنزيل الملفات

تنزيل بعنوان URL موقّع

للتنزيلات الآمنة، استدعِ endpoint في الخلفية يتحقق من الملكية ويُرجع عنوان URL الموقّع:

const { data } = await dypai.api.post('download_file', {
  entity_id: invoice.id,
});
const signedUrl = data?.signedUrl || data?.signed_url;

تنزيل مباشر

await dypai.api.download('download_file', { entity_id: invoice.id }, {
  fileName: 'invoice.pdf',
});

سرد الملفات

const { data } = await dypai.api.post('storage_files', {
  operation: 'list',
  prefix: 'invoices/2024',
});

حذف الملفات

const { error } = await dypai.api.delete('storage_delete_files', {
  params: { file_path: storedPath },
});

حدود التخزين والاستخدام

يُقاس تخزين الكائنات على مستوى مساحة العمل (المؤسسة): يأتي الحد من خطة مؤسستك وهو مشترك عبر كل التطبيقات في مساحة العمل. عند تجاوز حصة تخزين الكائنات، تُحظر عمليات الرفع الجديدة حتى تحرّر مساحة أو ترقّي.

تتبّع استهلاكك من صفحة Usage لكل مشروع (Observe → Usage)، التي تعرض تخزين الكائنات بجانب دقائق البناء وتخزين قاعدة البيانات.

حدود حجم الملف

يعتمد الحد الأقصى لحجم الملف على نوعه. هذه الحدود تقريبية وقد تتغيّر — اعتبرها إرشادية:

أنواع الملفات المحظورة

لأسباب أمنية، تُحظر امتدادات الملفات التالية من الرفع:

• Executables: .exe, .msi, .dmg, .pkg, .deb, .rpm
• Scripts: .bat, .cmd, .sh, .ps1, .vbs, .scr
• Office with macros: .xlsm, .pptm, .docm
• Java: .jar, .class
• Apps: .app, .ipa, .apk

الخطوات التالية

• مرجع تخزين SDK — الرفع والتنزيل وإدارة الملفات من SDK.
• بنّاء الـ API — أنشئ سير عمل مخصصاً لرفع الملفات وتنزيلها.
• الاستخدام والحصص — تتبّع تخزين الكائنات مقابل حد خطتك.