ویرایشگرهای سفارشی

گاهی کاری هست که در هیچ پنلی وجود ندارد، چون فقط مال شماست: بازمحاسبه قیمت‌ها با فرمول تأمین‌کننده، تطبیق کاتالوگ با یک سیستم حسابداری دیگر، صفحه‌ای برای «پر کردن مشخصات یک دسته در یک گذر». بخش «ویرایشگرهای سفارشی» به شما اجازه می‌دهد چنین ویرایشگر کوچکی را خودتان بنویسید (یا سفارش دهید) و آن را درون پنل مدیریت اجرا کنید — در یک محیط ایزوله، با دسترسی دقیقاً به همان داده‌هایی که اجازه داده‌اید.

باز کردن: پنل مدیریت → ویرایشگرهای سفارشی (admin.cenaly.com/custom-editors). این بخش با کارت «ویرایشگرهای سفارشی (SDK)» در فروشگاه برنامه‌ها فعال می‌شود — به‌طور پیش‌فرض پنهان است. دکمه «📌 افزودن به نوار کناری» در همان صفحه، آن را به منوی کناری می‌آورد، برای وقتی که زیاد لازمش دارید.

این بخش چیست#

افزونه یک اسکریپت ساخته‌شده (index.js) و توصیف آن (manifest.json) است. پنل اسکریپت را در یک قاب ایزوله بارگذاری می‌کند: نه به نشست شما دسترسی دارد، نه به کد پنل مدیریت، نه به شبکه. ارتباطش با داده‌ها فقط از طریق بریج ممکن است — مجموعه‌ای از درخواست‌های مجاز که هرکدام بر اساس مجوزهای صادرشده بررسی می‌شود.

صفحه از این بلوک‌ها تشکیل شده است:

ویرایشگر بازشده تمام صفحه را می‌گیرد و نشانی صفحه نشانه ?app=<شناسه> می‌گیرد — چنین پیوندی را می‌توانید با کسی که دسترسی دارد به اشتراک بگذارید.

برای راه‌اندازی چه لازم است#

گام ۱. تصمیم بگیرید چه کسی ویرایشگر را بنویسد#

سه مسیر وجود دارد و تفاوتشان در این است که کد دست کیست:

در هر سه حالت نصب بر عهده مالک می‌ماند: حتی توسعه‌دهنده‌ای با مجوز فقط می‌تواند کد خود را در حالت توسعه‌دهنده اجرا کند، اما نمی‌تواند آن را در حساب نصب کند.

گام ۲. توسعه با هوش مصنوعی (وایب‌کدینگ)#

بلوک «🤖 توسعه با هوش مصنوعی (وایب‌کدینگ)» چهار چیز می‌دهد تا کار را به یک عامل هوش مصنوعی (Claude Code، Cursor و مشابه) بسپارید و لازم نباشد قرارداد را از صفر برایش توضیح دهید:

1. «⬇️ دانلود قالب پروژه (zip)» — اسکلت آماده افزونه: مانیفست، نقطه ورود، توصیف قرارداد (GUIDE.en.md) و دستورالعمل برای عامل. آرشیو مستقیماً در مرورگر ساخته می‌شود و نیازی به دانلود چیزی از بیرون نیست.
2. «📋 کپی پرامپت برای عامل» — متن وظیفه به انگلیسی: از قالب شروع کن، با راهنما تطبیق بده، نتیجه را چطور بررسی کن.
3. پیکربندی مجموعه ابزارهای عامل — با آن، عامل افزونه را می‌سازد، یک پایه محلی به‌عنوان کپی محیط ایزوله بالا می‌آورد، عکس صفحه و عکس فوری وضعیت می‌گیرد و در پایان نسخه انتشار را می‌سازد: zip برای نصب دستی یا انتشار در GitHub.
4. «⬇️ دانلود عکس فوری کاتالوگ (فیکسچر آزمایشی)» — دسته‌ها و موارد شما به‌صورت فایل، تا عامل روی داده واقعی آزمایش کند، نه داده ساختگی.

