الميزات والمنطق البرمجي Features & Business Logic

تطبيق MRE CashBook بيحفظ بيانات مالية حساسة، عشان كدة كان لازم يكون فيه نظام أمان قوي بيعتمد على بصمة الصيد أو الوجه (Biometrics).

class AuthGuardScreen extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return FutureBuilder(
      future: sl().authenticate(),
      builder: (context, snapshot) {
        if (snapshot.data == true) return const MainScreen();
        return const LockScreen(); // شاشة القفل لو فشل
      },
    );
  }
}

لاحظ إننا استخدمنا الـ LocalAuthService اللي تم حقنه عن طريق الـ DI. دي ميزة إن كل حاجة تكون منفصلة وسهلة الاختبار.

الكتاب هو الحاوية الأساسية لكل المعاملات. الميزة دي بتسمح للمستخدم بإضافة، تعديل، أو حذف الكتب، وكمان تحديد إذا كان الكتاب "داخل في العرض الإجمالي" ولا لأ.

on((event, emit) async {
  await repository.insertBook(event.book);
  // البلوك هيرد أوتوماتيك لأننا مسجلين في الـ Stream بتاع الداتابيز
});

النقطة السحرية هنا هي الـ Reactivity. إنت مش محتاج تطلب البيانات يدوياً بعد الإضافة، الداتابيز هي اللي بتبعت إشارة لـ GetIt، والبلوك بيستلمها ويحدث الشاشة.

هنا بيحصل الشغل الحقيقي. كل معاملة ليها مبلغ، وصف، تاريخ، وكمان ممكن يكون ليها مرفقات (صور أو فيديوهات).

ميزة الـ Auth في التطبيق بتعتمد على مكتبة local_auth. إحنا مغلفين المكتبة دي في خدمة اسمها LocalAuthService عشان تكون سهلة الاستخدام.

class LocalAuthService {
  final LocalAuthentication _auth = LocalAuthentication();

  Future authenticate() async {
    final bool canAuthenticateWithBiometrics = await _auth.canCheckBiometrics;
    final bool isDeviceSupported = await _auth.isDeviceSupported();

    if (!canAuthenticateWithBiometrics || !isDeviceSupported) return false;

    return await _auth.authenticate(
      localizedReason: 'يرجى تأكيد هويتك للوصول إلى بياناتك المالية',
      options: const AuthenticationOptions(
        stickyAuth: true,
        biometricOnly: true,
      ),
    );
  }
}

إدارة الكتب بتتم عن طريق BooksBloc. البلوك ده هو اللي بيتحكم في كل "الأرفف" المالية بتاعتك. تعالوا نشوف أهم الـ Events اللي فيه:

كل "كتاب" جواه مئات "المعاملات". الميزة دي هي الأدق في التطبيق لأنها بتتعامل مع أرقام، تواريخ، وملفات.

class EntriesBloc extends Bloc {
  final BookDao _bookDao;
  final EntryDao _entryDao;

  // بنسمع للتغييرات في المعاملات بتاع الكتاب ده بس
  void _onLoadEntries(LoadEntries event, Emitter emit) {
    _entriesSubscription?.cancel();
    _entriesSubscription = _entryDao.watchEntriesWithBook(event.bookId).listen(
      (entries) => add(OnEntriesUpdated(entries)),
    );
  }
}

لاحظ هنا إننا استخدمنا watchEntriesWithBook. ده استعلام SQL معقد (Join) بيجيب بيانات المعاملة ومعاها بيانات الكتاب المرتبط بيها في "خبطة واحدة".

المعاملة ممكن يكون ليها صور أو فيديوهات. إحنا مش بنحفظ الصور جوه الداتابيز (عشان مساحتها متكبرش)، إحنا بنحفظ "المسار" (Path) بتاع الصورة بس.

// إزاي بنعرض الصورة؟
Image.file(File(entry.attachmentPath!));

الـ Dashboard هو مراية المستخدم. هنا بيعرف هو كسبان ولا خسران، وفلوسه بتروح فين بالظبط.

void _calculateStats(List data) {
  double totalIncome = 0;
  double totalExpense = 0;

  for (var item in data) {
    if (item.book.isIncludedInTotal) {
      totalIncome += item.totalIncome;
      totalExpense += item.totalExpense;
    }
  }
  emit(DashboardLoaded(income: totalIncome, expense: totalExpense));
}

الإعدادات هي المكان اللي المستخدم بيطوع فيه التطبيق لمزاجه. إحنا بنستخدم AppSettingsCubit عشان نتحكم في الحاجات دي.

class AppSettingsCubit extends Cubit {
  void toggleTheme() {
    final newMode = state.themeMode == ThemeMode.light 
        ? ThemeMode.dark 
        : ThemeMode.light;
    emit(state.copyWith(themeMode: newMode));
    _saveThemePref(newMode);
  }

