فایل‌ها و رسانه

فایل‌ها و رسانه‌ها را در اپ خود ذخیره کنید. هر فایل یک URL عمومی دائمی دریافت می‌کند.

رسانه در Proyecta در دو لایه ارائه می‌شود. اکثر اپ‌ها از قابلیت داخلی آپلود رسانه در CMS استفاده می‌کنند — آپلود تصویر و فایل که هوش مصنوعی آن‌ها را در پنل ادمین و فرم‌هایتان برایتان سیم‌کشی می‌کند. در زیر آن، یک Files API سطح پایین‌تر کنترل مستقیم را زمانی که نیاز دارید فراهم می‌کند. هر دو روی object storage با پشتیبانی CDN ذخیره می‌شوند و یک URL عمومی دائمی برمی‌گردانند.

پیوست‌های چت

ورودی چت مستقیماً تصاویر را می‌پذیرد — یک اسکرین‌شات را paste کنید یا یک فایل تصویری را روی ورودی بکشید. فرمت‌های پشتیبانی‌شده: PNG، JPEG، WebP، GIF، AVIF. حداکثر حجم: 10 MB برای هر تصویر.

پیوست‌های چت بخشی از پیام هستند، نه کتابخانه فایل شما. برای ذخیره‌سازی دائمی، از آپلود رسانه داخلی یا Files API استفاده کنید.

آپلود رسانه داخلی (قابلیت رسانه CMS)

اکثر اپ‌ها مستقیماً با Files API کار نمی‌کنند — رسانه یک قابلیت داخلی CMS است. قالب اپ دو upload hook در @/hooks/useContent دارد و هوش مصنوعی آن‌ها را در رابط کاربری شما سیم‌کشی می‌کند. شما توضیح می‌دهید چه می‌خواهید («یک فیلد تصویر روی محصولاتم»، «آپلود فایل در فرم تماسم») و Proyecta از hook مناسب استفاده می‌کند:

Hook	محل استفاده	Endpoint	محدودیت حجم
useAssetUpload()	کتابخانه رسانه ادمین — پشتیبان از asset picker در ویرایشگر محتوای پنل ادمین	POST /v1/public/files	10 MB
useFormFileUpload()	فایل‌های فرم عمومی — آپلود بازدیدکننده روی فیلد فایل <FormBlock/> (رسیدها، تصاویر)	POST /v1/public/uploads	5 MB

هر دو hook یک url عمومی دائمی برمی‌گردانند که روی آیتم محتوا (ادمین) یا ارسال فرم (عمومی) ذخیره می‌کنید. چند نکته مهم:

• هر دو محدودیت حجم در کد اعمال می‌شوند، نه بر اساس پلن — 10 MB برای رسانه ادمین، 5 MB برای فایل‌های فرم عمومی.
• فقط تصاویر (به‌جز SVG) و PDF پذیرفته می‌شوند. SVG به دلایل امنیتی رد می‌شود؛ تصاویر بزرگ قبل از آپلود به‌طور خودکار کوچک می‌شوند.
• این hookها را مستقیماً فراخوانی نمی‌کنید — هوش مصنوعی آن‌ها را نصب می‌کند. تنها برای مدیریت فایل سطح پایین‌تر یا سفارشی سراغ Files API پایین بروید.

Files API

هر اپ منتشرشده در Proyecta می‌تواند فایل ذخیره و سرو کند. از داخل صفحه‌های اپتان این کار یک فراخوانی واحد است — رقص چندمرحله‌ای آپلود امضاشده برایتان انجام می‌شود:

import * as platform from '@/lib/platformClient.ts';

// Upload straight from a file input — one call, no signed-URL juggling
async function onPick(file: File) {
    const asset = await platform.assetDirectUpload({
        blob: file,
        filename: file.name,
        mimeType: file.type,
    });
    console.log(asset.url); // permanent public URL
}

// List what's stored
const { assets, hasMore } = await platform.assetList({ limit: 20 });

// Remove one
await platform.assetDelete(asset.id);

فایل‌های خصوصی. با پاس دادن visibility: 'private' فایل خارج از bucket عمومی و بدون URL دائمی ذخیره می‌شود. به‌جای آن با یک لینک کوتاه‌عمر آن را بخوانید:

const { url, expiresAt } = await platform.assetSignedUrl(asset.id, { variant: 'thumbnail' });

برای هر چیزی که نباید قابل حدس زدن باشد — آپلودهای مشتریان، مدارک هویتی، دانلودهای پولی — از حالت خصوصی به‌همراه URL امضاشده استفاده کنید.

فایل‌ها چگونه به اپم آپلود می‌شوند؟

آپلود فایل از طریق AI builder انجام می‌شود. از هوش مصنوعی بخواهید فرآیند آپلود را برایتان بسازد:

• «به کاربران اجازه بده یک عکس پروفایل آپلود کنند و آن را در Proyecta Files ذخیره کنند»
• «یک گالری تصویر اضافه کن که کاربران وارد شده بتوانند عکس‌هایشان را آپلود و مشاهده کنند»
• «اجازه بده فاکتورهای PDF را به سفارش‌ها ضمیمه کنم»

هوش مصنوعی آپلود را در کد اپ شما سیم‌کشی می‌کند و URL عمومی بازگشتی را مرجع قرار می‌دهد.

سوالات متداول

آیا URL‌های فایل عمومی هستند؟

بله. هر فایل بازگشتی از Files API یک URL عمومی دائمی دارد. هیچ چیزی را که نمی‌خواهید در معرض عموم قرار گیرد آپلود نکنید.

حداکثر حجم فایل چقدر است؟

محدودیت حجم فایل در کد اعمال می‌شود، نه بر اساس پلن: 10 MB برای آپلودهای کتابخانه رسانه ادمین (useAssetUpload)، 5 MB برای آپلودهای فایل فرم عمومی (useFormFileUpload) و 10 MB برای پیوست‌های چت. آپلود رسانه داخلی فقط تصاویر (به‌جز SVG) و PDF را می‌پذیرد.

آیا می‌توانم تصاویر را از طریق URL تغییر اندازه داده یا برش بدهم؟

تبدیل تصویر به‌صورت لحظه‌ای (تغییر اندازه، برش، تبدیل فرمت) در roadmap قرار دارد.

به‌زودی

• تبدیل تصویر از طریق پارامترهای URL (تغییر اندازه، برش، تبدیل فرمت)
• سازماندهی پوشه — ایجاد و مدیریت مسیرهای پوشه برای فایل‌های ذخیره‌شده