⚠️ از عکس فوری فیلدهای سفارشی سایر افزونه‌ها کاملاً حذف می‌شوند: داده‌هایی که افزونه دیگری روی کارت‌های شما نگه می‌دارد، همراه فیکسچر از حساب خارج نمی‌شود.

گام ۳. نصب ویرایشگر#

از فایل‌ها. بلوک «نصب ویرایشگر»: «باندل (index.js)» و «مانیفست (manifest.json)» را انتخاب کنید → «بررسی و نصب». پنل ابتدا مانیفست را بررسی می‌کند — شناسه، نام بومی‌سازی‌شده، نسخه، کمینه نسخه SDK، محل‌های قرارگیری، مجوزها و فهرست میزبان‌های شبکه — و سپس رضایت را نشان می‌دهد: «این ویرایشگر درخواست می‌کند:» و فهرست مجوزها به زبان ساده. تا وقتی «نصب» را نزنید، چیزی نصب نمی‌شود.

از GitHub. بلوک «نصب از GitHub»: فیلد «مخزن (URL یا owner/repo)»، فیلد «برچسب (خالی = آخرین انتشار)» و دکمه «بررسی مخزن». قاعده ساده است: manifest.json در ریشه مخزن، dist/index.js ساخته‌شده در برچسب، برچسبی به شکل v{نسخه}. مانیفست و باندل مستقیماً از مرورگر شما دریافت می‌شوند. در هر دو حالت هنگام نصب اثر انگشت باندل (sha256) محاسبه و ذخیره می‌شود: اگر فایل بعداً جایگزین شود، اجرا مسدود می‌شود و پنل می‌خواهد ویرایشگر را دوباره نصب کنید.

حقوق و محل‌های قرارگیری#

حقوق (که به آن‌ها اسکوپ هم می‌گویند) توسط پلاگین در مانیفست درخواست می‌شود و شما هنگام نصب آن را تأیید می‌کنید. فهرست کامل همین است و بریج بیش از این کاری نمی‌تواند انجام دهد:

هر چیزی که در این فهرست نیست، پلاگین با هیچ تنظیمی به آن دسترسی نخواهد داشت: بریج مهمان‌ها و مشتریان، سفارش‌ها، رسیدها، امور مالی، کارکنان، مکالمات و تماس‌ها را در اختیار نمی‌گذارد.

محل‌های قرارگیری (اسلات‌ها) سه مورد است:

حالت توسعه‌دهنده و دسترسی پیمانکار#

حالت توسعه‌دهنده (بلوک «🛠️ حالت توسعه‌دهنده») پلاگین را به‌صورت زنده از رایانه شما نصب می‌کند: فیلد «URL باندل» فقط آدرس‌های localhost / 127.0.0.1 را می‌پذیرد، کنار آن «JSON مانیفست» و دکمه «شروع نشست توسعه» قرار دارد. در این حالت اثر انگشت پین نمی‌شود و نشست تا بستن تب فعال می‌ماند؛ «توقف نشست توسعه» آن را فوراً خاموش می‌کند.

دسترسی‌های توسعه‌دهنده (بلوک «👩‍💻 دسترسی توسعه‌دهنده») زمانی لازم است که نویسنده، مالک نباشد. برای توسعه‌دهنده یک حساب کارمند معمولی ساخته می‌شود و سپس مالک دسترسی را اعطا می‌کند: «ایمیل توسعه‌دهنده (همان ورود کارمندی او)»، «حقوق مجاز»، «مدت اعتبار (روز)» و یک یادداشت اختیاری → «اعطای دسترسی». لغو آن هر لحظه با دکمه «لغو» ممکن است.

دسترسی چه می‌دهد و چه نمی‌دهد:

• می‌دهد — فقط حالت توسعه‌دهنده با حقوقی که علامت زده‌اید (به‌طور پیش‌فرض ۱۴ روز، حداکثر ۹۰)؛
• حقوق با اشتراک محدود می‌شود: آنچه مانیفست درخواست می‌کند و آنچه با دسترسی اعطا شده است؛ پلاگین چیزی بیش از این نمی‌گیرد، حتی اگر در مانیفست درخواست کند؛
• نمی‌دهد — نصب، فعال‌سازی و حذف پلاگین‌ها: این‌ها برای مالک باقی می‌ماند.

