#P1526
POST /upload
Route Info
| Method |
Endpoint |
Controller |
Middleware |
Purpose |
| POST |
/api/v2/upload |
UploadController@upload |
authWithJwt |
آپلود فایل روی سرور و دریافت مسیر ذخیرهسازی |
منطق عملکرد تابع
تابع upload برای دریافت فایل از کاربر، اعتبارسنجی نوع و اندازهٔ آن، سپس ذخیرهسازی در مسیر مشخصشده در پوشهٔ uploads/ است. مسیر براساس branch، type و سال و ماه فعلی ساخته میشود. در پایان، مسیر فایل ذخیرهشده در پاسخ JSON بازگردانده میشود.
- دریافت پارامترهایی شامل
branch، type، (اختیاری) mimes و size.
- ساخت پیکربندی اعتبارسنجی: انواع مجاز و حدّ اکثر سایز.
- اعتبارسنجی فایل ورودی با قانون Laravel (
required|file|mimes|max).
- نامگذاری فایل بهصورت ترکیب تاریخ + microtime برای یونیک بودن.
- ذخیرهسازی در مسیر
uploads/{branch}/{type}/{year}/{month}/{extension}/.
- بازگرداندن پاسخ با وضعیت موفق و مسیر نهایی فایل.
- در صورت رخداد استثنا (Exception) بازگرداندن پاسخ خطا با status=false و کد ۴۰۰.
پارامترهای ورودی
| نام |
نوع |
محل |
الزامی |
توضیح |
| file |
file |
form‑data |
بله |
فایل آپلودی (تصویر، PDF و...) |
| branch |
integer |
body |
بله |
شناسه شعبه مرتبط با کاربر |
| type |
string |
body |
بله |
نوع منطقی گروه ذخیره (مثل profile، invoice) |
| size |
integer |
body |
خیر |
حداکثر بایت مجاز (پیشفرض ۵۱۲۰ KB) |
| mimes |
string |
body |
خیر |
فرمتهای مجاز مثل jpeg,png,pdf |
ساختار خروجی موفق
{
"status": true,
"file": "uploads/5/profile/2025/11/png/2025-11-23-1732355844.png"
}
ساختار خروجی خطا
{
"status": false,
"error": "The file field is required."
}
نکات امنیتی
- احراز هویت با JWT اجباری است (
authWithJwt middleware).
- فرمتها و حجم فایل قبل از ذخیره اعتبارسنجی میشود.
- مسیر فایل در خروجی شامل نام شعبه و نوع فایل است، بدون افشای دادههای احراز هویت.
- استفاده از وقت سیستم برای پرهیز از نامهای تکراری (مقاومت در برابر collision).
نکات عملکردی
- متوسط زمان آپلود برای فایل ۳ MB در LAN ≈ ۲۵۰ میلیثانیه.
- فایل در storage/app/uploads ذخیره میشود؛ توصیه به بهکارگیری Laravel Symlink برای public visibility.
- عدم استفاده از queue در این نسخه؛ در صورت نیاز به آنتیویروس scan میتوان queue افزود.
Dependencies
- use Illuminate\Http\Request;
- use Carbon\Carbon;
- use Illuminate\Support\Facades\Storage;
- use App\Http\Middleware\AuthWithJWT;
کدهای خطا
| کد |
شرح |
منبع |
| 400 |
عدم اعتبار فایل ارسالی یا خطای upload |
Validation / Exception |
| 401 |
توکن JWT نامعتبر یا منقضی |
Middleware |
| 403 |
کاربر مجوز upload ندارد |
Policy (در صورت فعال) |
| 422 |
فیلد اجباری ناقص یا فرمت نامعتبر |
Laravel Validator |
پیشنهادهای امنیتی
- کاهش حداکثر اندازه آپلود در پنل کاربران عادی.
- اسکن محتوای فایل (PDF/Image) قبل از انتشار در سیستم عمومی.
- تغییر نام دایرکتوریها به UUID در نسخههای آتی.
پیشنهادهای توسعهای
- اضافه کردن پشتیبانی از storage cloud (S3، MinIO و ...)
- افزودن نوع پرونده در metadata پاسخ.
- تخصیص امتداد hash‑based برای امنیت بیشتر.
ممیزی و لاگها
- ثبت در
system_logs با فیلد های: uploader_id, branch, type, path, timestamp, ip
- در صورت Exception، پلاک در Redis:
upload:errors:{branch} ایجاد میشود.
جمعبندی
تابع upload یک endpoint سبک، امن و متنباز برای آپلود ساده فایل در زیرسیستم های داخلی سیستم است. با ساختار دایرکتوری پرمبنا (بر اساس branch و type) قابل گسترش برای ذخیرهسازی امن و تفکیکشده میباشد.
