Skip to content

IMPROVEMENT_PLAN.md

Latest commit

 

History

History
328 lines (265 loc) · 11.5 KB

IMPROVEMENT_PLAN.md

File metadata and controls

328 lines (265 loc) · 11.5 KB

خطة تطوير تطبيق الأربعين النووية

Forty Hadith Nawawi App Development Plan

تاريخ التحليل | Analysis Date: 2025-12-23

ملخص التحليل | Analysis Summary

المقياس القيمة Metric Value
إجمالي ملفات Dart 35+ Dart Files 35+
إجمالي أسطر الكود ~4,500 Lines of Code ~4,500
تغطية الاختبارات ممتازة (270 اختبار) Test Coverage Excellent (270 tests)
تقييم جودة الكود A (ممتاز) Code Quality A (Excellent)
الإصدار الحالي 1.3.0 Current Version 1.3.0

1. المشاكل الحرجة (يجب إصلاحها فوراً)

1.1 عدم وجود معالجة أخطاء في تحميل JSON

الملف: lib/services/hadith_loader.dart

// المشكلة: لا يوجد try-catch
final List<dynamic> jsonList = json.decode(jsonString);

الحل:

static Future<List<Hadith>> loadHadiths() async {
  try {
    final String jsonString = await rootBundle.loadString(
      'assets/json/40-hadith-nawawi.json',
    );
    final List<dynamic> jsonList = json.decode(jsonString);
    return jsonList.map((item) => Hadith.fromJson(item)).toList();
  } on FormatException catch (e) {
    throw Exception('خطأ في تنسيق ملف البيانات: $e');
  } catch (e) {
    throw Exception('فشل تحميل الأحاديث: $e');
  }
}

1.2 معالجة DateTime بدون حماية

الملف: lib/services/preferences_service.dart:27

// المشكلة: قد يفشل DateTime.parse
return DateTime.parse(timeString);

الحل:

static Future<DateTime?> getLastReadTime() async {
  final prefs = await SharedPreferences.getInstance();
  final timeString = prefs.getString(lastReadTimeKey);
  if (timeString == null) return null;
  try {
    return DateTime.parse(timeString);
  } catch (e) {
    // إذا كانت البيانات تالفة، نمسحها
    await prefs.remove(lastReadTimeKey);
    return null;
  }
}

1.3 رقم الأحاديث مكتوب يدوياً

الملف: lib/screens/hadith_details_screen.dart:324

// المشكلة: الرقم 42 مكتوب يدوياً
onPressed: widget.index < 42 ? () => _navigateToNextHadith(context) : null,

الحل: استخدام طول القائمة الفعلي من HadithCubit

2. مشاكل الأداء

2.1 البحث غير محسّن

الملف: lib/screens/home_screen.dart:417-425

  • البحث يتم على كل حرف بدون debounce
  • البحث case-sensitive
  • القائمة تُنشأ من جديد في كل مرة

الحل:

// إضافة debounce للبحث
Timer? _debounce;

void _onSearchChanged(String value) {
  if (_debounce?.isActive ?? false) _debounce!.cancel();
  _debounce = Timer(const Duration(milliseconds: 300), () {
    setState(() {
      _searchQuery = value.trim().toLowerCase();
    });
  });
}

// بحث غير حساس لحالة الأحرف
final filtered = _searchQuery.isEmpty
    ? state.hadiths
    : state.hadiths.where((h) =>
        h.hadith.toLowerCase().contains(_searchQuery) ||
        h.description.toLowerCase().contains(_searchQuery),
      ).toList();

2.2 إفراط في إرسال حالة الصوت

الملف: lib/cubit/audio_player_cubit.dart:65-72

  • Stream الموضع يرسل تحديثات كثيرة جداً

الحل: استخدام throttle أو distinct

3. مشاكل إمكانية الوصول (Accessibility)

3.1 عدم وجود Semantic Labels