به‌روزرسانی، فعال‌سازی و حذف#

به‌روزرسانی خودکار به‌عمد وجود ندارد: نسخه جدید کد شخص دیگر، اثر انگشت جدید و احتمالاً حقوق جدید است، بنابراین به‌روزرسانی همیشه اقدام آگاهانه مالک است.

افزونه‌های داخلی#

بخشی از ماژول‌های خود ما در همان قالب بسته‌بندی شده‌اند — این از رفتارشان پیداست، اما نیازی به نصب آن‌ها نیست: همراه پنل می‌آیند و با کارت در فروشگاه برنامه‌ها فعال می‌شوند، نه در این بخش.

در حال حاضر یک چنین ماژول وجود دارد — «Mercury/VetIS» برای روسیه: به‌صورت تب بخش «انبار» نمایش داده می‌شود، در همان سندباکس و با همان بررسی‌های اثر انگشت اجرا می‌شود. افزونه‌های داخلی در فهرست ویرایشگرهای نصب‌شده قرار نمی‌گیرند.

ویرایشگر چه می‌تواند و چه نمی‌تواند#

پلاگین‌های شخص ثالث روی کارت با یک هشدار مشخص می‌شوند: «برنامه شخص ثالث در سندباکس — هرگز رمز عبور نمی‌پرسد.» اگر پلاگینی ورود به پنل، اطلاعات پرداخت یا کد پیامکی بخواهد، این کلاهبرداری است، نه کارکرد افزونه.

محدودیت‌ها#

• این بخش به‌صورت پیش‌فرض خاموش است و برای کسانی در نظر گرفته شده که کد می‌نویسند (یا سفارش می‌دهند): کار مالک معمولی اینجا نیست.
• همه‌چیز جز مشاهده، فقط در اختیار مالک حساب است. کارمند فقط هاب را به‌صورت read-only می‌بیند؛ حالت توسعه‌دهنده تنها با مجوز فعال در دسترس است.
• مخزن‌های خصوصی GitHub پشتیبانی نمی‌شوند — مخزن باید عمومی باشد و نصب بر اساس تگ انجام می‌شود.
• به‌روزرسانی خودکار وجود ندارد: به‌روزرسانی افزونه همیشه توسط مالک آغاز می‌شود.
• فروشگاه افزونه‌های دیگران وجود ندارد. افزونه‌های آماده از طریق پنل منتشر یا فروخته نمی‌شوند — تنها منبع، فایل یا مخزن خودتان است.
• سه جایگاه وجود دارد (صفحه اختصاصی، دکمه کاتالوگ، تب انبار) — افزونه نمی‌تواند در هر صفحه دلخواه پنل جای بگیرد.
• بریج اطلاعات مهمان‌ها، سفارش‌ها، مالی، کارمندان و مکالمات را ارائه نمی‌دهد — دور زدن این محدودیت با مجوزها ممکن نیست، چون چنین درخواست‌هایی اصلاً وجود ندارند.
• ژورنال جداگانه‌ای برای «افزونه فلان کار را انجام داد» وجود ندارد. مجوزها روی کارت دیده می‌شوند و تغییرات کاتالوگ در تاریخچه معمول موارد ثبت می‌شوند؛ اگر کنترل لازم است، با افزونه‌ای شروع کنید که فقط دسترسی خواندن دارد.
• سقف‌های فنی: باندل تا 4 MB، تا 8 آدرس شبکه در مانیفست، تا 1 MB برای هر کلید ذخیره‌سازی؛ اجرای سمت سرور تا 30 ثانیه و تا 50 درخواست اینترنتی در هر بار.
• داده‌های افزونه در ابر برند شما باقی می‌ماند: برای حسابی روی cenaly.ru وضعیت بخش سروری در محدوده روسیه قرار دارد.

رفع اشکال#

پرسش‌های متداول#

آیا باید برنامه‌نویسی بلد باشم؟#

