feat(apps): نظام التصميم والمصادقة الكاملة — المرحلتان 2 و3

## تصحيح بنيوي أولاً بنية المرحلة 1 كانت تخالف docs/23 §1 المُلزِم. أُعيدت للشجرة المفروضة حرفياً: app.dart في الجذر · core/{config,build_config,di,router}.dart · core/{design,ui,l10n,api,storage,session}/ · features/<f>/{cubit,data,view}/ ## المرحلة 2 — نظام التصميم (docs/26) - core/design: tokens (مسافات/زوايا/حركة/أحجام — الشاشة لا تخترع رقماً) · typography (IBM Plex Sans Arabic + Inter محليّان، بأرقام tabular للأسعار والعدّادات) · TripzColors كـThemeExtension للأدوار الدلالية · buildTheme(brightness, locale) بمدخلين لا ثالث لهما - core/ui: 11 مكوّناً. TripzScaffold يحوّل status الـCubit وحده إلى skeleton/خطأ/فراغ/محتوى — فلا تكتب أي شاشة if (loading) - core/l10n: ARB عربي/إنجليزي + gen_l10n. لا نص مرئي داخل widget - SettingsCubit: المظهر واللغة. الاتجاه يتبع اللغة آلياً بلا Directionality مفروضة، وسقف تكبير النص 1.3 ## المرحلة 3 — المصادقة - طبقة الشبكة: تجديد استباقي بطلقة واحدة (عمر التوكن 15 دقيقة) · x-app-role · x-device-id من device_info_plus — يُرسَل الآن كي يُفعَّل علم الخادم لاحقاً بلا تعديل التطبيق - SessionCubit في core/session خلف واجهة SessionSource: الجلسة حالة على مستوى التطبيق لا ميزة، و core لا يستورد من features - LoginCubit بخطواته الخمس، ProfileCubit، وست شاشات: الشروط ← إذن الموقع ← الهاتف ← الرمز ← إكمال الملف ← هيكل الرئيسية من سيرو نُقل السلوك لا الكود: بوابتان قبل أي حقل إدخال · إعادة فحص الإذن عند العودة من إعدادات النظام · تحقّق الهاتف الثلاثي. وأُضيف ما ينقصه: عدّاد إعادة إرسال الرمز — بدونه تُحظر ثلاث ضغطات المستخدمَ خمس دقائق (docs/38 §2). قراران موثّقان في docs/37: لا packages/tripz_ui (الوثيقتان المُلزِمتان تفرضان core/design و core/ui داخل التطبيق)، والـCubit يُصدر رمز فشل لا نصّاً (يجمع بين docs/23 §3 و docs/26 §4). flutter analyze نظيف في التطبيقين · 48 ملف و3,140 سطر لكل تطبيق · الفرق بينهما أربعة ملفات فقط: build_config · config · ملفّا ARB. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
2026-08-04 21:42:19 +03:00
parent 0de8573d27
commit c52338f3bb
117 changed files with 6061 additions and 374 deletions
@@ -0,0 +1,38 @@
+import '../../../core/api/api_exception.dart';
+
+/// سبب الفشل كـ**رمز** لا كنصّ.
+///
+/// docs/23 §3 يقول إن الـCubit يحوّل خطأ الشبكة إلى رسالة عربية؛ وdocs/26 §4
+/// (الأحدث، وهو الذي «يفعّل قاعدة docs/23 §2 التي كانت بلا أداة») يوجب مرور
+/// كل نص مرئي بطبقة الترجمة. والـCubit لا يعرف `BuildContext` (docs/23 §3).
+/// الجمع بينها: الـCubit يُصدر الرمز، والواجهة تترجمه سطراً واحداً — فتبقى
+/// الشاشة بلا منطق، والنص بلغتين.
+enum AuthFailure {
+  /// رمز خاطئ أو منتهي الصلاحية.
+  invalidCode,
+
+  /// تجاوز عدد المحاولات — الخادم يُبطل الرمز فوراً (docs/38 §2).
+  tooManyAttempts,
+
+  /// تجاوز حدّ طلب الرمز: ثلاثة كل خمس دقائق.
+  rateLimited,
+
+  network,
+  timeout,
+  server,
+}
+
+extension AuthFailureX on ApiException {
+  AuthFailure toAuthFailure() {
+    if (isRateLimited) return AuthFailure.rateLimited;
+    if (kind == ApiErrorKind.network) return AuthFailure.network;
+    if (kind == ApiErrorKind.timeout) return AuthFailure.timeout;
+    if (isUnauthorized) {
+      // الخادم يفرّق بين «رمز خاطئ» و«محاولات كثيرة» بالنصّ وحده.
+      return message.contains('Too many')
+          ? AuthFailure.tooManyAttempts
+          : AuthFailure.invalidCode;
+    }
+    return AuthFailure.server;
+  }
+}
@@ -0,0 +1,169 @@
+import 'dart:async';
+
+import 'package:flutter_bloc/flutter_bloc.dart';
+import 'package:permission_handler/permission_handler.dart';
+import 'package:shared_preferences/shared_preferences.dart';
+
+import '../../../core/api/api_exception.dart';
+import '../../../core/config.dart';
+import '../data/auth_repository.dart';
+import 'auth_failure.dart';
+import 'login_state.dart';
+import 'phone_error.dart';
+
+/// تدفّق الدخول كاملاً: الشروط ← إذن الموقع ← الهاتف ← الرمز.
+///
+/// الـCubit لا يعرف Flutter: لا `BuildContext` ولا تنقّل ولا `SnackBar`
+/// (docs/23 §3). يُصدر حالة، والواجهة تتصرّف.
+class LoginCubit extends Cubit<LoginState> {
+  LoginCubit(this._repo, this._prefs) : super(const LoginState()) {
+    _resolveInitialStep();
+  }
+
+  final AuthRepository _repo;
+  final SharedPreferences _prefs;
+
+  static const _kAgreed = 'auth.agreed_terms';
+
+  Timer? _resendTimer;
+
+  @override
+  Future<void> close() {
+    _resendTimer?.cancel();
+    return super.close();
+  }
+
+  // ── البوابتان ──────────────────────────────────────────────────────────
+
+  void _resolveInitialStep() {
+    if (_prefs.getBool(_kAgreed) != true) {
+      emit(state.copyWith(step: LoginStep.agreement));
+      return;
+    }
+    emit(state.copyWith(step: LoginStep.permission, agreed: true));
+    unawaited(checkLocationPermission());
+  }
+
+  void toggleAgreement(bool value) => emit(state.copyWith(agreed: value));
+
+  Future<void> acceptAgreement() async {
+    if (!state.agreed) return;
+    await _prefs.setBool(_kAgreed, true);
+    emit(state.copyWith(step: LoginStep.permission));
+    await checkLocationPermission();
+  }
+
+  /// تُستدعى أيضاً عند **العودة من إعدادات النظام**: بلا إعادة الفحص تبقى
+  /// الشاشة عالقة بعد أن يمنح المستخدم الإذن يدوياً (حالة حافة من docs/39 §2).
+  Future<void> checkLocationPermission() async {
+    final status = await Permission.locationWhenInUse.status;
+    if (status.isGranted || status.isLimited) {
+      emit(state.copyWith(step: LoginStep.phone));
+      return;
+    }
+    emit(state.copyWith(
+      permissionPermanentlyDenied: status.isPermanentlyDenied,
+    ));
+  }
+
+  Future<void> requestLocationPermission() async {
+    final status = await Permission.locationWhenInUse.request();
+    if (status.isGranted || status.isLimited) {
+      emit(state.copyWith(step: LoginStep.phone));
+      return;
+    }
+    emit(state.copyWith(
+      permissionPermanentlyDenied: status.isPermanentlyDenied,
+    ));
+  }
+
+  Future<void> openSystemSettings() => openAppSettings();
+
+  // ── الهاتف ─────────────────────────────────────────────────────────────
+
+  void phoneChanged(String value) {
+    emit(state.copyWith(
+      phone: value,
+      clearPhoneError: true,
+      clearFailure: true,
+    ));
+  }
+
+  Future<void> submitPhone() async {
+    final error = validatePhone(state.phone);
+    if (error != null) {
+      emit(state.copyWith(phoneError: error));
+      return;
+    }
+    emit(state.copyWith(status: LoginStatus.submitting, clearFailure: true));
+    try {
+      await _repo.sendOtp(state.phone.trim());
+      emit(state.copyWith(status: LoginStatus.idle, step: LoginStep.otp));
+      _startResendCountdown();
+    } on ApiException catch (e) {
+      emit(state.copyWith(
+        status: LoginStatus.failure,
+        failure: e.toAuthFailure(),
+      ));
+    }
+  }
+
+  void editPhone() {
+    _resendTimer?.cancel();
+    emit(state.copyWith(
+      step: LoginStep.phone,
+      status: LoginStatus.idle,
+      resendIn: 0,
+      clearFailure: true,
+    ));
+  }
+
+  // ── الرمز ──────────────────────────────────────────────────────────────
+
+  Future<void> resendOtp() async {
+    if (!state.canResend) return;
+    emit(state.copyWith(status: LoginStatus.submitting, clearFailure: true));
+    try {
+      await _repo.sendOtp(state.phone.trim());
+      emit(state.copyWith(status: LoginStatus.idle));
+      _startResendCountdown();
+    } on ApiException catch (e) {
+      emit(state.copyWith(
+        status: LoginStatus.failure,
+        failure: e.toAuthFailure(),
+      ));
+      // حتى عند الرفض بحدّ المعدّل نبدأ العدّاد — وإلا ضغط المستخدم مجدداً
+      // فوراً وعمّق الحظر.
+      _startResendCountdown();
+    }
+  }
+
+  Future<void> submitOtp(String code) async {
+    if (code.length != AppConfig.otpLength) return;
+    emit(state.copyWith(status: LoginStatus.submitting, clearFailure: true));
+    try {
+      final user = await _repo.verifyOtp(phone: state.phone.trim(), code: code);
+      _resendTimer?.cancel();
+      emit(state.copyWith(
+        status: LoginStatus.success,
+        step: LoginStep.done,
+        user: user,
+      ));
+    } on ApiException catch (e) {
+      emit(state.copyWith(
+        status: LoginStatus.failure,
+        failure: e.toAuthFailure(),
+      ));
+    }
+  }
+
+  void _startResendCountdown() {
+    _resendTimer?.cancel();
+    emit(state.copyWith(resendIn: AppConfig.otpResendCooldown.inSeconds));
+    _resendTimer = Timer.periodic(const Duration(seconds: 1), (timer) {
+      final next = state.resendIn - 1;
+      if (next <= 0) timer.cancel();
+      emit(state.copyWith(resendIn: next < 0 ? 0 : next));
+    });
+  }
+}
@@ -0,0 +1,87 @@
+import 'package:equatable/equatable.dart';
+
+import '../../../core/session/app_user.dart';
+import 'auth_failure.dart';
+import 'phone_error.dart';
+
+/// خطوات الدخول بالترتيب الميداني المثبت في سيرو (docs/39 §2): بوابتان
+/// كاملتان **قبل** أي حقل إدخال، ثم الهاتف فالرمز.
+enum LoginStep { agreement, permission, phone, otp, done }
+
+enum LoginStatus { idle, submitting, failure, success }
+
+class LoginState extends Equatable {
+  const LoginState({
+    this.step = LoginStep.agreement,
+    this.status = LoginStatus.idle,
+    this.phone = '',
+    this.agreed = false,
+    this.failure,
+    this.phoneError,
+    this.resendIn = 0,
+    this.permissionPermanentlyDenied = false,
+    this.user,
+  });
+
+  final LoginStep step;
+  final LoginStatus status;
+
+  /// الرقم كما أدخله المستخدم — الخادم يطبّعه، فلا نطبّعه نحن (docs/38 §2).
+  final String phone;
+
+  final bool agreed;
+  final AuthFailure? failure;
+  final PhoneError? phoneError;
+
+  /// ثوانٍ متبقّية قبل السماح بإعادة الإرسال. الخادم يحدّ بثلاثة طلبات كل
+  /// خمس دقائق، فالعدّاد ليس تجميلاً (docs/39 §2).
+  final int resendIn;
+
+  /// رُفض الإذن نهائياً — الحل الوحيد فتح إعدادات النظام.
+  final bool permissionPermanentlyDenied;
+
+  final AppUser? user;
+
+  bool get isSubmitting => status == LoginStatus.submitting;
+  bool get canResend => resendIn == 0 && !isSubmitting;
+
+  LoginState copyWith({
+    LoginStep? step,
+    LoginStatus? status,
+    String? phone,
+    bool? agreed,
+    AuthFailure? failure,
+    PhoneError? phoneError,
+    int? resendIn,
+    bool? permissionPermanentlyDenied,
+    AppUser? user,
+    bool clearFailure = false,
+    bool clearPhoneError = false,
+  }) {
+    return LoginState(
+      step: step ?? this.step,
+      status: status ?? this.status,
+      phone: phone ?? this.phone,
+      agreed: agreed ?? this.agreed,
+      failure: clearFailure ? null : (failure ?? this.failure),
+      phoneError: clearPhoneError ? null : (phoneError ?? this.phoneError),
+      resendIn: resendIn ?? this.resendIn,
+      permissionPermanentlyDenied:
+          permissionPermanentlyDenied ?? this.permissionPermanentlyDenied,
+      user: user ?? this.user,
+    );
+  }
+
+  @override
+  List<Object?> get props => [
+        step,
+        status,
+        phone,
+        agreed,
+        failure,
+        phoneError,
+        resendIn,
+        permissionPermanentlyDenied,
+        user,
+      ];
+}
@@ -0,0 +1,11 @@
+/// أخطاء تحقّق **محليّة** لرقم الهاتف — تُكتشف قبل أي نداء شبكة.
+/// الشروط الثلاثة منقولة من التحقّق المطبَّق ميدانياً في سيرو (docs/39 §2).
+enum PhoneError { empty, leadingZero, tooShort }
+
+PhoneError? validatePhone(String raw) {
+  final v = raw.trim();
+  if (v.isEmpty) return PhoneError.empty;
+  if (v.startsWith('0')) return PhoneError.leadingZero;
+  if (v.length < 9) return PhoneError.tooShort;
+  return null;
+}
@@ -0,0 +1,56 @@
+import 'package:flutter_bloc/flutter_bloc.dart';
+
+import '../../../core/api/api_exception.dart';
+import '../../../core/ui/view_status.dart';
+import '../data/auth_repository.dart';
+import '../../../core/session/app_user.dart';
+import 'auth_failure.dart';
+
+class ProfileState {
+  const ProfileState({
+    this.status = ViewStatus.success,
+    this.saving = false,
+    this.failure,
+    this.user,
+  });
+
+  final ViewStatus status;
+  final bool saving;
+  final AuthFailure? failure;
+  final AppUser? user;
+
+  ProfileState copyWith({
+    ViewStatus? status,
+    bool? saving,
+    AuthFailure? failure,
+    AppUser? user,
+    bool clearFailure = false,
+  }) {
+    return ProfileState(
+      status: status ?? this.status,
+      saving: saving ?? this.saving,
+      failure: clearFailure ? null : (failure ?? this.failure),
+      user: user ?? this.user,
+    );
+  }
+}
+
+/// إكمال الملف بعد أول دخول. عقد الخادم يقبل `{ name, language }` فقط
+/// (docs/38 §3) — لا اسم أول/أخير ولا بريد كما في سيرو (docs/39 §2).
+class ProfileCubit extends Cubit<ProfileState> {
+  ProfileCubit(this._repo) : super(const ProfileState());
+
+  final AuthRepository _repo;
+
+  Future<AppUser?> save(String name) async {
+    emit(state.copyWith(saving: true, clearFailure: true));
+    try {
+      final user = await _repo.updateProfile(name: name.trim());
+      emit(state.copyWith(saving: false, user: user));
+      return user;
+    } on ApiException catch (e) {
+      emit(state.copyWith(saving: false, failure: e.toAuthFailure()));
+      return null;
+    }
+  }
+}