mohaymen-notepad-module 1.0.0

package/README.md

@@ -0,0 +1,307 @@
+
+# Definition of Done (DOD) - ماژول نوت‌پد (فقط فاز اول)
+
+## 1. معرفی و دامنه
+
+- **نام پروژه:** ماژول نوت‌پد برای سامانه ستاره  
+- **نوع پروژه:** برون‌سپاری (Frontend)  
+- **فاز پوشش‌داده‌شده در این سند:** فقط **فاز اول – قابلیت‌های اصلی (Go-Live)**  
+
+این سند، DOD اختصاصی فاز اول است و فقط مواردی را پوشش می‌دهد که برای راه‌اندازی عملیاتی (Go-Live) ماژول نوت‌پد لازم هستند.
+
+---
+
+## 2. دامنه فاز اول (Scope)
+
+در پایان فاز اول، ماژول نوت‌پد باید حداقل قابلیت‌های زیر را به‌صورت کامل و قابل استفاده در محیط واقعی داشته باشد:
+
+- **ماژول مستقل نوت‌پد در سامانه ستاره**
+- **ویرایشگر متن مبتنی بر Tiptap** با امکانات ادیت متن تعریف‌شده
+- **مدیریت دسترسی View/Edit** در UI
+- **دریافت و ذخیره نوت از طریق Context API**
+- **افزودن گزارش‌های PA** از طریق Web Component
+- **منشن کردن داشبوردهای PA در متن** (Mention)
+- **UI/UX مطابق طراحی انجام شده** (شامل RTL/LTR)
+- **State Management با Zustand**
+- **Auto-save با Debounce + Save Notification**
+- **آپلود فایل/تصویر فقط با Browse**
+- **تست Integration با Cypress با حداقل ۸۰٪ پوشش** برای سناریوهای اصلی
+
+---
+
+## 3. معماری و Context API
+
+### 3.1 معماری ماژول
+
+- ماژول نوت‌پد به‌صورت یک ماژول مستقل در سامانه ستاره در دسترس است (ورود از منوی ماژول‌ها).
+- هر نوت/داک یک Object مستقل با شناسه یکتا است (برای دریافت/ویرایش/ذخیره).
+- UI برای هر نوت، وضعیت دسترسی کاربر (View یا Edit) را نشان می‌دهد و رفتار را بر اساس آن تنظیم می‌کند.
+
+### 3.2 Context API
+
+- تمام ارتباطات با سرور در ماژول نوت‌پد از طریق یک Context (یا چند Context مرتبط) به کامپوننت‌ها تزریق می‌شود.
+- حداقل متدهای زیر در Context در دسترس است:
+
+```typescript
+type AccessLevel = 'none' | 'view' | 'edit';
+
+interface NotepadContextAPI {
+  getNote: (noteId: string) => Promise<Note>;
+  updateNote: (noteId: string, content: any) => Promise<void>;
+
+  // گزارش‌ها
+  getReportsList: () => Promise<Array<{ id: string; title: string; type: string }>>;
+
+  // داشبوردها (برای منشن کردن در نوت)
+  getDashboardsList: () => Promise<Array<{ id: string; title: string }>>;
+
+  uploadFile: (file: File) => Promise<{ url: string }>;
+
+  // بررسی دسترسی: 
+  // مقدار برگشتی یک اینام متنی است که نشان می‌دهد کاربر هیچ دسترسی ندارد، فقط خواندن دارد یا دسترسی ویرایش دارد.
+  // 'none'  → کاربر هیچ دسترسی به نوت ندارد
+  // 'view'  → کاربر فقط دسترسی خواندن دارد
+  // 'edit'  → کاربر دسترسی ویرایش (و به‌صورت ضمنی خواندن) دارد
+  hasPermission: () => AccessLevel;
+}
+```
+
+- تمام متدها Promise-base هستند و خطاها به‌صورت مناسب Handle می‌شوند (Error Notifications در UI).
+
+### 3.3 مدیریت دسترسی در UI
+
+- اگر کاربر **دسترسی View ندارد**:
+  - نوت نمایش داده نمی‌شود (یا پیام مناسب نمایش داده می‌شود) مطابق سیاست محصول.
+  - Notification مناسب با متن عدم دسترسی نمایش داده می‌شود.
+
+- اگر کاربر **فقط View دارد و Edit ندارد**:
+  - محتوای نوت نمایش داده می‌شود، اما قابل ویرایش نیست.
+  - ویرایشگر در حالت Read-Only قرار می‌گیرد.
+  - NotepadToolbar غیرفعال یا مخفی می‌شود (طبق طراحی انجام شده).
+  - آیکن قفل یا Badge وضعیت Read-Only نشان داده می‌شود.
+
+- اگر کاربر **دسترسی Edit دارد**:
+  - تمام امکانات ویرایش فعال هستند.
+
+---
+
+## 4. ویرایشگر متن (Tiptap) – فاز اول
+
+### 4.1 امکانات ادیت متن
+
+در فاز اول، ویرایشگر متن باید حداقل امکانات زیر را داشته باشد:
+
+- **تعیین اندازه متن** از بین:
+  - H1  
+  - H2  
+  - Body  
+
+- **تعیین رنگ متن** (Text Color)  
+- **هایلایت کردن متن** (Text Highlight)  
+- **استایل متن**:
+  - Bold  
+  - StrikeThrough  
+  - Italic  
+
+- **لیست‌ها**:
+  - Ordered List  
+  - Unordered List  
+  - ToDo List (Check Box)  
+
+- **درج عناصر**:
+  - Add Link to Text (Create Link) – افزودن لینک به بخشی از متن انتخاب‌شده  
+  - Insert Table – درج جدول  
+  - Insert Photo – درج تصویر از طریق Browse  
+  - Insert Media – درج فایل‌های رسانه‌ای، در حدی که در طراحی انجام شده آمده است  
+
+### 4.2 Page Break (Paging)
+
+- استفاده از Tiptap به‌همراه اکستنشن **Pagination Plus / Page Size** برای پیاده‌سازی قابلیت جداسازی صفحات:  
+  - مرجع: `https://tiptapplus.com/pagination-plus/page-size/`  
+  - این اکستنشن مسئول مدیریت Page Break و اندازه صفحات در ادیتور است.  
+- قابلیت درج Page Break در متن.  
+- نمایش جداکننده صفحه در ادیتور (Line/Separator) مطابق طراحی انجام شده.  
+- امکان حذف Page Break.  
+
+**گزینه‌های جایگزین (در صورت عدم امکان استفاده از اکستنشن فوق):**
+
+- استفاده از یکی از اکستنشن‌های Community مانند:  
+  - `tiptap-extension-page-break` (NPM)  
+  - `@sereneinserenade/tiptap-page-break` (GitHub: `sereneinserenade/tiptap-extensions`)  
+- یا پیاده‌سازی یک **Custom Page Break Extension** بر اساس مستندات رسمی Tiptap.
+
+### 4.3 NotepadToolbar
+
+- NotepadToolbar ویرایشگر باید **از لحاظ ظاهر و گروه‌بندی دکمه‌ها مطابق طراحی انجام شده** باشد:
+  - دکمه‌های مربوط به اندازه متن، استایل متن، رنگ، هایلایت و لیست‌ها.
+  - دکمه‌های درج (Link, Table, Photo, Media, Page Break).
+  - Tooltip برای هر دکمه.
+  - نمایش وضعیت فعال/غیرفعال (Active/Disabled) برای دکمه‌ها.
+
+### 4.4 RTL / LTR
+
+- ادیتور باید بدون نیاز به دکمه تغییر جهت، از RTL و LTR پشتیبانی کند:
+  - در متن فارسی/عربی، چیدمان RTL و راست‌چین باشد.
+  - در متن انگلیسی، چیدمان LTR و چپ‌چین باشد.
+  - NotepadToolbar و سایر اجزا در RTL به‌درستی Mirror شوند و دچار به‌هم‌ریختگی نشوند.
+  - محتوای Mixed (فارسی+انگلیسی) بدون مشکل نمایش داده شود.
+- برای مدیریت جهت متن و پاراگراف‌ها، پیشنهاد می‌شود از اکستنشن **`tiptap-text-direction`** استفاده شود  
+  (مرجع: `https://github.com/amirhhashemi/tiptap-text-direction`).
+
+---
+
+## 5. گزارش‌های PA (Web Component)
+
+### 5.1 انتخاب و درج گزارش
+
+- امکان دریافت لیست گزارش‌ها از سرور از طریق Context:
+  - شامل حداقل: `id` و `title` (و `type` در صورت نیاز).
+- UI ساده برای انتخاب گزارش از لیست (طبق طراحی انجام شده).
+- پس از انتخاب، در محتوای نوت یک Web Component درج می‌شود، مانند:
+
+```html
+<report-component reportId="xxx"></report-component>
+```
+
+### 5.2 ذخیره و بازیابی
+
+- `reportId` و ساختار Web Component در محتوای نوت ذخیره می‌شود (HTML/JSON).
+- هنگام لود نوت، Web Component ها مجدداً رندر می‌شوند.
+- امکان حذف گزارش از داخل نوت (حذف Web Component از متن) وجود دارد.
+
+### 5.3 Slash Menu و منشن داشبورد PA
+
+- در ویرایشگر، یک **Slash Menu** (منوی `/`) وجود دارد که کاربر با تایپ `/` می‌تواند گزینه‌های درج محتوا را ببیند.  
+- حداقل دو آیتم زیر باید در Slash Menu موجود باشد:
+  - **افزودن گزارش PA** (Add PA Report)  
+  - **منشن داشبورد PA** (Mention PA Dashboard)  
+- برای آیتم **افزودن گزارش PA** می‌توان از همان لیست گزارش‌ها و Web Component توضیح‌داده‌شده در این بخش استفاده کرد.
+
+#### منشن داشبورد PA
+
+- لیست داشبوردها از طریق متد `getDashboardsList` در Context دریافت می‌شود (شامل حداقل `id` و `title`).  
+- پس از انتخاب گزینه «منشن داشبورد PA» از Slash Menu، لیست داشبوردها نمایش داده می‌شود و کاربر می‌تواند یک داشبورد را انتخاب کند.  
+- در متن، یک Mention (مثلاً به‌صورت تگ/Chip یا متن فرمت‌شده) درج می‌شود که `dashboardId` را در ساختار داده خود نگه می‌دارد و قابل کلیک/ارجاع است (رفتار دقیق مطابق طراحی انجام شده).  
+- Mentionهای داشبورد همراه با `dashboardId` در ساختار داده نوت ذخیره و هنگام لود مجدداً رندر می‌شوند.
+
+---
+
+## 6. UX/UI، Shortcutها و Read-Only
+
+### 6.1 Keyboard Shortcuts (فاز اول)
+
+- Ctrl+B → Bold  
+- Ctrl+I → Italic  
+- Ctrl+K → Add Link  
+- Ctrl+S → ذخیره دستی (Manual Save)  
+
+### 6.2 Save Notification و Auto-save
+
+- Auto-save با Debounce (مثلاً حدود ۲ ثانیه بعد از آخرین تغییر).
+- نمایش وضعیت ذخیره‌سازی در UI:
+  - `Saving...` هنگام ارسال تغییرات.
+  - `Saved` بعد از موفقیت.
+  - نمایش `Last saved at ...` (آخرین زمان ذخیره).
+- در صورت خطای ذخیره، پیام خطای واضح نمایش داده می‌شود.
+
+### 6.3 Loading & Error States
+
+- هنگام **بارگذاری اولیه نوت**:
+  - نمایش Skeleton/Spinner تا دریافت داده.
+- هنگام **Auto-save**:
+  - نمایش وضعیت در NotepadToolbar یا جای مناسب (Loading/Spinner کوچک).
+- هنگام **درج گزارش**:
+  - نمایش Loading تا تکمیل عملیات درج.
+- هنگام **آپلود فایل/تصویر (Browse)**:
+  - نمایش Loading / Progress (در حدی که در طراحی انجام شده آمده است).
+- برای خطاهای زیر، Notification مناسب نمایش داده می‌شود:
+  - عدم دسترسی (403)
+  - عدم اتصال به سرور / Timeout
+  - خطای سرور (۵۰۰)
+  - خطای آپلود (حجم/فرمت نامعتبر، شکست ارسال)
+
+### 6.4 Read-Only Mode
+
+- در حالت عدم دسترسی Edit:
+  - متن نوت غیرقابل ویرایش است.
+  - NotepadToolbar مخفی یا غیرفعال (طبق طراحی انجام شده).
+  - یک نشانگر (آیکن قفل یا Badge) وضعیت Read-Only را نمایش می‌دهد.
+
+### 6.5 Responsive Design
+
+- نمایش صحیح UI ماژول در:
+  - Desktop  
+  - Tablet  
+  - Mobile  
+- رفتار NotepadToolbar در عرض‌های مختلف مطابق طراحی انجام شده (ممکن است بخشی از دکمه‌ها در منوی بیشتر بروند).
+
+---
+
+## 7. State Management (Zustand)
+
+- استفاده از **Zustand** برای State Management ماژول.
+- حداقل دو سطح State:
+  - **Note State:** محتوای نوت، وضعیت ذخیره (Saving/Saved/Error)، Page Breakها، گزارش‌های درج‌شده.
+  - **UI State:** مود Read-Only، وضعیت Loadingها، نمایش/عدم نمایش دیالوگ‌ها، وضعیت NotepadToolbar.
+- Storeها به صورت ماژولار طراحی شوند تا توسعه فاز دوم (History, Comments, …) آسان باشد.
+
+---
+
+## 8. تست و کیفیت (فقط فاز اول)
+
+### 8.1 Cypress Integration Tests
+
+- سناریوهای حداقلی که باید با Cypress پوشش داده شوند:
+  - لود نوت و نمایش محتوا.
+  - ویرایش متن و ذخیره (Manual Save + Auto-save).
+  - نمایش و رفتار Save Notification.
+  - حالت Read-Only (عدم امکان ویرایش، نمایش قفل).
+  - درج Page Break و حذف آن.
+  - درج و حذف Web Component گزارش.
+  - آپلود تصویر/فایل با Browse (موفق + خطای حجم/فرمت).
+  - Shortcutهای Ctrl+B، Ctrl+I، Ctrl+K، Ctrl+S.
+- **حداقل ۸۰٪ Coverage** برای ماژول نوت‌پد (فاز اول).
+
+### 8.2 تطابق با طراحی و RTL/LTR
+
+- UI با طراحی انجام شده از نظر:
+  - رنگ، فونت، فاصله‌ها، آیکن‌ها، حالت‌های Hover/Active/Disabled.
+  - چیدمان NotepadToolbar و رفتار Responsive.
+- تست در حالت RTL و LTR با محتوای فارسی، عربی و انگلیسی.
+
+---
+
+## 9. Build، Review و چک‌لیست تحویل فاز اول
+
+### 9.1 Build & Deployment
+
+- Build production پروژه بدون خطا و Warning اجرا می‌شود.
+- ماژول نوت‌پد در محیط تست/Stage قابل استفاده است و به سامانه ستاره متصل می‌شود.
+
+### 9.2 Reviewها
+
+- **Design Review:**  
+  - تأیید Product Designer مبنی بر تطابق UI با طراحی انجام شده.
+- **Technical Review:**  
+  - تأیید Tech Lead مبنی بر کیفیت کد، ساختار معماری، استفاده از Zustand و رعایت SOLID در حد معقول.
+- **Product/UAT:**  
+  - تأیید Product Manager بعد از تست سناریوهای اصلی (ایجاد/ویرایش/ذخیره نوت، درج گزارش، Page Break، Read-Only).
+
+### 9.3 چک‌لیست نهایی فاز اول
+
+در زمان تحویل فاز اول، تمام موارد زیر باید ✅ باشند:
+
+- ماژول نوت‌پد به‌عنوان ماژول مستقل در سامانه ستاره در دسترس است.  
+- Context API برای `getNote`, `updateNote`, `getReportsList`, `uploadFile`, `hasPermission` پیاده‌سازی و در ماژول استفاده می‌شود.  
+- ویرایشگر Tiptap با امکانات ادیت متن ذکرشده (H1/H2/Body، رنگ، هایلایت، Bold/Italic/Strike، لیست‌ها، Link, Table, Photo, Media) کار می‌کند.  
+- Page Break با اکستنشن رایگان پیاده‌سازی شده و درج/حذف آن در ادیتور بدون مشکل است.  
+- RTL/LTR در متن و NotepadToolbar بدون به‌هم‌ریختگی کار می‌کند.  
+- گزارش‌ها از طریق Web Component و با `reportId` در نوت درج، ذخیره، لود و حذف می‌شوند.  
+- Auto-save با Debounce فعال است و Save Notification (`Saving.../Saved/Last saved at...`) درست کار می‌کند.  
+- آپلود فایل/تصویر از طریق Browse (بدون Drag & Drop) کار می‌کند و خطاها مدیریت می‌شود.  
+- Read-Only Mode طبق دسترسی کاربر رفتار می‌کند (عدم ویرایش، قفل، غیرفعال بودن NotepadToolbar).  
+- Keyboard Shortcuts تعریف‌شده برای فاز اول کار می‌کنند.  
+- تست‌های Cypress با حداقل ۸۰٪ Coverage برای سناریوهای فاز اول پاس می‌شوند.  
+- Build Production بدون خطا و Warning اجرا شده است.  
+
+

package/dist/index.d.ts

@@ -0,0 +1,39 @@
+import { Context } from 'react';
+import { JSONContent } from '@tiptap/react';
+import { JSX } from 'react/jsx-runtime';
+
+declare type AccessLevelNotepad = 'none' | 'view' | 'edit';
+
+export declare const Notepad: () => JSX.Element;
+
+declare type NotepadContent = JSONContent;
+
+export declare const NotepadContext: Context<NotepadContextAPI | null>;
+
+declare type NotepadContextAPI = {
+    getNote: (noteId: string) => Promise<NotepadNode>;
+    updateNote: (noteId: string, content: any) => Promise<void>;
+    getReportsList: () => Promise<Array<{
+        id: string;
+        title: string;
+        type: string;
+    }>>;
+    getDashboardsList: (query: string | null) => Promise<NotepadReportType[]>;
+    uploadFile: (file: File) => Promise<{
+        url: string;
+    }>;
+    hasAccess: (noteId: string) => Promise<AccessLevelNotepad>;
+    autoSaveInterval: () => number;
+};
+
+declare type NotepadNode = {
+    id: string;
+    content: NotepadContent;
+};
+
+declare type NotepadReportType = {
+    id: string;
+    title: string;
+};
+
+export { }