# مستندات کامل فنی و ساختاری سامانه مکتب‌خونه (MaktabKhaneh Full Context for LLMs)

نسخه سامانه: 3.0.2
زبان‌های پشتیبانی شده: فارسی (RTL)، انگلیسی
پشته فناوری: React 18, TypeScript, Tailwind CSS, Express.js (Node.js/Bun), SQLite (better-sqlite3/JSON memory sync), Google Gemini API, Bale Messenger API, Google Drive API

================================================================================
۱. ساختار مدل‌های داده‌ای (Data Models & Schemas)
================================================================================

### ۱.۱. مدل کاربر (User)
```typescript
interface User {
  id: string;                      // شناسه یکتا (مثلاً u_123456789)
  phone: string;                   // شماره موبایل معتبر (مثلاً 09121234567)
  password?: string;               // رمز عبور (هش‌شده یا ذخیره‌شده با امنیت)
  name: string;                    // نام و نام خانوادگی یا نام نمایشی
  avatar: string;                  // آدرس آواتار SVG یا تصویر آپلود شده
  role: 'student' | 'admin';      // نقش کاربر در سامانه
  status: 'pending' | 'approved' | 'suspended'; // وضعیت حساب کاربری
  className: string;               // نام کلاس یا شناسه کلاس مربوطه
  baleId?: string;                 // آیدی پیام‌رسان بله
  freeLoanQuota?: number;          // سهمیه امانت رایگان اهداشده توسط مدیر
  booksContributedCount: number;   // تعداد کتاب‌های اهداشده به سامانه
  booksReadCount: number;          // تعداد کتاب‌های خوانده‌شده
  rating: number;                  // میانگین امتیاز (بین ۱ تا ۵)
  ratingsCount: number;            // تعداد امتیازهای ثبت‌شده
  medals?: string[];               // نشان‌ها و مدال‌های کسب‌شده
  birthDate?: string;              // تاریخ تولد خورشیدی (YYYY/MM/DD)
  createdAt: string;               // تاریخ عضویت به صورت ISO string
}
```

### ۱.۲. مدل کتاب (Book)
```typescript
interface Book {
  id: string;                      // شناسه یکتا (مثلاً b_123456789)
  title: string;                   // عنوان کتاب
  author: string;                  // نام نویسنده / مترجم
  description: string;             // خلاصه یا معرفی کوتاه کتاب
  coverUrl: string;                // آدرس تصویر جلد یا پوستر پیش‌فرض
  category: string;                // دسته‌بندی و ژانر (داستان، علمی، تاریخی و...)
  ageGroup: 'کودک' | 'نوجوان' | 'جوان' | 'عمومی'; // رده سنی مجاز
  pageCount?: number;              // تعداد صفحات
  ownerId: string;                 // شناسه کاربر اهداکننده/مالک کتاب
  ownerName: string;               // نام اهداکننده
  ownerClass?: string;             // کلاس اهداکننده
  ownerAvatar?: string;            // تصویر اهداکننده
  status: 'available' | 'borrowed' | 'reserved' | 'lost'; // وضعیت امانت
  borrowerId?: string;             // شناسه کاربر امانت‌گیرنده فعلی
  borrowerName?: string;           // نام کاربر امانت‌گیرنده
  reviews?: BookReview[];          // نظرات و امتیازهای ثبت‌شده
  createdAt: string;
}
```

### ۱.۳. مدل درخواست امانت (LendingRequest)
```typescript
interface LendingRequest {
  id: string;                      // شناسه یکتا (مثلاً req_123456789)
  bookId: string;                  // شناسه کتاب درخواستی
  bookTitle: string;               // عنوان کتاب
  bookCover?: string;              // تصویر جلد کتاب
  ownerId: string;                 // شناسه امانت‌دهنده
  ownerName: string;               // نام امانت‌دهنده
  ownerClass?: string;             // کلاس امانت‌دهنده
  borrowerId: string;              // شناسه امانت‌گیرنده
  borrowerName: string;            // نام امانت‌گیرنده
  borrowerClass?: string;          // کلاس امانت‌گیرنده
  borrowerPhone?: string;          // شماره تماس امانت‌گیرنده
  status: 'pending' | 'accepted' | 'rejected' | 'delivered' | 'returned' | 'cancelled';
  trackingCode?: string;           // کد پیگیری واریز کارت به کارت
  paymentReceiptUrl?: string;      // تصویر فیش واریز
  deliveryLocation?: string;       // محل تحویل در مدرسه
  deliveryTime?: string;           // زمان تحویل
  requestDate: string;             // تاریخ ثبت درخواست
  acceptedDate?: string;           // تاریخ پذیرش
  deliveredDate?: string;          // تاریخ تحویل کتاب
  returnDeadline?: string;         // مهلت بازگرداندن (معمولاً ۷ روز)
  returnedDate?: string;           // تاریخ بازگشت قطعی
}
```

================================================================================
۲. رابط‌های برنامه‌نویسی سمت سرور (API Endpoints Overview)
================================================================================

- `GET /api/books`: دریافت لیست تمام کتاب‌ها با پشتیبانی از جستجو و فیلتر
- `POST /api/books`: ثبت کتاب جدید توسط کاربر
- `PUT /api/books/:id`: ویرایش اطلاعات کتاب
- `DELETE /api/books/:id`: حذف کتاب
- `GET /api/users`: لیست کاربران و دانش‌آموزان
- `POST /api/auth/register`: ثبت‌نام کاربر جدید
- `POST /api/auth/login`: ورود به سامانه با شماره و رمز عبور یا ورود از طریق بله
- `GET /api/requests`: دریافت درخواست‌های امانت
- `POST /api/requests`: ایجاد درخواست امانت جدید
- `PUT /api/requests/:id/status`: تغییر وضعیت درخواست (پذیرش، تحویل، بازگشت)
- `GET /api/classes`: لیست کلاس‌های فعال مدرسه
- `POST /api/classes`: ایجاد کلاس جدید
- `PUT /api/classes/:id`: ویرایش نام کلاس (همراه با به‌روزرسانی زنجیره‌ای تمامی کاربران)
- `GET /api/events`: لیست چالش‌ها و رویدادهای کتابخوانی
- `POST /api/ai/advisor`: مشاوره و پیشنهاد کتاب مبتنی بر هوش مصنوعی گوگل جیمینای

================================================================================
۳. قوانین و فرآیندهای تجاری (Business Rules & Workflows)
================================================================================

۱. چرخه پذیرش خانگی (Home Acceptance Flow):
   با توجه به سیاست‌های مدارس در خصوص عدم استفاده از تلفن همراه در طول ساعات درسی، فرآیند تایید درخواست‌های امانت به صورت ۱۲ ساعته طراحی شده تا دانش‌آموزان بتوانند بعد از بازگشت به منزل، درخواست‌ها را از طریق وب‌سایت بررسی کرده و هماهنگی لازم برای تحویل فردا در مدرسه را انجام دهند.

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

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

۴. اتصال به پیام‌رسان بله (Bale Bot Integration):
   سیستم مجهز به وب‌هوک و اتصال دوطرفه با بازوی رسمی بله (@Maktabkunebot) است و رویدادهای مهم مانند ثبت درخواست جدید، تایید امانت، سررسید بازگشت و ورود دو مرحله‌ای را از طریق بله به اطلاع دانش‌آموزان و مدیران می‌رساند.