# راه‌اندازی کارت‌به‌کارت تیکارت

اتصال بر اساس [Partner API رسمی تیکارت](https://www.tcartt.com/docs) ساخته شده است و فعلاً در localhost اجرا می‌شود. تیکارت واریز به کارت فروشنده را با پیامک بانکی تطبیق می‌دهد. این اتصال برای واریز است؛ برداشت وجه از طریق آن پیاده‌سازی نشده است.

## آماده‌سازی

1. پس از مهاجرت‌های قبلی، فایل [`202611020002_tcartt_payments.sql`](../supabase/migrations/202611020002_tcartt_payments.sql) را در پایگاه داده مشترک مدیریت و مارکت‌پلیس اعمال کنید. ساختارهای قبلی کیف پول، بررسی واریز و Vault لازم‌اند. مهاجرت، پذیرش تیکارت را به‌صورت پیش‌فرض خاموش نگه می‌دارد و هیچ موجودی را تغییر نمی‌دهد.
2. در فایل خصوصی `.env` مارکت‌پلیس، اتصال موجود Supabase و `SUPABASE_SERVICE_ROLE_KEY` را تنظیم کنید. این کلید فقط سمت سرور مصرف می‌شود؛ آن را در کد، مخزن Git، پیام گفتگو یا متغیرهای عمومی مرورگر قرار ندهید. کلید خصوصی ذخیره‌شده در پنل مدیریت خودکار در دسترس مارکت‌پلیس نیست.
3. مبدأهای مجاز محلی به‌صورت پیش‌فرض `http://localhost:3000` و `http://127.0.0.1:3000` هستند. اگر آدرس محلی متفاوت است، `TCARTT_ALLOWED_ORIGINS` را به فهرست دقیق مبدأها با جداکننده کاما تنظیم کنید. مبدأ شامل پروتکل و پورت است و نباید مسیر داشته باشد. پس از تغییر `.env` سرور را دوباره اجرا کنید.
4. حساب فروشنده تیکارت به اشتراک بیزنس یا بالاتر، کارت دریافت وجه و اپ تیکارت روی گوشی اندرویدی دریافت‌کننده پیامک بانک نیاز دارد. کلید Partner API همان حساب را در [مدیریت ← اتصال‌ها ← تیکارت](http://localhost:3001/?section=integrations#tcartt-payment-settings) ذخیره کنید و پس از آماده‌شدن تنظیمات، گزینه نمایش کارت‌به‌کارت را فعال کنید.

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

نمونه تنظیم غیرمحرمانه مبدأها:

```dotenv
TCARTT_ALLOWED_ORIGINS=http://localhost:3000,http://127.0.0.1:3000
```

## مسیر واریز و اعتبار

کاربر واردشده در [صفحه واریز](http://localhost:3000/wallet/deposit) مبلغ را به تومان وارد می‌کند و از گزینه کارت‌به‌کارت به صفحه پرداخت تیکارت می‌رود. حداقل مبلغ API تیکارت ۱٬۰۰۰ تومان است. مبلغ دقیق فاکتور ممکن است چند تومان بیشتر از مبلغ اولیه باشد؛ همان مبلغ یکتا باید پرداخت شود. کل مبلغ تأییدشده، شامل این تفاوت، پس از تصمیم نهایی مدیریت به کیف پول اضافه می‌شود؛ دفتر مالی پلانک آن را به ریال نگهداری می‌کند.

سرور از `POST /api/v1/invoices` برای ساخت فاکتور و از `GET /api/v1/invoices/{invoice_id}` برای استعلام استفاده می‌کند. شناسه فاکتور، شناسه سفارش و مبالغ باید با درخواست ذخیره‌شده تطبیق داشته باشند. پارامتر وضعیت در آدرس بازگشت مرورگر باعث شارژ حساب نمی‌شود.

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

## پیگیری محلی و حدود آزمون

صفحه کاربر هنگام قابل‌مشاهده‌بودن هر ۱۵ ثانیه و هنگام بازگشت به صفحه استعلام می‌کند. شناسه درخواست برای ادامه همان پرداخت حفظ می‌شود. مدیر نیز از پنل می‌تواند حداکثر ۵ واریز باز را در هر نوبت استعلام کند؛ سرور مدیریت برای این کار به کلید خصوصی سرویس از تنظیمات رمزگذاری‌شده پنل یا محیط خصوصی خودش نیاز دارد. راهنمای کامل آن در مخزن **planck-admin**، فایل `docs/tcartt-setup.md` است.

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

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

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

در اجرای محلی ۲۰۲۶-۱۱-۰۲، مهاجرت روی پروژه `wlsxzyeernwtsetzyltq` اعمال شد؛ حفاظت جدول‌ها و نبود دسترسی مرورگر به کلید و ثبت مدرک پرداخت بررسی شد. پذیرش تیکارت خاموش است و کلیدی ثبت نشده است. تنظیم خصوصی سرور و آزمون واقعی پرداخت باقی است.

آزمون‌های این مخزن:

```sh
npm run typecheck
node --test tests/tcartt-payment-service.test.mjs tests/tcartt-payment-api.test.mjs tests/tcartt-payments-db.test.mjs tests/tcartt-payment-ui.test.mjs
```