# مستندات کامل پلانک

---



---

# به مستندات پلانک خوش آمدید

مرجع یکپارچهٔ دارایی، توکنایزیشن، بازار، مدیریت و زیرساخت شبکهٔ پلانک.

وضعیت: مرجع | مخاطب: همهٔ کاربران
بازبینی مستندات: ۲۰۲۶/۰۹/۲۴ · ۲ مهر ۱۴۰۵

## یک اکوسیستم، چند مسئولیت روشن

پلانک مجموعه‌ای از محصولات مرتبط برای معرفی دارایی، طراحی توکن، عرضه و مدیریت بازار و راهبری زیرساخت شبکه است. مارکت‌پلیس، کنسول مدیریت وب و Admin Main وظایف یکسانی ندارند: اولی مسیر کاربر و نمایش دارایی را ارائه می‌کند، دومی محتوای بازار و اتصال‌های خدماتی را مدیریت می‌کند و سومی به عملیات شبکه و نودها اختصاص دارد.

این مرجع بر اساس کد و راهنماهای موجود پروژه تدوین شده است و علاوه بر قابلیت‌های کنونی، مراحل آینده را با برچسب مشخص پوشش می‌دهد. آماده بودن رابط یا کد، به معنای فعال بودن سرویس مالی، استقرار عمومی یا تأیید امنیتی مستقل نیست.

| محصول | کاربرد | مسیر مطالعه |
| --- | --- | --- |
| مارکت‌پلیس | کشف دارایی، جزئیات پروژه، قیمت بازار و تجربهٔ معامله | راهنمای بازار و کاربران |
| مدیریت وب | کاتالوگ، محتوا، احراز هویت، اتصال‌ها و گزارش تغییرات | کنسول مدیریت |
| Admin Main | پیکربندی، پایش و عملیات شبکهٔ Besu | شبکه و نودها |
| Planck Station | ابزار نود و اتصال به شبکه در محیط‌های پشتیبانی‌شده | Station و سیستم‌عامل‌ها |
| LIB Observer و macOS Remote | نقش‌های مشاهده‌گر و مدیریت از راه دور با حدود دسترسی متفاوت | محصولات شبکه |

## از مسیر مناسب خودتان شروع کنید

- سرمایه‌گذار: بازار، حقوق دارایی، قیمت‌گذاری، حساب کاربری و کیف پول را بخوانید.
- صاحب دارایی: مسیر پنج‌مرحله‌ای توکنایزیشن، توکنومیکس و الزامات عرضه را دنبال کنید.
- مدیر محصول: مدیریت کاتالوگ، نقش‌ها، اتصال‌ها و عملیات را مرور کنید.
- توسعه‌دهنده: معماری، قرارداد API، مدل احراز هویت و مرجع خطاها را ببینید.
- اپراتور شبکه: Admin Main، نودها، ولیدیتورها، راهنمای سیستم‌عامل و عملیات امن را مطالعه کنید.

## دامنه و تاریخ این نسخه

دامنهٔ این مستندات از خانوادهٔ قدیمی Besu و Station تا توسعه‌های وب شامل احراز هویت، بازار داده، سرمایه‌گذاری هوشمند، کپی‌ترید و ویترین اختصاصی است. تاریخ بازبینی این نسخه ۲۴ سپتامبر ۲۰۲۶، برابر با ۲ مهر ۱۴۰۵ است. تاریخ مذکور زمان بررسی مستندات است، نه تاریخ فعال‌سازی همهٔ قابلیت‌ها.

> وضعیت هر قابلیت را بخوانید: برچسب بالای صفحه وضعیت غالب آن موضوع را نشان می‌دهد؛ تفاوت بخش‌های فرعی در متن توضیح داده شده است. برای وضعیت اجرایی هر اتصال، همان محیط و سرویس باید بررسی شود.

## راهنما و ارتباط

برای راهنمای استفاده از خدمات و معرفی دارایی، از بخش پشتیبانی پلانک استفاده کنید. شمارهٔ مرکز تماس ۰۲۱۸۲۸۰۵۴۰۴ است. رمز، کد یک‌بارمصرف، کلید API و عبارت بازیابی را در گفت‌وگوی عمومی یا مدارک معرفی دارایی درج نکنید.