برای نصب یک نسخه آماده — نه. برای به دست آوردن خود نسخه — بله: آن را توسعه‌دهنده یا عامل هوش مصنوعی بر اساس قالب ما در بخش «توسعه با هوش مصنوعی» می‌نویسد. این بخش ابزاری برای کد است، نه سازنده «با ماوس».

آیا افزونه شخص دیگری می‌تواند مشتریان یا درآمد من را ببیند؟#

نه. افزونه در محیط ایزوله کار می‌کند و داده‌ها را فقط از طریق بریج دریافت می‌کند، و بریج دقیقاً شش کار انجام می‌دهد: کاتالوگ، قیمت‌ها و لیست‌های توقف فروش، دفتر انبار، ذخیره‌سازی اختصاصی، فراخوانی بخش سروری خودش و عناصر رابط کاربری. مهمان‌ها، سفارش‌ها، رسیدها، مالی، کارمندان و مکالمات اصولاً در آنجا وجود ندارند. اینکه دقیقاً چه چیزی برای یک افزونه مشخص مجاز است، همیشه روی کارت آن در سطر «مجوزها» دیده می‌شود.

چگونه توسعه را به پیمانکار بسپارم و او را به کل حساب راه ندهم؟#

برای او یک حساب کارمند بسازید و سپس در بخش «دسترسی توسعه‌دهنده» مجوز بدهید: فقط مجوزهای لازم را علامت بزنید و مدت را تعیین کنید (به‌صورت پیش‌فرض 14 روز، حداکثر 90). او حالت توسعه‌دهنده و چیز دیگری دریافت نمی‌کند؛ نصب افزونه در هر حال بر عهده شماست. مجوز با یک دکمه لغو می‌شود.

آیا افزونه وقتی نویسنده نسخه جدید منتشر کند، خودش به‌روز می‌شود؟#

نه. به‌روزرسانی را مالک آغاز می‌کند: «بررسی به‌روزرسانی‌ها» → «به‌روزرسانی به …». این‌گونه نسخه جدید بدون اطلاع فرد در حساب ظاهر نمی‌شود — همراه با نسخه، مجوزهای درخواستی هم ممکن است تغییر کرده باشند.

افزونه تنظیمات و داده‌های خود را کجا ذخیره می‌کند؟#

در حساب شما، در ذخیره‌سازی جداگانه‌ای زیر شناسه آن (تا 1 MB برای هر کلید)، و علاوه بر آن، اگر از آن‌ها استفاده کند، در فیلدهای سفارشی کارت‌های شما — هر افزونه فقط فضای خودش را می‌بیند. برای حسابی روی cenaly.ru بخش سروری و وضعیت آن در محدوده روسیه باقی می‌ماند.

تفاوت آن با API و MCP چیست؟#

API برای توسعه‌دهندگان و MCP مرکز تلفن شما زمانی لازم هستند که برنامه از بیرون کار می‌کند: سایت خودتان، سیستم حسابداری دیگری، عامل هوش مصنوعی. ویرایشگر سفارشی برعکس، رابطی درون پنل است: کارمند آن را مثل یک صفحه معمول پنل مدیریت باز می‌کند و از پنجره کاری خارج نمی‌شود.

بخش‌های مرتبط#

• فروشگاه برنامه‌ها — جایی که این بخش و افزونه‌های داخلی فعال می‌شوند
• انبار — تبی که افزونه‌هایی مانند «VetIS» در آن قرار دارند، و دفتر کالاها
• ورود کاتالوگ — مسیر استاندارد بارگذاری موارد، اگر کار فقط همین باشد
• ویترین روی کد خودتان (headless) — قرارداد باز داده برای سایت خارجی
• API و MCP مرکز تلفن شما و Guest API برای عامل‌های هوش مصنوعی — کار از بیرون، نه درون پنل
• کارمندان و شیفت‌ها — حساب برای توسعه‌دهنده و نقش‌ها
• امنیت و داده‌ها — داده‌ها کجا ذخیره می‌شوند و چه کسی به آن‌ها دسترسی دارد
• پشتیبانی — اگر افزونه رفتار مشکوکی داشت، کجا بنویسید