  void changeLanguage(Locale locale) {
    emit(state.copyWith(locale: locale));
    _saveLocalePref(locale);
  }
}

لاحظ إن التغيير بيسمع في التطبيق كله "لحظياً" لأننا بنستخدم BlocBuilder في أعلى نقطة في الـ Widget Tree (ملف main.dart).

إحنا بنعرض سياسة الخصوصية باستخدام webview_flutter. ده بيخلينا نحدث السياسة من غير ما نبعت تحديث جديد للأبلكيشن على الستور.

أقوى ميزة في MRE CashBook هي إنك تقدر تضيف حقول زيادة لأي معاملة (زي: اسم المورد، رقم الفاتورة، إلخ). إحنا معملناش ده بجدول واحد ثابت، إحنا عملنا نظام مرن جداً.

// إزاي بنجيب كل الحقول لمعاملة معينة؟
Future> getEntryWithFields(int entryId) {
  return (select(entries)..where((t) => t.id.equals(entryId)))
      .join([
        leftOuterJoin(entryFieldValues, entryFieldValues.entryId.equalsExp(entries.id)),
        leftOuterJoin(customFields, customFields.id.equalsExp(entryFieldValues.fieldId)),
      ]).get();
}

ده بيسمح للمستخدم بتحويل التطبيق لـ CRM صغير أو مخزن بسيط، وكل ده بفضل قوة الـ Joins في SQLite.

لما يكون عندك آلاف المعاملات، البحث بالعين بيكون مستحيل. إحنا عملنا محرك بحث "لحظي" (Debounced Search) بيفهم إنت بتكتب إيه وبيدور في الوصف، رقم المعاملة، وحتى الحقول المخصصة.

// في الـ Bloc، بنستخدم الـ Transformation عشان منعملش Search مع كل حرف
on(
  (event, emit) async {
    // استعلام SQL بسيط لكن فعال
    final results = await repository.searchEntries(event.query);
    emit(EntriesLoaded(results));
  },
  transformer: restartable(), // بيلغي البحث القديم لو كتبت حرف جديد بسرعة
);

إيه اللي حصل في التطبيق النهاردة؟ مين مسح الكتاب ده؟ سجل النشاطات هو "الصندوق الأسود" بتاع MRE CashBook.

class ActivityLogs extends Table {
  IntColumn get id => integer().autoIncrement()();
  TextColumn get action => text()(); // مثلاً: 'add_entry'
  TextColumn get description => text()(); // وصف بالعربي والإنجليزي
  DateTimeColumn get createdAt => dateTime()();
}

كل مرة بتعمل فيها عملية (Add, Update, Delete)، إحنا بنرمي "سطر" في الجدول ده. ده مش بس مفيد للمستخدم، ده كمان بيساعدنا في الـ Debugging لو حصلت مشكلة.

المستخدم غالباً بيحتاج يطبع كشف حساب أو يبعته للعميل. ميزة الـ PDF في MRE CashBook بتطلع ملفات منظمة، فيها براند التطبيق، وحسابات دقيقة.

class PdfExportService {
  Future generateReport(List entries, Book book) async {
    final pdf = pw.Document();
    
    pdf.addPage(
      pw.Page(
        build: (context) => pw.Column(
          children: [
            _buildHeader(book),
            _buildTable(entries),
            _buildFooter(), // فيه لينكات المبرمج والتايمستامب
          ],
        ),
      ),
    );
    return await _savePdf(pdf);
  }
}

عشان الجدول يكون سهل في القراءة، بنستخدم تقنية الـ Zebra Striping، وهي إننا نغير لون خلفية السطور بالتناوب (سطر أبيض وسطر رمادي فاتح).

// منطق التلوين
rowDecoration: index % 2 == 0 
    ? pw.BoxDecoration(color: PdfColors.grey100) 
    : null,

إيه اللي يحصل لو المستخدم غير موبايله؟ إحنا بنسمح للمستخدم "يصدر" (Export) ملف قاعدة البيانات بالكامل ويبعته على الواتساب أو الإيميل.

Future exportDatabase() async {
  final dbFile = await DatabaseProvider.getDatabaseFile();
  if (await dbFile.exists()) {
    await Share.shareXFiles(
      [XFile(dbFile.path)],
      text: 'MRE CashBook Database Backup',
    );
  }
}

الميزات في MRE CashBook مش شغالة في جزر منعزلة، هي بتكلم بعضها طول الوقت. الرسمة دي بتوضح المسار:

graph TD
    A[Auth Feature] -- Success --> B[Main Screen]
    B --> C[Books Feature]
    C -- Book Selected --> D[Entries Feature]
    D -- New Entry --> E[Database]
    E -- Stream Update --> F[Dashboard Feature]
    E -- Sync --> G[Backup/Export]
    D -- Generate --> H[PDF Service]