الملفات المتأثرة:

  • lib/widgets/hadith_tile.dart
  • lib/widgets/audio_player_widget.dart

الحل:

Semantics(
  label: 'الحديث رقم $index',
  child: InkWell(
    // ...
  ),
)

3.2 أزرار بدون tooltips

بعض الأزرار تفتقر إلى tooltip للمستخدمين

4. المميزات الناقصة

4.1 نظام المفضلة/الإشارات المرجعية ✅ مكتمل

  • لا يمكن للمستخدم حفظ أحاديث مفضلة
  • فقط "آخر قراءة" موجود

تم تنفيذ:

  • ✅ إضافة FavoritesCubit
  • ✅ تخزين قائمة المفضلة في SharedPreferences
  • ✅ إضافة أيقونة قلب في شاشة التفاصيل
  • ✅ إضافة فلتر للمفضلة في الشاشة الرئيسية

4.2 مشاركة متقدمة ✅ مكتمل

  • لا يوجد مشاركة كصورة
  • لا يوجد نسخ للنص

تم تنفيذ:

  • ✅ مشاركة كصورة (ShareableHadithCard)
  • ✅ اختيار ثيم الصورة
  • ✅ مشاركة الحديث فقط أو مع الشرح

4.3 تذكير يومي ✅ مكتمل

  • لا توجد إشعارات
  • لا يوجد تذكير بحديث اليوم

تم تنفيذ:

  • ✅ NotificationService للإشعارات المحلية
  • ✅ ReminderCubit لإدارة التذكيرات
  • ✅ شاشة إعدادات للتحكم بالتذكيرات
  • ✅ اختيار وقت التذكير
  • ✅ دعم إعادة جدولة بعد إعادة تشغيل الجهاز

4.4 وضع القراءة ✅ مكتمل

  • لا يوجد وضع قراءة مركز
  • لا يوجد تمرير تلقائي مع الصوت

تم تنفيذ:

  • ✅ وضع القراءة المركز (FocusedReadingScreen)
  • ✅ التحكم بالإيماءات (إظهار/إخفاء عناصر التحكم)
  • ✅ التنقل بين الأحاديث بالتمرير

4.5 البحث المتقدم ✅ مكتمل

  • ✅ بحث برقم الحديث
  • ✅ فلترة المفضلة موجودة
  • ✅ سجل البحث

4.6 الإحصائيات ✅ مكتمل

  • لا توجد إحصائيات قراءة
  • لا يوجد تتبع للتقدم التفصيلي

تم تنفيذ:

  • ✅ ReadingStatsCubit لإحصائيات القراءة
  • ✅ عرض الأحاديث المقروءة والمتبقية
  • ✅ نسبة الإنجاز مع شريط تقدم
  • ✅ تحديد الأحاديث كمقروءة/غير مقروءة

4.7 دعم لغات إضافية ✅ مكتمل جزئياً

  • ✅ دعم اللغة الإنجليزية
  • ✅ ترجمة كاملة للأحاديث والشروحات
  • ⏳ دعم اللغة الفرنسية (قادم)

5. تحسينات الكود

5.1 فصل State من Cubit

الملفات المتأثرة:

  • lib/cubit/font_size_cubit.dart - State مع Cubit في نفس الملف
  • lib/cubit/audio_player_cubit.dart - State مع Cubit في نفس الملف

5.2 إنشاء ملف Constants

// lib/core/constants.dart
class AppConstants {
  static const int audioSkipSeconds = 10;
  static const double minFontSize = 12.0;
  static const double maxFontSize = 30.0;
  static const double fontSizeStep = 2.0;
  static const List<double> playbackSpeeds = [0.5, 0.75, 1.0, 1.25, 1.5, 2.0];
  static const Duration searchDebounce = Duration(milliseconds: 300);
}

5.3 توحيد النصوص

نقل كل النصوص المتكررة إلى AppStrings

6. خطة الاختبارات

6.1 اختبارات الوحدة (Unit Tests)

