# تیکت پشتیبانی پلانک

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

## صفحه‌ها و API

| بخش | مسیر | رفتار |
| --- | --- | --- |
| کاربر | `/account/tickets` و `?ticket=<uuid>` | فهرست خصوصی، ایجاد تیکت، مشاهدهٔ گفتگو و پاسخ |
| مدیریت | `/?section=tickets` و `&ticket=<uuid>` | صف‌ها، فیلترها، پاسخ، تغییر اولویت/وضعیت و ارجاع |
| API مارکت‌پلیس | `GET /api/tickets` | فهرست؛ جزئیات با `?id=<uuid>` |
| API مدیریت | `GET /api/tickets` | فهرست؛ جزئیات با `?ticket=<uuid>` در سرویس مدیریت |

فیلترهای فهرست: `q`, `department`, `priority`, `status`, `page`, `page_size`. اندازهٔ پیش‌فرض صفحه ۲۰ و حداکثر ۵۰ است. جست‌وجو روی عنوان و شمارهٔ تیکت انجام می‌شود؛ مدیر می‌تواند مشخصات تماس یا نام کاربر را هم جست‌وجو کند. متن پیام‌ها وارد جست‌وجوی عمومی فهرست نمی‌شود.

- ایجاد توسط کاربر: `POST /api/tickets` با `{action:"create",subject,department,priority,body,client_id}`.
- پاسخ کاربر: همان مسیر با `{action:"reply",id,version,body,client_id}`.
- تغییر توسط مدیر: `POST /api/tickets` در سرویس مدیریت با `{ticket_id,version,department,priority,status,body,client_id}`. متن پاسخ اختیاری است؛ تغییر واحد و وضعیت بدون ارسال پیام هم ثبت می‌شود.

`client_id` شناسهٔ UUID ثابت هر تلاش است؛ هنگام تلاش مجدد همان درخواست، همان شناسه استفاده می‌شود. `version` از آخرین وضعیت سرور گرفته می‌شود. تغییر هم‌زمان پاسخ ۴۰۹ می‌دهد و به تازه‌سازی نیاز دارد. عنوان ۵ تا ۱۶۰ و متن پیام ۵ تا ۶٬۰۰۰ نویسه دارد. پاسخ جزئیات `{ticket,messages,events}` و پاسخ فهرست `{items,total,page,page_size}` است.

## واحدها، اولویت و وضعیت

| کلید واحد | عنوان |
| --- | --- |
| `general` | پشتیبانی عمومی |
| `account` | حساب کاربری |
| `identity` | احراز هویت |
| `wallet` | کیف پول و پرداخت |
| `trading` | خرید، فروش و تبدیل |
| `tokenization` | توکنایزیشن دارایی |
| `technical` | پشتیبانی فنی |
| `business` | همکاری و بازار اختصاصی |

اولویت‌ها `normal` (عادی)، `high` (بالا) و `urgent` (فوری) هستند. وضعیت‌ها `open`، `in_progress`، `waiting_customer`، `resolved` و `closed` هستند. پاسخ کاربر به تیکت حل‌شده یا منتظر پاسخ، آن را دوباره باز می‌کند؛ تیکت بسته‌شده برای پاسخ کاربر باید ابتدا توسط مدیر باز شود، یا کاربر تیکت تازه ایجاد کند.

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

## نصب پایگاه داده و کنترل دسترسی

پس از مهاجرت‌های قبلی پروژه، هر دو فایل زیر به ترتیب لازم‌اند:

1. `supabase/migrations/202611010001_support_tickets.sql`: جدول‌های خصوصی، RPCها، اعلان‌ها و عنوان فارسی فعالیت‌ها.
2. `supabase/migrations/202611010002_support_ticket_read_context.sql`: حالت اجرای RPCهای خواندن کاربر؛ بررسی دسترسی قفل ردیف می‌گیرد و ممکن است اعتبار احراز موقت را همگام کند، بنابراین در PostgREST باید `VOLATILE` باشد. خواندن مدیر `STABLE` می‌ماند.

شناسهٔ کاربر از نشست تأییدشده و `auth.uid()` تعیین می‌شود. مشتری فقط تیکت‌های خودش را می‌بیند؛ مدیریت نیازمند نقش `owner` و سیاست ورود فعلی مدیریت است. انتخاب واحد به‌تنهایی مجوز دسترسی کارشناس جدید ایجاد نمی‌کند. جدول‌ها RLS دارند و دسترسی مستقیم نقش‌های عمومی، کاربر و سرویس به آن‌ها لغو شده است؛ عملیات از RPCهای کنترل‌شده می‌گذرد. تیکت، پیام و تاریخچه حذف نمی‌شوند و پیام/رویداد قبلی قابل بازنویسی نیست. این تضمین برنامه و مجوزهاست؛ سیاست پشتیبان‌گیری زیرساخت باید جداگانه برقرار باشد.

## آزمون و پیش از انتشار

از ریشهٔ مارکت‌پلیس:

```sh
node --test tests/support-tickets-api.test.mjs tests/support-tickets-db.test.mjs
```

آزمون‌ها مالکیت، مجوز مدیر، ورودی‌ها، تکرار امن، تعارض نسخه، اعلان‌ها، حفظ سوابق و حالت تراکنش PostgREST را بررسی می‌کنند. `supabase/tests/support-tickets-verification.sql` برای بررسی پس از نصب، با کاربران ساختگی و `ROLLBACK` نوشته شده است؛ در نشست SQL دارای مجوز لازم اجرا شود. قبولی این آزمون‌ها جای آزمون ورود و گفتگوی واقعی در مرورگر را نمی‌گیرد.

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