راهنمای جامع افزونه
ParsEnergy Pro Request Manager
مدیریت درخواست، پیشنهاد قیمت، قرارداد، احراز هویت، پرداخت، پیامک و داشبورد کاربری در وردپرس
این سند برای تحویل پروژه، آموزش مدیر سایت، نگهداری فنی و استفاده روزمره از افزونه تهیه شده است.
اطلاعات سند
| عنوان | مستندات کامل افزونه ParsEnergy Pro Request Manager |
|---|---|
| دامنه سند | نصب، پیکربندی، معرفی ماژولها، فرایندهای کاری، شورتکدها، دیتابیس، یکپارچهسازیها و چکلیست تحویل |
| مخاطبان | کارفرما، مدیر سایت، تیم پشتیبانی، توسعهدهنده وردپرس و مسئول بهرهبرداری سامانه |
| مبنای تهیه | بررسی فایل افزونه و ساختار کد نسخه 1.4.4 |
فهرست مطالب
۱. خلاصه مدیریتی
افزونه ParsEnergy Pro Request Manager یک راهکار اختصاصی برای مدیریت چرخه خدمات و قراردادهای پارس انرژی در بستر وردپرس است. این افزونه مسیر کاری کاربر و مدیر را از ثبتنام اولیه تا ثبت درخواست، ارائه پیشنهاد قیمت، پذیرش پیشنهاد، تولید قرارداد، احراز هویت، پرداخت و پشتیبانی پس از ثبت قرارداد پوشش میدهد.
برای درخواستها، قراردادها، پیامکها، پرداختها، اعلانها و لاگها.
برای صفحات کاربری، ورود، ثبتنام، پروفایل، احراز هویت و مشارکت.
Gravity Forms، WooCommerce، Elementor، Digits، سرویسهای پیامک، Shabanic و OpenAI.
ارزش عملیاتی برای کارفرما
- تجمیع اطلاعات درخواستها و قراردادها در یک پیشخوان مدیریتی.
- کاهش عملیات دستی با شمارهگذاری، تولید قرارداد و اعلان خودکار.
- امکان پیگیری وضعیت هر درخواست از سمت کاربر و مدیر.
- ثبت لاگ پیامکها، پرداختها و فعالیتها برای کنترل و پشتیبانی بهتر.
- آمادگی برای توسعههای بعدی از طریق ساختار ماژولار افزونه.
۲. معماری و ماژولها
افزونه به صورت ماژولار طراحی شده است. فایل اصلی افزونه مسئول بارگذاری کلاسها، تعریف ثابتها، فعالسازی، ساخت جداول و ثبت hookهای اصلی است. هر حوزه کاری در یک ماژول یا کلاس جداگانه مدیریت میشود.
| ماژول/بخش | وظیفه | خروجی عملیاتی |
|---|---|---|
| Authentication | ثبتنام، ورود، OTP، پروفایل کاربر | کاربر معتبر و آماده ثبت درخواست |
| Requests | ثبت درخواست، ارتباط با فرمها، تغییر وضعیت | درخواست قابل بررسی توسط مدیر |
| Offers | ثبت پیشنهاد قیمت، محاسبه مبلغ، انتخاب پیشنهاد | پیشنهاد قابل پذیرش توسط کاربر |
| Contracts | ایجاد قرارداد، کنترل وضعیت امضا و پرداخت | قرارداد رسمی مبتنی بر قالب |
| Payments | ثبت لاگ پرداخت و ارتباط با سفارش | وضعیت مالی قرارداد |
| SMS | ارسال OTP و پیامکهای اطلاعرسانی | پیامک و لاگ ارسال |
| Notifications | اعلان داخلی برای کاربر یا مدیر | پیگیری رویدادها در داشبورد |
| Dashboard | نمایش اطلاعات کاربر در پنل فرانتاند | داشبورد کاربری کامل |
| WooCommerce | همگامسازی پرداخت و سفارشها | اتصال قرارداد به سفارش ووکامرس |
| Participation | فرم مشارکت سرمایهگذاری | درخواست مشارکت با نوع مشخص |
| Logger / Cache | ثبت رخدادها و بهینهسازی دادهها | قابلیت عیبیابی و نگهداری |
۳. پیشنیازها
- WordPress نسخه 5.8 یا بالاتر
- PHP نسخه 8.0 یا بالاتر
- دیتابیس MySQL/MariaDB با پشتیبانی utf8mb4
- دسترسی مدیر کل برای نصب و تنظیم افزونه
- Gravity Forms برای فرمهای درخواست سفارشی
- WooCommerce برای پرداخت و سفارش
- Elementor برای صفحات طراحیشده
- Digits برای ورود/ثبتنام جایگزین
- کلید سرویس پیامک و Shabanic برای OTP و احراز هویت
۴. نصب و راهاندازی
از سایت و دیتابیس بکاپ تهیه کنید و نسخه PHP و وردپرس را بررسی نمایید.
از پیشخوان وردپرس مسیر افزونهها ← افزودن ← بارگذاری افزونه را انتخاب و فایل ZIP را نصب کنید.
پس از فعالسازی، جدولهای افزونه، صفحات پیشفرض، تنظیمات اولیه و زمانبندیهای لازم ساخته میشوند.
اطلاعات شرکت، سرویس پیامک، فرمها، قالب قرارداد، صفحات و درگاه پرداخت را تنظیم کنید.
یک کاربر تست بسازید، OTP بفرستید، درخواست ثبت کنید، پیشنهاد ایجاد کنید و قرارداد را بررسی نمایید.
پس از تأیید، دسترسیها، کلیدهای سرویس و چکلیست تحویل نهایی تکمیل شود.
۵. پنل مدیریت
منوی «پارس انرژی» در پیشخوان وردپرس مرکز کنترل افزونه است. بخشهای قابل مشاهده برای مدیران دارای دسترسی manage_options طراحی شدهاند.
| بخش مدیریتی | شرح کاربرد | کاربر مسئول |
|---|---|---|
| داشبورد | نمایش خلاصه وضعیت سامانه، آمارها، وضعیت سرویسها و میانبرهای مدیریتی. | مدیر سیستم |
| درخواستها | مشاهده درخواستهای ثبتشده، بررسی جزئیات، تغییر وضعیت و پیگیری فرایند. | کارشناس فروش/عملیات |
| پیشنهادها | ثبت پیشنهاد، تعیین قیمت، تخفیف، مالیات، تاریخ انقضا و مدیریت پیشنهادهای ارسالشده. | کارشناس فروش |
| قراردادها | مشاهده قراردادهای ایجادشده، وضعیت امضا، پرداخت و اطلاعات مرتبط. | واحد قراردادها |
| قالب قرارداد | ویرایش متن و قالب قرارداد، وارد کردن HTML/Word و مدیریت متغیرها. | مدیر محتوا/حقوقی |
| پرداختها | کنترل وضعیت پرداختها، شماره سفارش، تراکنش، مبلغ و درگاه. | مالی |
| لاگ پیامکها | مشاهده پیامکهای ارسالشده، وضعیت ارسال و پاسخ سرویسدهنده. | پشتیبانی |
| لاگ افزونه | بررسی رخدادها، خطاها و اطلاعات عیبیابی. | توسعهدهنده/پشتیبانی فنی |
| تیکتها | دریافت و پاسخ به پیامهای پشتیبانی کاربران. | پشتیبانی |
| احراز هویت | بررسی درخواستهای احراز هویت دستی و تأیید یا رد کاربر. | واحد احراز هویت |
| تنظیمات | مدیریت تمامی تنظیمات پایه و سرویسهای جانبی. | مدیر سایت |
| صفحات | ایجاد، همگامسازی و کنترل صفحات پیشفرض افزونه. | مدیر سایت |
۶. تنظیمات
۶.۱ تنظیمات شرکت
اطلاعات هویتی شرکت شامل نام، آدرس، تلفن، ایمیل، شماره ثبت، شناسه ملی و امضا در این بخش ذخیره میشود. این دادهها در قراردادها و قالبهای خروجی استفاده میشوند.
۶.۲ تنظیمات پیامک و OTP
افزونه قابلیت ارسال OTP و پیامکهای اطلاعرسانی را دارد. سرویسهای قابل تنظیم شامل Kavenegar، Ghasedak، FaraPayamak، IPPanel و Shabanic هستند. زمان انقضای OTP، شماره فرستنده، API Key، نام کاربری، رمز عبور و حالت ارسال از همین بخش مدیریت میشود.
۶.۳ تنظیمات فرمها
در صورت استفاده از Gravity Forms، شناسه فرم یا فرمها و نگاشت فیلدهای فرم در این بخش تعریف میشود. افزونه اطلاعات فرم را به درخواست قابل پیگیری تبدیل میکند.
۶.۴ تنظیمات قرارداد
قالب قرارداد، تنظیمات PDF، صفحه Elementor قرارداد، ظرفیت و مدت پیشفرض، سود تضمینی، جریمه تأخیر و متنهای قراردادی در این بخش تعریف میشوند.
۶.۵ تنظیمات هوش مصنوعی
گزینههایی برای تعیین ارائهدهنده، کلید OpenAI، مدل و قابلیتهای هوشمند مانند خلاصهسازی، پاسخ هوشمند، تولید قرارداد و تحلیل داده پیشبینی شده است.
۶.۶ تنظیمات صفحات
صفحات ورود، ثبتنام، داشبورد، درخواستها و قراردادها قابل انتخاب یا بازسازی هستند. این بخش برای اتصال درست صفحات فرانتاند به افزونه اهمیت دارد.
۷. صفحات و شورتکدها
صفحات پیشفرض ایجادشونده
| صفحه | نشانی پیشنهادی | محتوا | کاربرد |
|---|---|---|---|
| ورود به حساب کاربری | login-parsenergy | [parsenergy_login_form] یا شورتکد Digits | ورود کاربر |
| ثبتنام | register-parsenergy | [parsenergy_register_form] یا شورتکد Digits | ثبتنام کاربر |
| داشبورد کاربری | dashboard-parsenergy | [parsenergy_dashboard] | مرکز پنل کاربر |
| درخواستهای من | my-requests-parsenergy | [parsenergy_user_requests] | لیست درخواستهای کاربر |
| قراردادهای من | my-contracts-parsenergy | [parsenergy_user_contracts] | لیست قراردادهای کاربر |
فهرست شورتکدها
| شورتکد | محل استفاده پیشنهادی | شرح |
|---|---|---|
| [parsenergy_login_form] | صفحه ورود | فرم ورود اختصاصی افزونه. |
| [parsenergy_register_form] | صفحه ثبتنام | فرم ثبتنام اختصاصی افزونه. |
| [parsenergy_dashboard] | داشبورد | داشبورد اصلی و مسیریابی بخشهای کاربر. |
| [parsenergy_user_dashboard_v2] | داشبورد جدید | نسخه دوم داشبورد با امکانات گستردهتر. |
| [parsenergy_user_requests] | درخواستهای من | نمایش درخواستهای ثبتشده کاربر. |
| [parsenergy_user_contracts] | قراردادهای من | نمایش قراردادهای مرتبط با کاربر. |
| [parsenergy_profile_form] | پروفایل | تکمیل و ویرایش اطلاعات تکمیلی کاربر. |
| [parsenergy_identity_verification] | احراز هویت | فرم احراز هویت و ثبت اطلاعات هویتی. |
| [parsenergy_create_test_request] | تست داخلی | ایجاد درخواست تست برای بررسی عملکرد. |
| [parsenergy_participation_form] | مشارکت | فرم مشارکت در سرمایهگذاری. |
| [parsenergy_forms_tabs] | صفحه فرمها | نمایش تب ثبت درخواست و مشارکت. |
۸. فرایندهای عملیاتی
۸.۱ فرایند ثبت درخواست تا قرارداد
- کاربر وارد سایت میشود یا با شماره موبایل ثبتنام میکند.
- کد OTP برای شماره موبایل ارسال و اعتبارسنجی میشود.
- کاربر اطلاعات پروفایل و در صورت نیاز اطلاعات احراز هویت را تکمیل میکند.
- درخواست پروژه از طریق فرم افزونه یا Gravity Forms ثبت میشود.
- درخواست با شماره یکتا در پنل مدیریت قابل مشاهده میشود.
- مدیر پیشنهاد قیمت ثبت میکند و وضعیت درخواست به مرحله دارای پیشنهاد تغییر میکند.
- کاربر پیشنهاد را مشاهده و در صورت تأیید، آن را میپذیرد.
- قرارداد بر اساس قالب تعریفشده ایجاد میشود.
- امضا/تأیید قرارداد از طریق OTP یا احراز هویت انجام میشود.
- در صورت نیاز، پرداخت ثبت و وضعیت قرارداد نهایی میشود.
۸.۲ فرایند تیکت پشتیبانی
- کاربر از داشبورد، موضوع و متن تیکت را ثبت میکند.
- تیکت در جدول تیکتها با وضعیت باز ذخیره میشود.
- مدیر از بخش تیکتها پاسخ میدهد و پیام در تاریخچه تیکت ثبت میشود.
- کاربر پاسخ را مشاهده کرده و در صورت نیاز پاسخ جدید ارسال میکند.
۸.۳ فرایند مشارکت
فرم مشارکت، اطلاعات کاربر مانند نام، شماره تماس، نوع مشارکت، شهر، استان، مبلغ و توضیحات را دریافت میکند و آن را به عنوان یک درخواست با نوع مشارکتی در جدول درخواستها ثبت مینماید.
۹. وضعیتها و شمارهگذاری
الگوی شمارهگذاری
| نوع | پیشوند | نمونه الگو | کاربرد |
|---|---|---|---|
| درخواست | REQ | REQ-[timestamp]-[random] | شناسه پیگیری درخواست |
| پیشنهاد | OFF | OFF-[timestamp]-[random] | شناسه پیشنهاد قیمت |
| قرارداد | CON | CON-[timestamp]-[random] | شناسه قرارداد |
وضعیتهای درخواست
| کلید وضعیت | معنی پیشنهادی |
|---|---|
| pending | در انتظار بررسی |
| has_offer | دارای پیشنهاد قیمت |
| expired | منقضی شده |
| awaiting_contract | در انتظار قرارداد |
| awaiting_inspection | در انتظار بازدید/بررسی |
| awaiting_installation | در انتظار نصب |
| awaiting_grid | در انتظار اتصال/شبکه |
| operational | بهرهبرداری شده |
وضعیتهای قرارداد و پرداخت
- draft: پیشنویس
- pending: در انتظار تأیید
- signed_by_user: امضا توسط مشتری
- verified: تأیید شده
- signed: امضا شده
- active: فعال
- completed: تکمیل شده
- cancelled: لغو شده
- pending: در انتظار پرداخت
- processing: در حال پردازش
- completed: پرداخت موفق
- failed: پرداخت ناموفق
- cancelled: لغو شده
- refunded: برگشت داده شده
۱۰. قراردادها و متغیرهای قالب
قالب قرارداد میتواند شامل متن HTML و متغیرهای قابل جایگزینی باشد. هنگام تولید قرارداد، افزونه متغیرها را با اطلاعات واقعی شرکت، کاربر، درخواست و پیشنهاد جایگزین میکند.
| گروه | متغیرها |
|---|---|
| اطلاعات قرارداد | {{contract_number}}، {{contract_date}}، {{signed_date}}، {{order_number}} |
| اطلاعات مشتری | {{customer_name}}، {{customer_national_id}}، {{customer_mobile}}، {{customer_address}}، {{customer_postal_code}}، {{customer_city}}، {{customer_province}}، {{customer_email}} |
| اطلاعات شرکت | {{company_name}}، {{company_id}}، {{company_address}}، {{company_phone}}، {{company_email}}، {{company_signature}} |
| درخواست و پیشنهاد | {{request_subject}}، {{request_number}}، {{offer_number}}، {{offer_amount}}، {{offer_amount_words}}، {{offer_description}}، {{project_description}} |
| شرایط پروژه | {{capacity}}، {{duration}}، {{guaranteed_profit}}، {{delay_penalty}}، {{custom_terms}}، {{notes}} |
| نامهای قدیمی | {{user_name}}، {{user_national_id}}، {{user_phone}}، {{offer_price}}، {{order_id}} |
۱۱. ساختار دیتابیس
افزونه جدولهای اختصاصی خود را با پیشوند دیتابیس وردپرس ایجاد میکند. در جدول زیر نام بدون پیشوند وردپرس آمده است.
| جدول | کاربرد | دادههای کلیدی |
|---|---|---|
| parsenergy_requests | درخواستها | کاربر، شماره درخواست، شهر، استان، نوع پروژه، اطلاعات فرم، وضعیت |
| parsenergy_offers | پیشنهادها | درخواست، شماره پیشنهاد، قیمت، تخفیف، مالیات، تاریخ انقضا، وضعیت |
| parsenergy_contracts | قراردادها | شماره قرارداد، محتوا، وضعیت، پرداخت، OTP، فایل PDF |
| parsenergy_payment_logs | پرداختها | کاربر، درخواست، قرارداد، مبلغ، سفارش، تراکنش، درگاه، وضعیت |
| parsenergy_sms_logs | لاگ پیامک | شماره، متن، نوع، سرویسدهنده، وضعیت، پاسخ سرویس |
| parsenergy_notifications | اعلانها | کاربر، عنوان، پیام، نوع، وضعیت خواندهشدن |
| parsenergy_otp_sessions | OTP | شماره، کد، نوع، مرجع، تعداد تلاش، زمان انقضا |
| parsenergy_user_meta | اطلاعات تکمیلی کاربر | کد ملی، آدرس، کدپستی، شرکت، تکمیل پروفایل |
| parsenergy_tickets | تیکتها | موضوع، پیام، پاسخ، وضعیت، زمانها |
| parsenergy_ticket_messages | پیامهای تیکت | شناسه تیکت، کاربر، پیام، نوع فرستنده |
| parsenergy_production | تولید ماهانه | کاربر، ماه، تاریخ، مقدار kWh |
| parsenergy_activity_logs | لاگ فعالیت | سطح، کانال، پیام، زمینه، کاربر، IP، مسیر درخواست |
| parsenergy_pages | مدیریت صفحات | عنوان، slug، محتوا، گزینه مرتبط |
۱۲. اتصالها و سرویسهای جانبی
| سرویس | کاربرد | اطلاعات مورد نیاز | تست پیشنهادی |
|---|---|---|---|
| Gravity Forms | ثبت درخواست با فرم سفارشی | شناسه فرم و نگاشت فیلدها | ارسال یک فرم تست و بررسی ایجاد درخواست |
| WooCommerce | پرداخت و سفارش | فعال بودن ووکامرس و محصول/سفارش مرتبط | ایجاد پرداخت تست و بررسی وضعیت قرارداد |
| Elementor | طراحی صفحات و ویجتها | فعال بودن Elementor و صفحه انتخابشده | نمایش داشبورد و قرارداد در فرانتاند |
| Digits | ورود/ثبتنام موبایلی جایگزین | شورتکد ورود و ثبتنام Digits | ورود و ثبتنام کاربر تست |
| Shabanic/Shahkar | احراز هویت و تطبیق موبایل/کد ملی | API Key و آدرس سرویس | استعلام تست با داده معتبر |
| سرویس پیامک | OTP و اطلاعرسانی | API Key، فرستنده، نام کاربری/رمز در صورت نیاز | ارسال OTP تست و مشاهده لاگ پیامک |
| OpenAI | قابلیتهای هوشمند | API Key، مدل و وضعیت فعالسازی | تست ارتباط از پنل مدیریت |
۱۳. نگهداری و پشتیبانی
اقدامات دورهای
- بررسی لاگ افزونه و لاگ پیامکها حداقل هفتهای یکبار.
- کنترل وضعیت پرداختهای ناموفق و سفارشهای ناقص.
- بررسی درخواستهای مانده در وضعیت pending یا has_offer.
- پاکسازی یا آرشیو لاگهای قدیمی پس از تهیه بکاپ.
- تست دورهای ارسال OTP و اتصال سرویس پیامک.
- تهیه بکاپ منظم از دیتابیس و فایلهای افزونه قبل از هر بهروزرسانی.
عیبیابی سریع
| مشکل | موارد قابل بررسی |
|---|---|
| OTP ارسال نمیشود | API Key پیامک، شماره فرستنده، اعتبار پنل، لاگ پیامکها و زمان انقضای OTP را بررسی کنید. |
| درخواست ثبت نمیشود | فرم، nonce، ورود کاربر، نگاشت فیلدها، جدول درخواستها و خطاهای لاگ افزونه را بررسی کنید. |
| قرارداد تولید نمیشود | پذیرش پیشنهاد، احراز هویت کاربر، قالب قرارداد و جدول قراردادها را بررسی کنید. |
| پرداخت همگام نمیشود | ووکامرس، وضعیت سفارش، metaهای سفارش و لاگ پرداخت را بررسی کنید. |
| متن فارسی بههمریخته است | collation دیتابیس، charset سایت، قالب قرارداد و خروجی PDF را بررسی کنید. |
۱۴. امنیت و کنترل دسترسی
افزونه در بخشهای مدیریتی از دسترسی مدیر وردپرس و در درخواستهای AJAX از nonce استفاده میکند. با این حال، رعایت موارد زیر برای بهرهبرداری امن ضروری است.
- کلیدهای API، رمزهای پیامک و اطلاعات سرویسها فقط در تنظیمات سایت واقعی وارد شوند و در فایلها نگهداری نشوند.
- مقادیر پیشفرض نام کاربری/رمز سرویس IPPanel بازبینی و در صورت عدم نیاز حذف یا تغییر داده شود.
- فایلهای نمونه و آزمایشی، مخصوصاً نمونههای پوشه nid، از محیط production حذف یا غیرقابل اجرا شوند.
- دسترسی مدیریت افزونه فقط به افراد مجاز داده شود.
- قبل از تحویل نهایی، آزمون دسترسی کاربران انجام شود تا هر کاربر فقط اطلاعات خود را مشاهده کند.
کنترلهای پیشنهادی
- فعالسازی SSL برای کل سایت.
- استفاده از نقشهای کاربری محدود برای اپراتورها به جای مدیر کل، در صورت توسعه نقش اختصاصی.
- محدودسازی دسترسی مستقیم به فایلهای لاگ و پوشههای آپلود.
- بهروزرسانی منظم وردپرس، قالب، افزونههای وابسته و PHP.
۱۵. چکلیست تحویل
چکلیست فنی
- نصب موفق افزونه و فعال بودن بدون خطای PHP.
- ایجاد جدولهای اختصاصی دیتابیس و صحت collation فارسی.
- ایجاد صفحات پیشفرض و قرارگیری صحیح شورتکدها.
- تکمیل تنظیمات شرکت، پیامک، فرمها، قرارداد و صفحات.
- تست ارسال OTP، ثبتنام، ورود، تکمیل پروفایل و احراز هویت.
- تست ثبت درخواست، ایجاد پیشنهاد، پذیرش پیشنهاد و تولید قرارداد.
- تست پرداخت، ثبت لاگ پرداخت و بهروزرسانی وضعیت قرارداد.
- تست تیکت، اعلان داخلی، پیامک اطلاعرسانی و لاگها.
چکلیست تحویل به کارفرما
| ردیف | مورد تحویلی | وضعیت |
|---|---|---|
| ۱ | فایل ZIP افزونه | تحویل شود |
| ۲ | این مستند HTML/PDF | تحویل شود |
| ۳ | اطلاعات دسترسی پنلهای پیامک و سرویسهای جانبی | توسط کارفرما تکمیل شود |
| ۴ | فهرست صفحات ساختهشده و لینکها | پس از نصب ثبت شود |
| ۵ | گزارش تست فرایند کامل درخواست تا قرارداد | قبل از production تکمیل شود |
| ۶ | بکاپ اولیه پس از راهاندازی | تهیه شود |