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

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

منبع نهایی آمادهٔ نمایش: `lib/docs/marketplace.ts`، شامل ۱۸ مقالهٔ فارسی با ۴ تا ۶ بخش، جدول API و شواهد فایل. تعریف ساختار: `lib/docs/types.ts`.

## طبقه‌بندی وضعیت‌ها

| قابلیت | وضعیت واقعی قابل اثبات از کد | شواهد |
| --- | --- | --- |
| صفحهٔ اصلی، دسته‌بندی، بازار کامل و صفحهٔ پروژه | پیاده‌سازی‌شده؛ محتوا وابسته به کاتالوگ منتشرشده | `components/marketplace.tsx`، `components/market-page.tsx`، `components/project-page.tsx` |
| قیمت پنج ابزار بازار، کندل و دفتر سفارش | آداپتور عمومی پیاده‌شده؛ پاسخ تازه به دسترس‌بودن ارائه‌دهنده وابسته است | `lib/wallex.ts`، `lib/wallex-server.ts` |
| فرم خرید و فروش | برآورد و بازبینی پیاده‌شده؛ تأیید نهایی غیرفعال | `components/token-trade.tsx`، `components/market-asset-trade.tsx` |
| ثبت سفارش واقعی | پیاده نشده؛ مسیر برآورد عمداً 503 می‌دهد | `app/api/quote/route.ts` |
| سرمایه‌گذاری هوشمند | قواعد شفاف تخصیص در مرورگر؛ نه سفارش، پیش‌بینی سود یا مدل هوش مصنوعی | `lib/unified-investment.ts`، `components/smart-investment.tsx` |
| انتخاب مرجع تبدیل ارز | آداپتور تکی والکس/نوبیتکس یا میانگین هر دو؛ تنظیم با مدیر | `lib/exchange-rate.ts`، `lib/exchange-rate-server.ts` |
| کپی‌ترید | پیش‌نمایش سه الگوی نمایشی؛ اتصال موقت در همان صفحه | `COPY_TRADING.md`، `components/copy-trading-page.tsx` |
| ویترین شخصی | صفحهٔ واقعی ساخته‌شده از لینک عمومی؛ فاقد فروشگاه ذخیره‌شدهٔ حساب | `lib/storefront.ts`، `components/storefront-page.tsx` |
| توکنایزیشن پنج‌مرحله‌ای | معرفی تعاملی مسیر؛ صدور و عرضهٔ خودکار توکن در این بخش وجود ندارد | `components/asset-tokenization.tsx` |
| ورود، نشست، پروفایل و تنظیمات | پیاده‌شده، وابسته به تنظیم و مهاجرت سرویس حساب | `lib/customer-auth.ts`، `AUTH_SETUP.md` |
| احراز و ثبت بانکی | API و مدل داده پیاده‌شده؛ نتیجهٔ واقعی به سرویس و مهاجرت محیط وابسته است | `lib/identity.ts`، `lib/bank-registration.ts` |
| اتصال والت عمومی EVM | پیام امضاشده و ثبت آدرس؛ بدون انتقال، مجوز خرج یا ساخت موجودی | `supabase/functions/_shared/wallet-link.ts` |
| شارژ و برداشت | تاریخچه و مبنای دفتر مالی آماده؛ درگاه و برداشت فعال نیست | `app/api/deposits/route.ts`، `CASH_WALLET.md` |
| استیک و اعتبار | فقط نمایش رکوردهای موجود؛ شروع طرح جدید غیرفعال | `components/customer-dashboard.tsx` |
| دعوت دوستان | ثبت کد و مبنای پاداش موجود؛ پرداخت و معاملهٔ واقعی متصل نیست | `REFERRALS.md`، `supabase/migrations/202609080007_referral_program.sql` |
| دستیار | بدون درگاه، FAQ با mode=guide؛ با درگاه و نشست، mode=ai | `app/api/assistant/route.ts` |

## معماری قابل انتشار