- [بازگشت به مارکت‌پلیس](/market)
- [پشتیبانی پلانک](/#planck-support)
- [شروع مطالعه](/docs/quickstart)

## مراجع پیاده‌سازی

- planck-marketplace/components/site-shell.tsx
- planck-marketplace/components/marketplace.tsx
- planck-marketplace/components/planck-support.tsx


---

# شروع سریع و مسیرهای استفاده

از اولین مشاهدهٔ دارایی تا انتخاب مسیر مناسب در بازار، مدیریت یا شبکه.

وضعیت: مرجع | مخاطب: کاربر، صاحب دارایی و تیم فنی
بازبینی مستندات: ۲۰۲۶/۰۹/۲۴ · ۲ مهر ۱۴۰۵

## مسیر سرمایه‌گذار

- از بازار، نوع دارایی و وضعیت دادهٔ آن را انتخاب کنید؛ پروژهٔ نمونه را از دارایی با قیمت دریافتی بازار تشخیص دهید.
- صفحهٔ دارایی را باز کنید و قیمت، واحد پول، اسناد، حقوق توکن، ریسک و شرایط خروج را مطالعه کنید.
- در صورت نیاز به خدمات حساب، ورود و تأییدهای مربوط را تکمیل کنید. سطح احراز هویت به‌تنهایی مجوز معاملهٔ هر دارایی نیست.
- محاسبهٔ تعداد توکن یا نمایش پنجرهٔ خریدوفروش را با ثبت سفارش قطعی اشتباه نگیرید؛ وضعیت اجرای مالی در همین مستندات مشخص است.
- برای مقایسهٔ انتخاب‌ها از سرمایه‌گذاری هوشمند و برای ساخت مجموعهٔ شخصی از ویترین استفاده کنید.

- [مشاهده بازار](/market)
- [ساخت ویترین](/storefront/create)

## مسیر صاحب دارایی

مسیر معرفی‌شده پنج مرحله دارد: انتخاب دارایی؛ ارزیابی مالکیت و مالی و استعلام‌ها؛ طراحی مقدار، نوع، شبکه و اقتصاد توکن؛ آمادگی عرضه در بازار پلانک یا بازار سازگار دیگر؛ و مدیریت چرخهٔ عمر دارایی. توضیح هر مرحله به معنای اجرای خودکار همهٔ فرایندها در نسخهٔ فعلی نیست.

- معرفی روشن دارایی و مدارک مالکیت را آماده کنید.
- حقوق خریدار، شیوهٔ ارزش‌گذاری و حدود انتقال را تعیین کنید.
- مدارک حساس را تنها در مسیر رسمی و دارای کنترل دسترسی ارسال کنید.
- برای شروع پذیرش واقعی، فعال بودن سرویس توکنایزیشن و قرارداد عرضه را بررسی کنید.

- [مسیر توکنایزیشن](/docs/tokenization)
- [حقوق و شرایط دارایی](/docs/asset-rights)

## مسیر مدیر و اپراتور

مدیریت وب و Admin Main دو برنامهٔ جدا هستند. دسترسی مدیریت محتوای سایت، مجوز مدیریت ولیدیتور نیست؛ در مقابل، دسترسی به نود، مجوز مشاهدهٔ مدارک هویتی مشتریان نمی‌دهد. برای هر نقش، اصل کمترین دسترسی و تأییدهای همان سامانه را دنبال کنید.

- [معماری محصولات](/docs/architecture)
- [مرجع امنیت](/docs/security)

## مسیر توسعه‌دهنده

ابتدا مرز API عمومی، نشست مشتری، نشست مدیر و سرویس شبکه را تشخیص دهید. مثال‌های خواندنی را در محیط آزمایش اجرا کنید و پاسخ‌های نمونه را قرارداد تسویه یا دادهٔ زنده تلقی نکنید. برای تغییرات دارای اثر مالی، از ثبت درخواست تا تطبیق نهایی به شناسهٔ یکتا و وضعیت قابل پیگیری نیاز است؛ بخشی از این چرخه در نقشهٔ راه قرار دارد.

- [راهنمای API](/docs/api-overview)
- [برنامهٔ توسعه](/docs/roadmap)

## مراجع پیاده‌سازی

- planck-marketplace/components/asset-tokenization.tsx
- planck-marketplace/components/token-trade.tsx
- planck-marketplace/components/storefront-page.tsx


---

# معماری محصولات و جریان داده

مرز مسئولیت مارکت‌پلیس، مدیریت وب، منابع داده و شبکهٔ پلانک.

وضعیت: مرجع | مخاطب: توسعه‌دهنده، معمار و مدیر محصول
بازبینی مستندات: ۲۰۲۶/۰۹/۲۴ · ۲ مهر ۱۴۰۵

## لایه‌های مستقل سامانه

| لایه | مسئولیت | مرز دسترسی |
| --- | --- | --- |
| رابط عمومی | نمایش پروژه‌های منتشرشده، جستجو و ابزارهای مقایسه | فقط اطلاعات عمومی |
| API مارکت‌پلیس | کاتالوگ، نشست مشتری، دادهٔ حساب و بازار | کنترل دسترسی متناسب با مسیر |
| مدیریت وب | ویرایش محتوا و دارایی، مدیریت اتصال و بازبینی | نشست مدیر، MFA و نقش |
| Supabase / PostgreSQL | دادهٔ ساختاریافته، Auth، Storage و سیاست‌های RLS | سیاست پایگاه داده و توابع محدود |
| ارائه‌دهندهٔ بیرونی | قیمت، هویت، بانک یا پیامک | فراخوانی سرور به سرور در اتصال مربوط |
| شبکه و ابزار نود | عملیات Besu، مشاهدهٔ سلامت و نقش ولیدیتور | پیکربندی و مجوز شبکه؛ مستقل از حساب وب |

## از پنل تا نمایش عمومی

پروژه‌ها از وضعیت پیش‌نویس تا انتشار در مدیریت کنترل می‌شوند. نمایش عمومی باید به رکوردهای مجاز محدود بماند؛ برچسب نمونه، وضعیت انتشار، اسناد و ریسک‌ها جزئی از معرفی دارایی‌اند. قیمت و ظرفیت معتبر باید در عملیات مالی سمت سرور دوباره بررسی شوند؛ محاسبهٔ مرورگر جای آن را نمی‌گیرد.

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

## قیمت بازار و نرخ تبدیل

دادهٔ Wallex در مسیرهای سرور دریافت و به مدل قابل استفادهٔ بازار تبدیل می‌شود. تنظیم Ondo در مدیریت، یک اتصال جدا با قابلیت بررسی دسترسی است و به‌تنهایی به معنای ورود همهٔ محصولات آن به کاتالوگ عمومی نیست. سیاست تبدیل ارز نیز تنظیم جداگانه دارد؛ مبنای نرخ و فعال بودن هر منبع باید از تنظیمات همان محیط خوانده شود.

واحد ریال، تومان، دلار و نماد توکن را همواره همراه عدد نگه دارید. فارسی‌سازی و جداکردن هزارگان برای نمایش است و نباید دقت مقدار یا واحد حسابداری را تغییر دهد.

## مرز هویت مشتری و هویت شبکه

نشست مشتری و پروندهٔ احراز هویت مربوط به خدمات وب است. اتصال یک آدرس عمومی کیف پول اثبات مالکیت خود دارایی یا تأیید همهٔ فعالیت‌های آن آدرس نیست. مجوز اپراتور شبکه و کلید امضای ولیدیتور نیز باید از مشخصات مشتریان و کلید اتصال سرویس‌ها مستقل بماند.

## مرز کد، انتشار و عملیات

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

> اتصال انتهابه‌انتها: صدور دارایی، تسویه، اجرای واقعی کپی‌ترید و یکپارچگی کامل چرخهٔ مالی به تکمیل سرویس‌ها و تأیید عملیاتی نیاز دارند؛ در نقشهٔ راه جداگانه آمده‌اند.

## مراجع پیاده‌سازی

- planck-marketplace/lib/server.ts
- planck-marketplace/lib/wallex-server.ts
- planck-marketplace/lib/storefront.ts
- planck-admin/README.md


---

# راهنمای وضعیت قابلیت‌ها

تفاوت پیاده‌سازی، نیاز به پیکربندی، پیش‌نمایش و برنامهٔ آینده.

وضعیت: مرجع | مخاطب: همهٔ خوانندگان
بازبینی مستندات: ۲۰۲۶/۰۹/۲۴ · ۲ مهر ۱۴۰۵

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

| برچسب | تعریف | برداشت صحیح |
| --- | --- | --- |
| پیاده‌سازی‌شده | مسیر یا رفتار مورد بحث در کد موجود است | اثبات استقرار عمومی یا ممیزی مستقل نیست |
| نیازمند پیکربندی | کد اتصال وجود دارد و به تنظیم سرویس/کلید/داده وابسته است | پاسخ محیط واقعی باید بررسی شود |
| پیش‌نمایش | رابط، محاسبه یا سناریوی نمونه برای بررسی تجربه ساخته شده است | ثبت معامله یا سود واقعی تلقی نشود |
| برنامهٔ آینده | قابلیت یا مرحلهٔ تکمیلی هنوز عملیاتی معرفی نشده است | تاریخ قطعی انتشار ندارد |
| مرجع | توضیح معماری، اصطلاحات یا دستورالعمل | ادعای فعال بودن یک سرویس نیست |

## تصویر کلی محصول

| موضوع | وضعیت و حدود |
| --- | --- |
| کاتالوگ و صفحات دارایی | پیاده‌سازی‌شده؛ کیفیت و انتشار داده به رکورد همان پروژه وابسته است |
| دادهٔ Wallex | اتصال موجود؛ تازگی قیمت و موجود بودن تاریخچه/عمق مستقل بررسی می‌شود |
| تنظیم Ondo و نرخ ارز | در مدیریت موجود؛ تنظیم کلید یا سیاست، معادل فعال‌سازی معامله نیست |
| سرمایه‌گذاری هوشمند | پیشنهاد و مقایسه در رابط؛ اجرای خودکار سفارش ادعا نمی‌شود |
| کپی‌ترید | پیش‌نمایش استراتژی و اتصال آزمایشی؛ بدون اجرای خودکار معامله |
| ویترین شخصی | ساخت مجموعه و لینک واقعی؛ بدون ذخیرهٔ فروشگاه در حساب |
| توکنایزیشن پنج‌مرحله‌ای | راهنمای فرایند و رابط معرفی؛ سرویس کامل صدور و عرضه در مسیر توسعه |
| حساب، بانک و هویت | مسیرها موجود؛ نتیجه به نشست، مهاجرت‌ها و اتصال سرویس وابسته است |
| نود و ولیدیتور | ابزارها و بسته‌های متفاوت؛ وضعیت دقیق هر محصول در صفحات شبکه |

## چه چیزی برای تأیید عملیاتی لازم است؟

- نسخه و محیط هدف مشخص باشد.
- ورود، نقش‌ها و خطاهای دسترسی در همان محیط آزمایش شوند.
- در عملیات مالی، نتیجه با دفترکل و ارائه‌دهنده یا شبکه تطبیق داده شود.
- امضای بسته، منبع دانلود و هش قابل اعتماد انتشار مشخص باشد.
- تست واحد و ساخت موفق، به‌عنوان شواهد کد گزارش شوند؛ با آزمون عملیاتی یکسان نیستند.

## چگونه این مرجع به‌روز می‌شود؟

با هر تغییر رفتار، قرارداد مسیر یا وضعیت سرویس، مقالهٔ مربوط و تاریخ بازبینی باید همراه همان تغییر اصلاح شود. قابلیت برنامه‌ریزی‌شده فقط پس از وجود شواهد پیاده‌سازی و بررسی محیط هدف تغییر وضعیت می‌دهد. این نسخه از مستندات به‌صورت خودکار وضعیت شبکهٔ زنده را پایش نمی‌کند.

## مراجع پیاده‌سازی

- planck-marketplace/app/api/quote/route.ts
- planck-marketplace/COPY_TRADING.md
- planck-marketplace/lib/storefront.ts


---

# واژه‌نامهٔ پلانک

اصطلاحات دارایی، بازار، شبکه و امنیت با تعریف روشن.

وضعیت: مرجع | مخاطب: همهٔ خوانندگان
بازبینی مستندات: ۲۰۲۶/۰۹/۲۴ · ۲ مهر ۱۴۰۵

## دارایی و بازار

| واژه | معنا |
| --- | --- |
| توکنایزیشن | تعریف و نمایش دیجیتال حقوق مشخص مرتبط با یک دارایی در قالب توکن |
| توکنومیکس | مدل تعداد، تخصیص، انتشار، کاربرد و حقوق و انگیزه‌های اقتصادی توکن |
| ناشر | شخص یا نهادی که مسئولیت صدور و شرایط توکن را بر عهده دارد |
| ارزش‌گذاری | برآورد ارزش دارایی بر اساس روش، زمان و فرض‌های معلوم |
| نقدشوندگی | امکان معامله در زمان و حجم مورد نظر بدون اثر نامتناسب بر قیمت |
| استیکینگ | قفل یا تخصیص دارایی طبق قواعد یک سازوکار مشخص؛ متفاوت با سود تضمین‌شده |
| کپی‌ترید | پیروی از معاملات یا برنامهٔ یک معامله‌گر طبق مجوزها و حدود از پیش تعیین‌شده |
| ویترین | مجموعهٔ منتخب از دارایی‌های عمومی با صفحه و لینک اختصاصی |

## شبکه

| واژه | معنا |
| --- | --- |
| نود | نرم‌افزار متصل به شبکه که داده و وضعیت زنجیره را پردازش می‌کند |
| ولیدیتور | نود دارای نقش مجاز در فرایند اعتبارسنجی یا اجماع شبکه |
| Observer | نقش مشاهده و پایش که لزوماً مجوز امضای بلوک ندارد |
| Genesis | پیکربندی و وضعیت آغاز زنجیره که هویت شبکه به آن وابسته است |
| RPC | رابط فراخوانی روش‌های سرویس؛ مجوز و نوع روش‌ها به پیکربندی بستگی دارد |
| Peer | همتای شبکه برای ارتباط نود با نود |
| Chain ID | شناسهٔ زنجیره؛ به‌تنهایی برای تأیید اصالت همهٔ تنظیمات شبکه کافی نیست |

## امنیت و عملیات

| واژه | معنا |
| --- | --- |
| MFA | تأیید هویت با عامل اضافی فراتر از رمز اصلی |
| TOTP | کد کوتاه‌عمر تولیدشده بر پایهٔ زمان |
| RLS | قواعد محدودسازی دسترسی به ردیف‌های داده در پایگاه داده |
| Vault | محل نگهداری محرمانهٔ مقادیر مانند کلید ارائه‌دهنده در اتصال مربوط |
| Idempotency | کنترل اینکه تکرار همان درخواست، اثر جدید ناخواسته ایجاد نکند |
| Audit log | تاریخچهٔ قابل پیگیری اقدامات و تغییرات |
| Ad-hoc signing | امضای محلی نرم‌افزار؛ معادل تأیید ناشر یا notarization عمومی نیست |
| End-to-end | آزمون کل مسیر واقعی خدمت از شروع تا نتیجهٔ نهایی |

## واحد و وضعیت

ریال واحد پایهٔ مبلغ در کاتالوگ است؛ نمایش تومان به تبدیل صحیح نیاز دارد. قیمت تتر لزوماً نرخ رسمی دلار نیست. «نمونه» به دادهٔ نمایشی اشاره دارد؛ «نیازمند پیکربندی» به وجود کد با وابستگی به محیط؛ و «برنامهٔ آینده» به قابلیت هنوز عملیاتی‌نشده اشاره می‌کند.

## مراجع پیاده‌سازی

- planck-marketplace/lib/trade.ts
- planck-marketplace/lib/exchange-rate.ts
- planck-admin/MFA_SETUP.md


---

# رفع اشکال و پرسش‌های رایج

تشخیص خطای داده، حساب، اتصال و شبکه بدون دست‌کاری تنظیمات حساس.

وضعیت: مرجع | مخاطب: کاربر و تیم پشتیبانی
بازبینی مستندات: ۲۰۲۶/۰۹/۲۴ · ۲ مهر ۱۴۰۵

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

ابتدا وضعیت دریافت داده و آخرین به‌روزرسانی را بررسی کنید. نبود تاریخچه یا عمق به معنای صفر بودن قیمت یا موجودی نیست. در اختلال ارائه‌دهنده، دادهٔ ساختگی را جای قیمت زنده قرار ندهید. نماد و واحد مورد انتظار باید با بازار پشتیبانی‌شده تطبیق داشته باشد.

## چرا تأیید خرید یا واریز فعال نیست؟

برخی پنجره‌ها برای مشاهده و برآورد ساخته شده‌اند و مسیر اجرای واقعی سفارش یا واریز هنوز فعال معرفی نشده است. راهنمای وضعیت همان قابلیت را بخوانید؛ کلیک‌های تکراری یا تغییر دستی ورودی درخواست، سرویس غیرفعال را فعال نمی‌کند.

## ورود یا تأیید هویت کامل نمی‌شود

کد یک‌بارمصرف، تأیید ایمیل، نشست معتبر و نتیجهٔ استعلام موضوعات جداگانه‌اند. پیام قابل نمایش برنامه را دنبال کنید و کد یا مدارک را برای افراد ناشناس ارسال نکنید. خطای اتصال سرویس نباید به رد هویت قطعی تعبیر شود. مدیر باید تنظیم اتصال و وضعیت ارائه‌دهنده را از مسیر مجاز بررسی کند.

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

ویترین فقط شناسه‌های معتبر و دارایی‌های قابل نمایش عمومی را حل می‌کند. حذف، تغییر انتشار یا ناموجود شدن دارایی باعث حذف آن از نمایش می‌شود؛ اطلاعات قدیمی داخل لینک، مجوز انتشار دوبارهٔ آن نیست. با سازندهٔ ویترین، مجموعهٔ جدید بسازید.

## برنامه باز است اما شبکه سالم نیست

باز بودن برنامه یا بالا بودن فرایند تنها بخشی از سلامت است. اتصال همتاها، همگامی زنجیره، نقش نود، تنظیم genesis و دادهٔ سلامت معتبر را مطابق راهنمای همان محصول بررسی کنید. بدون تشخیص علت، کلید جدید نسازید، دادهٔ زنجیره را حذف نکنید و RPC مدیریتی را عمومی نکنید.

## گزارش مشکل مفید

- نام محصول، نسخه، سیستم‌عامل و مرحله‌ای که مشکل در آن رخ داد را ذکر کنید.
- زمان رخداد و پیام قابل نمایش را ثبت کنید.
- شناسهٔ درخواست غیرمحرمانه را در صورت وجود ضمیمه کنید.
- کلید، کوکی، کد OTP، مدارک هویت و اطلاعات بانکی را از تصویر یا گزارش حذف کنید.

- [پشتیبانی پلانک](/#planck-support)

## مراجع پیاده‌سازی

- planck-marketplace/lib/wallex-server.ts
- planck-marketplace/app/api/quote/route.ts
- planck-marketplace/lib/storefront.ts
- planck-marketplace/components/planck-support.tsx


---

# آشنایی با مارکت‌پلیس پلانک

مسیر کشف دارایی، بررسی اطلاعات، ساخت سبد و ورود به صفحهٔ خرید و فروش.

وضعیت: پیاده‌سازی‌شده | مخاطب: همهٔ کاربران
بازبینی مستندات: ۲۰۲۶/۰۹/۲۴ · ۲ مهر ۱۴۰۵

## در بازار چه کاری می‌توان انجام داد؟

مارکت‌پلیس پلانک یک رابط فارسی‌محور برای معرفی پروژه‌ها و بررسی دارایی‌های توکنی است. صفحهٔ اصلی، دسته‌بندی‌ها، بازار کامل، صفحهٔ پروژه و پنجرهٔ دارایی به هم متصل‌اند؛ کاربر می‌تواند نام و نماد را جستجو کند، قیمت و اطلاعات منتشرشده را ببیند و محاسبهٔ خرید یا فروش را بررسی کند.

داشتن صفحهٔ بازار یا نمایش یک قیمت به معنی فعال بودن اجرای سفارش نیست. در این نسخه، ثبت نهایی خرید و فروش واقعی غیرفعال است و محاسبات فرم صرفاً برای بررسی هستند.

## مسیرهای اصلی

| مسیر | کاربرد |
| --- | --- |
| / | صفحهٔ اصلی، فرصت‌ها، سرمایه‌گذاری هوشمند، ویترین شخصی و معرفی توکنایزیشن |
| /market | جستجو، دسته‌بندی، مرتب‌سازی و نمای کارتی یا جدولی دارایی‌ها |
| /projects/[slug] | اطلاعات، مدارک، ریسک و محاسبهٔ خرید و فروش یک پروژه |
| /assets/USDTTMN | صفحهٔ اختصاصی دارایی متصل؛ اطلاعات، محاسبهٔ خرید و فروش و سفارش‌های بازار |
| /copy-trading | پیش‌نمایش کپی‌ترید |
| /storefront/create | ساخت لینک ویترین انتخابی |
| /account و /wallet | پروفایل و اطلاعات خصوصی دارایی‌های حساب |

## دسته‌بندی و مقایسه

دارایی‌ها در سه گروه مشهود، نامشهود و طرح سرمایه‌گذاری قرار می‌گیرند؛ گزینهٔ «همه» مجموعهٔ این دسته‌ها را نشان می‌دهد. قیمت، تغییرات ۲۴ساعته، مدت و بازده فقط در جایی نمایش داده می‌شوند که دادهٔ مرتبط وجود داشته باشد.

بازار کامل جستجو، مرتب‌سازی پیشنهادی، رشد، افت، قیمت و تازگی را ارائه می‌کند. نمای کارتی و جدولی و صفحه‌بندی ۱۲تایی برای مرور فهرست موجود است. مرتب‌سازی در مرورگر روی دادهٔ دریافت‌شده انجام می‌شود.

## تفاوت دادهٔ واقعی، نمونه و ناموجود

کاتالوگ سرور فقط پروژه‌های منتشرشده را می‌خواند. حالت live به دریافت کاتالوگ متصل اشاره می‌کند و به‌تنهایی به معنی غیرنمونه بودن همهٔ رکوردها نیست؛ برچسب is_demo هر پروژه همچنان اهمیت دارد.

حالت preview فقط برای ارزیابی طراحی است. وقتی خواندن کاتالوگ متصل شکست بخورد، حالت unavailable برمی‌گردد و اطلاعات ساختگی جای دادهٔ واقعی قرار نمی‌گیرد. دارایی‌های بازار با قیمت ناموجود یا منقضی، قیمت جایگزین ساختگی دریافت نمی‌کنند.

> برچسب نمونه را بخوانید: تصویر، نمودار و بازده پروژهٔ نمونه، مدرک عرضهٔ واقعی یا عملکرد تأییدشده نیست.

## نمایش و دسترس‌پذیری

طراحی فعلی از کارت‌ها و پنجره‌های شیشه‌ای، رنگ دسته‌بندی، تصاویر روشن‌تر، آیکون‌های سه‌بعدی و گرافیک کرهٔ زمین استفاده می‌کند. زبان نمایش و تم روشن یا تیره از تنظیمات رابط کنترل می‌شوند.

کاهش حرکت در تنظیمات حساب و ترجیح کاهش حرکت دستگاه برای بخش‌های متحرک پیش‌بینی شده است. فعال‌بودن یک زبان به تنظیمات محتوای سایت و تکمیل ترجمهٔ همان بخش وابسته است؛ وجود ساختار سه‌زبانه، تکمیل تمام ترجمه‌ها را تضمین نمی‌کند.

## مراجع پیاده‌سازی

- components/marketplace.tsx
- components/market-page.tsx
- components/site-shell.tsx
- lib/catalog.ts
- lib/server.ts
- lib/market-assets.ts
- ASSETS.md


---

# دارایی‌ها و پروژه‌های نمونه

شناخت ابزارهای بازار، هویت نمادها و تفاوت آن‌ها با پروژه‌های نمایشی.

وضعیت: نیازمند پیکربندی | مخاطب: کاربران و توسعه‌دهندگان
بازبینی مستندات: ۲۰۲۶/۰۹/۲۴ · ۲ مهر ۱۴۰۵

## پنج دارایی متصل به دادهٔ بازار

| عنوان رابط | نماد توکن | بازار مرجع | توضیح هویت |
| --- | --- | --- | --- |
| تتر | USDT | USDTTMN | تتر در بازار تومان |
| تترگلد | XAUT | XAUTTMN | Tether Gold |
| گواهی نفت دیجیتال | USOON | USOONTMN | United States Oil Fund · Ondo |
| گواهی مس دیجیتال | COPXON | COPXONTMN | Global X Copper Miners · Ondo |
| گواهی نقره دیجیتال | SLVON | SLVONTMN | iShares Silver Trust · Ondo |

## هر نماد چه چیزی را نمایش می‌دهد؟

مبدل بازار، نماد، دارایی پایه و واحد مظنه را به‌صورت دقیق تطبیق می‌دهد. قیمت این پنج بازار به تومان برای هر واحد توکن دریافت می‌شود. عنوان عمومی «نفت»، «مس» یا «نقره» نباید به‌عنوان تعداد بشکه، کیلوگرم یا اونس فیزیکی تفسیر شود؛ ابزارهای USOON، COPXON و SLVON در این اتصال، توکن‌های مرتبط با صندوق هستند.

حجم ۲۴ساعته، حجم معاملات انجام‌شده است. این عدد موجودی فروشنده، کل عرضه یا ظرفیت قطعی قابل خرید نیست. تعداد سفارش‌های دفتر سفارش نیز داده‌ای مستقل از حجم معاملات است.

## نمونه‌های طراحی در مخزن

فایل بذر نمونه، پروژه‌های زیر را با is_demo=true تعریف می‌کند. وجود فایل بذر به معنی نصب آن در هر محیط نیست. بازده‌ها و تصاویر این رکوردها برای نمایش محصول‌اند و نباید در مستندات به‌عنوان سود واقعی بازنشر شوند.

| پروژهٔ نمونه | شناسهٔ مسیر | کاربرد نمایشی |
| --- | --- | --- |
| توسعه نیروگاه خورشیدی | solar-power-revenue | مشارکت مفهومی در جریان درآمد فروش برق؛ نماد نمایشی در بذر بازار eSOL |
| مجتمع فرهنگی تفریحی ایزدشهر | izadshahr-cultural-complex | نمونهٔ توکن املاک و توسعهٔ فرهنگی و تفریحی؛ IZAD |
| اپلیکیشن استور غیرمتمرکز | decentralized-app-store | نمونهٔ استارتاپ و زیرساخت نرم‌افزار؛ DAPP |
| مارکت‌پلیس NFT | nft-marketplace | نمونهٔ بازار آثار و دارایی‌های دیجیتال؛ PNFT |

## تازگی و کیفیت قیمت

در اتصال فعلی، دریافت قیمت روی سرور برای ۲۰ ثانیه همگرا و نگهداری می‌شود؛ صفحات قابل مشاهده هر ۳۰ ثانیه تازه‌سازی می‌شوند. پس از ۹۰ ثانیه، قیمت معتبرِ تازه محسوب نمی‌شود. receivedAt زمان دریافت پاسخ توسط برنامه است، نه زمان آخرین معامله در سامانهٔ ارائه‌دهنده.

نمودار جزئیات از قیمت پایانی کندل‌های ساعتی و دفتر سفارش از سطوح معتبر خرید و فروش ساخته می‌شود. نبود داده یا پاسخ نامعتبر، به نمایش وضعیت ناموجود منجر می‌شود؛ نمودار ساختگی برای دارایی واقعی تولید نمی‌شود.

## نمایش یکپارچه در پلانک

این دارایی‌ها در همان کارت‌ها، دسته‌بندی‌ها، جستجو، مرتب‌سازی و انتخاب سبد پروژه‌های پلانک ظاهر می‌شوند. نمونه‌های کالایی مشخص‌شده در کد برای جلوگیری از تکرار از کاتالوگ نمایشی کنار گذاشته می‌شوند؛ رکورد پایگاه داده حذف یا تغییر نمی‌کند.

دادهٔ کاتالوگ پروژه‌ها و مظنهٔ بازار دو قرارداد جدا دارند. GET /api/catalog پروژه‌ها و محتوای سایت را می‌دهد؛ ابزارهای متصل در رابط با دادهٔ GET /api/markets/wallex ترکیب می‌شوند.

## مراجع پیاده‌سازی

- lib/wallex.ts
- lib/wallex-server.ts
- lib/market-assets.ts
- lib/server.ts
- lib/market-preview.ts
- supabase/seeds/20260908_sample_projects.sql
- supabase/seeds/20260908_token_market_samples.sql
- WALLEX_SETUP.md


---

# صفحهٔ دارایی و بررسی خرید و فروش

نحوهٔ خواندن اطلاعات پروژه و محدودیت‌های محاسبهٔ معامله.

وضعیت: پیاده‌سازی‌شده | مخاطب: سرمایه‌گذاران
بازبینی مستندات: ۲۰۲۶/۰۹/۲۴ · ۲ مهر ۱۴۰۵

## پیش از ورود مبلغ

صفحهٔ پروژه از مسیر /projects/[slug] باز می‌شود و عنوان، توضیح، مشخصات توکن، قیمت ثبت‌شده، مدت، ظرفیت، مدارک و ریسک منتشرشده را در اختیار کاربر قرار می‌دهد. مسیر نامعتبر یا پروژه‌ای که در کاتالوگ منتشرشده وجود ندارد، صفحهٔ یافت‌نشدن دریافت می‌کند.

نماد و تصویر برای شناسایی اولیه‌اند؛ تعریف حقوق دارنده، شرایط انتقال، سهم درآمد و شرایط خروج باید از توضیح و اسناد همان پروژه خوانده شود. برای دارایی متصل، پنجرهٔ بازار قیمت و اطلاعات واقعی موجود را کنار فرم خرید و فروش نشان می‌دهد.

## مبلغ، تعداد و موجودی

فرم‌های خرید و فروش از ورود ارقام فارسی و جداکنندهٔ سه‌رقمی پشتیبانی می‌کنند. گزینه‌های درصد موجودی تنها به موجودی آزاد حساب متصل‌اند؛ ارزش‌گذاری دارایی دیگر یا موجودی قفل‌شده به بودجهٔ قابل خرج تبدیل نمی‌شود.

برای پروژه‌ها، مقدار معامله به واحد کامل و ظرفیت باقی‌مانده محدود است. برای ابزارهای بازار، دقت تعداد از اطلاعات همان نماد خوانده می‌شود و حداقل یک توکن کامل فرض نمی‌شود. اگر دادهٔ موجودی نامعلوم باشد، رابط آن را با صفر ساختگی جایگزین نمی‌کند.

## گردکردن و مبلغ تخمینی

محاسبات مالی اصلی از رشتهٔ دهدهی و عدد صحیح بزرگ استفاده می‌کنند. در خرید ابزار بازار، تعداد رو به پایین و هزینهٔ نقدی به ریال کامل رو به بالا گرد می‌شود تا بودجهٔ واردشده تجاوز نشود. در فروش، مبلغ دریافتی رو به پایین گرد می‌شود.

مبلغ فرم، قیمت قطعی اجرا نیست. کارمزد نهایی، لغزش قیمت و نقدشوندگی باید در سرویس معامله تعیین شوند؛ رابط فعلی این عوامل را به‌صورت هزینهٔ قطعی جا نمی‌زند.

## پنجرهٔ بازبینی چه می‌کند؟

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

POST /api/quote در همین نسخه عمداً پاسخ 503 می‌دهد. هیچ محاسبهٔ سمت مرورگر، رزرو موجودی یا سفارش پذیرفته‌شده محسوب نمی‌شود.

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

## مراجع پیاده‌سازی

- app/projects/[slug]/page.tsx
- components/project-page.tsx
- components/token-trade.tsx
- components/market-asset-trade.tsx
- components/wallex-markets.tsx
- lib/trade.ts
- lib/market-trade.ts
- app/api/quote/route.ts


---

# سرمایه‌گذاری هوشمند و چیدمان سبد

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

وضعیت: پیاده‌سازی‌شده | مخاطب: سرمایه‌گذاران
بازبینی مستندات: ۲۰۲۶/۰۹/۲۴ · ۲ مهر ۱۴۰۵

## شروع از یک فیلد

در صفحهٔ اصلی ابتدا فقط ورودی میزان سرمایه و کنترل بازکردن تنظیمات دیده می‌شود. با ورود به فیلد یا بازکردن کشو، ارز مبنا، موجودی، افق زمانی، ریسک‌پذیری، انتخاب دارایی و سبد پیشنهادی ظاهر می‌شوند. بستن کشو یا عوض‌کردن تب، انتخاب‌ها را در همان بازدید حفظ می‌کند.

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

## انتخاب‌های قابل تنظیم

| کنترل | رفتار |
| --- | --- |
| ارز مبنا | تومان، ریال یا USDT؛ تومان یک رقم اعشار، ریال بدون اعشار و USDT تا شش رقم اعشار |
| موجودی | همهٔ موجودی، ۱۰، ۲۵، ۷۵ و ۱۰۰ درصد و نوار ۰ تا ۱۰۰ درصد از موجودی آزاد همین ارز |
| افق زمانی | گزینه‌های ۶، ۱۲، ۲۴ و ۳۶ ماه در رابط |
| دارایی‌ها | پروژه‌های واجد شرایط و پنج ابزار متصل در یک انتخاب مشترک |
| اولویت | توزیع متوازن یا وزن‌دهی بر اساس نزدیکی مدت پروژه به افق انتخابی |

## ریسک‌پذیری چه تغییری ایجاد می‌کند؟

این گزینه، نسبت ذخیره و حد تمرکز را تنظیم می‌کند؛ رتبه‌بندی کارشناسی ریسک هر دارایی یا پیش‌بینی سود نیست. سیاست روی کل سبد یکپارچه اعمال می‌شود.

| ترجیح | ذخیرهٔ نقدی هدف | حداکثر سهم هر دارایی از کل سرمایه |
| --- | --- | --- |
| محتاطانه | ۳۵٪ | ۲۰٪ |
| متعادل | ۲۰٪ | ۳۰٪ |
| جسورانه | ۱۰٪ | ۴۰٪ |

## چرا یک دارایی وارد سبد نمی‌شود؟

پروژه باید منتشرشده، دارای قیمت صحیح مثبت، ظرفیت باقی‌مانده و مدت معتبر تا افق انتخابی باشد. ابزار بازار باید هویت نماد منطبق، قیمت تازه، وضعیت اسپات و دقت تعداد معتبر داشته باشد. دادهٔ قدیمی یا انتخاب ناسازگار حذف می‌شود و تعداد انتخاب‌های کنارگذاشته‌شده در توضیح سبد قابل بررسی است.

ظرفیت محدود پروژه و سقف تمرکز در تقسیم بودجه لحاظ می‌شوند. حجم معاملات بازار ظرفیت قابل خرید تلقی نمی‌شود. باقیماندهٔ گردکردن یا نبود ظرفیت، نقدی می‌ماند و سهم‌های نمودار در مجموع صد درصد می‌شوند.

## مرجع تبدیل ارز

تبدیل تومان و ریال ثابت است: هر تومان برابر ده ریال. تبدیل USDT با مرجع انتخاب‌شده توسط مدیر انجام می‌شود؛ پیش‌فرض والکس است و ساختار فعلی انتخاب تکی والکس یا نوبیتکس و میانگین حسابی هر دو را پشتیبانی می‌کند.

این مرجع، نرخ USDT/IRR است و نباید نرخ نقدی دلار آمریکا نامیده شود. در حالت میانگین، همهٔ منابع انتخاب‌شده باید قیمت تازهٔ معتبر داشته باشند؛ برنامه بی‌صدا منبع خراب را حذف یا نرخ قدیمی را جایگزین نمی‌کند.

## خروجی سبد، دستور معامله نیست

سبد با هر انتخاب دوباره محاسبه می‌شود و هر دارایی برای بررسی بیشتر لینک دارد. این ابزار سفارش ثبت نمی‌کند، سود آینده را تخمین نمی‌زند و تضمین خروج در پایان مدت پروژه نمی‌دهد.

کارمزد، لغزش و عمق دفتر سفارش در برآورد لحاظ نشده‌اند. عنوان «هوشمند» در این بخش به قواعد شفاف چیدمان اشاره دارد؛ موتور فعلی مدل پیش‌بینی یا مشاور هوش مصنوعی متصل نیست.

## مراجع پیاده‌سازی

- components/smart-investment.tsx
- lib/smart-investment.ts
- lib/unified-investment.ts
- lib/investment-amount.ts
- lib/exchange-rate.ts
- lib/exchange-rate-server.ts
- COPY_TRADING.md
- WALLEX_SETUP.md


---

# کپی‌ترید: تجربهٔ فعلی و مسیر اتصال

بررسی الگوهای نمایشی، اتصال آزمایشی و مدل پیشنهادی سهم سود.

وضعیت: پیش‌نمایش | مخاطب: سرمایه‌گذاران و طراحان سرویس
بازبینی مستندات: ۲۰۲۶/۰۹/۲۴ · ۲ مهر ۱۴۰۵

## ورود به کپی‌ترید

تب کپی‌تریدرها در سرمایه‌گذاری هوشمند، معرفی کوتاه کشویی دارد و به /copy-trading می‌رود. صفحهٔ اختصاصی سه الگوی «ثبات و تنوع»، «تعادل هوشمند» و «فرصت‌های پویا» را برای آشنایی با تجربهٔ کاربری نشان می‌دهد.

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

## صفحهٔ اختصاصی هر الگو

فیلتر سبک به مقایسهٔ همین الگوهای نمایشی کمک می‌کند. هر صفحه توضیح سبک، فرم سرمایه و بخش برنامهٔ اختصاصی دارد؛ بازده یا تعداد دنبال‌کنندهٔ ساختگی نمایش داده نمی‌شود.

| مسیر | الگوی نمایشی |
| --- | --- |
| /copy-trading?trader=steady | ثبات و تنوع |
| /copy-trading?trader=balanced | تعادل هوشمند |
| /copy-trading?trader=dynamic | فرصت‌های پویا |

## اتصال آزمایشی و نمایش برنامه

کاربر سرمایهٔ مثبت، حد افت نمونه و بازهٔ بررسی را تعیین و آزمایشی بودن اتصال را تأیید می‌کند. سپس ترکیب بودجه و قواعد الگو نمایش داده می‌شوند. قطع اتصال، برنامه را دوباره می‌بندد و ویرایش تنظیمات را آزاد می‌کند.

اتصال تنها در وضعیت همان صفحه نگهداری می‌شود و با بارگذاری مجدد از بین می‌رود. هیچ موجودی خوانده یا تغییر داده نمی‌شود و هیچ سفارش، مجوز معامله یا رابطهٔ دنبال‌کردن پایدار ساخته نمی‌شود. حد افت نمونه، سفارش توقف واقعی ایجاد نمی‌کند.

## سهم سود چگونه معرفی شده است؟

نسبت نمایشی ۸۰ درصد برای سرمایه‌گذار و ۲۰ درصد برای تریدر، فقط مثال طراحی است؛ تعرفهٔ فعال یا محاسبهٔ تسویه نیست. مدل پیشنهادی قرار است سهم تریدر را فقط از سود خالص تحقق‌یافتهٔ مثبت بگیرد، نه از اصل سرمایه.

نرخ هر تریدر، جبران زیان قبلی، دورهٔ تسویه، هزینه‌ها و شرایط خروج باید پیش از اتصال واقعی تعریف و پذیرفته شوند. نسخهٔ فعلی هیچ سود یا کارمزدی ایجاد، جمع یا پرداخت نمی‌کند.

## چه چیزی برای کپی‌ترید واقعی باقی مانده است؟

- پذیرش و شناسایی تریدرهای واقعی و دریافت عملکرد قابل راستی‌آزمایی.
- دسترسی به برنامه پس از کنترل مجوز روی سرور و رابطهٔ اتصال پایدار.
- موتور اجرای سفارش، حدود مجوز، کنترل ریسک و رفتار مشخص هنگام قطع اتصال.
- قرارداد نرخ، گزارش تسویه و سازوکار محاسبه و پرداخت سهم سود.

> قفل نمایشی، کنترل دسترسی واقعی نیست: برنامه‌های این نسخه صرفاً محتوای نمونه‌اند. برنامهٔ واقعی باید پس از مجوز سرور دریافت شود؛ پنهان‌کردن بخش رابط به‌تنهایی حفاظت دسترسی ایجاد نمی‌کند.

## مراجع پیاده‌سازی

- components/copy-trading-page.tsx
- app/copy-trading/page.tsx
- lib/copy-trading.ts
- COPY_TRADING.md


---

# ساخت بازار و ویترین شخصی

انتخاب دارایی‌های عمومی و ساخت صفحه‌ای واقعی که با لینک باز می‌شود.

وضعیت: پیاده‌سازی‌شده | مخاطب: همهٔ کاربران
بازبینی مستندات: ۲۰۲۶/۰۹/۲۴ · ۲ مهر ۱۴۰۵

## ویترین خودتان را بسازید

از بخش «بازار خودتون را بسازید» به /storefront/create بروید. نامی برای ویترین، توضیحی کوتاه و یکی از رنگ‌های نعنایی، بنفش یا کهربایی انتخاب کنید؛ سپس دارایی‌های دلخواه را از کاتالوگ منتشرشده انتخاب کنید.

جستجو با نام یا نماد و پیش‌نمایش زنده در همان صفحه در دسترس است. ویترین می‌تواند پروژه‌های پلانک و ابزارهای بازار را در یک مجموعه نشان دهد.

## حدود اطلاعات و انتخاب

| فیلد | محدودیت |
| --- | --- |
| نام | اجباری؛ حداکثر ۶۰ نویسه |
| توضیح | اختیاری؛ حداکثر ۱۶۰ نویسه |
| دارایی‌ها | حداقل یک و حداکثر ۱۲ دارایی؛ شناسه‌های تکراری یکی می‌شوند |
| رنگ | mint، violet یا amber |
| دارایی ناموجود | در صفحهٔ عمومی نمایش داده نمی‌شود؛ برای ساخت لینک تازه باید از انتخاب نامعتبر حذف شود |

## لینک عمومی چگونه کار می‌کند؟

دکمهٔ «ساخت لینک ویترین»، آدرس /storefront را با نام، توضیح، شناسهٔ دارایی‌ها و رنگ در پارامترهای نشانی می‌سازد. کپی لینک فقط با کلیک کاربر انجام می‌شود و نتیجهٔ موفق یا ناموفق نمایش داده می‌شود.

این تنظیمات در لینک عمومی قرار دارند. ویرایش بعدی، لینک تازه‌ای می‌سازد؛ فروشگاهی در حساب کاربری یا پایگاه داده ذخیره نمی‌شود. دارایی‌های هر لینک هنگام بازشدن دوباره از فهرست عمومی فعلی تطبیق داده می‌شوند.

## بازدیدکننده چه می‌بیند؟

صفحهٔ عمومی فقط دارایی‌های انتخاب‌شده و همچنان منتشرشده را نشان می‌دهد. قیمت از اطلاعات موجود کاتالوگ یا قیمت تازهٔ بازار می‌آید؛ برچسب نمونه حفظ می‌شود و دادهٔ ناموجود به‌صورت ناموجود باقی می‌ماند.

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

## محدودهٔ فروشگاه فعلی

ویترین شخصی یک مجموعهٔ قابل اشتراک است. دامنهٔ مستقل، حساب فروشنده، سفارش مستقل فروشگاه، کمیسیون، پذیرش دارایی جدید و داشبورد فروش در این قابلیت پیاده نشده‌اند.

لینک ناقص یا نامعتبر، پیام مشخص و مسیر ساخت ویترین تازه دارد. اگر بخشی از دارایی‌ها حذف یا از انتشار خارج شده باشند، تعداد موارد ناموجود اعلام می‌شود و بقیهٔ مجموعه قابل مشاهده می‌ماند.

- [ساخت ویترین](/storefront/create)

## مراجع پیاده‌سازی

- components/market-builder-promo.tsx
- components/storefront-page.tsx
- lib/storefront.ts
- app/storefront/page.tsx
- app/storefront/create/page.tsx
- tests/storefront.test.mjs


---

# اعداد فارسی و دقت مبالغ

نمایش خوانا بدون تغییر مقدار واقعی مبلغ، قیمت و تعداد.

وضعیت: پیاده‌سازی‌شده | مخاطب: کاربران و توسعه‌دهندگان رابط
بازبینی مستندات: ۲۰۲۶/۰۹/۲۴ · ۲ مهر ۱۴۰۵

## قالب نمایش

فیلدهای مبلغ، قیمت و تعداد از نمایش ارقام فارسی و گروه‌بندی سه‌رقمی مانند ۱٬۲۵۰٬۰۰۰ پشتیبانی می‌کنند. در زبان انگلیسی، همان مقدار با رقم لاتین و جداکنندهٔ مناسب نمایش داده می‌شود؛ برای عربی نیز رقم‌های عربی پیش‌بینی شده‌اند.

فیلد عددی خالی، صفر نمایش می‌دهد اما مدل داخلی می‌تواند همچنان خالی باشد تا ورود مبلغ مثبت و اعتبارسنجی با مقدار ساخته‌شده اشتباه نشود.

## ورود و ویرایش عدد

کاربر می‌تواند رقم فارسی، عربی یا لاتین وارد یا جای‌گذاری کند. جداکننده‌ها و نشانهٔ اعشار به مدل دهدهی استاندارد تبدیل می‌شوند. جابه‌جایی نشانگر و حذف کنار جداکننده با گروه‌بندی هماهنگ شده است.

مدل مبلغ رشته‌ای باقی می‌ماند؛ اعشار تایپ‌شده و صفرهای انتهایی بدون تبدیل زودهنگام به عدد ممیز شناور حفظ می‌شوند. توان علمی، عدد منفی و ساختار نامعتبر به‌عنوان مبلغ قابل قبول تلقی نمی‌شوند.

## واحد مالی را از قالب جدا کنید

تغییر رقم یا جداکننده، واحد پول را عوض نمی‌کند. ریال و تومان نسبت ثابت ده به یک دارند و تبدیل USDT به مرجع تازهٔ نرخ نیاز دارد.

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

## کجا اعمال شده است؟

- ورودی خرید و فروش پروژه و دارایی متصل.
- سرمایه‌گذاری هوشمند و سرمایهٔ آزمایشی کپی‌ترید.
- فرم مبلغ شارژ و هدف هشدار قیمت.
- نمایش مقادیر مرتبط در خروجی‌ها؛ شناسه، موبایل، شبا، تاریخ و رمز این قرارداد مالی را ندارند.

> ناموجود برابر صفر نیست: صفرِ فیلد خالی با نبود قیمت، نبود موجودی معتبر یا اختلال سرویس تفاوت دارد؛ دادهٔ ناموجود همچنان با وضعیت مشخص یا خط تیره نمایش داده می‌شود.

## مراجع پیاده‌سازی

- components/localized-number-input.tsx
- lib/localized-number-input.ts
- lib/investment-amount.ts
- components/investment-amount-input.tsx
- components/token-trade.tsx
- components/market-asset-trade.tsx
- components/cash-wallet.tsx
- tests/localized-number-input.test.mjs


---

# پشتیبانی و دستیار پلانک

تماس، راهنمای پرسش‌های متداول و حالت اختیاری دستیار متصل.

وضعیت: نیازمند پیکربندی | مخاطب: همهٔ کاربران
بازبینی مستندات: ۲۰۲۶/۰۹/۲۴ · ۲ مهر ۱۴۰۵

## ارتباط با پلانک

بخش پشتیبانی صفحهٔ اصلی، تماس تلفنی با شمارهٔ ۰۲۱۸۲۸۰۵۴۰۴ و گفت‌وگو با دستیار را در دسترس می‌گذارد. دکمهٔ تماس، برنامهٔ تلفن دستگاه را باز می‌کند.

این رابط ساعات پاسخ‌گویی یا حضور قطعی کارشناس زنده را اعلام نمی‌کند. گفت‌وگوی آنلاین فعلی به دستیار محصول متصل است، نه سامانهٔ تیکت یا گفت‌وگوی انسانی پیاده‌شده.

## حالت راهنما

اگر درگاه هوش مصنوعی تنظیم نشده باشد، درخواست پیام با پرسش‌های متداول منتشرشده تطبیق داده می‌شود و پاسخ با mode:guide بازمی‌گردد. این حالت مدل هوش مصنوعی متصل معرفی نمی‌شود.

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

## حالت دستیار متصل

در صورت تنظیم درگاه دستیار روی سرور، ورود به حساب برای ارسال پیام لازم است. سرور پیام، شناسهٔ حساب و محتوای FAQ را به درگاه می‌فرستد و پاسخ را با mode:ai بازمی‌گرداند.

وجود این قرارداد، تعیین‌کنندهٔ ارائه‌دهنده یا کیفیت پاسخ نیست. کنترل مصرف و استناد به اطلاعات تأییدشده باید در سرویس درگاه اجرا شود؛ کلید درگاه نباید در مرورگر قرار گیرد.

## دامنهٔ درخواست و پاسخ

پیام بین ۱ تا ۱۰۰۰ نویسه پذیرفته می‌شود؛ پاسخ درگاه به حداکثر ۶۰۰۰ نویسه محدود است. خطای دریافت پاسخ، خطای روشن سرویس می‌دهد و پاسخ ساختگی تولید نمی‌شود.

دستیار دستور خرید، انتقال موجودی یا صدور توکن اجرا نمی‌کند. دکمهٔ مشاورهٔ توکنایزیشن فقط پرسش مرتبط را در همین جریان گفت‌وگو آماده می‌کند.

## مراجع پیاده‌سازی

- components/planck-support.tsx
- components/site-shell.tsx
- components/assistant-mark.tsx
- app/api/assistant/route.ts
- README.md


---

# حقوق دارایی، شرایط عرضه و ریسک

اطلاعاتی که پیش از تبدیل دارایی به توکن و معرفی آن به سرمایه‌گذار باید روشن باشد.

وضعیت: مرجع | مخاطب: صاحب دارایی و سرمایه‌گذار
بازبینی مستندات: ۲۰۲۶/۰۹/۲۴ · ۲ مهر ۱۴۰۵

## توکن دقیقاً نمایندهٔ چیست؟

توکن ممکن است نمایندهٔ حق یا منفعت مشخص در یک ساختار تعریف‌شده باشد. نام دارایی، تصویر آن یا وجود نماد روی شبکه به‌تنهایی مالکیت مستقیم ملک، طلا، نفت یا سهام را اثبات نمی‌کند. حقوق باید در اسناد همان پروژه مشخص شوند؛ این متن هیچ ساختار حقوقی واحدی را برای همهٔ دارایی‌ها تعیین نمی‌کند.

| موضوع | پرسش لازم |
| --- | --- |
| دارایی مبنا | دارایی چیست، کجا نگهداری می‌شود و چگونه شناسایی شده است؟ |
| ناشر و متولی | مسئول صدور، نگهداری، گزارش و پاسخ‌گویی چه کسی است؟ |
| حقوق دارنده | دارنده چه حق مالکیت، مطالبه، منفعت یا دسترسی دارد؟ |
| انتقال و بازخرید | انتقال به چه اشخاصی مجاز است و خروج چگونه انجام می‌شود؟ |
| ارزش‌گذاری | قیمت، هزینه‌ها و دورهٔ ارزیابی چگونه تعیین می‌شوند؟ |
| وقایع دارایی | تغییر بهره‌برداری، خسارت، توقف یا انحلال چگونه رسیدگی می‌شود؟ |

## افشا پیش از عرضه

- اسناد هویت و اختیار ناشر، مدارک مالکیت و محدودیت‌ها باید بررسی شوند.
- تعداد توکن، اعشار، تخصیص، برنامهٔ انتشار و حقوق هر واحد مشخص شود.
- شبکه و آدرس قرارداد تأییدشده، فقط پس از استقرار معتبر منتشر شود.
- کارمزد خرید، فروش، نگهداری و خروج از هم تفکیک شود.
- ادعای بازده یا ارزش‌گذاری باید با منبع و دورهٔ آن همراه باشد.

## ریسک‌های مستقل

ریسک قیمت دارایی، نقدشوندگی بازار، عملکرد ناشر، نگهداری دارایی، خطای قرارداد هوشمند و اختلال شبکه موضوعات جداگانه‌اند. معامله‌پذیری توکن به معنای نقدشوندگی دائمی نیست و وجود قیمت آخرین معامله، فروش قطعی همهٔ حجم مورد نظر را تضمین نمی‌کند.

محصولات خارجی شرایط دسترسی و محدودیت‌های خاص خود دارند. معرفی اتصال Ondo یا دریافت نماد یک دارایی از Wallex به‌معنای تأیید صلاحیت همهٔ کاربران برای استفاده از آن محصول نیست.

## بررسی تخصصی هر عرضه

بررسی حقوقی و الزامات حوزهٔ فعالیت باید برای هر پروژه و محل عرضه توسط مسئولان تخصصی انجام شود. این صفحه چک‌لیست طراحی اطلاعات محصول است و نظر حقوقی یا وعدهٔ سود نیست. وضعیت تأییدها و استعلام‌های واقعی باید در پروندهٔ همان دارایی مشخص باشد.

- [مراحل توکنایزیشن](/docs/tokenization)
- [وضعیت قابلیت‌ها](/docs/status)

## مراجع پیاده‌سازی

- planck-marketplace/components/asset-tokenization.tsx
- planck-marketplace/components/project-page.tsx
- planck-marketplace/lib/wallex.ts


---

# ثبت و پیگیری توکنایزیشن دارایی

پروندهٔ خصوصی دارایی، بررسی کارشناسی و پذیرش توکنومیکس تا ثبت نتیجهٔ واقعی صدور.

وضعیت: نیازمند پیکربندی | مخاطب: صاحبان دارایی و پروژه
بازبینی مستندات: ۲۰۲۶/۰۹/۲۴ · ۲ مهر ۱۴۰۵

## ورود به پروندهٔ دارایی

صفحهٔ /tokenize مسیر ثبت درخواست، نگهداری پیش‌نویس، بارگذاری مدارک و پیگیری نتیجه را فراهم می‌کند. معرفی پنج‌مرحله‌ای صفحهٔ اصلی، نمای کلی مسیر از دارایی تا بازار است؛ صفحهٔ پرونده مراحل اجرایی دریافت اطلاعات و بررسی همان درخواست را نشان می‌دهد.

ثبت درخواست به حساب واردشده نیاز دارد. کاربر ابتدا شرایط جاری را می‌خواند و می‌پذیرد، سپس نوع دارایی را انتخاب می‌کند. ثبت پرونده اثبات مالکیت، مجوز عرضه یا تضمین صدور و فروش توکن نیست.

- [شروع ثبت دارایی](/tokenize)

## ۲۰ نوع دارایی و اطلاعات اختصاصی

دارایی‌های مشهود شامل نیروگاه خورشیدی، املاک، زمین، ملک تجاری، کشاورزی، ماشین‌آلات، خودرو، فلزات گران‌بها، آثار هنری، پروژهٔ نفتی، نیروگاه بادی، زیرساخت و پروژهٔ معدنی هستند. دارایی‌های نامشهود شامل استارتاپ، سهام شرکت، مالکیت فکری، پتنت، برند، نرم‌افزار و حق دریافت درآمد هستند.

عنوان، مالک، نوع مالک، کشور، شهر، نشانی، معرفی و ارزش برآوردی ریالی اطلاعات مشترک‌اند. هر نوع دارایی فیلدهای تخصصی خود را دارد؛ برای مثال ظرفیت نیروگاه، مشخصات ثبتی ملک یا محدودهٔ حقوق نرم‌افزار. مبلغ‌ها به‌صورت رشتهٔ عددی دقیق نگهداری می‌شوند و ورود ارقام فارسی پشتیبانی می‌شود.

## پنج مرحلهٔ پرونده

| مرحله | عملیات فعلی |
| --- | --- |
| ۱. انتخاب دارایی | انتخاب گروه مشهود یا نامشهود و نوع دقیق دارایی پس از مطالعهٔ شرایط. |
| ۲. مشخصات دارایی | تکمیل اطلاعات مشترک و اختصاصی؛ ذخیرهٔ پیش‌نویس ناقص امکان‌پذیر است. |
| ۳. اسناد و مدارک | انتخاب موقت مدارک ضروری و اختیاری؛ بارگذاری فقط هنگام ذخیرهٔ پیش‌نویس یا ارسال انجام می‌شود. |
| ۴. بررسی و تأیید | مرور اطلاعات و مدارک و ارسال پرونده؛ پس از ارسال، نمایش نظرهای حقوقی، مالی و فنی و موارد نیازمند اصلاح. |
| ۵. توکنومیکس و واریز | مطالعه و دریافت متن پیشنهاد، پذیرش نسخهٔ نهایی و پیگیری نتیجهٔ صدور برای کیف پول داخلی پلانک. |

## مدارک خصوصی و اصلاح پرونده

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

مدارک متناسب با نوع دارایی دریافت می‌شوند. فایل‌های PDF، JPG و PNG تا ۱۰ مگابایت پذیرفته می‌شوند؛ نوع محتوای فایل در سرور بررسی می‌شود. مدارک در فضای خصوصی نگهداری می‌شوند و دانلود به مجوز صاحب پرونده یا کارشناس مجاز وابسته است.

پیش‌نویس و پروندهٔ نیازمند اصلاح قابل ویرایش‌اند. مدارک ردشده یا نیازمند اصلاح باید جایگزین شوند؛ وجود یک فایل به معنی تأیید آن نیست. پس از ارسال، تغییر مستقیم اطلاعات و مدارک توسط مشتری بسته می‌شود تا پرونده دوباره برای اصلاح بازگردانده شود.

یادداشت داخلی کارشناسان برای مشتری ارسال نمی‌شود. مشتری پیام نتیجهٔ هر بررسی و پیام مربوط به مدرک یا پروندهٔ خود را می‌بیند.

## وضعیت‌ها و پذیرش نسخهٔ مشخص

وضعیت پرونده از پیش‌نویس به ارسال‌شده و در حال بررسی می‌رود و ممکن است نیازمند اصلاح یا رد شود. پس از تکمیل بررسی‌های لازم، پیشنهاد توکنومیکس با شمارهٔ نسخه در اختیار صاحب دارایی قرار می‌گیرد.

پذیرش پیشنهاد به شمارهٔ نسخه و آخرین نسخهٔ پرونده وابسته است. تغییر مدارک یا اطلاعات، رضایت ثبت‌نشدهٔ رابط را پاک می‌کند و تعارض با تغییر هم‌زمان، خطای روشن می‌دهد. پذیرش نهایی درخواست صدور ایجاد می‌کند؛ این رویداد به‌تنهایی وضعیت صادرشده یا موجودی توکن ایجاد نمی‌کند.

## وضعیت فعال‌سازی و واریز واقعی

ثبت و بررسی پرونده در محیط تأییدشدهٔ پلانک در تاریخ ۲۰۲۶/۰۹/۲۴ راه‌اندازی شد؛ ۲۰ نوع دارایی، جدول‌های محافظت‌شده و فضای خصوصی مدارک در پایگاه داده فعال‌اند. برای نصب در محیط دیگر، اجرای مهاجرت 202609240001_asset_tokenization.sql و تنظیم فضای خصوصی مدارک همچنان لازم است.

پس از پذیرش، پرونده در انتظار صدور باقی می‌ماند تا فرایند معتبر صدور و سرویس بررسی رسید شبکه راه‌اندازی و تنظیم شود. سرویس مورد اعتماد باید شبکه، قرارداد، مقصد، مقدار و رسید واقعی را بررسی کند؛ ثبت قطعی و یک‌بارهٔ موجودی کیف پول داخلی فقط پس از این تأیید انجام می‌شود.

در این مسیر نشانی خارجی از مشتری دریافت نمی‌شود. انتخاب مقصد و بررسی رسید وظیفهٔ سرویس مورد اعتماد است و مرورگر مشتری یا کارشناس نمی‌تواند موفقیت صدور یا موجودی را اعلام کند.

در تخصیص اولیه، کل تعداد توکنِ تأییدشده در کیف پول داخلی صاحب پرونده قفل است. موجودی قابل معامله، برداشت یا استفاده در خدمات مالی به‌صورت خودکار فعال نمی‌شود و به فرایند جداگانهٔ آزادسازی نیاز دارد.

## مرز این فرایند

بررسی پرونده جای مجوز قانونی پروژه، استعلام مرجع مربوط یا قرارداد نهایی را نمی‌گیرد. ثبت تأیید کارشناس به معنی دریافت خودکار تمام مجوزهای هر حوزه نیست.

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

## مراجع پیاده‌سازی

- components/tokenize-page.tsx
- app/tokenize/page.tsx
- lib/tokenization.ts
- app/api/tokenization/route.ts
- app/api/tokenization/documents/route.ts
- lib/tokenization-files.ts
- supabase/migrations/202609240001_asset_tokenization.sql
- lib/tokenization-issuance.ts
- app/api/tokenization/issuance/route.ts
- TOKENIZATION_SETUP.md


---

# پیشنهاد توکنومیکس و حقوق دارنده

اطلاعات پیشنهاد، بررسی نسخه و معنای پذیرش و صدور در کیف پول داخلی.

وضعیت: نیازمند پیکربندی | مخاطب: صاحبان دارایی و طراحان محصول
بازبینی مستندات: ۲۰۲۶/۰۹/۲۴ · ۲ مهر ۱۴۰۵

## پیشنهاد وابسته به پرونده

کارشناس برای پروندهٔ بررسی‌شده، پیشنهاد توکنومیکس ثبت می‌کند. پیشنهاد شمارهٔ نسخه دارد و نام و نماد، تعداد کل، دقت توکن، قیمت ریالی، شبکه، حقوق دارنده، شرایط انتقال و بازخرید، ریسک‌ها و ردیف‌های تخصیص را مشخص می‌کند.

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

## اطلاعاتی که باید بررسی کنید

| موضوع | محتوا |
| --- | --- |
| تعداد و دقت | تعداد کل مثبت با دقت صفر تا ۱۸ رقم اعشار؛ مقدار در دفتر داخلی باید کمتر از ۱۰ به توان ۲۰ واحد باشد. |
| قیمت | قیمت مثبت هر واحد به ریال، بدون اعشار ریالی؛ قیمت پیشنهادی تضمین قیمت معامله یا نقدشوندگی نیست. |
| شبکه | نام شبکه و شناسهٔ عددی زنجیره؛ انتخاب در فرم به معنی فعال‌شدن اتصال صدور نیست. |
| تخصیص | عنوان، درصد با حداکثر دو رقم اعشار و دورهٔ قفل پیشنهادی هر ردیف؛ مجموع درصدها دقیقاً صد است. |
| حقوق و شرایط | حقوق دارنده، قواعد انتقال، شرایط بازخرید و افشای ریسک باید کامل باشند. |
| مقصد | کیف پول داخلی صاحب پرونده در پلانک؛ مقصد خارجی در فرم پیشنهاد قابل تعیین نیست. |

## مطالعه و دریافت متن پیشنهاد

صاحب پرونده مشخصات، جدول تخصیص و متن شرایط را در مرحلهٔ نهایی می‌بیند و می‌تواند متن کامل همان نسخه را دریافت کند. گزینهٔ پذیرش زمانی در دسترس است که پیشنهاد آمادهٔ پذیرش و بررسی‌ها و مدارک ضروری تأیید شده باشند.

نسخهٔ پیشنهاد و نسخهٔ پرونده همراه پذیرش کنترل می‌شوند. تغییر پیشنهاد به پذیرش نسخهٔ جدید نیاز دارد؛ رضایت قبلی به پیشنهاد تغییرکرده منتقل نمی‌شود. خطای تعارض باید با دریافت آخرین وضعیت و مطالعهٔ دوباره رفع شود.

## پذیرش با صدور فرق دارد

با پذیرش، نسخهٔ پذیرفته‌شدهٔ پیشنهاد و اطلاعات مربوط به آن ثبت و درخواست صدور ساخته می‌شود. نمایش «در انتظار صدور» به معنی ثبت این درخواست است؛ رسید شبکه، توکن صادرشده یا موجودی قابل خرج هنوز نتیجهٔ این عمل نیست.

این پذیرش اجازهٔ برداشت وجه یا ایجاد هزینهٔ اعلام‌نشده نمی‌دهد. هر هزینه یا تعهد اجرایی باید پیش از اجرا مشخص و جداگانه پذیرفته شود.

## از رسید معتبر تا ثبت موجودی

اتصال صدور و سرویس بررسی رسید باید پیش از واریز واقعی فعال شوند. نتیجه باید با پیشنهاد پذیرفته‌شده، شبکه، قرارداد و مقصد مورد انتظار و مقدار دقیق تطبیق داده شود. رسید نامعتبر، متفاوت یا مربوط به پروندهٔ دیگر نباید موجودی ایجاد کند.

پس از تأیید معتبر، ثبت موجودی داخلی، تراکنش و سابقهٔ تخصیص به همان صاحب پرونده انجام می‌شود و تمام تعداد در ابتدا قفل است. مقدار قابل خرج، برداشت یا انتقال خودکار ایجاد نمی‌شود. کنترل تکرار از اعتباردهی دوبارهٔ یک نتیجه جلوگیری می‌کند. رابط مشتری فقط نتیجهٔ ثبت‌شده را می‌خواند و برای اعلام صدور یا تغییر موجودی مجوز ندارد.

## شرایط پیشنهادی و اجرای قرارداد

ردیف تخصیص یا دورهٔ قفل در پیشنهاد، به‌خودی‌خود قرارداد قفل، توزیع خودکار به اشخاص، برنامهٔ واگذاری تدریجی یا کنترل انتقال روی شبکه ایجاد نمی‌کند. اجرای این شرایط باید در سرویس و قرارداد دارایی پیاده و بررسی شود.

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

- [مشاهدهٔ مسیر ثبت دارایی](/tokenize)
- [مراحل و پیش‌نیازهای فعال‌سازی](/docs/tokenization)

## مراجع پیاده‌سازی

- components/tokenize-page.tsx
- lib/tokenization.ts
- app/api/tokenization/route.ts
- supabase/migrations/202609240001_asset_tokenization.sql
- lib/catalog.ts
- lib/tokenization-issuance.ts
- app/api/tokenization/issuance/route.ts
- TOKENIZATION_SETUP.md


---

# مدیریت دارایی و سوابق

آنچه داشبورد کیف پول نمایش می‌دهد و خدماتی که هنوز عملیات جدید ندارند.

وضعیت: نیازمند پیکربندی | مخاطب: کاربران دارای حساب
بازبینی مستندات: ۲۰۲۶/۰۹/۲۴ · ۲ مهر ۱۴۰۵

## بخش‌های کیف پول

| مسیر | کاربرد |
| --- | --- |
| /wallet یا /wallet/overview | نمای کلی دارایی‌ها |
| /wallet/assets | فهرست و جستجوی دارایی‌های ثبت‌شده |
| /wallet/deposit | فرم مبلغ و سابقهٔ شارژ؛ درگاه غیرفعال |
| /wallet/withdraw | وضعیت برداشت؛ عملیات برداشت غیرفعال |
| /wallet/transactions | حداکثر ۱۰۰ تراکنش اخیر |
| /wallet/orders | حداکثر ۱۰۰ سفارش اخیر |
| /wallet/credit و /wallet/instant-credit | نمایش اعتبارهای ثبت‌شده؛ طرح جدید غیرفعال |
| /wallet/staking | نمایش موقعیت و پاداش ثبت‌شده؛ شروع استیک جدید غیرفعال |

## خواندن مقدار و ارزش

مقدار دارایی، مقدار قفل‌شده و ارزش ریالی یا USDT فیلدهای جدا هستند. مقدار قابل‌استفاده پس از کم‌کردن قفل‌شده به دست می‌آید؛ ارزش‌گذاری سبد به معنی پول نقد قابل خرج نیست.

کاربر می‌تواند نمایش موجودی را پنهان و دارایی‌های کوچک را فیلتر کند. دادهٔ ناموجود با موجودی واقعی صفر متفاوت است. همهٔ رکوردها باید متعلق به حساب واردشده باشند.

## سوابق چه معنایی دارند؟

جدول‌های سفارش و تراکنش، نوع، تاریخ، مقدار، وضعیت و شمارهٔ پیگیری رکوردهای موجود را نشان می‌دهند. فیلتر وضعیت برای مرور سوابق در دسترس است.

وجود جدول تاریخچه نشان‌دهندهٔ امکان ثبت سفارش از این نسخه نیست. مرورگر اجازهٔ نوشتن سفارش، ایجاد موجودی، کارمزد یا پاداش مالی را از API داشبورد ندارد.

## استیک، وام و اعتبار

داشبورد می‌تواند موقعیت‌های استیک، مقدار پاداش ثبت‌شده، اصل اعتبار، ماندهٔ تعهد و سررسید را بخواند. این قابلیت برای نمایش داده‌های سرویس مالی آماده شده است.

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

## ورود و حریم داده

صفحه‌های حساب و کیف پول تا تعیین نشست، حالت انتظار یا دروازهٔ ورود دارند. خواندن اطلاعات از API خصوصی و توابعی انجام می‌شود که صاحب داده را از نشست معتبر تعیین می‌کنند.

اطلاعات پروفایل، حساب بانکی، تراکنش و مدارک احراز در کاتالوگ عمومی یا ویترین انتخابی قرار نمی‌گیرند.

- [رفتن به کیف پول](/wallet)

## مراجع پیاده‌سازی

- lib/dashboard.ts
- components/customer-dashboard.tsx
- components/use-customer-data.ts
- app/api/dashboard/route.ts
- DASHBOARD_SETUP.md
- CASH_WALLET.md


---

# حساب، ورود و تنظیمات

ثبت‌نام با موبایل، روش‌های ورود، پروفایل و ترجیحات نمایش.

وضعیت: نیازمند پیکربندی | مخاطب: کاربران و تیم پشتیبانی
بازبینی مستندات: ۲۰۲۶/۰۹/۲۴ · ۲ مهر ۱۴۰۵

## ثبت‌نام

فرم ثبت‌نام نام، نام خانوادگی، ایمیل، موبایل و رمز عبور می‌گیرد؛ نام کاربری و کد دعوت اختیاری‌اند. شماره باید با پیامک تأیید شود و سرور روشن‌بودن تأیید موبایل را بررسی می‌کند.

رمز جدید بین ۱۲ و ۲۵۶ نویسه پذیرفته می‌شود. نام کاربری ۳ تا ۳۲ حرف انگلیسی، عدد یا زیرخط دارد و با حرف شروع می‌شود. اتصال ایمیل پس از تأیید موبایل مسیر تأیید جدا دارد.

## ورود و بازیابی

ورود با ایمیل یا موبایل و رمز عبور، ورود پیامکی و بازیابی از طریق ایمیل یا موبایل پیاده شده‌اند. ورود با نام کاربری نیازمند سرویس محدود جستجوی نام کاربری روی سرور است.

کد پیامکی یک تا شش رقم فارسی، عربی یا لاتین را می‌پذیرد و برای اعتبارسنجی به قالب شش‌رقمی تبدیل می‌کند. کنترل واقعی اعتبار کد بر عهدهٔ سرویس احراز هویت است؛ تبدیل رقم، تأیید امنیتی نیست. بازیابی ایمیلی از مسیر PKCE و همان مرورگر استفاده می‌کند.

## پروفایل و تصویر

در /account اطلاعات شخصی، وضعیت و سطح احراز دیده می‌شود. نام، نام خانوادگی، تاریخ تولد و در شرایط مجاز کد ملی قابل ثبت‌اند. مشخصات تأییدشده یا وابسته به تطبیق بانکی ممکن است برای ویرایش قفل باشند.

تصویر پروفایل از مسیر خصوصی خود حساب بارگذاری و خوانده می‌شود؛ قالب‌های JPG، PNG و WebP با سقف ۲ مگابایت پذیرفته‌اند. تصویر پروندهٔ احراز هویت و تصویر پروفایل دو فضای مستقل‌اند.

## تنظیمات قابل ذخیره

- تم روشن یا تیره، زبان فعال سایت و واحد نمایش TMN یا USDT.
- پنهان‌کردن موجودی، پنهان‌کردن دارایی‌های کوچک و کاهش حرکت.
- ترجیح اعلان ایمیلی و تأیید ثبت یا لغو سفارش؛ اعمال عملیاتی آن‌ها وابسته به فعال‌شدن همان سرویس است.
- خوانده‌شدن اعلان‌های موجود، ثبت و حذف هشدار قیمت؛ هشدارها تا اتصال سرویس اعلان متوقف می‌مانند.

## بخش‌های حساب و محدودیت‌ها

پروفایل، بانک‌ها، امنیت، تنظیمات، هشدارها، دعوت دوستان، API و اعلان‌ها در /account قابل دسترسی‌اند. مسیر بخش نامعتبر صفحهٔ یافت‌نشدن دریافت می‌کند.

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

## مراجع پیاده‌سازی

- components/customer-auth.tsx
- lib/auth-input.ts
- lib/customer-auth.ts
- lib/auth-cookies.ts
- lib/dashboard.ts
- components/customer-dashboard.tsx
- app/api/avatar/route.ts
- AUTH_SETUP.md
- DASHBOARD_SETUP.md


---

# کیف پول نقدی و اتصال والت عمومی

تفاوت موجودی ثبت‌شده، آدرس تأییدشده و امکان انتقال وجه.

وضعیت: نیازمند پیکربندی | مخاطب: کاربران دارای حساب
بازبینی مستندات: ۲۰۲۶/۰۹/۲۴ · ۲ مهر ۱۴۰۵

## موجودی نقدی واحد

موجودی نقدی جدید با واحد ریال صحیح ثبت می‌شود؛ رکوردهای قدیمی تومان حفظ و برای نمایش فقط یک‌بار در مجموع منظور می‌شوند. هر تومان ده ریال است. موجودی کل، قفل‌شده و قابل‌استفاده جدا نمایش داده می‌شوند.

شروع یک حساب جدید با موقعیت صفر ریالی، اعتبار رایگان یا شارژ واقعی ایجاد نمی‌کند. نبود رکورد معتبر با صفر یکسان نیست و رابط نباید ارزش توکن پروژه را پول نقد تلقی کند.

## شارژ و برداشت امروز

صفحهٔ شارژ، مبلغ و سابقهٔ خصوصی پرداخت را نمایش می‌دهد. API تاریخچه اکنون enabled:false و provider:null برمی‌گرداند. ارسال مبلغ معتبر هنوز پاسخ 503 دارد و نه درخواست پرداخت، نه هدایت درگاه و نه تغییر موجودی ایجاد می‌کند.

پایهٔ دفتر پرداخت و اعتباردهی یک‌باره در پایگاه داده طراحی شده است، اما آداپتور درگاه، تأیید مستقل پرداخت، تطبیق مالی، برداشت و بازپرداخت به سرویس عملیاتی نیاز دارند.

## اتصال آدرس عمومی

MetaMask، Trust Wallet و والت‌های تزریقی استاندارد EVM از رابط قابل انتخاب‌اند. اتصال QR از WalletConnect به شناسهٔ پروژهٔ معتبر و تنظیم دامنه نیاز دارد. کاربر باید وارد حساب باشد و پیام اتصال را در والت تأیید کند.

سرور پیام EIP-4361 محدود به حساب و دامنه می‌سازد و امضای شخصی را بررسی می‌کند. پیام پنج دقیقه اعتبار دارد و استفادهٔ مجدد یا امضای نامنطبق رد می‌شود. حداکثر ده والت عمومی برای هر حساب تعریف شده است.

## اتصال آدرس چه مجوزی نمی‌دهد؟

ثبت آدرس، موجودی زنجیره را خودکار وارد دفتر حساب نمی‌کند و مجوز خرج توکن، انتقال وجه یا ایجاد تراکنش نیست. عبارت بازیابی یا کلید خصوصی دریافت نمی‌شود. نشست موقت QR پس از پایان جریان بسته می‌شود؛ آدرس تأییدشده می‌تواند در حساب بماند.

ثبت نتیجهٔ صدور دارایی در کیف پول داخلی، مسیر جداگانهٔ پروندهٔ توکنایزیشن است و به نصب مهاجرت و فعال‌سازی سرویس بررسی رسید نیاز دارد. اعتبارسنجی قراردادهای EIP-1271، شبکه‌های غیر EVM و نمایه‌سازی خودکار موجودی از آدرس متصل در این جریان فعال نیستند.

## حساب بانکی و آدرس والت

حساب بانکی و والت در بخش /account/banks کنار هم مدیریت می‌شوند، اما تأیید آدرس والت با تطبیق شبا و کد ملی متفاوت است. ثبت هرکدام شواهد و مسیر مستقل دارد.

سوابق شارژ و آدرس‌ها خصوصی‌اند و از نشست همان کاربر خوانده می‌شوند. هیچ مجوز عمومی برای ویرایش مستقیم موجودی از این APIها وجود ندارد.

## مراجع پیاده‌سازی

- components/public-wallet-connect.tsx
- components/cash-wallet.tsx
- lib/cash-wallet.ts
- app/api/deposits/route.ts
- app/api/wallet-connect/route.ts
- supabase/functions/_shared/wallet-link.ts
- supabase/migrations/202609080006_public_wallets.sql
- PUBLIC_WALLETS.md
- CASH_WALLET.md


---

# احراز هویت و ثبت حساب بانکی

ثبت اطلاعات و مدارک، استعلام‌های مستقل و معنای وضعیت‌های پرونده.

وضعیت: نیازمند پیکربندی | مخاطب: کاربران و تیم پشتیبانی
بازبینی مستندات: ۲۰۲۶/۰۹/۲۴ · ۲ مهر ۱۴۰۵

## مسیر کاربر

کاربر دارای موبایل تأییدشده، درخواست احراز را شروع می‌کند، مشخصات لازم را می‌نویسد و تصویر کارت ملی و تصویر همراه کد درخواست را می‌فرستد. ارسال نهایی به رضایت صریح، مدارک لازم و اعتبار کد وابسته است.

کد ملی ده‌رقمی با رقم کنترل بررسی می‌شود؛ شماره شناسنامه یک تا ده رقم و کد پستی ده رقم است. نام‌ها بین ۲ تا ۸۰ نویسه و نشانی بین ۱۵ تا ۱۰۰۰ نویسه پذیرفته می‌شوند. درست‌بودن قالب، تأیید هویت یا مالکیت نیست.

## وضعیت پرونده و استعلام

| وضعیت | معنا |
| --- | --- |
| draft | پیش‌نویس کاربر |
| pending | در انتظار بررسی مدیر |
| documents_approved | مدارک تأیید شده‌اند؛ استعلام‌ها هنوز باید کامل شوند |
| verified | شواهد موردنیاز مسیر تأیید کامل شده است |
| rejected | مدارک یا اطلاعات نیاز به اصلاح دارد |
| superseded | درخواست تازه لازم است |
| not_connected / pending / passed / failed / error | وضعیت مستقل هر استعلام: متصل نیست، منتظر، تطبیق، عدم تطبیق یا خطا |

## سطح اولیه و کامل

مدل داده مسیر هویتی برای سطح اولیه و مسیر هویتی‌وبانکی برای سطح کامل را از سطح فعلی حساب جدا نگه می‌دارد. در طرح مرحله‌بندی، اطلاعات، مدارک، استعلام‌ها و تأیید نهایی مراحل بررسی‌اند.

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

## ثبت شبا و کارت

ثبت حساب با شبا، عنوان اختیاری، کارت اختیاری، شناسهٔ درخواست و رضایت انجام می‌شود. بانک از شبا شناسایی و تطبیق شبا با کد ملی از سرویس معتبر درخواست می‌شود؛ کارت اختیاری نیز در صورت ورود باید با شبا تطبیق داشته باشد.

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

## مدارک خصوصی و ویرایش هم‌زمان

برای هر تصویر احراز، JPG، PNG یا WebP تا ۵ مگابایت پذیرفته می‌شود و نوع واقعی فایل با هدر اعلام‌شده تطبیق داده می‌شود. مدارک در فضای خصوصی قرار دارند؛ خواندن مدرک نیازمند نشست و مجوز همان درخواست است.

شناسه و نسخهٔ پرونده هنگام ذخیره و ارسال بررسی می‌شوند تا تغییر هم‌زمان بی‌صدا بازنویسی نشود. نامعتبر یا منقضی‌شدن درخواست، تغییر موبایل و قفل‌شدن مشخصات باید با پیام مشخص پیگیری شوند.

## مراجع پیاده‌سازی

- lib/identity.ts
- lib/identity-server.ts
- lib/identity-files.ts
- lib/bank-registration.ts
- app/api/identity/route.ts
- app/api/identity/photo/route.ts
- app/api/dashboard/route.ts
- IDENTITY_VERIFICATION.md
- CUSTOMER_BANK_REGISTRATION.md
- supabase/migrations/202609200001_identity_review_levels.sql


---

# دعوت دوستان و پاداش‌ها

کد دعوت، شرایط ثبت پاداش و تفاوت محاسبهٔ پاداش با پرداخت پول.

وضعیت: نیازمند پیکربندی | مخاطب: کاربران دارای حساب
بازبینی مستندات: ۲۰۲۶/۰۹/۲۴ · ۲ مهر ۱۴۰۵

## ساخت و اشتراک کد

بخش /account/referrals کدهای دعوت، لینک اشتراک و گزارش مربوط را نمایش می‌دهد. حساب واجد شرایط می‌تواند تا ۲۰ کد با عنوان دلخواه داشته باشد؛ کد از منبع تصادفی سرور ساخته و یکتایی آن در پایگاه داده کنترل می‌شود.

دکمه‌های کپی، ایمیل و واتس‌اپ لینک و متن را آماده می‌کنند. ارسال نهایی با کاربر است و هیچ پیام دعوتی خودکار فرستاده نمی‌شود.

## ارتباط دعوت چگونه ثبت می‌شود؟

لینک دعوت دارای ref و auth=register است. اولین کد دارای قالب معتبر تا ۳۰ روز در مرورگر نگهداری می‌شود و کاربر می‌تواند پیش از ثبت‌نام آن را تغییر دهد یا حذف کند.

سرور اعتبار کد و تأیید اطلاعات تماس دعوت‌کننده را بررسی می‌کند. نسبت دعوت هنگام ساخت حساب تازه ثبت می‌شود؛ ورود یا ویرایش پروفایل بعدی آن را تغییر نمی‌دهد. دادهٔ نگهداری‌شدهٔ مرورگر پس از ورود پاک می‌شود.

## شرایط پاداش

تنظیمات پاداش ثابت، سهم از کارمزد و فعال‌بودن طرح توسط مدیر مجاز تعیین می‌شوند. مقادیر بذر، ۵۰٬۰۰۰ تومان و ۲۰ درصد از کارمزد دریافت‌شدهٔ معامله‌اند؛ نمایش نرخ جاری باید از تنظیمات واقعی خوانده شود.

پاداش ثابت به تأیید تماس، احراز هویت و نخستین معاملهٔ واقعیِ تسویه‌شدهٔ دعوت‌شونده وابسته است. سهم معامله از کارمزد نهایی محاسبه می‌شود، نه از اصل سرمایه یا مبلغ فرضی فرم. پروژهٔ نمونه پاداش واقعی ندارد.

## محاسبه و پرداخت دو وضعیت مستقل‌اند

پاداش accrued یعنی محاسبه‌شده؛ paid نیازمند ثبت و اثبات پرداخت واقعی است. محاسبهٔ پاداش به‌تنهایی موجودی کیف پول را افزایش نمی‌دهد.

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

## مراجع پیاده‌سازی

- components/referral-dashboard.tsx
- lib/referrals.ts
- app/api/referrals/route.ts
- supabase/migrations/202609080007_referral_program.sql
- REFERRALS.md


---

# بررسی درخواست‌های توکنایزیشن

پرونده دارایی، مدارک خصوصی، سه ارزیابی مستقل و پیشنهاد نسخه‌دار برای کیف پول داخلی پلانک.

وضعیت: نیازمند پیکربندی | مخاطب: مالک پنل و کارشناسان مجاز بررسی
بازبینی مستندات: ۲۰۲۶/۰۹/۲۴ · ۲ مهر ۱۴۰۵

## ثبت و بررسی فعال؛ صدور نیازمند تنظیم است

بخش «درخواست‌های توکنایزیشن» در پنل مدیریت و نشانی ?section=tokenization پیاده‌سازی شده است. کاربر مدیریت باید نقش مالک داشته باشد؛ ورود و مجوز دوباره در API و پایگاه داده بررسی می‌شوند.

مهاجرت توکنایزیشن و فضای خصوصی مدارک در محیط تأییدشدهٔ پلانک در تاریخ ۲۰۲۶/۰۹/۲۴ فعال و کنترل دسترسی آن‌ها بررسی شد. نصب در محیط دیگر همچنان به اجرای مهاجرت و اتصال درست سایت مشتری و پنل به پایگاه داده نیاز دارد. تنظیم شبکه، قرارداد و کیف پول امانی برای صدور واقعی جداگانه لازم است.

## صف و اطلاعات پرونده

فهرست بر اساس درخواست‌های دریافت‌شده از سرویس ساخته می‌شود و جست‌وجوی عنوان یا شناسه پیگیری و فیلتر وضعیت دارد. پرونده‌های پیش‌نویس مشتری وارد صف مدیریت نمی‌شوند.

هر پرونده عنوان، شناسه، نسخه، زمان ثبت، نوع دارایی و فیلدهای اختصاصی همان نوع را نشان می‌دهد. تعریف مشترک، ۲۰ نوع دارایی مشهود و نامشهود را پوشش می‌دهد.

مقادیر مالی و تعداد توکن به‌صورت رشته دقیق نگهداری و در رابط با ارقام فارسی و جداکننده سه‌رقمی نمایش داده می‌شوند. مقدار ثبت‌نشده در جزئیات، به‌جای ساختن ارزش مالی، مشخص می‌شود.

## مدارک خصوصی و نتیجه هر سند

برای هر نوع دارایی، مدارک الزامی و تکمیلی مشخص است. فایل‌ها فقط از مسیر خصوصی با کنترل دسترسی قابل دریافت‌اند. نسخه جاری PDF، JPG و PNG با حداکثر ۱۰ مگابایت برای هر فایل را می‌پذیرد.

کارشناس برای هر سند نتیجه تأیید، نیاز به اصلاح یا رد و یک پیام قابل مشاهده برای مشتری ثبت می‌کند. تأیید یک مدرک، جایگزین تأیید حقوقی، مالی و فنی پرونده نیست.

کنترل دسترسی فایل در پایگاه داده و فضای ذخیره انجام می‌شود. لینک مدرک، لینک عمومی پروژه یا رسانه منتشرشده نیست.

## سه ارزیابی مستقل

هر ارزیابی نتیجه مستقل دارد. پیام عمومی در پرونده مشتری نمایش داده می‌شود؛ یادداشت داخلی در پاسخ مخصوص مدیریت نگهداری و از پاسخ مشتری حذف می‌شود.

ثبت نتیجه روی ارزیابی یا سند، با ارسال کل پرونده برای اصلاح متفاوت است. برای بازگشت پرونده، اقدام «درخواست اصلاح» و برای توقف آن، اقدام «رد پرونده» با توضیح مشخص وجود دارد.

وقتی مشتری پرونده اصلاح‌شده را دوباره ارسال کند، ارزیابی‌ها و نتایج مدارک برای بررسی مجدد بازنشانی می‌شوند.

| ارزیابی | موضوع |
| --- | --- |
| حقوقی و مالکیت | مالکیت، اختیار اقدام، مجوزها و استعلام‌های لازم |
| مالی | ارزش‌گذاری، اسناد مالی و شرایط اقتصادی دارایی |
| فنی | مشخصات دارایی و امکان عرضه توکن |

## طراحی پیشنهاد توکنومیکس

فرم پیشنهاد زمانی فعال می‌شود که هر سه ارزیابی و تمام مدارک الزامی تأیید شده باشند. همین شرط در سرور نیز اعمال می‌شود.

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

تعداد توکن باید مثبت و با اعشار تعیین‌شده سازگار باشد. قیمت ریالی عدد صحیح مثبت است. مجموع درصد تخصیص‌ها باید دقیقاً ۱۰۰ باشد؛ قفل هر تخصیص به ماه ثبت می‌شود.

ارسال پیشنهاد یک نسخه مشخص ایجاد می‌کند و پرونده وارد وضعیت انتظار پذیرش مشتری می‌شود. پنل نمی‌تواند پذیرش را به‌جای مشتری ثبت کند.

## تغییر هم‌زمان و پذیرش مشتری

همه نوشتن‌های مدیریتی شناسه درخواست و نسخه فعلی را ارسال می‌کنند. تعارض نسخه با وضعیت ۴۰۹ برمی‌گردد؛ رابط نتیجه را موفق نشان نمی‌دهد و بارگذاری نسخه تازه را پیشنهاد می‌کند.

تا پذیرش مشتری، می‌توان پرونده را برای اصلاح برگرداند. پذیرش فقط نسخه جاری پیشنهاد را می‌پذیرد و نسخه پیشنهاد، اطلاعات دارایی و مدارک پذیرفته‌شده را در سرور تثبیت می‌کند.

پس از پذیرش، پرونده وارد صف صدور می‌شود و تغییر مدیریتی یا ویرایش مشتری برای آن وضعیت مجاز نیست. وضعیت و زمان پذیرش ثبت‌شده در پنل نمایش داده می‌شوند.

## صدور و موجودی کیف پول

پذیرش مشتری یک کار پایدار برای صدور ایجاد می‌کند. این وضعیت به‌تنهایی توکن صادرشده، تراکنش موفق یا موجودی کیف پول نیست.

مسیر نهایی‌سازی برای سرویس مورد اعتماد است و برای مرورگر مشتری یا مدیر قابل اجرا نیست. این مسیر باید نتیجه واقعی شبکه، نسخه پذیرفته‌شده، قرارداد، مقصد و تعداد توکن را تطبیق دهد.

ثبت موجودی داخلی و تراکنش مربوط در یک عملیات پایگاه داده و با شناسه‌های یکتا انجام می‌شود تا همان صدور دوباره اعتباردهی نشود. در صورت برخورد نماد با موقعیت موجود، دارایی‌های نامرتبط با هم ادغام نمی‌شوند.

تا راه‌اندازی و اجرای تأییدکننده واقعی، درخواست در انتظار صدور باقی می‌ماند. دکمه «صدور موفق» یا رسید ساختگی در پنل وجود ندارد. عرضه خودکار در بازار یا اجرای خرید، فروش، استیک و وام از این بخش انجام نمی‌شود.

## قرارداد API مدیریت

actionهای مدیریتی عبارت‌اند از review، document_review، propose، request_changes و reject. review شناسه لایه، نتیجه، message و internal_note اختیاری دارد؛ document_review شناسه سند، نتیجه و message دارد. propose شامل شیء tokenomics است.

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

| روش و مسیر | ورودی یا پاسخ | دسترسی |
| --- | --- | --- |
| GET /api/tokenization | {requests: TokenizationAdminRequest[]} | مالک مدیریت |
| POST /api/tokenization | action + id + version → {request} | مالک و همان مبدأ |
| GET /api/tokenization/documents | ?id=UUID&document=UUID → فایل خصوصی | مالک مدیریت؛ بدون کش |

## مراجع پیاده‌سازی

- planck-admin/components/tokenization-review.tsx
- planck-admin/components/admin-app.tsx
- planck-admin/lib/tokenization.ts
- planck-marketplace/supabase/migrations/202609240001_asset_tokenization.sql
- planck-marketplace/lib/tokenization-files.ts


---

# راهنمای پنل مدیریت پلانک

بخش‌های پنل، وظایف اعضای تیم و مرز مدیریت مارکت‌پلیس.

وضعیت: پیاده‌سازی‌شده | مخاطب: مالک، ناشر و ویراستار
بازبینی مستندات: ۲۰۲۶/۰۹/۲۴ · ۲ مهر ۱۴۰۵

## وظیفه پنل

پنل مدیریت مارکت‌پلیس برنامه‌ای مستقل از سایت عمومی است و رابط، API، ساخت و جلسه ورود جدا دارد. پروژه‌ها و محتوای قابل انتشار، بررسی احراز هویت، تنظیم استعلام‌ها، پاداش دعوت و اتصال‌های بازار از این پنل مدیریت می‌شوند.

این برنامه همان Admin Main نیست. سرویس آدرس‌های والت در بخش اتصال‌ها معرفی می‌شود، اما مدیریت کلید خصوصی، اجرای معامله یا انتقال دارایی در این پنل پیاده‌سازی نشده است.

## بخش‌های موجود

| بخش | کارکرد |
| --- | --- |
| پروژه‌ها | ایجاد، جست‌وجو، ویرایش و تعیین وضعیت انتشار |
| درخواست‌های توکنایزیشن | مدارک خصوصی، ارزیابی حقوقی، مالی و فنی و پیشنهاد توکنومیکس |
| ظاهر و هیرو | متن، لوگو، پس‌زمینه و پیش‌نمایش |
| محتوا و زبان‌ها | منوها، فوتر، لینک‌ها، پرسش‌ها و ورود ترجمه |
| اتصال‌ها | تنظیم والکس، Ondo و سیاست نرخ تبدیل |
| دعوت و پاداش‌ها | مبلغ دعوت، سهم کارمزد و آمار |
| احراز هویت | بررسی پرونده، مدارک، سطح احراز و استعلام |
| استعلام‌ها | تنظیم ارائه‌دهنده، کلید و نمایش آمادگی |
| تاریخچه تغییرات | رویدادهای ثبت‌شده پروژه‌ها و محتوا |

## نقش‌ها

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

| نقش | اختیار تعریف‌شده |
| --- | --- |
| مالک / owner | مدیریت محتوا و پروژه؛ بررسی هویت؛ تنظیم کلیدها، نرخ تبدیل و پاداش |
| ناشر / publisher | انتشار پروژه و محتوای سایت و مشاهده تاریخچه |
| ویراستار / editor | ایجاد و ویرایش پیش‌نویس؛ بدون انتشار یا تغییر محتوای مشترک |

## گردش کار انتشار

- پروژه را به‌صورت پیش‌نویس ایجاد و معرفی، قیمت، مدت، ظرفیت و مدارک را تکمیل کنید.
- اگر پروژه نمونه است، وضعیت نمونه را روشن نگه دارید. توضیحات و ریسک‌ها را قبل از انتشار بازبینی کنید.
- مالک یا ناشر وضعیت انتشار را تعیین و ذخیره می‌کند. اختلاف نسخه نیاز به تازه‌سازی دارد.
- متن‌ها و ظاهر از بخش محتوا ذخیره می‌شوند؛ کلیدها و سیاست نرخ تبدیل مسیر مستقل دارند.

## پیش‌نمایش و عملیات واقعی

پیش‌نمایش فقط هنگام نبود اتصال پایگاه داده و فعال بودن گزینه پیش‌نمایش اجرا می‌شود. فرم‌ها با داده نمونه قابل مشاهده‌اند، اما ذخیره، انتشار و بارگذاری واقعی انجام نمی‌شود.

اجرای واقعی به اتصال پایگاه داده، عضویت مجاز، تکمیل ورود و آمادگی سرویس مربوط نیاز دارد. وجود فرم یا دکمه به معنی آماده بودن ارائه‌دهنده نیست.

## مراجع پیاده‌سازی

- planck-admin/README.md
- planck-admin/app/page.tsx
- planck-admin/components/admin-app.tsx
- planck-admin/lib/server.ts


---

# مدیریت دارایی‌ها و محتوای سایت

اطلاعات پروژه، قواعد انتشار، نمودار قیمت، رسانه و محتوای سایت.

وضعیت: پیاده‌سازی‌شده | مخاطب: مدیر محتوا و ناشر
بازبینی مستندات: ۲۰۲۶/۰۹/۲۴ · ۲ مهر ۱۴۰۵

## اطلاعات هر پروژه

پروژه شناسه، نشانی اختصاصی و نماد دارد و در یکی از دسته‌های مشهود، نامشهود یا طرح سرمایه‌گذاری قرار می‌گیرد. وضعیت آن پیش‌نویس، منتشرشده یا آرشیوشده است؛ رابط حذف مخرب پروژه ارائه نمی‌کند.

| گروه | فیلدها |
| --- | --- |
| معرفی | عنوان، زیرعنوان، توضیح، موقعیت یا نوع دارایی، ریسک |
| مالی | قیمت واحد به ریال، بازده، مدت ماهانه، تعداد کل و تأمین‌شده |
| بازار | آیکون توکن، قیمت ۲۴ ساعت قبل، زمان ثبت و نمودار |
| انتشار | وضعیت، پرچم نمونه، ترتیب، تصویر و لینک مدارک |

## قواعد ثبت

- عنوان فارسی الزامی است. نشانی اختصاصی حروف کوچک لاتین، عدد و خط تیره می‌پذیرد و حداکثر ۱۰۰ نویسه دارد. نماد ۲ تا ۱۶ حرف یا عدد است.
- قیمت مثبت، تعداد تأمین‌شده حداکثر برابر ظرفیت و مدت عدد صحیح بین ۱ تا ۶۰۰ ماه است.
- انتشار به توضیح فارسی حداقل ۳۰ نویسه و ریسک فارسی حداقل ۲۰ نویسه نیاز دارد. هر پروژه حداکثر ۳۰ سند دارد.
- نسخه پروژه هنگام ویرایش ارسال می‌شود تا تغییر جدید مدیر دیگر بازنویسی نشود. پرچم نمونه مستقل از وضعیت انتشار است.

## قیمت و نمودار

قیمت پروژه به ریال وارد و در پنل به تومان نمایش داده می‌شود؛ هر تومان دقیقاً ۱۰ ریال است. بازده پروژه مستقل از تغییر قیمت ۲۴ ساعته نگهداری می‌شود.

قیمت ۲۴ ساعت قبل به زمان ثبت معتبر نیاز دارد. نمودار اختیاری از ۲ تا ۹۶ قیمت صحیح مثبت تشکیل می‌شود و ابتدا و انتهای آن باید با قیمت قدیم و فعلی برابر باشد. تغییر قیمت در فرم، نمودار ناسازگار را پاک می‌کند.

این فرم رکورد پروژه را ویرایش می‌کند و جایگزین دریافت خودکار داده دارایی‌های متصل به بازار نیست.

## هیرو، متن‌ها و زبان‌ها

عنوان کوتاه، تیتر اصلی، خط دوم، توضیح و متن زیر دکمه‌های هیرو قابل ویرایش‌اند. پس‌زمینه از انیمیشن، تصویر یا ویدیو انتخاب می‌شود؛ ویدیو تصویر جایگزین و نمایش مدار تنظیم جدا دارد.

لوگو، عنوان چهار منوی اصلی، فوتر، نشانی اپلیکیشن و پذیرش توکنایزیشن و حداکثر ۳۰ پرسش متداول قابل مدیریت‌اند.

ساختار ترجمه برای فارسی، انگلیسی و عربی آماده است؛ رابط منتشرشده فعلاً فقط فارسی را می‌پذیرد. ورود ترجمه به‌تنهایی زبان جدید سایت را فعال نمی‌کند.

## رسانه‌ها و اسناد

JPG، PNG، WebP و MP4 تا ۲۵ مگابایت بارگذاری می‌شوند و نوع فایل روی سرور نیز بررسی می‌شود. فایل جدید نام یکتا دارد و فایل قبلی را بازنویسی نمی‌کند.

رسانه معرفی پروژه در فضای عمومی رسانه ذخیره می‌شود؛ مدارک هویتی فضای خصوصی جدا دارند. اسناد پروژه در فرم به‌صورت عنوان و لینک ثبت می‌شوند. نشانی‌ها باید HTTPS یا از مسیر مجاز تصاویر داخلی باشند.

تصویر نمونه یا مفهومی، مدرک وجود و ارزش دارایی واقعی نیست.

## مراجع پیاده‌سازی

- planck-admin/components/admin-app.tsx
- planck-admin/lib/catalog.ts
- planck-admin/lib/validation.ts
- planck-admin/app/api/projects/route.ts
- planck-admin/app/api/content/route.ts
- planck-admin/app/api/media/route.ts
- planck-admin/ASSETS.md


---

# بررسی احراز هویت کاربران

پرونده‌ها، بررسی مدارک، سطح احراز و نتایج استعلام.

وضعیت: پیاده‌سازی‌شده | مخاطب: مالک و مسئول مجاز احراز هویت
بازبینی مستندات: ۲۰۲۶/۰۹/۲۴ · ۲ مهر ۱۴۰۵

## دسترسی به پرونده

مشاهده و بررسی اطلاعات هویتی فقط برای مالک واردشده فعال است. پیش‌نمایش مدارک واقعی نشان نمی‌دهد. فهرست، نام، پایان کد ملی، زمان ارسال، وضعیت، سطح تأییدشده و مرحله بررسی را نمایش می‌دهد.

فیلتر وضعیت و باز کردن جزئیات در دسترس است. رابط فهرست را به‌عنوان آخرین ۱۰۰ درخواست ثبت‌شده معرفی می‌کند و داده‌ها از سرویس پایگاه داده می‌آیند.

## سطح و مرحله احراز

نوع احراز و مرحله جداگانه ذخیره می‌شوند. انتخاب مرحله نهایی جایگزین شواهد لازم نیست؛ تکمیل مدارک و استعلام‌های سطح انتخابی در سرویس پایگاه داده کنترل می‌شود.

| مفهوم | الزام |
| --- | --- |
| سطح پایه | پیش از تکمیل احراز موردنیاز |
| هویتی / اولیه | مدارک تأییدشده، تطبیق هویت و مالکیت موبایل |
| هویتی و بانکی / کامل | شرایط سطح اولیه همراه تأیید حداقل یک حساب بانکی |
| مراحل پرونده | اطلاعات، مدارک، استعلام‌ها، تأیید نهایی |

## بررسی مدارک توسط مدیر

جزئیات پرونده اطلاعات هویتی، نشانی، موبایل تأییدشده و تاریخ تولد مورد استفاده در استعلام را نشان می‌دهد. تصویر کارت و عکس همراه کد اختصاصی از مسیر خصوصی دریافت می‌شوند.

- وضوح چهره و تطبیق آن با کارت بررسی می‌شود.
- خوانایی کارت و مطابقت مشخصات با فرم بررسی می‌شود.
- وجود کد اختصاصی و عبارت احراز هویت روی کاغذ بررسی می‌شود.
- بازگرداندن مدارک برای اصلاح به توضیح مدیر نیاز دارد. تأیید عکس‌ها جایگزین نتیجه استعلام نیست.

## اجرای استعلام و نتیجه

تطبیق هویت، مالکیت موبایل و مالکیت حساب بانکی نتیجه مستقل دارند. انتظار اتصال، انتظار پاسخ، تأیید تطبیق، عدم تطبیق و خطای استعلام جدا نمایش داده می‌شوند.

مدیر سرویس آماده مرتبط را انتخاب و استعلام را اجرا می‌کند. سرویس باید کلید و اتصال آماده داشته باشد. تنظیمات تغییرکرده نوع احراز ابتدا باید ذخیره شوند.

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

## مدارک خصوصی و آمادگی اجرا

تصاویر از مسیر احرازشده اختصاصی، بدون کش دریافت می‌شوند. JPEG، PNG و WebP پشتیبانی می‌شوند و سقف فایل هویتی ۵ مگابایت در نظر گرفته شده است.

اجرای واقعی به پرونده معتبر، رضایت و شواهد لازم، نصب سرویس‌های پایگاه داده و اعتبار ارائه‌دهنده وابسته است. گزارش راه‌اندازی تاریخی وضعیت امروز یک پرونده را اثبات نمی‌کند.

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

## مراجع پیاده‌سازی

- planck-admin/components/identity-review.tsx
- planck-admin/lib/identity.ts
- planck-admin/lib/identity-files.ts
- planck-admin/lib/identity-server.ts
- planck-admin/app/api/identity/route.ts
- planck-admin/app/api/identity/photo/route.ts


---

# تنظیم سرویس‌های استعلام

ثبت ارائه‌دهنده و کلید و تفاوت تنظیم سرویس با آماده بودن اجرای آن.

وضعیت: پیاده‌سازی‌شده | مخاطب: مالک پنل
بازبینی مستندات: ۲۰۲۶/۰۹/۲۴ · ۲ مهر ۱۴۰۵

## فهرست سرویس‌ها

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

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

## ثبت مشخصات و کلید

فرم عنوان، شناسه، نوع استعلام، ارائه‌دهنده، نشانی و کادر رمزدار کلید دارد. شناسه سرویس موجود ثابت است؛ نوع از هویت، مالکیت موبایل، مالکیت بانکی یا سایر انتخاب می‌شود.

کلید ذخیره‌شده نمایش داده نمی‌شود. خالی گذاشتن کادر سرویس موجود می‌تواند کلید فعلی را حفظ کند. ذخیره نسخه‌دار است و تغییر هم‌زمان را تشخیص می‌دهد.

نشانی باید HTTPS و بدون نام کاربری، رمز، پارامتر یا بخش اضافی باشد. کلید فقط در فیلد اختصاصی قرار می‌گیرد.

## اتصال‌های شناخته‌شده

| سرویس | کاربرد و وضعیت |
| --- | --- |
| ثبت‌احوال شبانیک | تطبیق مشخصات و تاریخ تولد؛ راهنما و مسیر اجرای هویتی موجود |
| شاهکار شبانیک | تطبیق موبایل تأییدشده و کد ملی؛ راهنما و مسیر اجرا موجود |
| تطبیق شبا با کد ملی | مالکیت حساب بانکی؛ انتخاب سرویس آماده و اجرای بررسی |
| تبدیل کارت به حساب و شبا | راهنمای کلید برای جریان ثبت حساب بانکی |
| سایر سرویس‌ها | قابل ثبت در فهرست؛ ثبت کلید به‌تنهایی اتصال اجرایی ایجاد نمی‌کند |

## ذخیره تنظیمات و اجرای استعلام

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

مسیر اجرا شناسه استعلام و سرویس را می‌پذیرد؛ اطلاعات لازم از پرونده مرتبط توسط سرویس پایگاه داده تأمین می‌شود. نتیجه مثبت، عدم تطبیق و خطای سرویس جدا نمایش داده می‌شوند.

## پیش‌نیازهای راه‌اندازی

- مهاجرت و سیاست‌های دسترسی سرویس باید نصب باشد.
- کلید و مجوز هر محصول ارائه‌دهنده جداگانه تأمین می‌شود.
- تغییر ارائه‌دهنده به قرارداد سازگار نیاز دارد؛ وارد کردن URL به‌تنهایی اجرای دلخواه ایجاد نمی‌کند.
- در نبود تابع اجرایی پایگاه داده، API آماده نبودن سرویس را اعلام می‌کند.

> دامنه بررسی: برای این مستند هیچ استعلام واقعی ارسال نشده و وضعیت زنده کلیدها بررسی نشده است.

## مراجع پیاده‌سازی

- planck-admin/components/inquiry-settings.tsx
- planck-admin/lib/inquiries.ts
- planck-admin/lib/inquiry-catalog.ts
- planck-admin/app/api/inquiries/route.ts
- planck-admin/app/api/inquiries/run/route.ts
- planck-admin/SHABANIC_IDENTITY_INQUIRIES.md


---

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

تنظیم پاداش دعوت، سهم کارمزد و مشاهده وضعیت محاسبه و پرداخت.

وضعیت: پیاده‌سازی‌شده | مخاطب: مالک و اعضای مجاز پنل
بازبینی مستندات: ۲۰۲۶/۰۹/۲۴ · ۲ مهر ۱۴۰۵

## تنظیم برنامه

فعال بودن محاسبه پاداش‌های جدید، مبلغ ثابت دعوت واجد شرایط و سهم دعوت‌کننده از کارمزد معاملات قابل تنظیم است. فقط مالک می‌تواند نرخ‌ها را تغییر دهد.

داده برنامه از پایگاه داده خوانده می‌شود. حالت پیش‌نمایش، ذخیره واقعی تنظیمات پاداش را انجام نمی‌دهد.

## واحدها و محدوده

| تنظیم | قاعده |
| --- | --- |
| پاداش ثابت | عدد صحیح از صفر تا ۱۰۰ میلیون تومان |
| سهم کارمزد | صفر تا ۱۰۰ درصد با حداکثر دو رقم اعشار |
| ذخیره مبلغ | تبدیل دقیق تومان به ریال |
| ذخیره درصد | تبدیل به واحد یک‌صدم درصد |
| نسخه | عدد صحیح مثبت؛ تعارض نیاز به تازه‌سازی دارد |

## شرایط معرفی‌شده در رابط

پاداش ثابت پس از احراز هویت و اولین معامله واقعی تسویه‌شده دوست تعریف شده است. سهم معاملاتی از کارمزد دریافت‌شده محاسبه می‌شود، نه مبلغ کل معامله.

رابط معاملات نمایشی و تسویه‌نشده را فاقد پاداش معرفی می‌کند. هر معامله تنها یک بار باید محاسبه شود و نرخ نسخه تنظیمات همراه پاداش بماند؛ تغییر نرخ جدید، پاداش قبلی را تغییر نمی‌دهد.

## آمار و وضعیت پرداخت

دعوت‌های ثبت‌شده، دوستان واجد شرایط، مبلغ در انتظار پرداخت و مبلغ پرداخت‌شده از سرویس برنامه دریافت و نمایش داده می‌شوند.

محاسبه پاداش به‌تنهایی موجودی قابل برداشت ایجاد نمی‌کند. پرداخت‌شدن وابسته به تراکنش پاداش تأییدشده است. این بخش دکمه انتقال یا برداشت وجه ندارد.

## مرز قابلیت

قواعد رابط برای کد دعوت شامل پیشوند plk، حداکثر ۲۰ کد در هر حساب و ثبت ارتباط دعوت هنگام ساخت حساب است. اجرای مالی به سرویس‌های مرتبط و جریان معامله واقعی وابسته است.

ثبت نرخ در پنل، فعال شدن معامله یا پرداخت خودکار را ثابت نمی‌کند. این مقاله قرارداد مدیریت را توضیح می‌دهد و مبلغ یا سابقه واقعی کاربران را منتشر نمی‌کند.

## مراجع پیاده‌سازی

- planck-admin/components/referral-settings.tsx
- planck-admin/lib/referrals.ts
- planck-admin/app/api/referrals/route.ts
- planck-admin/tests/referrals.test.mjs


---

# اتصال بازار والکس

محل ثبت کلید API و رابطه آن با داده‌های عمومی بازار.

وضعیت: پیاده‌سازی‌شده | مخاطب: مالک پنل و تیم اتصال بازار
بازبینی مستندات: ۲۰۲۶/۰۹/۲۴ · ۲ مهر ۱۴۰۵

## کاربرد اتصال

کارت والکس در بخش اتصال‌ها برای تتر، تترگلد و نمادهای نفت، مس و نقره دیجیتال در نظر گرفته شده است. نمادهای معرفی‌شده USDT، XAUT، USOON، COPXON و SLVON و واحد بازار TMN هستند.

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

## ثبت کلید

مالک کلید را در کادر رمزدار وارد و ذخیره می‌کند. ورودی پس از ذخیره پاک می‌شود و وضعیت حضور کلید نمایش داده می‌شود.

پاسخ تنظیمات فقط حضور کلید، نسخه و زمان تغییر دارد. مقدار کلید موجود بازگردانده نمی‌شود. قرارداد حفظ کلید با مقدار خالی را پشتیبانی می‌کند؛ رابط برای ذخیره کلید جدید ورودی غیرخالی می‌خواهد.

## نگهداری و تغییرات

تنظیمات از ثبت‌خانه سرویس‌ها و مخزن امن کلیدها استفاده می‌کنند. هویت سرویس و مقصد والکس در کد مشخص است و فرم مقصد دلخواه انتخاب نمی‌کند.

ذخیره نسخه‌دار است و در تغییر هم‌زمان تازه‌سازی لازم می‌شود. کلید در فهرست عمومی دارایی‌ها یا پاسخ تنظیمات منتشر نمی‌شود.

## قرارداد مدیریت

کلید باید رشته معتبر و نسخه عدد صحیح نامنفی باشد. سقف بدنه ۱۲٬۰۰۰ بایت است. نبود جلسه ۴۰۱، نقش غیرمالک ۴۰۳ و اختلاف نسخه از مسیر خطای تنظیمات گزارش می‌شود.

| روش و مسیر | ورودی | پاسخ |
| --- | --- | --- |
| GET /api/integrations/wallex | جلسه مالک | {hasKey, version, updatedAt} |
| PUT /api/integrations/wallex | {secret, version} و مبدأ همان پنل | وضعیت ذخیره بدون مقدار کلید |

## نرخ تبدیل و مرز عملیات

نرخ تبدیل ریال و دلار در کارت مستقل تنظیم می‌شود. ذخیره کلید، سیاست نرخ تبدیل را تغییر نمی‌دهد.

این کارت مسیر خرید، فروش یا برداشت ندارد. دریافت داده عمومی و ثبت امن کلید دو قابلیت جدا هستند؛ حضور کلید ذخیره‌شده به معنی بررسی موفق اعتبار آن نیست.

- [مستندات رسمی والکس](https://developers.wallex.ir/docs)

## مراجع پیاده‌سازی

- planck-admin/components/wallex-settings.tsx
- planck-admin/lib/wallex-settings.ts
- planck-admin/app/api/integrations/wallex/route.ts
- planck-admin/tests/wallex-settings.test.mjs


---

# اتصال و بررسی کلید Ondo

ذخیره امن کلید و بررسی دسترسی به فهرست دارایی‌های Ondo.

وضعیت: پیاده‌سازی‌شده | مخاطب: مالک پنل و تیم اتصال بازار
بازبینی مستندات: ۲۰۲۶/۰۹/۲۴ · ۲ مهر ۱۴۰۵

## قابلیت پیاده‌سازی‌شده

کارت Ondo در بخش اتصال‌ها اجازه می‌دهد مالک کلید حساب مجاز خود را وارد کند، دسترسی آن به فهرست دارایی‌ها را بررسی کند و سپس ذخیره کند.

معرفی سهام توکنیزه‌شده و صندوق‌های ETF در کارت به معنی اضافه شدن خودکار آن‌ها به بازار عمومی یا فعال شدن معامله نیست. قابلیت اجرایی این بخش، تنظیم کلید و خواندن فهرست برای بررسی دسترسی است.

## بررسی پیش از ذخیره

دکمه بررسی فقط کلیدی را می‌آزماید که همان لحظه وارد شده است. این عمل کلید را ذخیره نمی‌کند و کلید قبلی را نیز از مخزن بازخوانی نمی‌کند.

سرور فهرست متادیتای دارایی‌ها را از نشانی ثابت رسمی با هدر x-api-key می‌خواند. خروجی فقط تعداد نمادهای یکتا و زمان بررسی است؛ قیمت قطعی یا معامله‌ای ایجاد نمی‌شود.

## ثبت در مخزن امن

ذخیره از ثبت‌خانه نسخه‌دار کلیدهای اتصال استفاده می‌کند. پس از ذخیره، ورودی پاک می‌شود و حضور کلید نمایش داده می‌شود؛ مقدار کلید دوباره به مرورگر برنمی‌گردد.

پیام موفقیت ذخیره، تأیید موفقیت اتصال نیست. دریافت کلید به پذیرش و مجوز Ondo وابسته است و بررسی دسترسی جدا انجام می‌شود.

## مسیرها و نتیجه‌ها

کلید نامعتبر یا فاقد مجوز داده در بررسی، وضعیت ۴۲۲ می‌گیرد. پاسخ نامعتبر سرویس ۵۰۲ و قطع ارتباط یا محدودیت درخواست ۵۰۳ است. متن خام خطای ارائه‌دهنده منتشر نمی‌شود.

| روش و مسیر | قرارداد |
| --- | --- |
| GET /api/integrations/ondo | پاسخ {hasKey, version, updatedAt} |
| PUT /api/integrations/ondo | ورودی {secret, version}؛ مالک و همان مبدأ |
| POST /api/integrations/ondo/check | ورودی {secret}؛ پاسخ {assetCount, checkedAt} |

## آمادگی و حدود اتصال

درخواست بررسی به فهرست رسمی محدود است، زمان انتظار ۱۰ ثانیه دارد و حداکثر ۲ مگابایت پاسخ خوانده می‌شود. ساختار نماد، ticker و tags قبل از موفقیت بررسی می‌شود.

عملیات زنده به کلید معتبر نیاز دارد و ذخیره به آماده بودن ثبت‌خانه و مخزن امن پایگاه داده وابسته است. این بخش سیاست نرخ ریال را تغییر نمی‌دهد.

- [راهنمای رسمی API در Ondo](https://docs.ondo.finance/api-reference/overview)
- [احراز دسترسی و راه‌اندازی](https://docs.ondo.finance/api-reference/quickstart)

## مراجع پیاده‌سازی

- planck-admin/components/ondo-settings.tsx
- planck-admin/lib/ondo-settings.ts
- planck-admin/lib/ondo-server.ts
- planck-admin/app/api/integrations/ondo/route.ts
- planck-admin/app/api/integrations/ondo/check/route.ts
- planck-admin/ONDO_SETUP.md
- planck-admin/tests/ondo-settings.test.mjs


---

# تنظیم نرخ تبدیل ریال و دلار

انتخاب تک‌مرجع یا میانگین چند مرجع برای نرخ مبتنی بر تتر.

وضعیت: پیاده‌سازی‌شده | مخاطب: مالک پنل
بازبینی مستندات: ۲۰۲۶/۰۹/۲۴ · ۲ مهر ۱۴۰۵

## معنای نرخ

نرخ مرجع مبلغ دلاری در سرمایه‌گذاری هوشمند بر مبنای قیمت تتر است و معادل قیمت دلار نقدی نیست. پیش‌فرض ذخیره‌نشده، حالت یک مرجع با انتخاب والکس است.

هر تومان همیشه برابر ۱۰ ریال است. انتخاب مرجع، قیمت تتر به ریال را تعیین می‌کند و ضریب تومان را تغییر نمی‌دهد.

## روش‌های انتخاب

انتخاب تکراری یا نام ناشناخته پذیرفته نمی‌شود. افزودن ارائه‌دهنده جدید به اتصال و پشتیبانی کد نیاز دارد و با وارد کردن یک URL در فرم انجام نمی‌شود.

| روش | قاعده |
| --- | --- |
| یک مرجع / single | دقیقاً یک گزینه: والکس یا نوبیتکس |
| میانگین / average | حداقل دو مرجع متمایز؛ فعلاً والکس و نوبیتکس |
| وزن‌ها | میانگین ساده با وزن برابر |
| تازگی | میانگین نیازمند نرخ تازه تمام انتخاب‌ها است |

## تنظیم در پنل

تنظیم فقط برای مالک واردشده قابل ذخیره است. کنترل‌های پیش‌نمایش و نقش‌های دیگر امکان ذخیره واقعی ندارند.

- در اتصال‌ها کارت «نرخ تبدیل ریال و دلار» را باز کنید.
- یک مرجع یا میانگین چند مرجع را انتخاب کنید.
- گزینه‌های موردنظر را تعیین و روش محاسبه را ذخیره کنید.
- در صورت تغییر هم‌زمان محتوا یا تنظیمات، تازه‌سازی و انتخاب را دوباره بررسی کنید.

## حفظ سایر تنظیمات

سیاست در فیلد exchange_rate داده محتوای سایت ذخیره می‌شود. ذخیره سایر محتوا را حفظ می‌کند و نسخه زمانی مانع بازنویسی تغییر هم‌زمان می‌شود.

خواندن در نبود رکورد فقط پیش‌فرض برمی‌گرداند. اولین ذخیره صریح، محتوای پیش‌فرض همراه سیاست را ایجاد می‌کند.

ویرایش معمولی محتوا، سیاست فعلی را حفظ می‌کند؛ مقدار قدیمی یا متفاوت باقی‌مانده در فرم محتوا آن را جایگزین نمی‌کند.

## قرارداد و مرز نتیجه

| مسیر یا فیلد | قرارداد |
| --- | --- |
| GET /api/integrations/exchange-rate | {policy, expectedUpdatedAt, configured} |
| PUT /api/integrations/exchange-rate | {policy, expectedUpdatedAt} |
| policy | mode: single یا average؛ sources: آرایه شناسه‌ها |
| configured | سیاست صریح ذخیره شده؛ به معنی سلامت لحظه‌ای مرجع نیست |

> دریافت نرخ زنده: این API سیاست را مدیریت می‌کند. دریافت نرخ زنده و بررسی تازگی در مارکت‌پلیس انجام می‌شود؛ ذخیره سیاست به‌تنهایی موفقیت دریافت از ارائه‌دهنده را ثابت نمی‌کند.

## مراجع پیاده‌سازی

- planck-admin/components/exchange-rate-settings.tsx
- planck-admin/lib/exchange-rate-settings.ts
- planck-admin/app/api/integrations/exchange-rate/route.ts
- planck-admin/app/api/content/route.ts
- planck-admin/tests/exchange-rate-settings.test.mjs


---

# راه‌اندازی و وضعیت عملیاتی پنل

اجزای برنامه، پیش‌نیازها، آزمون‌ها و مرز وضعیت اجرایی.

وضعیت: مرجع | مخاطب: تیم راه‌اندازی و نگهداری
بازبینی مستندات: ۲۰۲۶/۰۹/۲۴ · ۲ مهر ۱۴۰۵

## اجزای برنامه

پنل برنامه‌ای مستقل با React، TypeScript و Vinext است. به Supabase برای هویت کارکنان، داده پروژه و محتوا، سرویس‌های پایگاه داده و رسانه متصل می‌شود. رابط، API، ساخت و کوکی مستقل دارد.

سایت عمومی و پنل باید اتصال درست به پروژه داده موردنظر داشته باشند. نشانی مارکت‌پلیس در راه‌اندازی پنل تعریف می‌شود؛ این مقاله مقدار متغیر محیطی یا شناسه پروژه خصوصی را منتشر نمی‌کند.

## پیش‌نیاز بهره‌برداری

- اتصال پایگاه داده و پیکربندی عمومی مناسب برنامه تنظیم شود.
- مهاجرت‌ها، نقش‌ها، سیاست‌های دسترسی و فضای ذخیره رسانه نصب و بررسی شوند.
- اعضای تیم از مسیر مورد اعتماد تعریف و ورود دومرحله‌ای آن‌ها تکمیل شود.
- ثبت‌خانه، مخزن کلید و اتصال اجرای استعلام‌ها آماده باشد.
- برای Ondo کلید مجاز تهیه شود؛ ذخیره و بررسی دو گام مستقل‌اند.
- پیش از بهره‌برداری عمومی HTTPS، مبدأ و محدودیت درخواست میزبانی تکمیل شود.

## دامنه پیش‌نمایش

بدون اتصال و با گزینه پیش‌نمایش، فرم پروژه، ظاهر و محتوا با داده نمونه نمایش داده می‌شوند. وضعیت ویرایش موقت است و ذخیره یا بارگذاری واقعی انجام نمی‌شود.

مدارک واقعی نمایش داده نمی‌شوند و کلیدها، نرخ ارز و پاداش بدون مالک قابل ذخیره نیستند. اتصال پایگاه داده به‌تنهایی ورود موفق کاربر یا اعتبار ارائه‌دهنده را اثبات نمی‌کند.

## آزمون و بررسی

آزمون‌های موجود اعتبارسنجی پروژه و محتوا، ورود و MFA، هویت، دعوت، والکس، نرخ تبدیل و Ondo را پوشش می‌دهند.

آزمون مسیر سرویس از پاسخ کنترل‌شده استفاده می‌کند و موفقیت آن به معنی تماس موفق با ارائه‌دهنده زنده نیست. بررسی واقعی ورود، بارگذاری، انقضا و انتشار به پیکربندی و اعتبارنامه واقعی نیاز دارد.

```sh
npm run typecheck
npm test
npm run build
```

## وضعیت قابل اثبات

گزارش قدیمی راه‌اندازی جای بررسی وضعیت جاری را نمی‌گیرد. برای این مستند هیچ داده عملیاتی، پرونده یا تنظیمی تغییر نکرده است.

| قابلیت | وضعیت |
| --- | --- |
| پروژه و CMS | رابط، اعتبارسنجی و API موجود؛ نوشتن نیازمند اتصال و نقش |
| ورود MFA | جریان پیاده‌سازی شده؛ کاربر باید راه‌اندازی و ورود را کامل کند |
| مدارک و استعلام | رابط و API موجود؛ وابسته به پرونده، مجوز و سرویس |
| والکس و Ondo | ذخیره نسخه‌دار موجود؛ ذخیره تأیید اعتبار کلید نیست |
| سیاست نرخ | فرم مستقل موجود؛ نرخ زنده در مارکت‌پلیس دریافت می‌شود |
| معامله و پرداخت | پنل مسیر اجرای مالی مستقیم ندارد |
| انگلیسی و عربی | ورود ترجمه آماده؛ انتشار رابط این زبان‌ها فعال نیست |

## مراجع پیاده‌سازی

- planck-admin/README.md
- planck-admin/package.json
- planck-admin/app/page.tsx
- planck-admin/lib/server.ts
- planck-admin/MFA_SETUP.md
- planck-admin/ONDO_SETUP.md
- planck-admin/tests/admin-auth.test.mjs
- planck-admin/tests/validation.test.mjs
- planck-admin/tests/identity.test.mjs
- planck-admin/tests/referrals.test.mjs
- planck-admin/tests/exchange-rate-settings.test.mjs
- planck-admin/tests/ondo-settings.test.mjs


---

# معماری شبکه و مرز مسئولیت‌ها

ارتباط شبکه Besu، کنترل‌گر Admin Main، ایستگاه سازمانی و مارکت‌پلیس؛ با تفکیک کد موجود از استقرار عملیاتی.

وضعیت: پیاده‌سازی‌شده | مخاطب: توسعه‌دهندگان، مدیران زیرساخت و نهادهای همکار
بازبینی مستندات: ۲۰۲۶/۰۹/۲۴ · ۲ مهر ۱۴۰۵

## چهار بخش مستقل

مارکت‌پلیس رابط انتخاب دارایی، حساب کاربری و درخواست‌های تجاری است. پنل مدیریت وب محتوای همین محصول و اتصال‌های آن را اداره می‌کند. Admin Main محصول زیرساختی دیگری برای مدیریت شبکه Besu، اعتبارسنج‌ها و گردش کنترل قراردادهاست؛ این دو پنل نقش و سطح دسترسی یکسان ندارند.

Plank Station محیط کاری محدود به نقش سازمان است. نصب Station لزوماً نود بلاک‌چین، عضویت اجماع یا اختیار مدیریت کل شبکه ایجاد نمی‌کند. نسخه Remote نیز برای مشاهده اطلاعات سرور طراحی شده و دفترکل کامل را روی رایانه کاربر دانلود نمی‌کند.

| جزء | مسئولیت اصلی | مرز دسترسی |
| --- | --- | --- |
| مارکت‌پلیس و مدیر وب | دارایی‌ها، حساب و اتصال‌های تجاری | مجوزهای برنامه وب |
| Admin Main | هویت شبکه، زیرساخت و چرخه اعتبارسنج | دسترسی اپراتور مجاز زیرساخت |
| Station سازمانی | عضویت، وظایف و منابع متصل به ایستگاه | نقش‌های تأییدشده همان سازمان |
| Besu | اجرای EVM، دفترکل و اجماع QBFT | پیکربندی و مجموعه اعتبارسنج شبکه |

## هویت شبکه از کجا مشخص می‌شود؟

در نسخه تولیدی، هویت مورد انتظار شبکه با Chain ID و هش بلاک آغازین پیکربندی می‌شود. پاسخ RPC باید با این مقادیر تطبیق داشته باشد؛ پاسخ‌دادن یک سرویس یا تشابه نام شبکه کافی نیست. برخی مسیرها Network ID را نیز کنترل می‌کنند.

هش بلاک صفر که از RPC خوانده می‌شود با SHA-256 فایل genesis.json دو شاهد متفاوت است. اولی برای تطبیق زنجیره و دومی در بعضی مجوزها برای اتصال تصمیم به فایل پیکربندی به کار می‌رود. مستند اتصال هر مؤلفه مشخص می‌کند کدام‌یک مورد نیاز است.

## Besu و اجماع مجوزدار

سورس Admin Main تصویر Besu با نسخه ثابت 26.7.1 و تولید Genesis مبتنی بر QBFT را نشان می‌دهد. اجرای قراردادها با EVM و خواندن داده از JSON-RPC انجام می‌شود. دوره بلاک، دوره بلاک خالی و مهلت درخواست، تنظیمات شبکه هستند و نباید به‌عنوان یک زمان قطعی عمومی برای همه نصب‌ها معرفی شوند.

پیکربندی تولیدشده epoch برابر ۳۰٬۰۰۰ و zeroBaseFee دارد. وجود این گزینه در مولد شبکه به‌تنهایی ثابت نمی‌کند هر شبکه موجود همین تنظیمات را دارد یا کارمزد تجاری همه خدمات صفر است؛ تنظیمات واقعی باید از Genesis همان استقرار بررسی شوند.

## سه سطح شواهد

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

گزارش‌های نسخه‌ای داخل پروژه مرجع تاریخی بررسی‌ها هستند. در تهیه این مستندات کد و گزارش‌ها خوانده شده‌اند؛ اتصال به سرور، رأی اجماع، نصب سرویس و اجرای تراکنش تولیدی انجام نشده است.

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

## اتصال برنامه‌ها به یکدیگر

شناخت سلامت Admin Main، ثبت یک نود در رجیستری، عضویت رسمی QBFT و داشتن نقش تجاری چهار موضوع جدا هستند. هیچ‌کدام را نباید از دیگری نتیجه گرفت. برای نمونه، سازمان می‌تواند Station فعال داشته باشد و اصلاً اعتبارسنج نباشد.

برای راه‌اندازی یک خدمت کامل باید قرارداد API، نقش سازمان، منبع RPC، امضاکننده و ثبت نتیجه تراکنش در هر دو سوی اتصال مشخص شوند. اتصال‌های قیمت مارکت‌پلیس نیز به‌خودی‌خود دسترسی مدیریت شبکه یا تسویه روی زنجیره ایجاد نمی‌کنند.

## مراجع پیاده‌سازی

- admin-main-new/backend/app/production.py
- admin-main-new/backend/app/services/network_service.py
- plank-station-new/agent/app.py
- plank-station-mac-remote/server/gateway.py


---

# Admin Main؛ کنترل‌گر شبکه پلانک

قابلیت‌های کنترل شبکه، ابزارهای تشخیص، مدیریت قرارداد و تفاوت Admin Main با پنل مدیر مارکت‌پلیس.

وضعیت: پیاده‌سازی‌شده | مخاطب: اپراتور شبکه و مدیر فنی
بازبینی مستندات: ۲۰۲۶/۰۹/۲۴ · ۲ مهر ۱۴۰۵

## محصول و ساختار فنی

نسخه بررسی‌شده admin-main-new با شناسه نسخه 0.18.7-production.2 یک محصول مستقل با رابط React و TypeScript، ساخت Vite و سرویس Python/FastAPI است. لایه بلاک‌چین از Web3 و ابزارهای امضای اتریوم استفاده می‌کند. فایل‌های قرارداد Solidity و خروجی ABI نیز در همین محصول وجود دارند.

پنل مدیر مارکت‌پلیس وظایفی مانند محتوا و تنظیم ارائه‌دهندگان داده دارد؛ Admin Main با نود، Genesis، رأی QBFT و عملیات قرارداد سروکار دارد. استفاده از واژه «مدیر» در هر دو برنامه نباید به معنای اشتراک نشست، حساب یا اختیار آن‌ها تعبیر شود.

## عملیات موجود در سورس

سرویس‌های شبکه برای ساخت تنظیمات، کار با Docker، بازیابی نصب شناخته‌شده، نصب و تشخیص اعتبارسنج راه‌دور و پیگیری عملیات طولانی وجود دارند. زیرسامانه‌های خواندن بلاک، تراکنش، انتقال توکن، اطلاعات قرارداد و شاخص‌های امضاکنندگان از RPC استفاده می‌کنند.

ابزار تشخیص، سلامت فرایند، RPC واقعی، ارتباط همتا، همگام‌سازی، هویت زنجیره و عضویت اجماع را جدا می‌سنجد. تست وضعیت یک مسیر خواندنی است؛ بازیابی یا راه‌اندازی مجدد، عملیات جدا و صریح اپراتور است.

## نقش سازمانی و گردش قرارداد

کنترل‌گر شامل رجیستری سازمان، سیاست تأیید پروژه، تأیید نهایی، کنترل ضرب، توکن فعال، اوراکل، قیمت و درخواست عرضه عمومی است. این مدل مراحل پروژه را ثبت می‌کند، اما صرف تغییر وضعیت محلی معادل انجام یک تراکنش موفق روی زنجیره نیست.

در محیط تولید، ساخت خودکار نقش‌های آزمایشی و امضای شبیه‌سازی‌شده سازمان‌ها غیرفعال می‌شود. تصمیم واقعی باید از مرجع مجاز و مسیر امضای واقعی برسد؛ فعال‌کردن گزینه تولید، اتصال کامل Station و امضاکننده را خودکار ایجاد نمی‌کند.

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

محافظ آغاز به کار تولیدی، مسیر داده پایدار، اتصال محدود به loopback، مبدأ عمومی HTTPS، RPC مرجع، Chain ID معتبر، هش Genesis و مبدأهای مجاز مشخص را بررسی می‌کند. توکن برنامه نیز باید پیکربندی شود. CORS با مقدار wildcard برای این حالت پذیرفته نیست.

پروب canonical سپس اتصال، Chain ID، هش بلاک صفر و مجموعه اعتبارسنج‌ها را می‌خواند. خطای این مرحله نباید با داده نمایشی جبران شود. دسترسی بیرونی باید از درگاه مصوب عبور کند و RPC مدیریتی برای کاربران عمومی منتشر نشود.

## آنچه بسته و گزارش اثبات می‌کنند

گزارش پایه تولیدی از موفقیت ۱۴۴ آزمون و ساخت رابط و قراردادها سخن می‌گوید و استقرار سرور را انجام‌نشده اعلام می‌کند. یادداشت 0.18.7-production.2 موفقیت ۱۴۸ آزمون و ساخت را ثبت کرده و نشان می‌دهد healthy بودن کانتینر، موفقیت RPC را تضمین نمی‌کند. این اعداد گزارش تاریخی همان نسخه‌اند؛ در این بررسی دوباره اجرا نشده‌اند.

کد Electron قدیمی در درخت سورس باقی است و به backend اجرایی ویندوز اشاره می‌کند؛ اما package.json نسخه جاری مسیر ساخت و اجرای سروری دارد. حضور آن فایل‌ها مدرک انتشار نصب‌کننده دسکتاپ امضاشده برای نسخه جاری نیست.

## مراجع پیاده‌سازی

- admin-main-new/package.json
- admin-main-new/backend/app/main.py
- admin-main-new/backend/app/services/control_plane_service.py
- admin-main-new/backend/app/production.py
- admin-main-new/electron/main.ts
- admin-main-new/VERIFICATION_NEW_FA.md
- admin-main-new/RELEASE_NOTES_v0.18.7-production.2_FA.md


---

# Plank Station؛ ایستگاه کاری سازمان

عضویت مستقل، نقش‌های سازمانی، وظایف، اتصال اختیاری نود و مرز آمادگی امضا.

وضعیت: پیاده‌سازی‌شده | مخاطب: نهادهای همکار و کاربران سازمانی
بازبینی مستندات: ۲۰۲۶/۰۹/۲۴ · ۲ مهر ۱۴۰۵

## هویت سازمان از هویت نود جداست

Station نسخه 1.2.0-production.1 یک رابط React و عامل محلی Python با داده SQLite است. نام نمایشی و مشخصات سازمان به Station تعلق دارند؛ هویت اعتبارسنج متصل از منبع کشف نود می‌آید و با تغییر نام سازمان بازنویسی نمی‌شود.

عضویت فعال Station می‌تواند بدون Node، Validator یا Signer برقرار باشد. در این حالت بررسی‌های RPC، همگام‌سازی و تولید بلاک «نامرتبط» گزارش می‌شوند؛ نبود نود اختیاری به‌تنهایی خرابی یا رد عضویت سازمان نیست.

## نقش‌های پشتیبانی‌شده

مدل نقش شامل نهاد دولتی، بانک، ناظر مقرراتی، مالی، حقوقی، ثبت، فنی و مشاهده‌گر است. انتخاب نوع سازمان تنها نقش‌های درخواستی را مشخص می‌کند؛ اختیار واقعی پس از رسید معتبر و نقش‌های تأییدشده مرجع شبکه فعال می‌شود.

یک نقش مانند LEGAL_APPROVER برای تصمیم حقوقی با عضویت در مجموعه Validatorهای QBFT یکسان نیست. همچنین نقش NODE_OBSERVER به معنی دسترسی به کلید اجماع یا اختیار تغییر اعضای شبکه نیست.

## درخواست و رسید عضویت

جریان عضویت شامل شناسه درخواست، شناسه ایستگاه، شبکه، سازمان، روش تأیید و نقش‌های درخواستی است. فعال‌سازی، رسید امضاشده Ed25519 را با کلید عمومی مرجع مورد اعتماد بررسی می‌کند و تطبیق همین شناسه‌ها و روش تأیید را می‌سنجد.

رسید تکراری یا قدیمی با شماره توالی رد می‌شود؛ زمان صدور و انقضا نیز بررسی می‌شوند. در تأیید عضویت، نقش‌های مصوب باید زیرمجموعه نقش‌های درخواست‌شده باشند. کلید عمومی مرجع باید از مسیر معتبر دریافت شود، نه صرفاً از یک فایل همراه نامشخص.

## تصمیم و امضا دو مرحله‌اند

برای ثبت تصمیم روی وظیفه، نسخه سیاست و شناسه درخواست بررسی می‌شوند و وظیفه پایان‌یافته دوباره تصمیم‌پذیر نیست. وظیفه‌ای که امضای سازمانی لازم دارد می‌تواند به READY_FOR_SIGNATURE برسد؛ این وضعیت اثبات ایجاد امضا یا ثبت تراکنش نیست.

اتصال HSM، MPC یا Web3Signer با شناسه عمومی کلید، نشانی و مسیر فایل‌های اعتماد پیکربندی می‌شود. در این سورس، بررسی آمادگی و صف تصمیم موجود است؛ اجرای کامل امضا و ارسال نیازمند قرارداد واقعی سرویس و آزمون یکپارچه همان سازمان است.

## حالت تولید و وضعیت بررسی

در حالت تولید، Demo و ایجاد Software Vault رد می‌شوند، مسیر runtime باید پایدار و مطلق باشد و عامل فقط روی loopback اجرا شود. گزارش عمومی، جزئیات حساس را کنار می‌گذارد و گزارش قدیمی شبکه به‌صورت وضعیت نامشخص یا قدیمی نمایش داده می‌شود.

گزارش Station New موفقیت ۴۲ آزمون و ساخت رابط را ثبت کرده است، اما عضویت واقعی، پروب RPC واقعی و نصب سرویس Linux را تأییدشده نمی‌داند. این مستندات نیز صرفاً سورس را بررسی کرده‌اند و چنین اتصالی ایجاد نکرده‌اند.

## مراجع پیاده‌سازی

- plank-station-new/package.json
- plank-station-new/agent/app.py
- plank-station-new/SECURITY.md
- plank-station-new/VERIFICATION_NEW_FA.md


---

# انواع نود و چرخه راه‌اندازی

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

وضعیت: پیاده‌سازی‌شده | مخاطب: اپراتور Station و مدیر زیرساخت
بازبینی مستندات: ۲۰۲۶/۰۹/۲۴ · ۲ مهر ۱۴۰۵

## نقش‌های فنی متفاوت

کاتالوگ توسعه Station چند نوع منبع را توصیف می‌کند. این کاتالوگ مشخص می‌کند هر درخواست به چه اطلاعات و مجوزی نیاز دارد؛ وجود نام یک نوع منبع در رابط به معنی نصب‌شدن خودکار آن نیست.

| منبع | کارکرد | حق اجماع |
| --- | --- | --- |
| Validator | اجرای نود عضو و مشارکت QBFT | فقط پس از عضویت canonical |
| Standby Validator | آمادگی برای جایگزینی کنترل‌شده | تا پیش از رأی و عضویت ندارد |
| Full / RPC Node | کنترل مستقل زنجیره یا ارائه RPC خصوصی | ندارد |
| Mini / Operational Node | منبع عملیاتی با داده کم‌حجم‌تر | عنوان Mini به معنای Light Client نیست |
| Observer / Archive | مشاهده یا نگهداری تاریخچه state | ندارد |
| Bootnode | کشف همتایان | نقش خودکار اعتبارسنج ندارد |
| Monitoring Agent | پایش و گزارش وضعیت | ندارد |

## ابتدا منابع موجود شناسایی می‌شوند

Inventory سرور به‌صورت محدود و پاک‌سازی‌شده تولید می‌شود. Station ابتدا نامزدهای موجود را می‌خواند و نود انتخاب‌شده را به خود متصل می‌کند. وجود اعتبارسنج قابل استفاده، مسیر ساخت موازی اعتبارسنج تازه را محدود می‌کند.

تطبیق شامل هویت نود، وضعیت فرایند، RPC اختصاصی، Chain ID، Genesis و در صورت وجود مرجع، هش در ارتفاع مشترک است. نام یک کانتینر یا یک رکورد محلی به‌تنهایی هویت canonical را اثبات نمی‌کند.

## درخواست توسعه، استقرار نیست

فرم توسعه می‌تواند نوع منبع، نام فنی، پورت‌ها، حالت همگام‌سازی FULL یا SNAP، سیاست داده PRUNED/FULL/ARCHIVE و مرجع بسته ادمین را ثبت کند. نشانی عمومی RPC به‌عنوان یک قابلیت خودکار مجاز فرض نشده است.

خروجی درخواست بر اساس اطلاعات و سیاست می‌تواند WAITING_ADMIN_PACKAGE، WAITING_NETWORK_GOVERNANCE یا DRAFT_READY باشد. این وضعیت‌ها پیش‌نویس و انتظار را توصیف می‌کنند؛ تولید Genesis، دریافت مجوز و ساخت کانتینر واقعی مراحل جدا هستند.

## کنترل فقط منبع متصل

عامل Station برای start، stop و restart از مسیر محدود کنترل نود استفاده می‌کند. helper نصب‌شده باید مالک root داشته باشد؛ سرویس درخواستی را با binding همان Station و Inventory مورد اعتماد تطبیق می‌دهد و نوع کانتینر Besu را بررسی می‌کند.

این اختیار، دسترسی عمومی به همه کانتینرهای میزبان نیست. در نسخه Remote macOS حتی همین کنترل محدود runtime نیز وجود ندارد و فقط خواندن اطلاعات مجاز است.

## توقف محلی، خروج از شبکه و حذف داده

مدل چرخه عمر میان غیرفعال‌سازی محلی، درخواست خروج از شبکه و پاک‌سازی سرور تفاوت می‌گذارد. خاموش‌کردن کانتینر، آدرس را از مجموعه QBFT حذف نمی‌کند و حذف یک رکورد رابط نیز جای رأی شبکه را نمی‌گیرد.

شرایط اقدام باید از وضعیت تازه بررسی شوند: binding معتبر، رمز محلی، حضور در Inventory، وضعیت اجرا و تأیید خروج از مجموعه canonical. پیش از هر پاک‌سازی، هویت و داده بازیابی باید در برنامه عملیاتی مستقل حفاظت شوند.

## مراجع پیاده‌سازی

- plank-station-new/agent/app.py
- plank-station-new/scripts/refresh-node-inventory.py
- plank-station-new/scripts/node-runtime-control.sh
- plank-station-new/deploy/install-ubuntu-24.04.sh


---

# اعتبارسنج‌ها و حاکمیت QBFT

مجوز سازمانی، رأی اجماع، عضویت canonical و مشارکت در تولید بلاک را جدا دنبال کنید.

وضعیت: پیاده‌سازی‌شده | مخاطب: مدیران شبکه و ناظران فنی
بازبینی مستندات: ۲۰۲۶/۰۹/۲۴ · ۲ مهر ۱۴۰۵

## دو نوع مجوز مستقل

Admin Main دو سیاست QBFT_STANDARD و ADMIN_GATED_QBFT را می‌شناسد. در سیاست دوم، مجوز سازمانی ادمین پیش‌شرط عملیات است، اما همچنان جای رأی اعضای QBFT را نمی‌گیرد. سیاست پیش‌فرض برای رکوردهای قدیمی، حالت دارای دروازه ادمین است.

مجوز ادمین به عملیات افزودن یا حذف، آدرس هدف، Chain ID، هش فایل Genesis، زمان اعتبار و nonce متصل می‌شود. نتیجه موفق مصرف مجوز را ثبت می‌کند تا یک تأیید سازمانی به مجوز دائمی برای عملیات نامرتبط تبدیل نشود.

## اکثریت تغییر عضو و حد نصاب بلاک

در منطق همین پیاده‌سازی، تغییر مجموعه اعتبارسنج با اکثریت بیش از نصف اعضای فعلی محاسبه می‌شود: floor(n/2)+1. حد نصاب ثبت بلاک جداست و با ceil(2n/3) محاسبه می‌شود. بنابراین «تعداد رأی لازم برای عضویت» و «حد نصاب ادامه تولید بلاک» یک شمارنده نیستند.

این محاسبات برای ارزیابی ایمنی عملیات در کد به کار می‌روند. تعداد اعضای واقعی و وضعیت آنلاین آن‌ها باید از شبکه همان لحظه خوانده شود؛ مستندات تعداد ثابت یا تضمین تحمل خرابی برای استقرار فعلی اعلام نمی‌کنند.

## ماشین حالت عملیات

مسیر افزودن از ثبت درخواست و در صورت لزوم انتظار تأیید ادمین، به راه‌اندازی، همگام‌سازی، آمادگی رأی و رأی‌گیری می‌رسد. پس از اثبات عضویت، پایش مشارکت ادامه پیدا می‌کند. خطا باید با مرحله و شواهد قابل پیگیری همراه باشد.

ذخیره عملیات پایدار و کلید idempotency از ایجاد کارهای هم‌زمان تکراری جلوگیری می‌کنند. پس از قطع backend، کار بدون thread فعال «قطع‌شده» گزارش می‌شود؛ نباید از یک وضعیت running ذخیره‌شده، اجرای واقعی همچنان فعال را نتیجه گرفت.

## عضویت با شواهد Besu تأیید می‌شود

مجموعه latest و نمای pending از روش‌های QBFT خوانده می‌شوند. رجیستری داخلی یا پیام موفق رابط منبع نهایی عضویت نیست. مقایسه شاخه زنجیره در ارتفاع مشترک انجام می‌شود تا عقب‌بودن نود با fork اشتباه نشود.

سلامت فرایند، دسترسی RPC، peers، sync، عضویت و مشارکت proposer مستقل‌اند. اعتبارسنج عضو ممکن است هنوز نوبت پیشنهاد بلاک نداشته باشد؛ برعکس سابقه پیشنهاد یک بلاک ثابت نمی‌کند همین حالا آنلاین و همگام است.

## اعتبارسنج راه‌دور و محدودیت تأیید

تشخیص راه‌دور شامل بررسی اتصال امن، پاسخ RPC محدود و شواهد فرایند است. یادداشت نسخه جدید صریحاً healthy بودن کانتینر را برای تأیید سلامت RPC کافی نمی‌داند. تست خواندنی نباید برای سبزشدن کارت، خودکار رأی یا restart اجرا کند.

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

## مراجع پیاده‌سازی

- admin-main-new/ARCHITECTURE_v0.14.0_FA.md
- admin-main-new/backend/app/services/validator_governance_service.py
- admin-main-new/backend/app/services/validator_lifecycle_service.py
- admin-main-new/backend/app/services/operation_store.py
- admin-main-new/backend/app/services/validator_diagnostics_service.py


---

# قراردادها و کنترل‌های روی زنجیره

خانواده قراردادهای موجود، محدودیت‌های توکن و تفاوت ثبت محلی، اجرای EVM و پیام میان‌زنجیره‌ای.

وضعیت: پیاده‌سازی‌شده | مخاطب: توسعه‌دهندگان قرارداد و ارزیابان فنی
بازبینی مستندات: ۲۰۲۶/۰۹/۲۴ · ۲ مهر ۱۴۰۵

## دوازده قرارداد در زنجیره ابزار

درخت سورس خانواده‌ای شامل PlankToken، ProjectGovernance، PlankOrganizationRegistry، PlankProjectRegistry، PlankApprovalManager، PlankMintController، PlankActiveTokenRegistry، PlankOracleReportRegistry، PlankTokenPriceRegistry، PlankPublicizationController و دو قرارداد CCIP Sender/Receiver دارد.

فایل Solidity و artifact قرارداد نشان‌دهنده وجود کد قابل کامپایل است. برای معرفی قرارداد مستقر باید آدرس، Chain ID، نسخه bytecode و تراکنش استقرار همان شبکه به‌صورت جدا ثبت و تأیید شوند؛ فهرست نام قراردادها جای این شواهد را نمی‌گیرد.

## توکن پایه و حاکمیت پروژه

PlankToken موجودی و allowance، انتقال، ضرب، سوزاندن، سقف عرضه، توقف، تنظیم انتقال، نقش minter و قفل زمانی موجودی را پیاده می‌کند. دقت ثابت توکن ۱۸ رقم اعشار است. فراداده دارایی و سیاست درآمد و تبدیل نیز در مدل قرارداد وجود دارند.

ProjectGovernance دو الگوی رأی بر اساس وزن توکن و یک کیف‌پول/یک رأی دارد. وجود این امکان در قرارداد اثبات هویت یکتای اشخاص یا ارزش حقوقی یک رأی نیست؛ معیار مشارکت و سازوکار احراز باید برای همان پروژه روشن شوند.

## کنترل عرضه و مجوز ضرب

Mint Controller پیش از ضرب، اختیار operator، وضعیت توقف، گیرنده، شناسه مجوز و عدم استفاده قبلی مجوز را کنترل می‌کند. رجیستری پروژه باید امکان ضرب مقدار موردنظر را تأیید کند و ثبت نتیجه نیز انجام می‌شود.

عرضه مجاز، عرضه ضرب‌شده و عرضه توزیع‌شده مفاهیم متفاوت‌اند. وضعیت محلی پروژه باید با رویداد و نتیجه تراکنش زنجیره تطبیق داده شود؛ گزارش داخلی به‌تنهایی اثبات موجودی قابل معامله کاربران نیست.

## گزارش اوراکل و عرضه عمومی

کنترل‌گر عرضه عمومی وضعیت‌هایی مانند انتظار مشاهده‌گر، مجاز، اجراشده، لغوشده و منقضی دارد و به اعتبار پروژه و گزارش اوراکل وابسته است. در کد، سیاست و شواهد پیش از انتقال وضعیت بررسی می‌شوند.

ثبت داده اوراکل صحت دارایی بیرونی را خودکار تضمین نمی‌کند. منبع، تازگی داده، سیاست پذیرش و اعتبار امضا باید جدا تعریف شوند؛ امکان نگهداری گزارش در قرارداد جای ارزیابی حقوقی یا مالی دارایی را نمی‌گیرد.

## مرز پیام میان‌زنجیره‌ای

قراردادهای CCIP بررسی‌شده برای پیام داده و شواهد طراحی شده‌اند. Sender مسیر و گیرنده مجاز و محدودیت ارسال دارد؛ Receiver روتر، شبکه و فرستنده مجاز، جلوگیری از تکرار و اعتبار payload را کنترل می‌کند. مسیر دریافت، انتقال توکن همراه پیام را پشتیبانی‌شده فرض نمی‌کند.

پس این کد را نباید «پل آماده انتقال همه دارایی‌ها» معرفی کرد. فعال‌سازی واقعی نیازمند شبکه و مسیر پشتیبانی‌شده ارائه‌دهنده، قراردادهای مستقر، پیکربندی و آزمون ارسال و تأیید مقصد است. آزمون محلی EVM یا mock روتر، موفقیت مسیر واقعی را ثابت نمی‌کند.

## مراجع پیاده‌سازی

- admin-main-new/contracts/PlankToken.sol
- admin-main-new/contracts/ProjectGovernance.sol
- admin-main-new/contracts/PlankMintController.sol
- admin-main-new/contracts/PlankPublicizationController.sol
- admin-main-new/contracts/PlankCCIPSender.sol
- admin-main-new/contracts/PlankCCIPReceiver.sol
- admin-main-new/backend/tests/test_onchain_control_plane.py


---

# پلانک روی macOS

تفاوت Station محلی قدیمی و بسته بومی Remote، نیازمندی‌ها و وضعیت واقعی امضا و آزمون.

وضعیت: نیازمند پیکربندی | مخاطب: کاربران macOS و مسئولان توزیع سازمانی
بازبینی مستندات: ۲۰۲۶/۰۹/۲۴ · ۲ مهر ۱۴۰۵

## دو مسیر جدا برای مک

بسته تاریخی Plank Station 1.0.0 برای macOS، توزیع سورس با setup و run است: عامل Python و رابط محلی را اجرا و مرورگر را باز می‌کند. این بسته با محصول جدید Plank Station Remote 1.3.0 یکسان نیست.

Remote از سورس Station 1.2 جدا شده، اما نقطه ورود و درگاه متفاوت دارد. فایل‌های عامل و رابط قدیمی برای ردیابی در سورس باقی‌اند؛ در بسته بومی جدید اجرا نمی‌شوند. Remote جایگزین کامل قابلیت‌های نوشتن Station سازمانی نیست.

## ساخت و محتوای بسته Remote

اسکریپت ساخت، Swift را برای arm64 و x86_64 با حداقل macOS 12 کامپایل و خروجی Universal ایجاد می‌کند. برنامه از AppKit، WebKit و Security استفاده می‌کند؛ رابط React از منابع داخل بسته و scheme اختصاصی بارگذاری می‌شود.

در خروجی بومی برای اجرای برنامه به Python، Node، Docker، Besu یا وب‌سرور localhost روی مک نیاز نیست. دفترکل روی سرور می‌ماند و برنامه خلاصه وضعیت، بلاک‌های اخیر و بلاک انتخابی را می‌خواند. این رفتار، نود کامل یا light client با اثبات مستقل نیست.

## اتصال و دسترسی

دو مسیر ارتباط HTTPS و SSH با forced command وجود دارند. در مسیر SSH، بررسی هویت میزبان اجباری است و forwarding، PTY و فرمان محلی دلخواه فعال نمی‌شوند. مسیر HTTPS تغییرمقصد خودکار و گواهی نامعتبر را راه‌حل اتصال نمی‌داند.

توکن دسترسی Station با کلید SSH، کلید کیف پول و کلید اجماع متفاوت است. نقش و دامنه دسترسی از سرور می‌آیند. تنظیمات عمومی در فایل اتصال و توکن به انتخاب کاربر در حافظه یا Keychain اختصاصی محصول نگهداری می‌شود؛ lock نشست حافظه را پاک می‌کند.

## وضعیت ساخت و امضا

گزارش نسخه 1.3.0 موفقیت ۱۸ آزمون درگاه، ساخت React و ساخت Universal را ثبت می‌کند. خودآزمایی منطق بومی روی arm64 و بررسی ساختار امضای ad-hoc نیز در همان گزارش آمده است.

این بسته Developer ID و notarization اپل ندارد. آزمون نهایی پنجره WebKit و مسیرهای SSH/Keychain در نشست عادی کاربر و اتصال کامل به تولید در گزارش تأیید نشده‌اند. وجود باینری x86_64 داخل Universal به معنی آزمون اجرایی مستقل روی مک Intel نیست.

> بسته محلی با انتشار عمومی فرق دارد: برای توزیع عمومی قابل اعتماد، امضای ناشر، notarization، کنترل نسخه و آزمون پذیرش هنوز باید تکمیل شوند. غیرفعال‌کردن Gatekeeper یا بررسی TLS بخشی از راهنمای اتصال نیست.

## راه‌اندازی سازمانی

مدیر شبکه باید درگاه را جداگانه روی سرور آماده کند، هویت Station و کلید دسترسی اختصاصی بدهد و Chain ID، Network ID و هش بلاک صفر مورد انتظار را از مسیر معتبر تحویل دهد. نمایش فرم اتصال یا نصب برنامه به‌تنهایی عضویت یا مجوز نمی‌سازد.

اسکریپت بسته‌بندی runtime، محیط‌ها، دیتابیس، وابستگی‌های ساخت و تنظیمات واقعی درگاه را از بسته سورس کنار می‌گذارد. پیش‌فرض‌ها و مثال‌های تاریخی باید هنگام تحویل بازبینی شوند؛ در مستند عمومی از نشانی عملیاتی، آدرس اعتبارسنج یا کلید واقعی استفاده نمی‌شود.

## مراجع پیاده‌سازی

- plank-station-mac-remote/package.json
- plank-station-mac-remote/macos/Station.swift
- plank-station-mac-remote/scripts/build-mac.mjs
- plank-station-mac-remote/scripts/package-release.mjs
- plank-station-mac-remote/server/gateway.py
- plank-station-mac-remote/VERIFICATION_REMOTE_FA.md
- Plank-Station-macOS-v1.0.0/tools/run.mjs


---

# پلانک روی Windows

آنچه در بسته Windows نسخه 1.0.0 موجود است و آنچه درباره نصب‌کننده، امضا و سازگاری هنوز تأیید نشده است.

وضعیت: مرجع | مخاطب: کاربران Windows و تیم بسته‌بندی
بازبینی مستندات: ۲۰۲۶/۰۹/۲۴ · ۲ مهر ۱۴۰۵

## ماهیت بسته موجود

مرجع بررسی‌شده Windows نسخه 1.0.0، سورس Station با فایل‌های setup.cmd، setup.ps1 و run.cmd است. این بسته رابط React و عامل Python را روی رایانه اجرا می‌کند و مرورگر را به رابط محلی می‌برد.

در محدوده بررسی‌شده، مدرک نصب‌کننده MSI یا EXE امضاشده برای Station جاری پیدا نشد. بنابراین عبارت «پشتیبانی ویندوز» در این نسخه باید به مسیر اجرای سورس و launcher ویندوز اشاره کند، نه انتشار عمومی یک نرم‌افزار بومی نصب‌شونده.

## پیش‌نیازهای راه‌اندازی

اسکریپت setup حداقل Node.js 20 و Python را بررسی می‌کند. در صورت نبود وابستگی، مسیر نصب با winget برای Node.js LTS و Python 3.12 در کد پیش‌بینی شده است. سپس محیط مجازی Python ساخته و وابستگی‌های Python و npm نصب می‌شوند.

اسکریپت در ادامه آزمون و ساخت رابط را فراخوانی می‌کند. وجود این گام‌ها در فایل نصاب، نتیجه موفق روی یک دستگاه Windows مشخص را اثبات نمی‌کند؛ نسخه سیستم‌عامل، معماری، سیاست PowerShell و گزارش اجرای واقعی باید در پذیرش انتشار ثبت شوند.

## اجرای روزمره

run.cmd ابزار مشترک Node را اجرا می‌کند. این ابزار runtime برنامه را انتخاب کرده، حالت Demo را خاموش نگه می‌دارد، عامل و رابط را بالا می‌آورد و پس از آماده‌شدن صفحه مرورگر را باز می‌کند. اجرای نخست با نقش، کیف پول و شبکه خالی آغاز می‌شود.

نصب این Station باعث نصب Besu یا فعال‌شدن Validator نمی‌شود. منابع شبکه، عضویت سازمان و امضاکننده باید از مسیرهای مستقل پیکربندی شوند. اسکریپت‌های Linux که در بسته تاریخی باقی‌اند نیز قابلیت بومی Windows محسوب نمی‌شوند.

## اعتبار بسته و داده محلی

اطلاعات محیط اجرا، دیتابیس Station، توکن نشست و مراجع امضاکننده جزو داده‌های عملیاتی‌اند. این داده‌ها نباید همراه بسته عمومی یا گزارش خطا منتشر شوند. مسیر اجرای سورس با اجرای یک باینری دارای امضای ناشر و زنجیره به‌روزرسانی امضاشده یکسان نیست.

در سورس تاریخی، محدودیت امضای واقعی و تنظیم امضاکننده بیرونی توضیح داده شده است. هیچ رمز یا کلید عمومیِ اشتراکی برای ورود کاربران نباید به‌عنوان پیش‌فرض مستند شود. اطلاعات واقعی هر سازمان باید از مسئول مجاز همان سازمان دریافت شود.

## محدودیت و مسیر تکمیل

آزمون نصب پاک Windows، گزارش سازگاری نسخه‌های سیستم‌عامل، امضای Authenticode، نصب‌کننده رسمی، حذف امن برنامه و به‌روزرسانی امضاشده در شواهد این بررسی تأیید نشده‌اند. این موارد باید پیش از معرفی نسخه آماده انتشار به کاربران عمومی تکمیل شوند.

کد Electron موجود در خانواده Admin Main به backend اجرایی Windows اشاره می‌کند، اما محصول و جریان ساخت آن با Station متفاوت است. از این فایل نمی‌توان وجود یک نسخه نصب‌شونده جاری Station یا هم‌سطح بودن قابلیت‌های آن با Remote macOS را نتیجه گرفت.

## مراجع پیاده‌سازی

- Plank-Station-Windows-v1.0.0/package.json
- Plank-Station-Windows-v1.0.0/setup.cmd
- Plank-Station-Windows-v1.0.0/setup.ps1
- Plank-Station-Windows-v1.0.0/run.cmd
- Plank-Station-Windows-v1.0.0/tools/run.mjs
- admin-main-new/electron/main.ts


---

# نسخه‌های Linux و شبکه مستقل

توزیع Station، سرویس‌های سروری و شاخه مستقل Admin Main برای ساخت یک شبکه جدید بدون دست‌زدن به شبکه قبلی.

وضعیت: نیازمند پیکربندی | مخاطب: مدیران Linux و تیم استقرار
بازبینی مستندات: ۲۰۲۶/۰۹/۲۴ · ۲ مهر ۱۴۰۵

## سه کاربرد Linux

بسته تاریخی Station 1.0.0 مسیر اجرای سورس محلی دارد. Station New 1.2.0-production.1 نصاب Ubuntu 24.04، عامل systemd، تولید Inventory و reverse proxy ارائه می‌دهد. Admin Main Linux New Network 0.18.7-linux-newnet.1 شاخه مستقلی برای شروع یک شبکه تازه است.

این نسخه‌ها قابل جایگزینی بی‌برنامه نیستند. هرکدام هویت سرویس، مسیر داده، تنظیمات و هدف عملیاتی خودش را دارد. وجود یک فایل نصب در یک بسته به معنی سازگاری همان فایل با همه نسخه‌ها و همه توزیع‌های Linux نیست.

## نصب Station سروری

نصاب Station New حساب سرویس اختصاصی، محیط Python، خروجی رابط، سرویس Inventory و helper محدود کنترل نود را آماده می‌کند. عامل به loopback متکی است و دسترسی بیرونی باید از مسیر خصوصی یا reverse proxy با TLS معتبر فراهم شود.

نصاب پس از آماده‌سازی، سرویس تازه را خودکار فعال نمی‌کند. پیکربندی مبدأها، هویت شبکه، اتصال Admin Main و رسید عضویت باید بازبینی شوند. گروه‌ها و مجوزهای helper نیز بخشی از محدوده اعتماد همان نصب‌اند.

## Admin Main برای شبکه تازه

شاخه Linux New Network از Admin Main جدا شده و با manifest خالی آغاز می‌کند. ساخت Genesis و شروع کانتینرها دو عملیات مستقل‌اند؛ شکست start نباید باعث بازتولید کلید یا بازنویسی Genesis شود. دسترسی به پروژه‌ها و RPC شبکه قبلی در لایه هویت نسخه محدود شده است.

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

## پیش‌نیاز و اختیار میزبان

نصاب Linux New Network به Python 3.11 تا 3.13، Docker و Compose فعال، nginx و گواهی معتبر نیاز دارد. خروجی رابط باید از قبل ساخته شده باشد. حساب سرویس این شاخه عضو گروه Docker است؛ چنین دسترسی‌ای از نظر اختیار میزبان گسترده است و برای یک میزبان اختصاصی باید برنامه‌ریزی شود.

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

## دامنه آزمون ثبت‌شده

گزارش ۱۴ سپتامبر ۲۰۲۶ موفقیت ۱۸۲ آزمون، ساخت ۱۲ قرارداد و خروجی رابط را ثبت می‌کند. تولید کلید و Genesis در فضای موقت، کنترل تداخل و رد پروژه و RPC بیگانه نیز در آزمون‌ها پوشش داده شده‌اند.

همان گزارش تصریح می‌کند آزمون‌ها روی محیط ساخت macOS اجرا شده‌اند، عملیات تغییردهنده Docker mock بوده و نصب systemd/nginx، شروع واقعی Besu، استقرار راه‌دور، آزمون بار و بازیابی سرور Linux هنوز تأیید نشده‌اند. نسخه آماده آزمون پذیرش است؛ نه گواهی استقرار بی‌نقص تولید.

## مراجع پیاده‌سازی

- plank-station-new/deploy/install-ubuntu-24.04.sh
- plank-station-new/deploy/plank-station-new-agent.service
- admin-main-linux-newnet/package.json
- admin-main-linux-newnet/backend/app/new_network.py
- admin-main-linux-newnet/deploy/install-linux-newnet.sh
- admin-main-linux-newnet/deploy/linux-newnet-api.service
- admin-main-linux-newnet/VERIFICATION_LINUX_NEWNET_FA.md


---

# مشاهده‌گرها و نسخه LIB Observer

تفاوت نقش مشاهده‌گر سازمانی، نود مشاهده‌گر و Station Remote و اطلاعات لازم برای عضویت.

وضعیت: نیازمند پیکربندی | مخاطب: نهادهای نظارتی، کتابخانه و حسابرسان
بازبینی مستندات: ۲۰۲۶/۰۹/۲۴ · ۲ مهر ۱۴۰۵

## LIB Observer چه چیزی از پیش دارد؟

نسخه LIB Observer شاخه‌ای از Station New با هویت نمایشی اولیه و نقش درخواستی NODE_OBSERVER است. نام سازمانی و نوع مشاهده‌گر برای ساده‌ترشدن راه‌اندازی فرم آماده‌اند؛ این پیش‌تنظیم‌ها مجوز شبکه یا رسید عضویت نیستند.

در راهنمای Edition، وضعیت اولیه عضویت NOT_REQUESTED است. Network ID، شناسه رسمی سازمان، کلید عمومی مرجع، کد عضویت و رسید امضاشده باید بعداً از مرجع مجاز دریافت شوند. نشانی نمونه در مستند یا تصویر نباید به‌عنوان سرویس واقعی استفاده شود.

## سه معنای متفاوت مشاهده‌گر

Station سازمانی مشاهده‌گر یک هویت و نقش کاری است. Observer Node منبعی است که داده زنجیره را همگام و مشاهده می‌کند، ولی عضو رأی‌دهنده QBFT نیست. Remote Station برنامه‌ای است که اطلاعات مجاز را از درگاه سرور می‌خواند و خودش دفترکل را همگام نمی‌کند.

هیچ‌یک از این عنوان‌ها به‌تنهایی نشانه اعتبارسنج‌بودن نیست. برای تشخیص اختیار باید نقش تأییدشده، نوع منبع متصل و عضویت canonical به‌صورت جدا بررسی شوند.

| مدل | دفترکل محلی | رأی اجماع |
| --- | --- | --- |
| Station سازمانی | الزامی نیست | از نقش مشاهده‌گر حاصل نمی‌شود |
| Observer Node | وابسته به منبع Besu متصل | ندارد |
| Station Remote | دفترکل کامل روی کلاینت ندارد | عملیات رأی در درگاه ندارد |

## فعال‌سازی بدون نود اجباری

LIB Observer نیز از همان رسید عضویت امضاشده Station استفاده می‌کند. تطبیق درخواست، سازمان، شبکه، نقش‌ها و شماره توالی لازم است. راهنما تأکید می‌کند Node، Validator و Signer پیش‌شرط فعال‌شدن عضویت این Edition نیستند.

نیاز به امضا در یک وظیفه مشخص موضوع جداگانه‌ای است. فعال‌بودن عضویت مشاهده‌گر اجازه ساخت امضای سازمان دیگر، کنترل نود نامرتبط یا استفاده از کلید اجماع را ایجاد نمی‌کند.

## گزارش سلامت و دید شبکه

Station فهرست وضعیت مرکزی را با قرارداد عمومی محدود می‌خواند: شناسه ایستگاه، نقش، نوع منبع، زمان گزارش و خلاصه کنترل‌ها. فیلدهای خارج از قرارداد کنار گذاشته می‌شوند و قدیمی‌بودن گزارش روی سطح اطمینان نمایش اثر دارد.

وقتی فقط Head و عضویت canonical قابل خواندن‌اند، وضعیت همه ایستگاه‌ها «سالم» فرض نمی‌شود. حالت‌های دید کامل، دید قدیمی، فقط عضویت، فقط محلی و ناموجود از یکدیگر متمایز هستند.

## معیار پذیرش نسخه مشاهده‌گر

آزمون پذیرش باید هویت خالی یا اولیه، رد رسید نامعتبر، محدودبودن نقش، انقضای داده و عدم دسترسی به منابع دیگر را پوشش دهد. ثبت نقش در سورس یا فرم، موفقیت عضویت در شبکه تولیدی را اثبات نمی‌کند.

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

## مراجع پیاده‌سازی

- plank-station-lib-observer-new/LIB_OBSERVER_EDITION_FA.md
- plank-station-lib-observer-new/package.json
- plank-station-lib-observer-new/agent/app.py
- plank-station-lib-observer-new/deploy/plank-station-lib-observer-new-agent.service
- plank-station-mac-remote/server/gateway.py


---

# بهره‌برداری، پشتیبان‌گیری و بازیابی

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

وضعیت: نیازمند پیکربندی | مخاطب: مدیر زیرساخت و مسئول تداوم خدمت
بازبینی مستندات: ۲۰۲۶/۰۹/۲۴ · ۲ مهر ۱۴۰۵

## سلامت را چندبعدی بخوانید

پایش باید فرایند، RPC، ارتباط همتا، sync، هویت شبکه، مجموعه اعضا و مشارکت بلاک را جدا نشان دهد. پاسخ health مربوط به برنامه با سلامت اجماع یکسان نیست؛ همچنین زمان آخرین گزارش برای تفسیر هر وضعیت لازم است.

در Station، گزارش مرکزی قدیمی به وضعیت نامشخص یا محدودیت دید تبدیل می‌شود. نبود گزارش سایر ایستگاه‌ها به‌تنهایی به معنی قطع نود محلی نیست. در شبکه چندمنبعی، هش بلاک‌ها در ارتفاع مشترک مقایسه می‌شود تا تفاوت ارتفاع با تفاوت شاخه اشتباه نشود.

## قطع فرایند و پیگیری عملیات

Admin Main کارهای طولانی Validator را در فایل پایدار عملیات ثبت می‌کند. شناسه پردازه مالک، زمان به‌روزرسانی و وضعیت قطع‌شده کمک می‌کنند پس از restart یک کار یتیم به‌اشتباه فعال نمایش داده نشود.

برای ادامه، ابتدا نتیجه canonical و مرحله واقعی کار بررسی شود. درخواست تکراری نباید باعث نصب اعتبارسنج دوم، بازتولید کلید یا اجرای موازی رأی شود. این رفتار در محدوده قفل و idempotency کد پیاده شده است؛ جای برنامه بازیابی کل میزبان را نمی‌گیرد.

## چه داده‌ای باید حفاظت شود؟

دامنه پشتیبان شامل هویت شبکه و Genesis، داده زنجیره لازم برای نقش نود، کلیدها در محل مصوب، خزانه رمز‌شده و اطلاعات بازیابی آن، رجیستری‌ها، تنظیم سرویس و داده Station است. این موارد را نباید در یک آرشیو عمومی سورس قرار داد.

SQLite فعال ممکن است فایل‌های WAL داشته باشد؛ کپی ساده یک فایل در زمان نوشتن، تضمین نسخه سازگار نیست. روش snapshot یا توقف کنترل‌شده باید در برنامه پشتیبان همان محیط تعریف شود. نگهداری کلید و رمز بازیابی نیز باید از نسخه داده عادی تفکیک شود.

> این بخش برنامه عملیاتی پیشنهادی است: در بررسی سورس، سرویس جامع پشتیبان‌گیری زمان‌بندی‌شده با آزمون restore انتهابه‌انتها تأیید نشده است. نمایش اطلاعات خزانه پس از رمز یا حفظ فایل هنگام خطای start، معادل چنین سرویسی نیست.

## بازیابی با حفظ هویت

شاخه Linux New Network مانع بازتولید Genesis و کلید در یک نصب موجود می‌شود و فایل‌های آماده‌شده را پس از شکست start حفظ می‌کند. برای شبکه قبلی، بازیابی باید همان هویت تأییدشده را حفظ کند؛ ساخت شبکه تازه با نام مشابه، بازیابی شبکه قبلی نیست.

پس از restore، تطبیق Chain ID و Genesis، ارتفاع و هش بلاک، مجموعه Validator، مالکیت داده و اتصال امضاکننده باید بررسی شوند. نبود این کنترل‌ها می‌تواند یک سرویس ظاهراً روشن را به منبع داده اشتباه تبدیل کند.

## به‌روزرسانی و برگشت نسخه

در بسته تاریخی Station، updater مبتنی بر Git برای Linux وجود دارد که تغییرات checkout را نگه می‌دارد، نسخه جدید می‌گیرد و نصاب را اجرا می‌کند. این مسیر یک سامانه به‌روزرسانی امضاشده سراسری برای Windows، macOS و Linux نیست؛ حفظ تغییرات Git نیز پشتیبان دیتابیس و کلید محسوب نمی‌شود.

پیش از ارتقا، نسخه برنامه، ساختار داده، نسخه قرارداد و روش بازگشت باید ثبت شوند. بسته جدید نباید runtime قدیمی را بی‌بررسی جایگزین کند. انتشار Remote macOS هنوز امضای ناشر و notarization عمومی ندارد و نباید کانال به‌روزرسانی تأییدشده برای آن فرض کرد.

## معیار پایان تحویل عملیاتی

پذیرش باید نصب پاک، شروع و توقف کنترل‌شده، بازیابی نسخه پشتیبان، قطع منبع RPC، انقضای دسترسی، ورود سازمان و خطاهای امضاکننده را در محیط مجاز پوشش دهد. برای شبکه، پیشروی واقعی بلاک و هماهنگی منابع باید شاهد داشته باشد.

گزارش Linux New Network صریحاً آزمون بار، نفوذ و بازیابی را در کارهای باقی‌مانده آورده است. زمان بازیابی، میزان داده قابل ازدست‌رفتن و تعهد دسترس‌پذیری در این سورس‌ها به‌عنوان SLA عمومی تأیید نشده‌اند.

## مراجع پیاده‌سازی

- admin-main-new/backend/app/services/operation_store.py
- admin-main-new/backend/app/services/validator_diagnostics_service.py
- admin-main-new/backend/app/services/security_service.py
- admin-main-linux-newnet/backend/app/new_network.py
- admin-main-linux-newnet/VERIFICATION_LINUX_NEWNET_FA.md
- plank-station-new/agent/app.py
- Plank-Station-Linux-v1.0.0/deploy/update-ubuntu-24.04.sh


---

# تاریخچه نسخه‌ها و سطح آمادگی

نقشه نسخه‌های بررسی‌شده؛ منبع تاریخی، شاخه تولید، بسته محلی و کارهای تأییدنشده.

وضعیت: مرجع | مخاطب: تیم محصول، توسعه‌دهنده و مسئول انتشار
بازبینی مستندات: ۲۰۲۶/۰۹/۲۴ · ۲ مهر ۱۴۰۵

## نسخه‌های موجود در منابع

نام پوشه تاریخی یا زمان ایجاد آن به‌تنهایی نسخه برنامه نیست. شماره package، نقطه ورود، provenance و گزارش همان انتشار با هم خوانده شده‌اند. شاخه‌های مستقل نیز صرفاً به دلیل جدیدتر بودن تاریخ، جایگزین کامل یکدیگر نیستند.

| خانواده | نسخه درج‌شده در سورس | نقش |
| --- | --- | --- |
| plank-besu-active | 0.18.6 | مرجع تاریخی کنترل‌گر شبکه و قرارداد |
| Admin Main New | 0.18.7-production.2 | لایه تولید و تشخیص canonical |
| Station بسته‌های macOS/Windows/Linux | 1.0.0 | توزیع سورس و launcher چندسکویی |
| Station New و LIB Observer | 1.2.0-production.1 | عامل سازمانی با محافظ تولید |
| Station Remote macOS | 1.3.0 | کلاینت بومی خواندنی؛ شاخه مستقل |
| Admin Main Linux New Network | 0.18.7-linux-newnet.1 | شبکه تازه و هویت نصب مستقل |

## شواهد ساخت، به تفکیک نسخه

گزارش Admin Main New پایه از ۱۴۴ آزمون و یادداشت production.2 از ۱۴۸ آزمون موفق نام می‌برند. Station New گزارش ۴۲ آزمون دارد. Remote گزارش ۱۸ آزمون درگاه و ساخت Universal دارد. گزارش Linux New Network در ۱۴ سپتامبر ۲۰۲۶، ۱۸۲ آزمون و ساخت قراردادها را ثبت کرده است.

این اعداد از گزارش‌های همان پروژه نقل شده‌اند و شمارش آزمون‌های دوباره‌اجراشده در این مستندسازی نیستند. دامنه آزمون‌ها نیز یکسان نیست: آزمون mock، EVM حافظه‌ای، ساخت frontend و اتصال زنده شبکه سطح‌های متفاوتی از شواهد هستند.

## تغییرهای مهم در معماری

در مسیر Admin Main، تأکید از نمایش صرف وضعیت به تفکیک سلامت RPC، sync، عضویت و مشارکت رفته است. مقایسه ارتفاع مشترک و ثبت کار پایدار برای جلوگیری از موفقیت یا شکست کاذب اضافه شده‌اند.

در Station، عضویت سازمانی از وابستگی اجباری به نود و امضاکننده جدا شده است. Remote یک مسیر خواندنی مستقل با هویت صادرشده سرور دارد. Linux New Network نیز از نصب موجود جدا می‌شود تا ساخت آزمایشی یا تازه، شبکه قبلی را بازنویسی نکند.

## کارهای باز

برای Remote، Developer ID، notarization، آزمون کامل پنجره بومی و SSH/Keychain در نشست عادی و اتصال تولید باقی است. برای Windows، انتشار نصب‌کننده امضاشده و ماتریس سازگاری واقعی در شواهد بررسی‌شده وجود ندارد.

برای Linux New Network، نصب روی سرور هدف، اجرای واقعی تصویر Besu، همگام‌سازی همه نودها، استقرار راه‌دور و آزمون بار و restore در گزارش باز هستند. برای گردش سازمانی نیز اتصال واقعی امضاکنندگان و ثبت انتهابه‌انتهای نتیجه نباید از وجود فرم یا صف وظایف نتیجه گرفته شود.

## چگونه نسخه را درست معرفی کنیم؟

در معرفی فنی، «پیاده‌سازی‌شده» یعنی مسیر در سورس موجود است؛ «بسته‌بندی‌شده» یعنی خروجی مشخص تولید شده؛ «بررسی‌شده» باید نام محیط و آزمون را همراه داشته باشد. عبارت «فعال در تولید» فقط با شواهد همان استقرار قابل استفاده است.

این مستندات نشانی عملیاتی، تعداد فعلی اعتبارسنج، سرمایه یا عرضه واقعی و تضمین دسترس‌پذیری برای شبکه اعلام نمی‌کنند. پیش از تحویل هر نسخه، گزارش عمومی با اطلاعات محرمانه حذف‌شده و نتیجه آزمون پذیرش همان نسخه باید تکمیل شود.

## مراجع پیاده‌سازی

- plank-besu-active/package.json
- admin-main-new/SOURCE_PROVENANCE.md
- admin-main-new/VERIFICATION_NEW_FA.md
- plank-station-new/SOURCE_PROVENANCE.md
- plank-station-new/VERIFICATION_NEW_FA.md
- plank-station-mac-remote/SOURCE_PROVENANCE.md
- plank-station-mac-remote/VERIFICATION_REMOTE_FA.md
- admin-main-linux-newnet/SOURCE_PROVENANCE.md
- admin-main-linux-newnet/VERIFICATION_LINUX_NEWNET_FA.md


---

# مدل امنیت و مرز اعتماد

کنترل دسترسی، نگهداری کلید، ورودی‌ها، ثبت رویداد و الزامات انتشار.

وضعیت: مرجع | مخاطب: توسعه‌دهنده، مدیر و اپراتور
بازبینی مستندات: ۲۰۲۶/۰۹/۲۴ · ۲ مهر ۱۴۰۵

## امنیت در چند مرز مستقل

مرورگر، API، پایگاه داده، ارائه‌دهندهٔ بیرونی و شبکه، مرزهای اعتماد جداگانه‌اند. اعتبارسنجی در فرم برای تجربهٔ کاربر مفید است، اما کنترل مجوز باید در API و پایگاه داده نیز اعمال شود. پاسخ یک سرویس بیرونی نباید بدون تطبیق شناسه، واحد و وضعیت به یک نتیجهٔ مالی قطعی تبدیل شود.

- کلید خصوصی ولیدیتور با کلید API سرویس قیمت یا هویت متفاوت است.
- مجوز مدیر محتوا نباید به عملیات شبکه یا کلیدهای امضا گسترش یابد.
- دادهٔ عمومی دارایی با پروندهٔ هویتی یا بانکی مشتری یکسان نیست.

## نشست و اطلاعات محرمانه

مسیرهای نشست مشتری و مدیریت مستقل‌اند. مدیریت وب بر اساس نقش و احراز هویت دومرحله‌ای محدود می‌شود؛ جزئیات همان پیاده‌سازی در راهنمای مدیریت آمده است. کلید ارائه‌دهنده باید سمت سرور و در مسیر ذخیره‌سازی محرمانهٔ مربوط نگهداری شود؛ دریافت کلید از پنل، مجوز نمایش آن به کاربران عمومی نیست.

- مقادیر کلید، کوکی نشست، کد OTP و عبارت بازیابی را در نمونه‌کد، URL، خروجی خطا و گزارش عمومی قرار ندهید.
- در جابه‌جایی یا تعویض کلید، دسترسی قبلی و وضعیت وابستگی‌ها را بررسی کنید.
- کلیدهای مدیریتی سرور نباید با پیشوندهای مخصوص متغیر عمومی مرورگر منتشر شوند.

## مجوز داده و فایل

قواعد RLS، توابع پایگاه داده و کنترل مالکیت فایل برای تفکیک دادهٔ کاربر و مدیر در پروژه وجود دارند. نام جدول، مسیر فایل یا پنهان بودن دکمه مجوز محسوب نمی‌شود. برای اسناد خصوصی، زمان و دامنهٔ دسترسی باید محدود بماند و بررسی مجوز در هر درخواست انجام شود.

پذیرش تصویر و مدارک باید نوع فایل، اندازه و مالکیت پرونده را کنترل کند. موفقیت بارگذاری، نتیجهٔ تأیید هویت یا تأیید حقوقی دارایی نیست.

## درستی عملیات مالی

مرور قیمت و محاسبهٔ تعداد، عملیات مالی قطعی نیست. چرخهٔ سفارش واقعی به بازخوانی قیمت، کارمزد و موجودی سمت سرور، جلوگیری از تکرار، ثبت دفترکل، رسید و تطبیق نهایی نیاز دارد. تا زمانی که این مسیر برای یک محصول فعال نشده است، رابط نباید موفقیت خرید یا برداشت را القا کند.

> کنترل‌های مرحلهٔ عملیاتی: ارزیابی مستقل امنیت، آزمون نفوذ، بازیابی بحران، کنترل سوءاستفاده و بررسی چرخهٔ تسویه باید برای نسخهٔ عملیاتی برنامه‌ریزی و نتیجهٔ قابل بررسی آن ثبت شود. این مستندات ادعای تکمیل عمومی همهٔ آن‌ها را ندارد.

## امنیت نود و بستهٔ نرم‌افزار

دسترسی RPC مدیریتی، فرمان‌های چرخهٔ نود، نسخهٔ genesis و نقش ولیدیتور باید متناسب با محیط کنترل شوند. راهنمای شبکه جزئیات واقعی محصولات را پوشش می‌دهد. داشتن برنامهٔ دسکتاپ یا فایل نصبی به‌تنهایی اثبات امضای رسمی یا ایمن بودن استقرار اینترنتی نیست.

- [مستندات شبکه](/docs/network-overview)
- [حریم خصوصی](/docs/privacy)

## مراجع پیاده‌سازی

- planck-admin/MFA_SETUP.md
- planck-marketplace/lib/auth-cookies.ts
- planck-marketplace/IDENTITY_VERIFICATION.md
- planck-marketplace/PUBLIC_WALLETS.md


---

# حریم خصوصی و مدیریت داده

چه داده‌ای عمومی است، چه داده‌ای خصوصی است و چگونه باید از آن استفاده شود.

وضعیت: مرجع | مخاطب: کاربر، مدیر و تیم امنیت
بازبینی مستندات: ۲۰۲۶/۰۹/۲۴ · ۲ مهر ۱۴۰۵

## طبقه‌بندی داده

| دسته | نمونه | اصل دسترسی |
| --- | --- | --- |
| عمومی | عنوان دارایی منتشرشده، نماد، اسناد عمومی و قیمت | قابل نمایش در بازار با وضعیت روشن |
| حساب | مشخصات پروفایل، ترجیحات و آدرس‌های متصل | همان کاربر و مسیرهای مجاز |
| حساس | مدارک هویت، اطلاعات بانکی و نتیجهٔ استعلام | محدود به نقش و نیاز عملیاتی |
| محرمانهٔ فنی | کلید سرویس، نشست، کلید امضا و عبارت بازیابی | عدم انتشار؛ ذخیره و دسترسی اختصاصی |

## لینک ویترین چه چیزی را منتشر می‌کند؟

نام، توضیح، رنگ و شناسهٔ دارایی‌های انتخابی داخل لینک ویترین قرار می‌گیرند. هر کسی که لینک را داشته باشد می‌تواند این اطلاعات عمومی را باز کند. متن خصوصی، شماره حساب یا اطلاعات شناسایی را در نام و توضیح ویترین ننویسید. این لینک پروندهٔ حساب یا دارایی‌های خصوصی کیف پول را منتقل نمی‌کند.

## ارسال به ارائه‌دهندهٔ خدمات

قیمت‌گیری عمومی با استعلام هویت یا مالکیت حساب بانکی از نظر حساسیت یکسان نیست. درخواست هویت باید از مسیر همان خدمت، برای هدف مشخص و با حداقل دادهٔ لازم انجام شود. درج کلید ارائه‌دهنده در پنل، مجوز ارسال نامحدود اطلاعات مشتری نیست.

## چرخهٔ نگهداری و حذف

سیاست مدت نگهداری، حذف مدارک، پاسخ به درخواست دسترسی و نگهداری گزارش حسابرسی باید پیش از ارائهٔ عملیاتی هر خدمت مشخص شود. وجود قابلیت ویرایش پروفایل به معنی پیاده‌سازی کامل حذف حساب یا حذف سوابق قانونی نیست. این صفحه شرح فنی و الزامات طراحی است و جای متن نهایی سیاست حریم خصوصی منتشرشدهٔ سرویس را نمی‌گیرد.

> تکمیل سیاست عملیاتی: زمان‌های نگهداری، دامنهٔ دسترسی پشتیبانی، فرایند حذف و فهرست پردازشگران باید با شرایط واقعی خدمات نهایی و منتشر شوند.

## حدود همین مستندات

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

## مراجع پیاده‌سازی

- planck-marketplace/lib/storefront.ts
- planck-marketplace/IDENTITY_VERIFICATION.md
- planck-marketplace/SHABANIC_BANK_INQUIRY.md


---

# ورود و امنیت دسترسی مدیریت

ورود دومرحله‌ای، نقش‌ها، جلسات و اطلاعات حساس پنل.

وضعیت: پیاده‌سازی‌شده | مخاطب: اعضای مدیریت و تیم راه‌اندازی
بازبینی مستندات: ۲۰۲۶/۰۹/۲۴ · ۲ مهر ۱۴۰۵

## آماده‌سازی حساب کارکنان

حساب و عضویت کارکنان باید از مسیر قابل اعتماد راه‌اندازی پایگاه داده تعریف شود. پنل عمومی ایجاد نقش مدیریتی یا افزودن خودکار کارمند ارائه نمی‌کند.

بعد از ورود با ایمیل و رمز، اجازه مدیریت بررسی می‌شود. برای عضو مجاز بدون عامل تأییدشده، راه‌اندازی اپلیکیشن TOTP ارائه می‌شود. ورود با موفقیت مرحله دوم تکمیل می‌شود.

## کد اپلیکیشن تأیید هویت

کد شش‌رقمی با ارقام فارسی یا عربی و فاصله‌گذاری پذیرفته و به قالب مناسب تبدیل می‌شود؛ صفر ابتدای کد حفظ می‌شود.

رابط زمان باقی‌مانده و شروع دوباره را نشان می‌دهد. درخواست بررسی کد هنگام ارسال آن ساخته می‌شود تا زمان راه‌اندازی، بررسی قبلی را منقضی نکند.

کد اشتباه، پایان مهلت، تغییر شبکه، محدودیت تلاش و آماده نبودن سرویس پیام‌های جدا دارند. اطلاعات راه‌اندازی نباید در گزارش عمومی بازنشر شوند.

## جلسه مدیریت

ورود موقت حداکثر پنج دقیقه و جلسه تکمیل‌شده حداکثر ۳۰ دقیقه عمر دارد؛ انقضای نشست سرویس ورود ممکن است آن را کوتاه‌تر کند. پس از پایان نشست ورود مجدد لازم است.

کوکی برای اسکریپت صفحه قابل خواندن نیست، محدود به همان میزبان و دارای SameSite Strict است و روی HTTPS ویژگی Secure دارد. خروج، نشست محلی و کوکی‌های ورود را پایان می‌دهد.

## کنترل نقش و درخواست

API اعتبار کاربر و نقش را دوباره بررسی می‌کند. درخواست تغییردهنده به مبدأ همان پنل نیاز دارد. مسیرهای مالک برای هویت و اتصال‌ها نقش ناشر یا ویراستار را نمی‌پذیرند.

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

## کلید، مدرک و گزارش

کلید اتصال در مخزن امن ذخیره می‌شود و پاسخ تنظیمات فقط حضور و نسخه را نشان می‌دهد. عکس هویتی از فضای خصوصی با کنترل مالک و بدون کش دریافت می‌شود.

رسانه معرفی پروژه فضای عمومی جدا دارد. تغییرات پروژه و محتوا از رویدادهای پایگاه داده قابل پیگیری‌اند.

این مقاله کنترل‌های پیاده‌سازی‌شده را توضیح می‌دهد. بهره‌برداری عمومی به تنظیم درست ورود، پایگاه داده، استقرار و محدودیت درخواست میزبانی نیز وابسته است.

## مراجع پیاده‌سازی

- planck-admin/README.md
- planck-admin/lib/mfa.ts
- planck-admin/lib/server.ts
- planck-admin/lib/identity-server.ts
- planck-admin/lib/identity-files.ts
- planck-admin/app/api/auth/login/route.ts
- planck-admin/app/api/auth/verify/route.ts
- planck-admin/app/api/auth/logout/route.ts
- planck-admin/tests/admin-auth.test.mjs


---

# امنیت شبکه، نشست و کلیدها

تفکیک دامنه‌های کلید، خزانه Admin Main، رسید Station و دسترسی خواندنی Remote؛ همراه حدود واقعی پیاده‌سازی.

وضعیت: پیاده‌سازی‌شده | مخاطب: مدیر امنیت، اپراتور و توسعه‌دهنده یکپارچه‌سازی
بازبینی مستندات: ۲۰۲۶/۰۹/۲۴ · ۲ مهر ۱۴۰۵

## کلیدها کاربرد یکسان ندارند

کلید اجماع نود برای هویت و مشارکت در شبکه، کلید تراکنش برای عملیات کیف پول یا قرارداد، امضاکننده سازمانی برای تصمیم نقش و توکن Station برای دسترسی به برنامه استفاده می‌شوند. جایگزین‌کردن یکی با دیگری مرز اعتماد را از بین می‌برد.

کلید عمومی مرجع عضویت نیز با توکن ورود تفاوت دارد: Station با آن امضای رسید را بررسی می‌کند. فایل‌های محیط، runtime، دیتابیس، پیکربندی درگاه و مسیرهای زیرساخت اطلاعات عمومی مستندات نیستند.

## خزانه و نشست Admin Main

کد امنیت Admin Main رمز اولیه را در راه‌اندازی صریح می‌گیرد، حداقل طول تعیین می‌کند و مشتق‌سازی رمز را با PBKDF2 انجام می‌دهد. کلید اصلی به‌صورت بسته رمز‌شده AES-GCM نگهداری می‌شود و مسیر مهاجرت کلید اصلی قدیمی به نگهداری رمز‌شده وجود دارد.

نشست امنیتی کوتاه‌عمر، امکان دسترسی به امضاکننده خزانه را فراهم می‌کند. بعضی مسیرهای امنیتیِ دارای تأیید رمز عمداً اطلاعات حساس خزانه را برای مدیریت یا بازیابی برمی‌گردانند؛ بنابراین نباید همه پاسخ‌های Admin Main را «عمومی و بدون کلید» فرض کرد. این مسیرها باید صرفاً در محدوده مدیریتی حفاظت‌شده استفاده شوند.

## Station و امضاکننده بیرونی

در Station تولیدی، ایجاد Software Vault ممنوع است. ثبت کیف پول تولیدی بر نشانی عمومی، نقش و مرجع امضاکننده بیرونی تکیه دارد. برای HSM، MPC و Web3Signer، کد مدل تنظیمات و کنترل آمادگی دارد؛ دریافت PIN، share خصوصی یا محتوای کلید TLS به‌عنوان ورودی عادی تنظیمات پیش‌بینی نشده است.

کد تاریخی مهاجرت یا بازیابی خزانه محلی با مسیر پیشنهادی تولید یکسان نیست. همچنین آماده‌بودن تنظیم امضاکننده با انجام امضای واقعی و تأیید تراکنش فرق دارد؛ صف READY_FOR_SIGNATURE باید همین محدودیت را روشن نگه دارد.

## درگاه‌ها و محدودیت دسترسی

Admin Main و Station تولیدی اتصال عامل به loopback، مبدأهای صریح و مسیر HTTPS خارج از loopback را کنترل می‌کنند. نصب‌های Linux از سرویس اختصاصی و reverse proxy استفاده می‌کنند. عضویت در گروه Docker یا helper دارای sudo همچنان اختیار عملیاتی مهمی است و نباید با یک sandbox کامل اشتباه شود.

Remote Gateway فقط دو عمل snapshot و block را می‌پذیرد. نشانی منابع و هویت‌ها سمت سرور تعیین می‌شوند؛ کلاینت نمی‌تواند روش دلخواه RPC یا مسیر فایل دلخواه تزریق کند. توکن اختصاصی به‌صورت هش نگهداری و فعال‌بودن و انقضای آن در درخواست بررسی می‌شود.

## امنیت کلاینت بومی مک

Remote از نشست شبکه موقت بدون cache پایدار، رد redirect و کنترل مبدأ WebKit استفاده می‌کند. محتوای رابط به منابع بسته محدود است و ارتباط شبکه از لایه بومی انجام می‌شود. ذخیره توکن در Keychain اختیاری است و کاربر می‌تواند آن را حذف کند.

بررسی چند RPC فقط سازگاری منابع مورد اعتماد را بیشتر می‌کند؛ این برنامه light client اثبات‌محور نیست. امنیت TLS/SSH، کلید دسترسی و پیکربندی صحیح سرور همچنان بخشی از حد اعتماد آن است.

## آنچه هنوز باید مستقل تأیید شود

وجود کنترل امنیتی در سورس یا آزمون محلی، ممیزی مستقل و تست نفوذ را جایگزین نمی‌کند. گزارش Linux New Network آزمون بار، نفوذ و بازیابی را باز اعلام کرده و گزارش Remote اتصال انتهابه‌انتهای تولید و بخشی از تجربه بومی را تأییدنشده می‌داند.

برای گزارش آسیب‌پذیری، نسخه و سناریوی بازتولید با داده پوشانده‌شده کافی است. کلید، credential، نشانی خصوصی، enode یا خروجی کامل خزانه را در مستند عمومی، issue یا تصویر صفحه منتشر نکنید.

## مراجع پیاده‌سازی

- admin-main-new/backend/app/services/security_service.py
- admin-main-new/backend/app/production.py
- plank-station-new/agent/app.py
- plank-station-new/SECURITY.md
- plank-station-mac-remote/macos/Station.swift
- plank-station-mac-remote/server/gateway.py
- admin-main-linux-newnet/VERIFICATION_LINUX_NEWNET_FA.md


---

# راهنمای یکپارچهٔ API

مسیرها، مدل دسترسی، واحدها، پاسخ خطا و تفاوت سرویس وب و شبکه.

وضعیت: مرجع | مخاطب: توسعه‌دهنده و یکپارچه‌ساز
بازبینی مستندات: ۲۰۲۶/۰۹/۲۴ · ۲ مهر ۱۴۰۵

## چهار خانوادهٔ API

| خانواده | مبدأ | کاربرد |
| --- | --- | --- |
| عمومی بازار | مبدأ مارکت‌پلیس | کاتالوگ و دادهٔ بازار |
| مشتری | مبدأ مارکت‌پلیس با نشست مشتری | حساب، هویت، بانک و اتصال کیف پول |
| مدیریت | مبدأ مستقل مدیریت با نشست و نقش مدیر | کاتالوگ، اتصال‌ها، محتوا و بررسی‌ها |
| شبکه | سرویس محلی یا دروازهٔ مجاز همان محصول | پایش و عملیات Admin Main / Station / Besu |

## قرارداد هر مسیر را جدا بخوانید

الگوی احراز هویت همهٔ مسیرها یکسان نیست. مسیرهای وب ممکن است نشست مبتنی بر کوکی داشته باشند؛ یک API شبکه یا ارائه‌دهندهٔ بیرونی قرارداد دیگری دارد. کلید Wallex یا Ondo را به‌عنوان رمز ورود پلانک به API مشتری ارسال نکنید. جدول هر صفحه، روش HTTP، مسیر، دسترسی و رفتار واقعی آن مسیر را مشخص می‌کند.

پاسخ HTTP موفق به‌تنهایی نشان‌دهندهٔ کامل بودن همهٔ داده‌ها نیست؛ mode، پرچم دسترس‌پذیری داده، timestamp و خطای جزئی همان پاسخ نیز اهمیت دارند. برای مثال خالی بودن تاریخچهٔ بازار می‌تواند همراه با پاسخ موفق اطلاعات اصلی بازار باشد.

## نمونهٔ خواندن کاتالوگ عمومی

این نمونه فقط دادهٔ عمومی را می‌خواند و سفارش، پرداخت یا تغییر حساب ایجاد نمی‌کند. فیلدهای دقیق مدل در مرجع API مارکت‌پلیس توضیح داده شده‌اند.

```javascript
const response = await fetch("/api/catalog");
const catalog = await response.json();
if (!response.ok || catalog.mode === "unavailable") {
  throw new Error("Catalog is unavailable");
}
console.log(catalog.mode, catalog.projects);
```

## عدد، زمان و ارز

- عدد فارسی و جداکنندهٔ هزارگان مربوط به نمایش کاربر است؛ در JSON طبق قرارداد همان مسیر داده را ارسال کنید.
- تومان و ریال را بدون تبدیل صریح جایگزین نکنید؛ مقدار پایهٔ کاتالوگ در ریال نگهداری می‌شود.
- برای مقدار دقیق مالی و تعداد توکن، از تبدیل بی‌ضابطه به اعشار شناور خودداری کنید.
- زمان آخرین دریافت قیمت و در دسترس بودن داده را جدا از مقدار قیمت نمایش دهید.
- برای قیمت دلاری، نرخ تبدیل و واحد نهایی را همراه عدد گزارش کنید.

## مدیریت خطا و تکرار درخواست

کدهای ۴۰۰ برای ورودی نامعتبر، ۴۰۱/۴۰۳ برای دسترسی و ۵۰۳ برای سرویس ناموجود یا فعال‌نشده در مسیرهای مختلف به کار می‌روند؛ پاسخ دقیق هر مسیر مرجع نهایی است. هر خطا را به پیام روشن برای کاربر تبدیل کنید و جزئیات محرمانهٔ پاسخ ارائه‌دهنده را نمایش ندهید.

بازآزمایی خودکار عملیات نوشتن بدون دانستن نتیجهٔ قبلی، می‌تواند اثر تکراری بسازد. از بازآزمایی کنترل‌شدهٔ درخواست خواندن استفاده کنید و عملیات مالی آینده را به کلید یکتایی و پیگیری وضعیت وابسته کنید.

> نسخه‌بندی: مسیرهای وب فعلی عمدتاً بدون پیشوند نسخه ارائه شده‌اند. این مستندات قرارداد ثابت یک API عمومی دارای SLA یا مجوز دسترسی تجاری ایجاد نمی‌کند.

## مراجع قراردادها

- [API مارکت‌پلیس](/docs/api-marketplace)
- [API مشتری](/docs/api-customer)
- [API مدیریت](/docs/api-admin)
- [API شبکه](/docs/network-api)

## مراجع پیاده‌سازی

- planck-marketplace/app/api/catalog/route.ts
- planck-marketplace/app/api/quote/route.ts
- planck-marketplace/lib/trade.ts


---

# API کاتالوگ، بازار و راهنما

قرارداد واقعی مسیرهای عمومی و رفتار خطا بدون نیاز به کلید کاربر.

وضعیت: پیاده‌سازی‌شده | مخاطب: توسعه‌دهندگان
بازبینی مستندات: ۲۰۲۶/۰۹/۲۴ · ۲ مهر ۱۴۰۵

## قواعد مشترک

این‌ها مسیرهای برنامهٔ مارکت‌پلیس‌اند، نه یک API معاملهٔ عمومی دارای کلید توسعه‌دهنده. پاسخ‌های JSON از کمک‌تابع مشترک با Cache-Control:no-store و X-Content-Type-Options:nosniff تولید می‌شوند.

مقادیر دهدهی قیمت و حجم بازار رشته‌اند تا دقت آن‌ها حفظ شود. GETهای جدول زیر ورود نمی‌خواهند؛ POSTهای راهنما و برآورد، کنترل Origin هم‌مبدأ دارند.

## مسیرها و وضعیت HTTP

| روش و مسیر | ورودی / دسترسی | موفقیت و خطا |
| --- | --- | --- |
| GET /api/catalog | عمومی؛ بدون پارامتر پیش‌نمایش | 200 با Catalog؛ حتی هنگام ناموجود بودن، mode=unavailable در بدنه است. |
| GET /api/markets/wallex | عمومی؛ بدون symbol | 200 در status=ready؛ 503 در unavailable. |
| GET /api/markets/wallex?symbol=USDTTMN | عمومی؛ یکی از پنج نماد مجاز | 400 برای نماد نامعتبر؛ جزئیات معتبر 200 و پرچم‌های وجود داده. |
| GET /api/markets/exchange-rate | عمومی؛ سیاست روی سرور خوانده می‌شود | 200 برای ready؛ 503 برای unavailable. |
| POST /api/quote | Origin هم‌مبدأ؛ سفارش قابل اجرا ندارد | 403 برای Origin نامعتبر؛ در غیر این صورت همیشه 503. |
| POST /api/assistant | بدنهٔ JSON {message}؛ در حالت AI نشست لازم است | 200 با reply/mode؛ 400 پیام نامعتبر، 401 نیاز به ورود، 403 Origin و 503 اختلال. |

## قرارداد کاتالوگ

بدنه شامل projects، content و mode است. mode یکی از live، preview یا unavailable است. Project فیلدهای id، slug، category، status، عنوان‌ها و توضیح‌های محلی، symbol، image_url، unit_price_rial، duration_months، total_units، sold_units، documents و شاخص نمونهٔ اختیاری دارد.

Content شامل معرفی هیرو، FAQ، فوتر، عنوان منوها، نشانی اختیاری اپلیکیشن و پذیرش توکنایزیشن، نشان تجاری و enabled_locales است. دادهٔ شخصی مشتری جزو این قرارداد نیست.

```javascript
const response = await fetch('/api/catalog');
const catalog = await response.json();
if (catalog.mode === 'unavailable') {
  console.log('فهرست اکنون در دسترس نیست');
} else {
  console.log(catalog.projects.map(({slug, symbol}) => ({slug, symbol})));
}
```

## قرارداد مظنه و جزئیات

Feed شامل source:wallex، status، quotes، receivedAt و در خطا error است. هر Quote شامل symbol، base، name، price، change24h، volume24h، quoteVolume24h، high24h، low24h، amountPrecision، pricePrecision، spot، otc و receivedAt است؛ چند فیلد عددی می‌توانند null باشند.

جزئیات شامل symbol، receivedAt، candles با time/close، asks و bids با price/quantity، historyAvailable و depthAvailable است. خطای منبع نمودار یا عمق، لزوماً HTTP503 نمی‌دهد؛ برنامه می‌تواند HTTP200 با پرچم false و آرایهٔ خالی دریافت کند. دادهٔ ناموجود را از همین پرچم‌ها تشخیص دهید.

## قرارداد نرخ مرجع

پاسخ آماده شامل status:ready، base:USDT، quote:IRR، rateRial، rateToman، receivedAt و expiresAt است. پاسخ ناموجود شامل status:unavailable، همان base/quote و error است.

سیاست پیش‌فرض single با والکس است. آداپتورهای فعلی والکس و نوبیتکس‌اند؛ میانگین، میانگین حسابی هم‌وزن منابع انتخابی و وابسته به تازگی همهٔ آن‌هاست. نرخ نهایی به نزدیک‌ترین ریال گرد می‌شود.

```javascript
const response = await fetch('/api/markets/exchange-rate');
const rate = await response.json();
if (response.ok && rate.status === 'ready') {
  console.log(rate.rateToman, rate.expiresAt);
}
// بدون دادهٔ معتبر، نرخ جایگزین نسازید.
```

## پیش‌نمایش و نبود مسیر سفارش

پارامتر preview=design فقط در صفحات و محیط توسعه برای کاتالوگ نمونه کاربرد دارد و /api/catalog را به دادهٔ نمونهٔ اجباری تبدیل نمی‌کند. شکست خواندن کاتالوگ متصل با نمونه جبران نمی‌شود.

POST /api/quote هیچ قرارداد اجرایی مقدار/قیمت یا سفارش نهایی ندارد. تا زمان پیاده‌سازی سرویس معامله، 503 پاسخ مورد انتظار این مسیر است؛ نباید با retry نامحدود آن را به سفارش واقعی تبدیل کرد.

## مراجع پیاده‌سازی

- app/api/catalog/route.ts
- app/api/markets/wallex/route.ts
- app/api/markets/exchange-rate/route.ts
- app/api/quote/route.ts
- app/api/assistant/route.ts
- lib/server.ts
- lib/wallex.ts
- lib/exchange-rate.ts


---

# API نشست و داشبورد مشتری

روش‌ها، بدنه‌ها و محدودیت‌های مسیرهای خصوصی حساب.

وضعیت: نیازمند پیکربندی | مخاطب: توسعه‌دهندگان
بازبینی مستندات: ۲۰۲۶/۰۹/۲۴ · ۲ مهر ۱۴۰۵

## نشست و خطاهای مشترک

مسیرهای خصوصی از کوکی HttpOnly نشست مشتری استفاده می‌کنند؛ شناسهٔ کاربر ارسالی در بدنه جای نشست معتبر را نمی‌گیرد. مسیرهای authBody به Origin هم‌مبدأ، Content-Type شامل application/json، تنظیم بودن سرویس و بدنهٔ شیء حداکثر ۱۶٬۰۰۰ بایت نیاز دارند.

خطای اعتبارسنجی معمولاً 400، نیاز به ورود 401، Origin نامعتبر 403، نوع محتوا 415، محدودیت سرویس ورود 429 و نبود اتصال 503 است. خطاهای AuthError با بدنهٔ {error:string} برمی‌گردند. بعضی GETهای خصوصی نیز Sec-Fetch-Site:cross-site را رد می‌کنند.

## ورود و ثبت‌نام

| روش و مسیر | بدنه یا رفتار | پاسخ موفق |
| --- | --- | --- |
| GET /api/auth/session | بدون بدنه؛ بررسی و در صورت امکان تازه‌سازی نشست | {user} یا {user:null}؛ نبود نشست معتبر لزوماً 401 نیست. |
| POST /api/auth/login | identifier یا email، password، remember اختیاری | {user,notice?} و کوکی نشست |
| POST /api/auth/register | firstName، lastName، phone، email، password؛ username و referralCode اختیاری | {phone,step:verify}؛ ثبت‌نام باید به تأیید موبایل برسد. |
| POST /api/auth/otp | action=send\|resend\|verify، phone؛ verify با code؛ intent و remember اختیاری | ارسال: {phone,step:verify}؛ تأیید: نشست یا {step:reset} برای بازیابی |
| POST /api/auth/email | email؛ نیازمند نشست | {message} برای درخواست تأیید ایمیل |
| POST /api/auth/logout | Origin هم‌مبدأ؛ پاک‌کردن نشست حتی در اختلال سرویس بالادست | {ok:true} |

## بازیابی رمز

POST /api/auth/recovery با action=request و email، بازیابی PKCE را آغاز می‌کند؛ پاسخ عمومی وجود حساب را افشا نمی‌کند. بازگشت GET /auth/recovery?code=… پس از بررسی verifier با HTTP303 به صفحهٔ تنظیم رمز یا خطای بازیابی می‌رود.

action=reset و password به کوکی بازیابی معتبر نیاز دارد. رمز جدید ۱۲ تا ۲۵۶ نویسه است؛ پس از موفقیت، دسترسی بازیابی و نشست محلی پاک می‌شوند. نبود یا انقضای دسترسی بازیابی 401 می‌دهد. مقادیر کوکی و توکن در مثال مستندات قرار نمی‌گیرند.

## خواندن و ویرایش داشبورد

GET /api/dashboard وضعیت خصوصی حساب، preferences، banks، notifications، unread_count، alerts، referral_codes، referral_stats، api_keys، wallets، positions، transactions، orders، credits، staking و sessions را می‌خواند. مدل کامل در lib/dashboard.ts تعریف شده است.

POST /api/dashboard بدنهٔ {action,payload} می‌گیرد. پاسخ معمول ویرایش {ok:true} است؛ حساب بانکی قرارداد نتیجهٔ جداگانه دارد. عملیات مالی مانند تغییر موجودی، خرید، برداشت یا ایجاد اعتبار جزو actionهای مجاز نیستند.

| action | payload مجاز |
| --- | --- |
| profile | first_name، last_name، birth_date اختیاری و national_id در صورت مجازبودن |
| preferences | پرچم‌های نمایش و اعلان/تأیید، theme=dark\|light، locale=fa\|en\|ar، currency=TMN\|USDT |
| alert_add | project_id از نوع UUID، direction=above\|below، target_price_rial رشتهٔ صحیح مثبت ۱ تا ۳۰ رقم |
| bank_remove / bank_primary / alert_remove / api_revoke | id از نوع UUID |
| notification_read | id اختیاری؛ نبود آن برای ثبت خوانده‌شدن مجموعه |
| bank_add | iban، account_title و card_number اختیاری، request_key از نوع UUID و consent=true |

## نتیجهٔ ثبت بانکی و تعارض‌ها

موفقیت bank_add به‌صورت {ok:true,id} است. رد قابل تشخیص می‌تواند {ok:false,code,error} باشد: bank_not_matched با HTTP422، bank_registration_unavailable با 503 و دیگر وضعیت‌های فرایند معمولاً با 409 برمی‌گردند.

نسخهٔ قدیمی پایگاه داده، قفل اطلاعات هویتی، تعارض داده یا سقف حساب و هشدار پاسخ مشخص دارند. در خطای شبکه یا نتیجهٔ نامطمئن، نمایش موفقیت پیش‌فرض مجاز نیست.

## دعوت و شارژ

| روش و مسیر | قرارداد | وضعیت |
| --- | --- | --- |
| GET /api/referrals | program، codes، stats، invitees، rewards برای همان حساب | 200؛ نیاز به نشست، اختلال503 |
| POST /api/referrals | {action:create,label}؛ عنوان حداکثر۶۰ نویسه | نتیجهٔ ایجاد کد؛ سقف۲۰ کد و تماس تأییدشده |
| GET /api/deposits | {enabled:false,provider:null,deposits}؛ تا۱۰۰ سابقهٔ اخیر | 200؛ نیاز به نشست |
| POST /api/deposits | {amountToman}؛ رشتهٔ صحیح مثبت حداکثر۱۲ رقم پس از نرمال‌سازی | 400 مبلغ نامعتبر؛ مبلغ معتبر نیز503 چون درگاه متصل نیست. |

## API خصوصی پروندهٔ دارایی

GET /api/tokenization فهرست پرونده‌های صاحب نشست را می‌خواند. POST همان مسیر با action=start نوع دارایی و پذیرش نسخهٔ شرایط را دریافت می‌کند؛ action=save اطلاعات پیش‌نویس، action=submit تأیید و ارسال پرونده و action=accept شمارهٔ نسخهٔ پیشنهاد و پذیرش صریح آن را ثبت می‌کند. به‌جز شروع، شناسهٔ پرونده و آخرین version برای جلوگیری از تغییر هم‌زمان لازم‌اند.

POST /api/tokenization/documents فایل و شناسهٔ جایگاه مدرک را به‌صورت multipart دریافت می‌کند. GET با id و document فقط پس از مجوز، فایل خصوصی را برمی‌گرداند. DELETE به شناسهٔ پرونده، نسخه و شناسهٔ مدرک نیاز دارد و فقط در وضعیت قابل ویرایش مجاز است.

کنترل صاحب داده، وضعیت و نسخه در سرور و پایگاه داده اعمال می‌شود. یادداشت داخلی کارشناسان در پاسخ مشتری قرار نمی‌گیرد. نبود سرویس یا مهاجرت، خطای عدم دسترسی سرویس می‌دهد؛ هیچ مسیر عمومی برای اعلام موفقیت صدور یا افزودن موجودی وجود ندارد.

- [ثبت و پیگیری توکنایزیشن](/docs/tokenization)

## مراجع پیاده‌سازی

- lib/customer-auth.ts
- lib/auth-cookies.ts
- lib/auth-input.ts
- lib/dashboard.ts
- lib/bank-registration.ts
- app/api/auth/session/route.ts
- app/api/auth/login/route.ts
- app/api/auth/register/route.ts
- app/api/auth/otp/route.ts
- app/api/auth/recovery/route.ts
- app/auth/recovery/route.ts
- app/api/dashboard/route.ts
- app/api/referrals/route.ts
- app/api/deposits/route.ts
- app/api/tokenization/route.ts
- app/api/tokenization/documents/route.ts
- lib/tokenization.ts
- supabase/migrations/202609240001_asset_tokenization.sql


---

# API مدارک، تصویر و اتصال والت

مسیرهای خصوصی فایل و قرارداد چالش امضای آدرس عمومی.

وضعیت: نیازمند پیکربندی | مخاطب: توسعه‌دهندگان
بازبینی مستندات: ۲۰۲۶/۰۹/۲۴ · ۲ مهر ۱۴۰۵

## درخواست احراز

| روش و مسیر | ورودی | خروجی و محدودیت |
| --- | --- | --- |
| GET /api/identity | نشست معتبر؛ بدون بدنه | IdentityState شامل request و checks |
| POST /api/identity | {action:start} | آغاز یا دریافت وضعیت درخواست توسط RPC حساب |
| POST /api/identity | {action:save,id,version,fields} | id معتبر، version صحیح مثبت و فیلدهای اعتبارسنجی‌شده |
| POST /api/identity | {action:submit,id,version,consent:true} | ارسال نهایی با کنترل شواهد و نسخه روی سرور |

## فیلدها و وضعیت‌ها

fields شامل first_name، last_name، national_id، birth_certificate_number، father_name، address و postal_code است. تاریخ تولد در مسیر پروفایل مدیریت می‌شود و نباید به این بدنهٔ احراز افزوده فرض شود.

خطای RPC احراز، در صورت منع دسترسی 403، اختلال بالادست 503 و خطا یا تعارض دیگر 409 می‌دهد. وضعیت‌های پرونده draft، pending، documents_approved، verified، rejected و superseded و وضعیت‌های استعلام not_connected، pending، passed، failed و error هستند.

## بارگذاری و دریافت مدرک

| مسیر | قرارداد |
| --- | --- |
| POST /api/identity/photo | بدنهٔ خام تصویر؛ هدر x-identity-id، هدر x-document-kind با card یا selfie و Content-Type معتبر؛ Origin و نشست بررسی می‌شوند. |
| GET /api/identity/photo?id=…&kind=card | شناسهٔ درخواست و kind=card\|selfie؛ دریافت فایل فقط با مجوز خصوصی. |
| قالب و حجم | JPG، PNG یا WebP تا۵ مگابایت؛ امضای فایل با نوع اعلامی تطبیق داده می‌شود. |
| نتیجه و خطا | POST وضعیت احراز را برمی‌گرداند؛413 برای حجم،415 برای نوع،503 برای اختلال و خطاهای نشست/مجوز مطابق کنترل مشترک. |

## تصویر پروفایل

POST /api/avatar تصویر خام با MIME معتبر و حداکثر ۲ مگابایت می‌گیرد و {ok:true,path} برمی‌گرداند. مسیر فایل به حساب و نام تصادفی وابسته است؛ مرورگر مسیر دلخواه برای بازنویسی فایل تعیین نمی‌کند.

GET /api/avatar یا GET /api/avatar?user=… فقط تصویر خود حساب را می‌خواند. شناسهٔ کاربر دیگر یا نبود تصویر 404، نوع نامعتبر 415 و اختلال ذخیره 503 می‌دهد. پاسخ تصویر private,no-store، nosniff و same-origin است.

## قرارداد اتصال والت

| روش و مسیر | ورودی / خروجی | دسترسی |
| --- | --- | --- |
| GET /api/wallet-connect | {projectId:string\|null}؛ شناسهٔ عمومی معتبر WalletConnect یا null | عمومی |
| POST /api/wallet-connect | {action:challenge,address,chainId,label?}؛ پاسخ {id,message,expires_at} | نشست معتبر، Origin هم‌مبدأ و JSON حداکثر۸۰۰۰ بایت |
| POST /api/wallet-connect | {action:verify,id,signature}؛ نتیجهٔ {wallet} | همان نشست و پیام تک‌استفاده؛ امضای EOA معتبر |
| GET /api/wallets | {wallets:[{network,address,label,verified_at}]} | فقط آدرس‌های حساب واردشده |

## اعتبارسنجی و خطاهای والت

address باید آدرس ۲۰بایتی EVM غیرصفر باشد و chainId عدد صحیح مثبت امن است. امضا در مسیر وب با 0x و ۱۳۰ رقم هگز پذیرفته می‌شود. origin از خود درخواست سرور تعیین می‌شود، نه بدنهٔ دلخواه مرورگر.

کدهای شناخته‌شده شامل wallet_rate_limit، wallet_challenge_expired، wallet_already_linked، wallet_limit، invalid_signature، origin_not_allowed و unauthorized هستند. وضعیت‌های 400،401،403،409 و429 مجاز حفظ می‌شوند و خطای نامشخص سرویس به wallet_unavailable و503 تبدیل می‌شود. این API درخواست امضای پیام است و تراکنش مالی یا تأیید خرج توکن نمی‌سازد.

## مراجع پیاده‌سازی

- app/api/identity/route.ts
- app/api/identity/photo/route.ts
- app/api/avatar/route.ts
- app/api/wallet-connect/route.ts
- app/api/wallets/route.ts
- lib/identity.ts
- lib/identity-server.ts
- lib/identity-files.ts
- lib/profile-photo.ts
- supabase/functions/_shared/wallet-link.ts


---

# مرجع API مدیریت

روش‌ها، ورودی‌ها، پاسخ‌ها و دسترسی مسیرهای اصلی پنل.

وضعیت: مرجع | مخاطب: توسعه‌دهندگان پنل و یکپارچه‌سازی داخلی
بازبینی مستندات: ۲۰۲۶/۰۹/۲۴ · ۲ مهر ۱۴۰۵

## قرارداد مشترک

مسیرها روی مبدأ برنامه مدیریت قرار دارند. پاسخ JSON معمولاً وضعیت ۲۰۰ و هدر جلوگیری از کش دارد؛ خطا با error برمی‌گردد. نوع دسترسی هر مسیر در جدول مشخص شده است.

درخواست تغییردهنده به مبدأ یکسان نیاز دارد. بدنه عمومی JSON سقف ۱۵۰٬۰۰۰ بایت دارد و بعضی مسیرهای حساس سقف کوچک‌تر دارند. قیمت پروژه در قرارداد به ریال است.

## جلسه و ورود

| روش و مسیر | ورودی و خروجی | دسترسی و خطای اصلی |
| --- | --- | --- |
| GET /api/session | {connected, user}؛ user ممکن است null باشد | خواندن وضعیت؛ پاسخ ۲۰۰ |
| POST /api/auth/login | {email,password} → مرحله MFA | همان مبدأ؛ ۴۰۰ ورودی، ۴۰۱ ورود، ۴۰۳ عضویت، ۴۲۹ محدودیت، ۵۰۳ اتصال |
| POST /api/auth/verify | {factorId,code} → {user} و جلسه | ورود موقت؛ ۴۰۰، ۴۰۱، ۴۰۳، ۴۰۹ تغییر شبکه، ۴۲۹، ۵۰۳ |
| POST /api/auth/logout | داده الزامی ندارد → {ok:true} | همان مبدأ؛ پاک کردن کوکی‌های ورود |

## پروژه، محتوا و رسانه

| روش و مسیر | قرارداد | دسترسی و خطای اصلی |
| --- | --- | --- |
| GET /api/projects | {projects} مرتب بر اساس sort_order | عضو؛ ۴۰۱ / ۵۰۲ |
| POST /api/projects | {project} → {project} | عضو؛ ویراستار فقط پیش‌نویس؛ ۴۰۰ / ۴۰۱ / ۴۰۳ / ۴۰۹ |
| PATCH /api/projects | {project,expectedUpdatedAt} → {project} | نسخه الزامی؛ تعارض یا نشانی تکراری ۴۰۹ |
| GET /api/content | {record} یا record:null | عضو؛ ۴۰۱ / ۵۰۲ |
| PUT /api/content | {content,expectedUpdatedAt} → {record} | مالک/ناشر؛ حفظ سیاست نرخ؛ اختلاف نسخه ۴۰۹ |
| POST /api/media | فایل خام با Content-Type معتبر → {url} | عضو؛ ۴۰۰ فرمت، ۴۰۱ / ۴۰۳، ۴۱۳ حجم، ۵۰۲ ذخیره |
| GET /api/audit | {events} | مالک/ناشر؛ نبود مجوز ۴۰۳، دریافت ناموفق ۵۰۲ |

## پرونده و تصاویر هویتی

ثبت بررسی تا ۵٬۰۰۰ و تغییر نوع و مرحله تا ۲٬۰۰۰ بایت می‌پذیرد. نسخه مثبت و یادداشت حداکثر ۱۰۰۰ نویسه است. checks شامل face_visible، card_readable و challenge_match است.

خطاهای عمومی این خانواده ۴۰۰ ورودی، ۴۰۱ جلسه، ۴۰۳ دسترسی، ۴۰۹ تعارض یا شرط پرونده و ۵۰۳ آماده نبودن سرویس است.

| روش و مسیر | قرارداد | دسترسی و اعتبارسنجی |
| --- | --- | --- |
| GET /api/identity | بدون id فهرست؛ ?id=UUID جزئیات | مالک؛ شناسه معتبر |
| POST /api/identity | {id,version,decision,note,checks} | مالک؛ approve/reject؛ سه بررسی مدرک |
| PATCH /api/identity | {id,version,verification_type,review_stage} | مالک؛ identity یا identity_bank؛ مرحله معتبر |
| GET /api/identity/photo | ?id=UUID&kind=card یا selfie → تصویر | مالک؛ بدون کش؛ ۴۰۴ فایل، ۴۱۵ فرمت، ۵۰۳ سرویس |

## برنامه دعوت

مبلغ و درصد رشته عددی هستند تا تبدیل دقیق انجام شود. سابقه معامله یا فرمان پرداخت از این API قابل ارسال نیست. مسیرهای تنظیم اتصال در مقاله API اتصال‌ها آمده‌اند.

| روش و مسیر | قرارداد | دسترسی |
| --- | --- | --- |
| GET /api/referrals | برنامه و آمار دعوت | عضو مدیریت؛ ۴۰۱ / ۵۰۳ |
| PUT /api/referrals | {enabled,inviteRewardToman,tradeSharePercent,version} | مالک و همان مبدأ؛ تا ۴٬۰۰۰ بایت؛ ۴۰۰ / ۴۰۱ / ۴۰۳ / ۴۰۹ |

## مراجع پیاده‌سازی

- planck-admin/app/api/session/route.ts
- planck-admin/app/api/auth/login/route.ts
- planck-admin/app/api/auth/verify/route.ts
- planck-admin/app/api/auth/logout/route.ts
- planck-admin/app/api/projects/route.ts
- planck-admin/app/api/content/route.ts
- planck-admin/app/api/media/route.ts
- planck-admin/app/api/audit/route.ts
- planck-admin/app/api/identity/route.ts
- planck-admin/app/api/identity/photo/route.ts
- planck-admin/app/api/referrals/route.ts
- planck-admin/lib/server.ts


---

# API اتصال‌ها و استعلام‌ها

مسیرهای کلید بازار، سیاست نرخ و اجرای بررسی ارائه‌دهندگان.

وضعیت: مرجع | مخاطب: توسعه‌دهندگان اتصال و مالک فنی
بازبینی مستندات: ۲۰۲۶/۰۹/۲۴ · ۲ مهر ۱۴۰۵

## دسترسی مشترک

تمام مسیرهای این مقاله متعلق به پنل مدیریت و نیازمند نقش مالک‌اند. PUT و POST مبدأ همان پنل را نیز بررسی می‌کنند. دریافت تنظیمات مقدار کلید ذخیره‌شده را بازنمی‌گرداند.

خطاهای پایه شامل ۴۰۰ ورودی، ۴۰۱ جلسه، ۴۰۳ دسترسی، ۴۰۹ تعارض یا شرط اجرایی و ۵۰۳ آماده نبودن اتصال است. نتیجه ارائه‌دهنده با خطای ورود به پنل یکسان نیست.

## تنظیم و اجرای استعلام

شناسه‌ها باید UUID باشند. نوع هویت یا موبایل به اجرای هویتی می‌رود؛ bank_owner و حالت قدیمی بدون kind به اجرای بانکی می‌رود. این مسیر اطلاعات هویتی یا بانکی دلخواه برای جایگزینی پرونده نمی‌پذیرد.

| روش و مسیر | قرارداد | حد و رفتار |
| --- | --- | --- |
| GET /api/inquiries | تنظیمات و services | مالک؛ فهرست برای بازدیدکننده عمومی نیست |
| PUT /api/inquiries | {service_key,label,scope,provider_name,base_url,secret?,version} | حداکثر ۱۶٬۰۰۰ بایت؛ ذخیره نسخه‌دار |
| POST /api/inquiries/run | {inquiry_id,service_id,kind?} | حداکثر ۱٬۰۰۰ بایت؛ identity، mobile_owner یا bank_owner |

## کلیدهای بازار

حد ورودی ۱۲٬۰۰۰ بایت است. ارائه‌دهنده و مقصد در کد مشخص‌اند. بررسی Ondo برای خواندن فهرست است؛ ذخیره کلیدها تماس معاملاتی ایجاد نمی‌کند.

| روش و مسیر | ورودی | خروجی |
| --- | --- | --- |
| GET /api/integrations/wallex | — | {hasKey,version,updatedAt} |
| PUT /api/integrations/wallex | {secret,version} | وضعیت بدون مقدار کلید |
| GET /api/integrations/ondo | — | {hasKey,version,updatedAt} |
| PUT /api/integrations/ondo | {secret,version} | وضعیت بدون مقدار کلید |
| POST /api/integrations/ondo/check | {secret} | {assetCount,checkedAt}؛ بدون ذخیره |

## سیاست نرخ تبدیل

mode فقط single یا average و شناسه‌ها فعلاً wallex و nobitex هستند. single یک گزینه و average حداقل دو گزینه غیرتکراری می‌خواهد. بدون اتصال پایگاه داده، وضعیت ۵۰۳ برمی‌گردد.

| روش و مسیر | قرارداد | قاعده |
| --- | --- | --- |
| GET /api/integrations/exchange-rate | {policy,expectedUpdatedAt,configured} | نبود سیاست: single با wallex |
| PUT /api/integrations/exchange-rate | {policy:{mode,sources},expectedUpdatedAt} | تا ۲٬۰۰۰ بایت؛ نسخه باید برابر رکورد فعلی باشد |

## مقصدهای تعریف‌شده در کد

| اتصال | مقصد | کاربرد |
| --- | --- | --- |
| والکس | https://api.wallex.ir/hector/web/v1/markets | نشانی ثابت داده عمومی در تنظیمات |
| Ondo | GET https://api.gm.ondo.finance/v1/assets/all/metadata | بررسی دسترسی کلید به فهرست |
| ثبت‌احوال شبانیک | https://shabanic.ir/api/v1/nid_inquiry | شناسایی اتصال هویتی |
| شاهکار شبانیک | https://shabanic.ir/api/v2/shahkar | شناسایی اتصال مالکیت موبایل |
| مالکیت شبا شبانیک | https://shabanic.ir/api/v2/matchIbanByNationalcode | شناسایی اتصال بانکی |

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

## مراجع پیاده‌سازی

- planck-admin/app/api/inquiries/route.ts
- planck-admin/app/api/inquiries/run/route.ts
- planck-admin/app/api/integrations/wallex/route.ts
- planck-admin/app/api/integrations/ondo/route.ts
- planck-admin/app/api/integrations/ondo/check/route.ts
- planck-admin/app/api/integrations/exchange-rate/route.ts
- planck-admin/lib/inquiries.ts
- planck-admin/lib/ondo-server.ts
- planck-admin/lib/identity-server.ts


---

# API شبکه و قرارداد ارتباطی Station

لایه‌های JSON-RPC، API کنترل‌گر، عامل Station و درگاه Remote؛ با مثال‌های خواندنی و بدون نشانی عملیاتی.

وضعیت: پیاده‌سازی‌شده | مخاطب: توسعه‌دهندگان یکپارچه‌سازی و اپراتورهای مجاز
بازبینی مستندات: ۲۰۲۶/۰۹/۲۴ · ۲ مهر ۱۴۰۵

## هر API برای یک مخاطب است

API مارکت‌پلیس با API زیرساخت Admin Main، عامل Station و JSON-RPC Besu متفاوت است. این مستند یک endpoint عمومی واحد برای همه آن‌ها معرفی نمی‌کند؛ مبدأ و احراز هویت باید از مدیر همان استقرار دریافت شود.

روش‌های خواندن Besu داده زنجیره را می‌دهند. API کنترل‌گر می‌تواند عملیات مدیریتی داشته باشد. Agent Station دامنه ایستگاه را اعمال می‌کند و Remote Gateway فقط قرارداد خواندنی محدود خود را در اختیار کلاینت می‌گذارد.

## خواندن هویت و وضعیت Besu

روش‌های مورد استفاده در سورس شامل eth_chainId، net_version، eth_blockNumber، eth_getBlockByNumber، eth_syncing، net_peerCount، eth_getBalance و qbft_getValidatorsByBlockNumber هستند. بعضی تشخیص‌های مدیریتی از admin_nodeInfo و روش‌های QBFT استفاده می‌کنند؛ این مجوزها نباید بدون نیاز در RPC عمومی قرار گیرند.

پاسخ eth_syncing=false فقط می‌گوید نود در آن لحظه فرایند sync گزارش نمی‌کند؛ تازگی Head، پیشروی بلاک و هم‌خوانی شاخه هنوز باید بررسی شوند. برای تطبیق شبکه، هش بلاک صفر از داده RPC گرفته می‌شود.

```json
{"jsonrpc":"2.0","id":1,"method":"eth_getBlockByNumber","params":["0x0",false]}
```

## API کنترل‌گر و وضعیت عملیات

Admin Main مسیرهایی مانند /health، /api/production/readiness و /api/state دارد. APIهای شبکه، قرارداد، خزانه و رأی، عملیات داخلی مدیریتی‌اند. در حالت تولید، توکن برنامه و تنظیم درگاه لازم است و بعضی عملیات حساس نشست امنیتی مستقل می‌خواهند.

عملیات طولانی باید از شناسه کار و نتیجه ثبت‌شده پیگیری شوند. موفقیت پاسخ HTTP آغاز عملیات، با نهایی‌شدن عضویت QBFT یا موفقیت تراکنش برابر نیست. تکرار درخواست نیز باید سیاست idempotency همان endpoint را رعایت کند.

## عضویت و منابع Station

عامل Station مسیرهای /api/v1/membership/status، /api/v1/membership/request و /api/v1/membership/activation را برای عضویت دارد. اتصال مرجع، امضاکننده و آمادگی در شاخه /api/v1/production مدیریت می‌شوند. کشف و binding در /api/v1/nodes قرار دارند.

ثبت تصمیم وظیفه از مسیر /api/v1/tasks/{task_id}/decisions انجام می‌شود و شناسه درخواست و نسخه سیاست بخشی از کنترل تکرار و هم‌زمانی‌اند. پاسخ READY_FOR_SIGNATURE را نباید امضای تکمیل‌شده یا tx hash معتبر تلقی کرد.

## قرارداد خواندنی Remote

درگاه Remote بدنه‌ای با action برابر snapshot یا block می‌پذیرد؛ برای block شماره غیرمنفی در محدوده Head لازم است. روش RPC از کلاینت دریافت نمی‌شود. سرور برای هر درخواست توکن، زمان اعتبار، نقش و هویت مجاز را تعیین می‌کند.

پاسخ شامل نسخه قرارداد، زمان تولید، هویت مجاز همان ایستگاه، شبکه، منابع، وضعیت Admin Main، خلاصه نود و بلاک‌های عمومی است. تعداد منابع بین یک تا چهار محدود می‌شود؛ منابع باید Chain ID، Network ID و Genesis یکسان داشته باشند و هش ارتفاع مشترک آن‌ها تطبیق کند.

```json
{"action":"snapshot"}
```

## پیش‌شرط اتصال واقعی

برای یکپارچه‌سازی، محیط، نسخه سرویس، نقش، دامنه دسترسی، سیاست خطا و انقضا باید ثبت شوند. مقدار unknown یا unavailable باید حفظ شود؛ اتصال قطع‌شده نباید با یک پاسخ موفق نمونه پوشانده شود.

درگاه Remote در گزارش انتشار مستقرشده روی تولید معرفی نشده است و مسیر امضای سازمانی Station نیز به سرویس واقعی وابسته است. نمونه‌های این صفحه قرارداد داده را توضیح می‌دهند و هیچ آدرس، credential یا دستور تراکنش واقعی در خود ندارند.

## مراجع پیاده‌سازی

- admin-main-new/backend/app/main.py
- admin-main-new/backend/app/services/rpc_service.py
- plank-station-new/agent/app.py
- plank-station-mac-remote/server/gateway.py
- plank-station-mac-remote/src/remote.ts
- plank-station-mac-remote/VERIFICATION_REMOTE_FA.md


---

# نقشهٔ راه و قابلیت‌های آینده

مراحل بعدی محصول، وابستگی‌ها و معیارهای آمادگی؛ بدون تاریخ انتشار ساختگی.

وضعیت: برنامهٔ آینده | مخاطب: کاربر، مدیر محصول و توسعه‌دهنده
بازبینی مستندات: ۲۰۲۶/۰۹/۲۴ · ۲ مهر ۱۴۰۵

## چگونه برنامهٔ آینده را بخوانیم؟

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

## پذیرش و صدور دارایی

| موضوع | بخش موجود | تکمیل مورد نیاز |
| --- | --- | --- |
| پذیرش صاحب دارایی | معرفی پنج مرحله و راهنمای آماده‌سازی | پروندهٔ قابل پیگیری، بارگذاری امن و گردش تأییدها |
| ارزیابی حقوقی و مالی | ساختار توضیحات و اسناد پروژه | فرایند بررسی متخصص، ثبت نتیجه و اعتبار زمانی |
| توکنومیکس | معرفی تعداد، نوع، شبکه و اقتصاد توکن | مدل قابل ویرایش، تأیید نهایی و اتصال به صدور |
| صدور و عرضه | زیرساخت‌های مستقل بازار و شبکه | قرارداد تأییدشده، ثبت عرضه و اتصال انتهابه‌انتها |
| مدیریت پس از عرضه | مسیر معرفی و بخش‌های حساب | گزارش دارایی، وقایع، توزیع منافع و چرخهٔ بازخرید |

## اجرای مالی و ابزارهای بازار

- چرخهٔ واقعی سفارش، پرداخت و تسویه با رزرو ظرفیت، جلوگیری از درخواست تکراری و دفترکل قابل تطبیق.
- تکمیل واریز و برداشت متناسب با ارائه‌دهندهٔ مجاز و کنترل مالکیت حساب.
- تکمیل روش‌های معاملهٔ معرفی‌شده در رابط، مانند سفارش پیشرفته، در صورت تصویب محصول و فراهم بودن زیرساخت.
- استیکینگ، وام و وثیقه با قرارداد و پارامترهای روشن؛ نمایش آن‌ها در مسیر مدیریت دارایی به معنای فعال بودن خدمت نیست.
- گردآوری منابع قیمت بیشتر و سیاست قابل اتکای انتخاب یا میانگین‌گیری با کنترل دادهٔ کهنه و پرت.

## کپی‌ترید و فروشگاه شخصی

کپی‌ترید عملیاتی به هویت و سابقهٔ قابل بررسی تریدر، رضایت روشن سرمایه‌گذار، حدود سرمایه و زیان، اجرای سفارش و محاسبهٔ کارمزد از سود محقق‌شده نیاز دارد. پروفایل‌های نمونهٔ کنونی، رتبه‌بندی واقعی افراد نیستند.

ویترین فعلی لینک قابل اشتراک می‌سازد. ذخیرهٔ دائمی فروشگاه در حساب، نامک ثابت، مدیریت نسخه، آمار بازدید و مدل درآمد فروشگاه، مراحل تکمیلی احتمالی‌اند و اکنون نباید قابلیت فعال معرفی شوند.

## انتشار و بهره‌برداری شبکه

- تأیید سازگاری بسته‌های Windows، macOS و Linux در محیط هدف و انتشار شواهد آزمون.
- تکمیل زنجیرهٔ امضا، توزیع و بررسی نسخهٔ نرم‌افزار برای بسته‌هایی که هنوز این شواهد را ندارند.
- بررسی انتهابه‌انتهای دروازهٔ Remote و کنترل مجوزهای سمت سرور پیش از عرضهٔ عملیاتی.
- مستندسازی تمرین بازیابی، ارتقای نسخه، پایش و واکنش به رخداد برای هر محیط شبکه.

## معیار عبور به مرحلهٔ عملیاتی

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

## مراجع پیاده‌سازی

- planck-marketplace/components/site-shell.tsx
- planck-marketplace/components/trade-menu.tsx
- planck-marketplace/app/api/quote/route.ts
- planck-marketplace/app/api/deposits/route.ts
- planck-marketplace/COPY_TRADING.md
- planck-marketplace/lib/storefront.ts


---

# سیر توسعه و نسخه‌های پروژه

از ابزارهای Besu و Station تا مارکت‌پلیس، مدیریت و خدمات جدید.

وضعیت: مرجع | مخاطب: مدیر پروژه و تیم توسعه
بازبینی مستندات: ۲۰۲۶/۰۹/۲۴ · ۲ مهر ۱۴۰۵

## خانوادهٔ اولیهٔ شبکه

آرشیو توسعه شامل خانوادهٔ نسخه‌های Besu از شاخهٔ ۰٫۱۳ تا ۰٫۱۷ و ابزارهای اولیهٔ Station است. این نسخه‌ها برای فهم روند توسعه و مهاجرت ارزش دارند، اما نباید به‌عنوان نسخهٔ توصیه‌شدهٔ فعلی دانلود یا نصب معرفی شوند. فهرست دقیق‌تر نسخه‌ها و تفاوت محصولات در تاریخچهٔ شبکه آمده است.

## تفکیک محصولات شبکه

در مسیر بعدی، نقش‌های Admin Main، Station، LIB Observer و macOS Remote تفکیک شده‌اند. وجود بسته‌های تاریخی برای Windows، macOS و Linux نشان‌دهندهٔ مسیر چندسکویی پروژه است؛ هر بسته باید با نسخه، معماری پردازنده، امضا و نتیجهٔ آزمون خودش ارزیابی شود.

## مارکت‌پلیس و مدیریت مستقل

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

> خواندن گزارش‌های قدیمی: گزارش قدیمی ممکن است از مهاجرت معوق، اتصال غیرفعال یا تعداد آزمون‌های همان روز صحبت کند. مرجع وضعیت فعلی، کد و پیکربندی بررسی‌شدهٔ همان محیط است؛ این صفحه تاریخچه را جای وضعیت زنده نمی‌نشاند.

## توسعهٔ تجربهٔ دارایی

- بازار اختصاصی با جستجو، دسته‌بندی، مرتب‌سازی و صفحهٔ دارایی.
- طراحی شیشه‌ای، تصاویر روشن، آیکون‌های سه‌بعدی، کرهٔ دارایی و خوانایی بیشتر متن‌ها.
- ورودی‌های مالی فارسی با جداکنندهٔ هزارگان و ابزار انتخاب درصد سرمایه.
- معرفی پنج‌مرحله‌ای توکنایزیشن و پشتیبانی با نشان رسمی پلانک.
- اتصال دادهٔ Wallex در کاتالوگ یکپارچه و افزودن تنظیمات Ondo و نرخ تبدیل در مدیریت.

## گام‌های اخیر

سرمایه‌گذاری هوشمند به نمایش اولیهٔ کوتاه با فرم بازشونده تبدیل شد. تب کپی‌ترید و صفحهٔ اختصاصی پیش‌نمایش استراتژی اضافه شدند. سپس سکشن ساخت بازار شخصی و سازندهٔ ویترین با انتخاب نام، رنگ، دارایی و لینک قابل اشتراک آماده شد. این مرجع یکپارچهٔ مستندات، مرحلهٔ بعد برای معرفی روشن محصولات، قراردادها و برنامهٔ توسعه است.

- [تاریخچهٔ فنی شبکه](/docs/network-history)
- [برنامهٔ آینده](/docs/roadmap)

## مراجع پیاده‌سازی

- planck-marketplace/README.md
- planck-marketplace/COPY_TRADING.md
- planck-marketplace/components/marketplace.tsx
- planck-marketplace/components/storefront-page.tsx
- planck-admin/ONDO_SETUP.md