لاحظ إن الـ Database هي القلب اللي كل الميزات بتسمع منه. ده بيخلي الواجهة دايماً متحدثة (Reactive UI).

أشهر المشاكل اللي ممكن تقابلك وأنت بتطور ميزات جديدة:

دي المصطلحات اللي بنستخدمها كفريق تطوير عشان نوصف الميزات:

• Biometrics: التحقق الحيوي عن طريق البصمة أو الوجه.
• Reactivity: قدرة الواجهة على التحديث التلقائي بمجرد تغيير البيانات.
• Cascade Delete: الحذف المتتابع (مثلاً حذف المعاملات عند حذف الكتاب).
• Debounce: تأخير تنفيذ العملية (زي البحث) لغاية ما المستخدم يبطل كتابة.
• Zebra Striping: تلوين سطور الجدول بألوان مختلفة لسهولة القراءة.
• Custom Fields: حقول إإضافية بيعرفها المستخدم حسب حاجته.
• Audit Log: سجل تتبع لكل العمليات اللي حصلت في السيستم.
• Sticky Auth: بقاء عملية التحقق نشطة حتى لو خرجت من التطبيق ورجعت بسرعة.
• Pie Chart: الرسم البياني الدائري اللي بيوضح توزيع المصاريف.
• Export: تصدير البيانات بصيغة .sqlite أو .pdf.
• SQL Join: ربط أكتر من جدول ببعض عشان نجيب بيانات متكاملة.
• PDF Layout: تصميم شكل الملف اللي هيطلع للمطبعة أو للمشاركة.
• Cubit: نسخة خفيفة ومبسطة من الـ Bloc لإدارة الحالة البسيطة.
• Repository: الطبقة اللي بتفصل بين الـ Bloc ومصدر البيانات (DB/API).
• UI Overlay: طبقة فوق الواجهة لعرض تنبيهات أو قوائم اختيار سريعة.

الجدول ده بيلخص كل اللي التطبيق بيقدر يعمله، والملفات المسؤولة عن كل جزء:

عشان تبني ميزة صح في MRE CashBook، إحنا بنمشي على خطوات ثابتة بتضمن الجودة:

اختبر نفسك وشوف مدى فهمك لأجزاء التطبيق:

 [ User Action ] ──▶ [ AddEntry Screen ] ──▶ [ EntriesBloc ]
                                                 │
       ┌─────────────────────────────────────────┘
       ▼
 [ EntryDao (Drift) ] ──▶ [ SQLite DB File ]
       │
       ▼ (Reactive Stream Update)
       │
 [ DashboardCubit ] ──▶ [ Stats Map ] ──▶ [ FlChart UI ]
        

التدفق ده بيحصل في أجزاء من الثانية، وده اللي بيدي إحساس الـ Smoothness في التطبيق.

إحنا مش بنوقف تطوير. دي أهم الميزات اللي بنخطط لإضافتها في الإصدارات الجاية:

• Cloud Sync: ربط الحسابات بـ Firebase عشان البيانات تكون متاحة على أكتر من جهاز.
• Dynamic Tax Calculation: حساب الضرائب والقيمة المضافة أوتوماتيك لكل معاملة.
• OCR Scan: تصوير الفاتورة بالموبايل والتطبيق يستخرج منها المبلغ والتاريخ لوحده باستخدام الـ AI.
• CSV/Excel Export: تصدير البيانات بصيغة إكسيل عشان المحاسبين يقدروا يشتغلوا عليها.

عشان تحافظ على نظافة الكود في MRE CashBook، لازم تتبع القواعد دي وأنت بتبني أي ميزة جديدة:

تخيل إنك عاوز تضيف ميزة "الاشتراكات الشهرية" (Subscriptions). فكر في الخطوات دي:

تعال نتبع رحلة "حذف كتاب" من ساعة ما المستخدم يدوس على الزرار لغاية ما يختفي من الشاشة:

قبل ما تقول إن الميزة دي "خيرة"، اتأكد إنك عملت الـ 15 حاجة دول:

الفصل ده كان الأطول والأهم في كورس MRE CashBook. لأن الميزات هي اللي بتقدم القيمة للمستخدم في الآخر. لما بتنفذ ميزة بنظام الـ Clean Architecture وتراعي فيها الأداء والأمان، إنت مش بس بتبني تطبيق، إنت بتبني "أداة" المستخدم يقدر يعتمد عليها في حياته اليومية.

في الفصل الجاي: هننقل من "المنطق" لـ "الجمال". هنعرف إزاي عملنا نظام الثيمات (UI Theming) اللي بيخلي التطبيق مريح للعين في كل الأوقات.

الميزات هي قلب التطبيق. تنظيمها في فولدرات منفصلة (Clean Architecture) هو اللي بيخليه يعيش سنين بدون مشاكل.