- برنامهٔ عمومی از React 19، TypeScript، Vinext/Vite، Base UI، Tailwind و Lucide استفاده می‌کند. ساخت فعلی با ابزار Cloudflare و خروجی worker پشتیبانی می‌شود. نسخه‌های وابستگی را باید از `package.json` همان انتشار خواند، نه از یک ادعای «همیشه آخرین نسخه».
- `app/` مسیرها و APIها را نگه می‌دارد. `components/` رابط‌ها، `lib/` قراردادها و محاسبات و `supabase/migrations/` ساختار و مجوزهای پایگاه داده را تعریف می‌کنند.
- `lib/server.ts` کاتالوگ منتشرشده و محتوای سایت را با کلید عمومی پروژه می‌خواند. رابط مدیریتی یک برنامهٔ جداست؛ API عمومی مارکت‌پلیس محل نوشتن مدیریتی نیست.
- `getCatalog()` سه حالت دارد: `live`، `preview` و `unavailable`. محیط توسعه می‌تواند با `preview=design` روی صفحات نمونهٔ صریح نشان دهد. این پارامتر `/api/catalog` را عوض نمی‌کند. در اتصال زندهٔ ناموفق، دادهٔ نمونه جایگزین نمی‌شود.
- کاتالوگ عمومی از اطلاعات خصوصی حساب جداست. اطلاعات حساب، موجودی، آدرس‌ها، بانک‌ها و مدارک با نشست معتبر و RPC محدود به همان کاربر خوانده می‌شوند. نام جدول یا قابلیت درج‌شده در migration، اثبات نصب آن در محیط جاری نیست.
- کوکی‌های نشست HttpOnly هستند؛ در HTTPS ویژگی Secure دارند. بازیابی ایمیلی از PKCE استفاده می‌کند. `proxy.ts` هدرهای امنیتی و nonce تولید را تعریف می‌کند؛ حالت توسعه CSP متفاوتی دارد.
- تصاویر بازاریابی عمومی از مدارک احراز و عکس پروفایل خصوصی جدا هستند. مقدار کلید و رکورد شخصی نباید در محتوای سایت، کاتالوگ، ویترین URL یا مستندات عمومی قرار گیرد.
- شواهد: `package.json`، `vite.config.ts`، `proxy.ts`، `lib/server.ts`، `lib/auth-cookies.ts`، `lib/dashboard.ts`، `lib/identity-files.ts`، `README.md`.

## هویت و کیفیت دارایی

ابزارهای فعلی دقیقاً `USDTTMN/USDT`، `XAUTTMN/XAUT`، `USOONTMN/USOON`، `COPXONTMN/COPXON` و `SLVONTMN/SLVON` هستند. نفت، مس و نقرهٔ این اتصال توکن مرتبط با صندوق‌اند؛ نباید به واحد فیزیکی بشکه، کیلو یا اونس ترجمه شوند. قیمت مظنه تومان است، نه ریال.

حجم ۲۴ساعته نه کل عرضه است و نه موجودی قطعی قابل خرید. مقدار سفارش‌های خرید و فروش از دفتر سفارش مستقل دریافت می‌شود. کندل‌ها قیمت پایانی ساعتی‌اند. قیمت پس از ۹۰ ثانیه تازه محسوب نمی‌شود؛ receivedAt زمان دریافت پاسخ است، نه timestamp معامله.

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

تصاویر تولیدشدهٔ این نمونه‌ها طرح مفهومی‌اند و مدرک وجود یا تکمیل پروژه نیستند. نمونهٔ نفت قدیمی از خروجی کاتالوگ نمایشی مشخص‌شده در `withoutWallexSamples` کنار گذاشته می‌شود؛ این فیلتر حذف رکورد DB نیست.

شواهد: `lib/wallex.ts`، `lib/wallex-server.ts`، `lib/server.ts`، `lib/market-assets.ts`، `supabase/seeds/20260908_sample_projects.sql`، `supabase/seeds/20260908_token_market_samples.sql`، `ASSETS.md`.

## قواعد مهم سرمایه‌گذاری و نمایش عدد

سیاست‌های سبد: محتاطانه ذخیرهٔ ۳۵٪ و سقف ۲۰٪ برای هر دارایی؛ متعادل ۲۰٪ و ۳۰٪؛ جسورانه ۱۰٪ و ۴۰٪. این اعداد ریسک واقعی پروژه یا سود پیش‌بینی‌شده نیستند. سبد مشترک پروژه و ابزار بازار، یک ذخیره و سقف تمرکز دارد. پروژه‌ها واحد کامل، مدت و ظرفیت دارند؛ ابزار بازار دقت تعداد و قیمت تازه دارد و حجم معاملات آن ظرفیت عرضه فرض نمی‌شود.

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

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

شواهد: `lib/smart-investment.ts`، `lib/unified-investment.ts`، `lib/investment-amount.ts`، `lib/localized-number-input.ts`، `components/localized-number-input.tsx`، `tests/localized-number-input.test.mjs`.

## نکته‌های API که مستندات نباید ساده‌سازی غلط کنند

