01 / شرح پروژه
مسئله چه بود؟
در پنل‌های سازمانی، هر قابلیت جدید معمولاً به فرم ثبت و ویرایش، اعتبارسنجی، کنترل دسترسی، فهرست قابل جست‌وجو و گزارش نیاز دارد. ساخت جداگانه این اجزا، حجم زیادی کد مشابه ایجاد می‌کند و اصلاح یک رفتار مشترک را به تغییر در چندین صفحه تبدیل می‌کند. هدف من، ساخت زیرساختی بود که توسعه‌دهنده بتواند ساختار داده، فیلدها، قواعد و نحوه نمایش را تعریف کند و از همان تعریف، بخش‌های تکرارشونده رابط و عملیات داده ساخته شوند؛ در عین حال، منطق خاص هر پروژه قابل توسعه بماند.
نقش من در پروژه
این رویکرد را در SamirCore و ابزارهای تکمیلی پنل پیاده‌سازی کردم: موتور فرم و عملیات داده، گزارش‌ساز قابل تنظیم، زیرساخت هویت و مدل مجوزها، و الگوهای نمایش نمودار از داده‌های سیستم. هسته مشترک در کتابخانه قرار دارد و تنظیمات، قالب‌ها و قواعد اختصاصی در لایه محصول اضافه می‌شوند. استفاده از این ابزارها در فرم‌های مدیریتی، فهرست پرداخت‌ها، تاریخچه کیف پول و داشبوردهای فروش، آن‌ها را به بخشی از مسیر واقعی توسعه محصول تبدیل کرده است.
معماری داینامیک؛ از تعریف تا اجرای صفحه
فرم‌ساز و گزارش‌ساز بر پایه تعریف ساختار در کد کار می‌کنند. توسعه‌دهنده به‌جای تکرار HTML و عملیات عمومی، مشخصات صفحه را به موتور مشترک می‌دهد.
تعریف یک‌بارِ مشخصات هر بخش
در فرم، نام فیلد، نوع ورودی، عنوان، چیدمان، اعتبارسنجی و اتصال به داده تعریف می‌شود. در گزارش، منبع داده، ستون‌ها، فیلترها و نحوه نمایش مشخص می‌شود. موتور مشترک این تنظیمات را به رابط و رفتار اجرایی تبدیل می‌کند.
هسته مشترک و لایه اختصاصی محصول
SamirCore مسئول رفتارهای عمومی است؛ قالب گزارش پیشرفته و ابزارهای تکمیلی در لایه پنل قرار می‌گیرند. این تفکیک اجازه می‌دهد ظاهر و قواعد پروژه تغییر کنند و از موتور پایه دوباره استفاده شود.
مسیر روشن برای توسعه قابلیت جدید
برای افزودن یک بخش مدیریتی، ابتدا داده و دامنه دسترسی مشخص می‌شود، سپس فرم و فهرست تعریف می‌شوند و منطق اختصاصی به نقاط توسعه متصل می‌شود. ساختار مشترک، پیاده‌سازی و مرور کد صفحات مختلف را یکدست‌تر می‌کند.
فرم‌ساز پیشرفته و عملیات داده
FormRecords فراتر از تولید ورودی‌هاست؛ ساخت رابط، دریافت داده، اعتبارسنجی و مسیر ثبت، ویرایش و حذف را در یک ساختار قابل تنظیم کنار هم قرار می‌دهد.
فیلدهای متنوع و انتخاب‌های وابسته
متن کوتاه و چندخطی، عدد صحیح و اعشاری، رمز، تلفن، انتخاب ساده و جست‌وجوپذیر، چندانتخابی، رادیویی و چک‌باکس پشتیبانی می‌شوند. انتخاب‌های وابسته با اتصال به API، انتخاب سلسله‌مراتبی و ورودی‌های مبتنی بر پنجره انتخاب نیز در ساختار فرم پیش‌بینی شده‌اند.
تاریخ شمسی، فایل و تصویر
ورودی تاریخ و زمان و تاریخ شمسی، آپلود فایل و چندفایل، انتخاب تصویر و تنظیمات برش تصویر در همان تعریف فرم قرار می‌گیرند. نمایش فایل‌ها، مسیر ذخیره‌سازی و تنظیمات تصویر متناسب با هر فیلد قابل تعیین است.
اعتبارسنجی و تجربه فارسی و انگلیسی
اجباری‌بودن فیلد، حداکثر طول و الگوی Regex از تنظیمات فیلد خوانده می‌شوند. بررسی داده در سرور و تنظیمات اعتبارسنجی رابط، همراه با پیام‌ها و عنوان دکمه‌های فارسی و انگلیسی، از اجزای مشترک فرم هستند. چیدمان، حالت فقط‌خواندنی و محتوای سفارشی نیز قابل تنظیم‌اند.
ثبت، ویرایش و ذخیره‌سازی منعطف
فرم به جدول و شناسه رکورد متصل می‌شود و عملیات درج، ویرایش و حذف را انجام می‌دهد. علاوه بر ستون‌های معمول دیتابیس، ذخیره در فیلد JSON و رکوردهای ویجت داینامیک پشتیبانی می‌شود. تنظیم حذف واقعی یا نرم و نحوه بازگشت پس از عملیات، در اختیار توسعه‌دهنده است.
منطق اختصاصی قبل و بعد از عملیات
نقاط توسعه همگام و ناهمگام قبل و بعد از ثبت، ویرایش و حذف، امکان بررسی قواعد کسب‌وکار، تغییر داده یا توقف عملیات با پیام مشخص را فراهم می‌کنند. ثبت سابقه تغییرات و اتصال فرم به مسیر مشاهده تاریخچه نیز در هسته پیش‌بینی شده است.
امنیت و کنترل دسترسی
مدیریت هویت و مجوزها، محدودکردن دامنه داده و محافظت از ورودی‌ها و درخواست‌ها، در هسته و لایه محصول کنار هم قرار می‌گیرند. کوئری‌های پارامتری، اعتبارسنجی سمت سرور، توکن ضدجعل و کدگذاری خروجی از روش‌های به‌کاررفته در این ساختار هستند.
هویت و محدوده ورود به بخش‌ها
مدیریت JWT و اطلاعات کاربر واردشده در هسته قرار دارد. کنترلر پایه امکان تعریف بخش عمومی، بخش مخصوص مدیر، بخش مخصوص کاربر یا بخش مشترک را فراهم می‌کند و اطلاعات هویت را در اختیار اجزای پنل می‌گذارد.
مدل مجوزهای جزئی برای عملیات
مدل دسترسی، مشاهده، افزودن، ویرایش، تأیید، حذف، گزارش، تاریخچه، ورود و خروج داده و چاپ را جداگانه تعریف می‌کند. فرم‌ساز مجوزهای دریافتی را برای فعال‌بودن عملیات و دکمه‌های ثبت، ویرایش، حذف و تاریخچه به کار می‌گیرد؛ سیاست تخصیص این مجوزها در لایه محصول تعیین می‌شود.
شرط دسترسی در بازیابی رکورد
فرم هنگام بازیابی رکورد برای ویرایش می‌تواند شرط‌های اضافی مانند مالک یا سازمان را دریافت و به پرس‌وجو اضافه کند. این قابلیت به توسعه‌دهنده امکان می‌دهد دامنه مجاز داده را همراه با شناسه رکورد بررسی کند و فرم را به قواعد دسترسی همان بخش متصل نگه دارد.
دامنه سازمانی در صفحات واقعی
در لایه محصول، شناسه سازمان یا Tenant برای محدودکردن داده استفاده می‌شود؛ برای نمونه، داده نمودار فروش از سفارش‌های همان سازمان استخراج می‌شود. تعریف مجوز عملیات و تعیین دامنه داده، دو بخش مکمل در پیاده‌سازی صفحات مدیریتی هستند.
مقابله با SQL Injection با کوئری‌های پارامتری
در مسیرهای پارامتری لایه داده و فرم‌ساز، مقادیر ورودی از متن دستور SQL جدا و با Dapper یا SqlParameter ارسال می‌شوند. برای نمونه، شناسه رکورد و شرط‌های مالک یا سازمان در بازیابی فرم به‌صورت پارامتر به کوئری اضافه می‌شوند؛ ورودی در این مسیرها به‌عنوان داده پردازش می‌شود.
اعتبارسنجی ورودی در سمت سرور
فرم‌ساز پیش از ذخیره، اجباری‌بودن فیلدها، طول مجاز و الگوهای تعریف‌شده را در سرور بررسی می‌کند. نقاط توسعه قبل از عملیات نیز امکان بررسی قواعد اختصاصی کسب‌وکار و توقف ثبت یا ویرایش را فراهم می‌کنند؛ کنترل داده به بررسی‌های مرورگر وابسته نمی‌ماند.
محافظت از درخواست‌ها در برابر CSRF
زیرساخت کنترلر، توکن Anti-forgery تولید و اعتبار درخواست را بررسی می‌کند. مسیرهای فرم‌ساز و گزارش‌ساز مجهز به این کنترل، درخواست دارای توکن نامعتبر را رد می‌کنند. در لایه محصول نیز عملیات مشخصی مانند تغییر رمز و ثبت اطلاعات مشتری از اعتبارسنجی ضدجعل استفاده می‌کنند.
کدگذاری خروجی برای کاهش خطر XSS
در بخش‌هایی که داده در HTML سفارشی قرار می‌گیرد، از کدگذاری خروجی استفاده شده است؛ برای نمونه، عنوان و خلاصه اعلان‌ها و نام سازمان‌ها در برخی گزارش‌ها پیش از نمایش با HtmlEncode آماده می‌شوند. این روش مانع تفسیر متن آن مقادیر به‌عنوان کد HTML می‌شود.
گزارش‌ساز حرفه‌ای و فهرست‌های قابل تنظیم
ReportCreate با دریافت پرس‌وجو و تعریف ستون‌ها، ساختار مشترک جست‌وجو، نمایش داده، صفحه‌بندی و خروجی را تولید می‌کند. قالب پیشرفته پنل نیز روی همین موتور ساخته شده است.
ستون‌ها و نمایش سفارشی داده
عنوان، ترتیب نمایش، قابلیت مرتب‌سازی و حضور در خروجی برای هر ستون تعریف می‌شود. توابع نمایش می‌توانند مقدار یا کل ردیف را به متن، نشان وضعیت یا پیوند عملیات تبدیل کنند. کلاس و ویژگی‌های هر ردیف نیز بر اساس داده قابل تنظیم‌اند.
جست‌وجوی چندفیلدی و فیلترهای ترکیبی
فیلتر متنی، انتخابی، چندانتخابی، تاریخ تکی و بازه تاریخ پشتیبانی می‌شوند. می‌توان جست‌وجوی چندفیلدی، مقدار پیش‌فرض فیلتر، محل اعمال شرط و نمایش فیلترها را تنظیم کرد تا گزارش با نوع داده و نیاز هر صفحه هماهنگ شود.
مرتب‌سازی، شمارش و صفحه‌بندی
مرتب‌سازی قابل تنظیم، ترتیب پیش‌فرض، انتخاب تعداد رکورد در صفحه، شمارش نتایج و جابه‌جایی بین صفحات در موتور مشترک قرار دارند. امکان دریافت شمارش از بیرون یا غیرفعال‌کردن آن نیز برای گزارش‌هایی با نیاز متفاوت پیش‌بینی شده است.
بارگذاری AJAX و قالب پیشرفته پنل
نتایج، فیلترها و اجزای صفحه‌بندی می‌توانند از مسیر AJAX به‌روزرسانی شوند. در قالب پیشرفته، جست‌وجوی عمومی، پنل فیلتر، دکمه‌های عملیات و تعداد نتایج در یک ساختار مشترک قرار می‌گیرند؛ ظاهر این ساختار در لایه محصول قابل تغییر است.
خروجی Excel و استفاده عملی
خروجی XLSX با EPPlus و ستون‌های مجاز هر گزارش ساخته می‌شود. همین زیرساخت در فهرست پرداخت‌ها، تاریخچه پرداخت فاکتور، گردش کیف پول، کاربران و بخش‌های دیگر پنل استفاده شده است؛ هر صفحه منبع داده و تنظیمات اختصاصی خودش را تعریف می‌کند.
نمودارهای داینامیک و داشبوردهای تحلیلی
در داشبوردها، داده از بک‌اند یا مدل صفحه دریافت می‌شود و سری‌ها، برچسب‌ها و مقادیر نمودار با داده واقعی ساخته می‌شوند. ApexCharts لایه نمایش این تحلیل‌ها را فراهم می‌کند.
ساخت سری‌ها از داده عملیاتی
در نمودار فروش، بک‌اند سفارش‌های سازمان را بر اساس روز تجمیع می‌کند و برچسب‌های زمانی و مقادیر را به رابط می‌فرستد. رابط نمودار را از همین داده می‌سازد؛ روزهای بدون فروش نیز در توالی زمانی قرار می‌گیرند تا روند قابل مقایسه بماند.
نمایش متناسب با سؤال تحلیلی
نمودارهای ستونی برای مقایسه، نمودارهای روند برای تغییرات زمانی، دونات برای سهم فروش و پراکندگی برای ارتباط شاخص‌ها به کار رفته‌اند. در تحلیل خرید، فروش برندها، ترکیب مشتریان، تعداد سفارش و نرخ تبدیل از داده سیستم به نمودار تبدیل می‌شوند.
به‌روزرسانی و جزئیات قابل فهم
نمودار فروش با درخواست AJAX و دکمه تازه‌سازی به‌روزرسانی می‌شود. راهنمای جزئیات، قالب‌بندی عددها، برچسب‌های فارسی، چیدمان متناسب با اندازه صفحه و پیام نبود داده، خواندن نمودارها را در پنل آسان‌تر می‌کنند.
اتصال نمودار به تصمیم مدیریتی
نمایش روند فروش، سهم برندها، عملکرد گریدهای مشتری و رابطه بازدید با سفارش، داده‌های عملیاتی را به دید تحلیلی تبدیل می‌کند. توسعه هر تحلیل بر تعیین شاخص، استخراج داده و تنظیم نمایش آن متمرکز می‌شود.
نتیجه برای سرعت و کیفیت توسعه
ارزش این زیرساخت در مسیر روزمره توسعه دیده می‌شود: اجزای عمومی از یک پایه مشترک ساخته می‌شوند و منطق اختصاصی هر قابلیت در نقاط مشخص قرار می‌گیرد.
کاهش کدهای تکراری
افزودن فرم یا گزارش جدید به تعریف فیلدها، قواعد، منبع داده و نمایش وابسته است. بخش زیادی از تولید رابط، دریافت داده، اعتبارسنجی، عملیات عمومی و صفحه‌بندی از هسته مشترک تأمین می‌شود.
نگهداری متمرکز و رفتار یکدست
اصلاح رفتار مشترک در موتور فرم یا گزارش انجام می‌شود و صفحات استفاده‌کننده از همان پیاده‌سازی بهره می‌برند. این ساختار، پراکندگی منطق را کمتر می‌کند و مرور، نگهداری و گسترش بخش‌های مشابه را آسان‌تر می‌سازد.
انعطاف برای قواعد واقعی محصول
قالب‌های قابل تغییر، توابع نمایش، شرط‌های دامنه داده و نقاط توسعه قبل و بعد از عملیات اجازه می‌دهند نیازهای اختصاصی در کنار ساختار مشترک پیاده‌سازی شوند. هدف، توسعه سریع‌تر همراه با کدی منظم و قابل ادامه‌دادن است.