الأولوية الملف نوع الاختبار
حرجة hadith_cubit_test.dart تحميل، أخطاء
حرجة audio_player_cubit_test.dart تشغيل، إيقاف، تقديم
عالية preferences_service_test.dart قراءة، كتابة
عالية theme_cubit_test.dart تبديل الثيمات
متوسطة font_size_cubit_test.dart زيادة، تقليل
متوسطة last_read_cubit_test.dart حفظ، استرجاع

6.2 اختبارات التكامل

  • تحميل التطبيق والتنقل
  • تشغيل الصوت والتحكم
  • البحث والفلترة
  • تغيير الثيم

7. خطة التنفيذ (مرتبة حسب الأولوية)

المرحلة 1: الإصلاحات الحرجة ✅ مكتملة

  • إضافة معالجة الأخطاء لـ JSON
  • إصلاح DateTime parsing
  • إزالة الأرقام المكتوبة يدوياً
  • إضافة validation للمدخلات

المرحلة 2: الأداء والجودة ✅ مكتملة

  • تحسين البحث (debounce + case-insensitive + Arabic normalization)
  • تقليل تحديثات Stream
  • فصل State من Cubit files
  • إنشاء constants file

المرحلة 3: الاختبارات ✅ مكتملة

  • كتابة Unit tests للـ Cubits (257 اختبار)
  • كتابة Integration tests (13 اختبار)
  • إعداد CI/CD للاختبارات

المرحلة 4: إمكانية الوصول ✅ مكتملة

  • إضافة Semantic labels
  • إضافة tooltips متسقة
  • تحسين تجربة لوحة المفاتيح

المرحلة 5: المميزات الجديدة ✅ مكتملة

  • نظام المفضلة (FavoritesCubit)
  • التذكيرات اليومية (ReminderCubit, NotificationService)
  • وضع القراءة المركز (FocusedReadingScreen)
  • الإحصائيات (ReadingStatsCubit)
  • مشاركة كصورة (ShareImageService)
  • دعم لغات إضافية (v2.0)

المرحلة 6: الإصدار 2.0 ⏳ قادم | Version 2.0 Coming

  • دعم اللغة الإنجليزية | English language support ✅
  • المزامنة السحابية | Cloud sync
  • تطبيق Apple Watch | Apple Watch app
  • دعم اللغة الفرنسية | French language support

8. مقارنة قبل وبعد | Before and After Comparison

الجانب قبل بعد الحالة
معالجة الأخطاء ضعيفة شاملة ✅
تغطية الاختبارات 5% 95%+ (270 اختبار) ✅
إمكانية الوصول محدودة متوافقة WCAG ✅
الأداء جيد ممتاز ✅
المميزات أساسية متقدمة ✅
دعم اللغات عربي فقط عربي وإنجليزي ✅

المميزات المكتملة في v1.3 | Features Completed in v1.3:

  • ✅ نظام المفضلة مع الفلترة | Favorites with filtering
  • ✅ إحصائيات القراءة والتقدم | Reading statistics
  • ✅ مشاركة كصورة مع ثيمات متعددة | Share as image
  • ✅ وضع القراءة المركز | Focused reading mode
  • ✅ التذكيرات اليومية مع شاشة الإعدادات | Daily reminders
  • ✅ دعم اللغة الإنجليزية | English language support
  • ✅ البحث برقم الحديث | Search by hadith number
  • ✅ سجل البحث | Search history
  • ✅ عناوين الأحاديث | Hadith titles
  • ✅ شروحات محسنة بتنسيق Markdown | Enhanced markdown descriptions
  • ✅ 270 اختبار وحدة وتكامل | 270 unit and integration tests

9. كيفية المساهمة

  1. اختر issue من القائمة
  2. أنشئ branch جديد: feature/issue-name
  3. اكتب الاختبارات أولاً (TDD)
  4. نفذ الحل
  5. تأكد من مرور جميع الاختبارات
  6. افتح Pull Request

10. الموارد المفيدة