1. `GET /api/catalog` همواره JSON با HTTP200 تولید می‌کند؛ نبود داده با `mode=unavailable` مشخص می‌شود.
2. `GET /api/markets/wallex` برای feed آماده 200 و ناموجود503 دارد. اما GET دارای symbol معتبر، جزئیات را با200 می‌دهد و نبود نمودار/عمق را با `historyAvailable=false` یا `depthAvailable=false` اعلام می‌کند. symbol نامعتبر400 است.
3. `GET /api/markets/exchange-rate` برای ready200 و unavailable503 دارد؛ مظنهٔ base=USDT و quote=IRR است، نه دلار نقدی.
4. `POST /api/quote` پس از بررسی Origin عمداً503 می‌دهد و body سفارش اجراشدنی تعریف نشده است. Origin نامعتبر403 است.
5. `GET /api/auth/session` نبود نشست معتبر را عموماً با200 و `{user:null}` پاسخ می‌دهد؛ لزوماً401 نیست. اختلال سرویس با نبود ورود یکسان نیست.
6. `authBody` درخواست شیء JSON با سقف۱۶٬۰۰۰ بایت، تنظیم بودن سرویس و Origin هم‌مبدأ می‌خواهد. خروجی موفق ورود، user و کوکی است، نه توکن خام در پاسخ عمومی مرورگر.
7. `POST /api/dashboard` actionهای مشخص پروفایل، ترجیحات، بانک، هشدار، اعلان و ابطال API را دارد؛ نوشتن موجودی یا سفارش در این مسیر وجود ندارد.
8. ثبت بانک موفق `{ok:true,id}` می‌دهد. عدم تطبیق بانک422، نبود RPC ثبت503 و دیگر نتایج مشخص فرایند409 هستند؛ بسیاری از آن‌ها `{ok:false,code,error}` دارند و نباید فقط HTTP200 را معیار همهٔ نتیجه‌ها فرض کرد.
9. `GET /api/deposits` خروجی `{enabled:false,provider:null,deposits}` دارد. POST معتبر هم503 است و هیچ intent، redirect یا اعتباردهی نمی‌سازد.
10. آپلود avatar و identity/photo از بدنهٔ خام فایل استفاده می‌کنند، نه multipart. محدودیت تصویر پروفایل۲ مگابایت و مدارک۵ مگابایت است. هدر اعلامی با امضای فایل تطبیق داده می‌شود.
11. `POST /api/wallet-connect` چالش امضا یا تأیید آن را انجام می‌دهد. چالش `{id,message,expires_at}` است؛ تأیید `{wallet}` می‌دهد. origin از URL درخواست سرور می‌آید. این قرارداد امضای تراکنش نیست.
12. `POST /api/assistant` بدون درگاه AI، FAQ عمومی با mode=guide می‌دهد. در حالت درگاه، نشست الزامی است و context فقط FAQ منتشرشده است. پیام۱–۱۰۰۰ نویسه، پاسخ حداکثر۶۰۰۰ نویسه.

جداول کامل روش، بدنه، پاسخ، خطا و دسترسی در مقاله‌های `api-marketplace`، `api-customer` و `api-identity-wallets` قرار گرفته‌اند. مثال‌های اجرایی فقط GET عمومی و بدون credential هستند.

## تغییرات اخیر قابل توصیف در تاریخچهٔ محصول

- هویت بصری لوگوی اصلی، نشان دستیار همراه badge، کارت‌های دسته‌بندی با رنگ متمایز و جلوهٔ شیشه‌ای، تصاویر روشن‌تر و گرافیک سه‌بعدی مرحله‌های توکنایزیشن.
- کرهٔ هیرو با موضوع‌های متنوع دارایی، کنترل تراکم بصری و رعایت کاهش حرکت؛ این تصویر نقشهٔ فهرست عرضه یا مالکیت واقعی در کشورها نیست.
- بخش پشتیبانی با تلفن عمومی اعلام‌شدهٔ محصول و دستیار؛ بدون ادعای پاسخ‌گویی شبانه‌روزی یا چت انسانی زنده.
- ادغام ابزارهای بازار در همان دسته‌بندی‌ها و کارت‌های دارایی‌های پلانک و افزودن پنجرهٔ محاسبهٔ خرید و فروش آن‌ها.
- مرجع تبدیل قابل انتخاب و برنامه‌ریز واحد برای پروژه و ابزار بازار.
- ورودی‌های مالی فارسی و جداکنندهٔ سه‌رقمی با صفرِ نمایشی برای فیلد خالی.
- جمع‌وجور شدن سرمایه‌گذاری هوشمند و افزوده‌شدن تب و صفحات پیش‌نمایش کپی‌ترید.
- بخش «بازار خودتون را بسازید»، ویرایشگر ویترین و صفحهٔ عمومی قابل ساخت از URL با انتخاب حداکثر۱۲ دارایی.

این فهرست از وجود فایل‌ها و رفتار کد تهیه شده است؛ برای تاریخ قطعی انتشار یا ادعای استقرار عمومی باید تاریخچهٔ انتشار مستقلی وجود داشته باشد. شواهد عمده: `ASSETS.md`، `components/marketplace.tsx`، `components/planck-support.tsx`، `components/asset-tokenization.tsx`، `components/smart-investment.tsx`، `COPY_TRADING.md`، `components/market-builder-promo.tsx`، `components/storefront-page.tsx`.

## تعارض‌های فایل‌های قدیمی و اولویت شواهد

`README.md` و بعضی فایل‌های setup گزارش یک مقطع قبلی‌اند؛ عبارت‌هایی مثل «بررسی مرورگر انجام نشده» یا «QR هنوز Project ID ندارد» را نباید وضعیت قطعی امروز دانست. آن‌ها شواهد تاریخی‌اند؛ کد قرارداد را مشخص می‌کند و فعال‌بودن هر محیط به تنظیم عملیاتی نیاز دارد.

فایل احراز هویت صریحاً برای یکی از مهاجرت‌های جدید، تحویل محلی را از اجرای دیتابیس اصلی جدا کرده است. مستندات عمومی نباید از وجود migration، «روی تولید نصب است» نتیجه بگیرند. اعداد آزمون در markdownهای قبلی نیز snapshot هستند؛ در صفحهٔ وضعیت فقط نتایج تازهٔ همان انتشار ذکر شوند.

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