343 lines
15 KiB
Markdown
343 lines
15 KiB
Markdown
# کاتالوگ دیجیتال (Digital Catalog)
|
||
|
||
سند مرجع پروژه — ۱۸ اوت ۲۰۲۶
|
||
قبل از پیاده‌سازی نوشته شده است. اگر رفتار محصول عوض شد، همین فایل باید به‌روز شود.
|
||
|
||
---
|
||
|
||
## ۱. محصول چیست
|
||
|
||
کاربر یک PDF چندصفحه‌ای یا چند تصویر می‌دهد. سیستم یک **کاتالوگ دیجیتال** می‌سازد: صفحات با افکت ورق‌زدن نمایش داده می‌شوند، یک **لینک مشاهده** و یک **QR** تحویل می‌شود.
|
||
|
||
هدف دو کار با هم است:
|
||
|
||
1. ساخت و دیدن کاتالوگ همان لحظه
|
||
2. اشتراک‌گذاری همان کاتالوگ با لینک و QR، بدون ثبت‌نام
|
||
|
||
کاتالوگ‌ها در سایت **لیست نمی‌شوند**. فقط کسی که لینک یا QR را دارد می‌تواند ببیند.
|
||
|
||
---
|
||
|
||
## ۲. تصمیم‌های قفل‌شده
|
||
|
||
| موضوع | تصمیم |
|
||
|---|---|
|
||
| ثبت‌نام / ورود | ندارد. هر بازدیدکننده دامنه می‌تواند بسازد |
|
||
| گالری عمومی | ندارد |
|
||
| خروجی ساخت | لینک مشاهده + تصویر QR + لینک حذف |
|
||
| ویرایش بعدی | ندارد (صفحات، PDF، افکت بعد از ساخت عوض نمی‌شود) |
|
||
| انقضای خودکار | ندارد |
|
||
| زبان رابط | فارسی، راست‌به‌چپ |
|
||
| نسخه اول | ساده؛ بدون حساب کاربری، بدون پنل ادمین، بدون SEO کاتالوگ |
|
||
|
||
---
|
||
|
||
## ۳. چه چیزهایی نسخه اول نیست
|
||
|
||
این‌ها عمداً بیرون هستند تا پروژه ساده بماند:
|
||
|
||
- حساب کاربری، نقش، پنل مدیریت
|
||
- گالری، جستجو، نقشه سایت از کاتالوگ‌ها
|
||
- ویرایش کاتالوگ بعد از ساخت
|
||
- نقطه کلیک‌پذیر روی صفحه، فهرست مطالب، ویدیو داخل صفحه
|
||
- موسیقی پس‌زمینه، پخش خودکار اجباری
|
||
- اپ دسکتاپ / موبایل بومی
|
||
- پرداخت، چندزبانه بودن رابط، تم‌های زیاد
|
||
- Three.js و شبیه‌سازی فیزیک کاغذ از صفر
|
||
|
||
اگر فایل اشتباه آپلود شد: کاتالوگ را با لینک حذف پاک می‌کند و یکی جدید می‌سازد.
|
||
|
||
---
|
||
|
||
## ۴. مسیر کاربر
|
||
|
||
```text
|
||
ورود به دامنه
|
||
→ صفحه ساخت (آپلود PDF یا چند تصویر + انتخاب افکت)
|
||
→ پردازش و ذخیره
|
||
→ صفحه نتیجه:
|
||
• لینک مشاهده (کپی)
|
||
• QR (نمایش + دانلود PNG)
|
||
• باز کردن کاتالوگ
|
||
• لینک حذف (یک‌بار نشان داده می‌شود)
|
||
→ بیننده با لینک یا اسکن QR کاتالوگ را ورق می‌زند
|
||
```
|
||
|
||
لینک حذف را باید همان لحظه ذخیره کند. اگر گم شود، راه بازیابی نیست (چون حساب کاربری نداریم). این محدودیت باید روی صفحه نتیجه نوشته شود.
|
||
|
||
---
|
||
|
||
## ۵. امکانات نسخه اول
|
||
|
||
### ساخت
|
||
|
||
- Drag & drop یا انتخاب فایل
|
||
- هنگام خواندن PDF/تصویر، آماده‌سازی صفحات و ساخت کاتالوگ، لودینگ با متن پیشرفت نشان داده می‌شود
|
||
- یک PDF **یا** چند تصویر (نه هر دو با هم در یک کاتالوگ)
|
||
- ترتیب تصاویر = ترتیب انتخاب / ترتیب نام فایل؛ امکان جابه‌جایی قبل از ساخت
|
||
- انتخاب یکی از افکت‌های ورق‌زدن
|
||
- تعیین زمان ورق‌خوردن (۴۰۰ تا ۵۰۰۰ میلی‌ثانیه؛ پیش‌فرض ۱ ثانیه). بعد از ساخت عوض نمی‌شود
|
||
- عنوان اختیاری (اگر خالی باشد: «کاتالوگ»)
|
||
|
||
### مشاهده
|
||
|
||
- نمایش صفحات با افکت انتخاب‌شده (اسلاید، محو و کارت با انتقال ورودی/خروجی واقعی)
|
||
- ۳ ثانیه پس از باز شدن، پخش خودکار شروع می‌شود؛ فاصلهٔ بین ورق‌ها برابر زمان ورق‌خوردن ذخیره‌شده به‌علاوهٔ کمی مکث است
|
||
- قبلی / بعدی، کلیدهای جهت، کلیک/اسوایپ روی صفحه
|
||
- بندانگشتی صفحات
|
||
- زوم و تمام‌صفحه
|
||
- دسکتاپ: فقط افکت `magazine` دو صفحه روبه‌رو نشان می‌دهد؛ بقیه همیشه یک صفحه
|
||
- موبایل: همیشه یک صفحه؛ اگر ورق سه‌بعدی روی دستگاه ضعیف بود، همان کاتالوگ با اسلاید افقی دیده می‌شود (تنظیم ذخیره‌شده عوض نمی‌شود)
|
||
|
||
### اشتراک
|
||
|
||
- آدرس ثابت: `{BASE_URL}/c/{id}`
|
||
- QR همان آدرس را کد می‌کند
|
||
- دانلود QR به صورت PNG
|
||
|
||
### حذف
|
||
|
||
- حذف فقط با توکن مخفی
|
||
- بعد از حذف، لینک و QR دیگر کار نمی‌کنند
|
||
- فایل صفحات از دیسک پاک می‌شوند
|
||
|
||
---
|
||
|
||
## ۶. افکت‌های ورق‌زدن
|
||
|
||
موقع ساخت، **یکی** انتخاب می‌شود و برای همیشه روی همان کاتالوگ می‌ماند.
|
||
|
||
| شناسه | نام نمایشی | رفتار |
|
||
|---|---|---|
|
||
| `magazine` | ورق مجله | سه‌بعدی واقعی؛ افکت اصلی |
|
||
| `slide` | اسلاید افقی | صفحه بعدی از بغل می‌آید |
|
||
| `fade` | محو شدن | صفحه فعلی محو، بعدی ظاهر می‌شود |
|
||
| `card` | کارت | ورق دوبعدی مثل کارت |
|
||
| `scroll` | اسکرول عمودی | صفحات زیر هم؛ مناسب موبایل |
|
||
|
||
پیاده‌سازی: برای `magazine` از کتابخانه **StPageFlip** استفاده می‌شود. بقیه با Vue + CSS/transition. فیزیک کاغذ از صفر نوشته نمی‌شود.
|
||
|
||
---
|
||
|
||
## ۷. معماری
|
||
|
||
یک اپلیکیشن با دو بخش در یک مخزن:
|
||
|
||
- **فرانت‌اند:** Vue 3 — ساخت، نتیجه، نمایش کاتالوگ
|
||
- **بک‌اند:** API سبک Node — آپلود، ذخیره، سرو کردن صفحات، QR، حذف
|
||
|
||
کاتالوگ‌ها روی سرور ذخیره می‌شوند تا لینک برای همه باز شود. تبدیل PDF به تصویر **در مرورگر با pdf.js** انجام می‌شود. سرور PDF خام نمی‌گیرد؛ فقط JPEG صفحات را ذخیره می‌کند. به ابزار native مثل Poppler نیاز نیست.
|
||
|
||
```text
|
||
مرورگر سرور
|
||
────── ────
|
||
انتخاب PDF/تصویر
|
||
pdf.js → تصویر هر صفحه
|
||
آپلود تصاویر + افکت + عنوان → ذخیره فایل‌ها روی دیسک
|
||
→ ردیف در SQLite
|
||
→ ساخت QR
|
||
صفحه نتیجه ← لینک/QR/حذف
|
||
بیننده /c/:id → متادیتا + آدرس تصاویر
|
||
نمایش با افکت انتخاب‌شده
|
||
```
|
||
|
||
---
|
||
|
||
## ۸. استک قفل‌شده
|
||
|
||
| لایه | انتخاب | دلیل |
|
||
|---|---|---|
|
||
| UI | Vue 3 + Vite + TypeScript | کامپوننت و state برای آپلود و نمایش |
|
||
| استایل | CSS ساده + RTL | بدون UI kit سنگین |
|
||
| PDF در مرورگر | pdf.js | تبدیل صفحه به تصویر بدون سرور خاص |
|
||
| ورق مجله | StPageFlip | افکت آماده و قابل‌نگهداری |
|
||
| QR | بسته `qrcode` در سرور | PNG قابل دانلود |
|
||
| API | Hono روی Node | سبک، TypeScript |
|
||
| داده | SQLite از طریق sql.js + Drizzle | بدون کامپایل native (روی ویندوز بدون Visual Studio هم نصب می‌شود) |
|
||
| فایل صفحات | پوشه محلی دیسک | ساده برای یک سرور |
|
||
| شناسه | nanoid | کوتاه و غیرقابل حدس نسبی |
|
||
|
||
HTML/CSS خالی رد شد: آپلود، تبدیل PDF، چند افکت، موبایل و صفحه نتیجه خیلی زود شلوغ می‌شود.
|
||
|
||
Nuxt و فریم‌ورک سنگین بک‌اند رد شد: نمایش کاتالوگ تقریباً همه در کلاینت است؛ یک API کوچک کافی است.
|
||
|
||
---
|
||
|
||
## ۹. مدل داده
|
||
|
||
جدول `catalogs`:
|
||
|
||
| فیلد | نوع | توضیح |
|
||
|---|---|---|
|
||
| `id` | متن، حدود ۱۰ کاراکتر | شناسه عمومی در لینک |
|
||
| `delete_token` | متن، حدود ۲۴ کاراکتر | فقط برای حذف؛ در URL مشاهده نیست |
|
||
| `title` | متن | عنوان |
|
||
| `effect` | متن | یکی از شناسه‌های بخش ۶ |
|
||
| `page_count` | عدد | تعداد صفحات ذخیره‌شده |
|
||
| `flip_ms` | عدد | مدت انیمیشن ورق‌خوردن به میلی‌ثانیه (۴۰۰–۵۰۰۰) |
|
||
| `created_at` | زمان | |
|
||
|
||
فایل‌ها:
|
||
|
||
```text
|
||
storage/catalogs/{id}/
|
||
page-001.jpg
|
||
page-002.jpg
|
||
...
|
||
qr.png
|
||
```
|
||
|
||
صفحات با عرض حداکثر ۱۶۰۰ پیکسل، JPEG با کیفیت حدود ۸۵ ذخیره می‌شوند.
|
||
|
||
---
|
||
|
||
## ۱۰. API
|
||
|
||
پایه: `/api`
|
||
|
||
| متد | مسیر | کار |
|
||
|---|---|---|
|
||
| `POST` | `/catalogs` | ساخت. بدنه: تصاویر JPEG صفحات (نه خود PDF) + `title` + `effect` + `flipMs` |
|
||
| `GET` | `/catalogs/:id` | متادیتا برای بیننده (بدون `delete_token`)؛ شامل `flipMs` |
|
||
| `GET` | `/catalogs/:id/pages/:n` | فایل تصویر صفحه |
|
||
| `GET` | `/catalogs/:id/qr` | PNG کد QR. عمومی است چون فقط همان لینک مشاهده را کد می‌کند |
|
||
| `DELETE` | `/catalogs/:id` | حذف؛ کوئری `token` باید با `delete_token` یکی باشد |
|
||
|
||
پاسخ ساخت:
|
||
|
||
```json
|
||
{
|
||
"id": "abc12xyz90",
|
||
"viewUrl": "https://example.com/c/abc12xyz90",
|
||
"deleteUrl": "https://example.com/c/abc12xyz90/delete?token=...",
|
||
"qrUrl": "https://example.com/api/catalogs/abc12xyz90/qr"
|
||
}
|
||
```
|
||
|
||
`deleteUrl` فقط همین یک‌بار به سازنده داده می‌شود. از `GET` عمومی برنمی‌گردد.
|
||
|
||
صفحات فرانت:
|
||
|
||
| مسیر | صفحه |
|
||
|---|---|
|
||
| `/` | ساخت کاتالوگ |
|
||
| `/c/:id` | نمایش کاتالوگ |
|
||
| `/c/:id/done?token=...` | صفحه نتیجه (لینک، QR، حذف) — توکن فقط برای نشان دادن دکمه حذف و جلوگیری از دیدن این صفحه توسط بیننده معمولی |
|
||
| `/c/:id/delete?token=...` | تأیید حذف |
|
||
|
||
بیننده `/c/:id` را می‌بیند. صفحه نتیجه بدون توکن باز نشود.
|
||
|
||
---
|
||
|
||
## ۱۱. محدودیت‌ها (ضد سوءاستفاده)
|
||
|
||
چون ثبت‌نام نیست، این سقف‌ها اجباری‌اند:
|
||
|
||
| مورد | سقف نسخه اول |
|
||
|---|---|
|
||
| حجم هر فایل ورودی | ۱۰۰ مگابایت |
|
||
| تعداد صفحه | حداکثر ۲۰۰ |
|
||
| فرمت PDF | `application/pdf` |
|
||
| فرمت تصویر | jpeg, png, webp, gif |
|
||
| ساخت از یک IP | ۱۰ کاتالوگ در ساعت (شمارنده در حافظه همان پروسه Node؛ یک سرور) |
|
||
| عرض تصویر ذخیره‌شده | حداکثر ۱۶۰۰px |
|
||
| زمان ورق‌خوردن | ۴۰۰ تا ۵۰۰۰ میلی‌ثانیه |
|
||
|
||
اگر سقف رد شود، پیام فارسی واضح نشان داده می‌شود و چیزی ذخیره نمی‌شود.
|
||
|
||
---
|
||
|
||
## ۱۲. امنیت و حریم
|
||
|
||
- کاتالوگ **unlisted** است: endpoint لیست وجود ندارد
|
||
- `id` تصادفی است؛ نباید پشت سر هم و قابل حدس باشد
|
||
- حذف فقط با `delete_token`
|
||
- نوع فایل واقعی بررسی شود، نه فقط پسوند
|
||
- فایل آپلودی هرگز به عنوان اسکریپت سرو نشود
|
||
- برای QR باید `PUBLIC_BASE_URL` در محیط سرور تنظیم شود تا لینک داخل QR درست باشد
|
||
|
||
این مدل «امنیت از طریق مخفی بودن لینک» است، نه قفل رمز روی کاتالوگ. هر کس لینک را داشته باشد محتوا را می‌بیند.
|
||
|
||
---
|
||
|
||
## ۱۳. رابط کاربری (خلاصه)
|
||
|
||
سه صفحه اصلی، فارسی و RTL:
|
||
|
||
1. **ساخت:** ناحیه آپلود، لیست صفحات (مرتب‌سازی)، انتخاب افکت، دکمه ساخت
|
||
2. **نتیجه:** لینک، QR، هشدار «لینک حذف را ذخیره کن»، دکمه حذف
|
||
3. **نمایش:** استیج کاتالوگ، کنترل‌ها، بندانگشتی
|
||
|
||
ظاهر نسخه اول تمیز و ساده باشد، نه داشبورد شلوغ.
|
||
|
||
---
|
||
|
||
## ۱۴. اجرا و پیکربندی
|
||
|
||
یک سرور Node کافی است. SQLite و پوشه `storage/` کنار اپ می‌مانند.
|
||
|
||
متغیرهای محیط:
|
||
|
||
```text
|
||
PORT=3000
|
||
API_PORT=3010
|
||
PUBLIC_BASE_URL=https://ktg.montzar.ir
|
||
STORAGE_DIR=./storage
|
||
DATABASE_PATH=./data/catalogs.sqlite
|
||
```
|
||
|
||
`PUBLIC_BASE_URL` همان دامنه‌ای است که داخل QR نوشته می‌شود.
|
||
|
||
---
|
||
|
||
## ۱۵. گزینه‌هایی که بررسی شد و انتخاب نشد
|
||
|
||
1. **فقط HTML/CSS** — برای دمو کافی است؛ برای آپلود، PDF، چند افکت و لینک عمومی کافی نیست.
|
||
2. **فقط Vue در مرورگر، بدون سرور** — کاتالوگ بعد از بستن تب از بین می‌رود؛ لینک و QR برای دیگری کار نمی‌کند.
|
||
3. **Vue + بک‌اند + حساب کاربری / گالری** — برای نسخه اول اضافه است.
|
||
|
||
انتخاب نهایی: **Vue 3 + API سبک Node + SQLite + فایل روی دیسک.**
|
||
|
||
---
|
||
|
||
## ۱۶. معیار تمام شدن نسخه اول
|
||
|
||
نسخه اول وقتی تمام است که:
|
||
|
||
- [x] با چند تصویر کاتالوگ ساخته شود (تست API با JPEG)
|
||
- [ ] با PDF چندصفحه‌ای در مرورگر (نیاز به بررسی دستی)
|
||
- [x] پنج افکت در UI پیاده شده‌اند (بررسی ظاهری باقی است)
|
||
- [x] لینک `/c/:id` از API متادیتا می‌گیرد
|
||
- [x] QR همان لینک را کد می‌کند
|
||
- [x] حذف با توکن کاتالوگ را از بین ببرد
|
||
- [x] بدون توکن نشود حذف کرد
|
||
- [x] گالری یا لیست عمومی وجود نداشته باشد
|
||
- [ ] روی موبایل بررسی دستی
|
||
- [x] سقف تعداد صفحه پیام خطا بدهد
|
||
|
||
---
|
||
|
||
## ۱۷. کارهای بعدی (عمداً بعد از نسخه اول)
|
||
|
||
فقط اگر بعداً لازم شد، نه الان:
|
||
|
||
- ذخیره لینک‌های همین مرورگر در `localStorage`
|
||
- عوض کردن افکت بدون آپلود دوباره
|
||
- انقضای اختیاری
|
||
- رمز روی کاتالوگ
|
||
- هاست چند سروره / S3
|
||
- حساب کاربری برای تیم
|
||
|
||
---
|
||
|
||
## تاریخچه تصمیم
|
||
|
||
| تاریخ | تصمیم |
|
||
|---|---|
|
||
| ۲۰۲۶-۰۸-۱۸ | محصول: کاتالوگ دیجیتال از PDF/تصویر با افکت و اشتراک |
|
||
| ۲۰۲۶-۰۸-۱۸ | از اول هم مشاهده همان‌جا، هم لینک عمومی + QR |
|
||
| ۲۰۲۶-۰۸-۱۸ | بدون ورود؛ هر بازدیدکننده می‌تواند بسازد |
|
||
| ۲۰۲۶-۰۸-۱۸ | بدون گالری؛ فقط لینک و QR |
|
||
| ۲۰۲۶-۰۸-۱۸ | بعد از ساخت: لینک + QR + لینک حذف؛ بدون ویرایش و بدون انقضا |
|
||
| ۲۰۲۶-۰۸-۱۸ | استک: Vue 3 + Hono + SQLite + pdf.js + StPageFlip |
|