نداء — دليل مبرمج الواجهة / Frontend engineer guide

1. الهيكل — لا تبنِ شاشات من الصفر مرتين

المستودع مونوريبو. التطبيقان رفيعان؛ المنطق والشاشات مشتركة.

apps/farmer_app     org.nidaa.user     AppKind.farmer
apps/admin_app      org.nidaa.admin    AppKind.admin
packages/shared_ui  BridgeApp + كل الشاشات
packages/core       HttpBridgeRepository + النماذج

main.dart في كل تطبيق ينشئ HttpBridgeRepository() ثم BridgeApp(kind: ..., repository: ...).

عنوان المختبر: packages/core/lib/src/lab_url.dart → http://174.138.29.61:18080/v1.

البناء الميداني يستخدم --dart-define=USE_HTTP=true وGOOGLE_SERVER_CLIENT_ID=....

العقد الوحيد مع الخادم

كل الطلبات تمر من HttpBridgeRepository الذي ينفّذ BridgeRepository. لا تستدعِ http من الشاشة مباشرة.

JSON UTF-8، الرأس Authorization: Bearer بعد الدخول.
المعرّفات BigInt تُرسل وتُقرأ نصوصاً: "id": "1".
رمز الوصول يُجدَّد تلقائياً عبر POST /auth/refresh عند 401.
الأخطاء: اعرض messageAr أو messageEn حسب repo.english.
الوسائط: uploadBytes ثم احفظ url. للعرض استخدم mediaAccessUrl (يضيف access_token للاستعلام).

2. المصادقة — اختلاف التطبيقين

تطبيق	حقل الدخول	من يُقبل
مزارع	هاتف + كلمة مرور	دور `farmer` فقط. ارفض مشرف/مالك محلياً.
إدارة	بريد + كلمة مرور	دور `admin` أو `owner` فقط. ارفض مزارع محلياً.

login() يرسل phone إن لم يحتوِ المعرّف على @، وإلا email.

POST /v1/auth/login
{ "phone": "0120000001", "password": "LabBridge#2026" }
{ "email": "admin.lab@nidaa.local", "password": "LabBridge#2026" }

الاستجابة إما جلسة status: ok أو otp_required أو phone_required (بعد قوقل/فيسبوك بلا هاتف).

حسابات @nidaa.local تتجاوز OTP في المختبر. فاطمة 0120000004 هاتفها غير موثّق لكنها تدخل لأن البريد مختبري؛ المشرف يوثّق الرقم من تفاصيل المزارع.

موقوف (عمر 0120000005): الخادم يرفض الدخول. لا تحاول «إصلاح» ذلك في الواجهة.

بعد الجلسة

احفظ access/refresh في FlutterSecureStorage (المفاتيح nidaa.access / nidaa.refresh / nidaa.user).
restoreSession() يعيد المستخدم إن وُجد رمز صالح.
GET /auth/me يحدّث الأهلية والملف.

3. خريطة الشاشات → المستودع

التبويبات تُبنى في ShellPage حسب AppKind وuser.role وuser.supportEligible.

الشاشة	متى تظهر	استدعاءات أساسية
الرئيسية	دائماً	`content()`
الأسعار	دائماً	`cropPrices()` — الكتابة: `createCropPrice` / `updateCropPrice`
الإرشاد / المعلومات	دائماً	`content(stage:, kind:)` — الكتابة: `createContent` / `publishContent`
الدفعات	مزارع + أهلية	`myPayments()` `myBank()` `submitBank()` `myQr()` `getPayment()`
المزارعون	إدارة	`searchFarmers` `getFarmer` `reviewPhone` `reviewBank` `setEligibility` `setPaymentStatus` `reopenPayment` `resetFarmerPayments` `suspendFarmer` `deleteFarmer`
المحاصيل	إدارة	`lookups()` `createCrop` `createMarket`
مسح QR	إدارة (أيقونة العنوان)	`verifyQr(token)`
لوحة المالك	owner فقط	`ownerDashboard` `listBackups` `createBackup` `restoreBackup` `backupSchedule`
الإشعارات	دائماً	`notifications` `markRead` — إن وُجد `paymentId` افتح `PaymentDetailPage`
الملف	دائماً	`updateProfile` `setLang`

قواعد أعمال يجب احترامها في الواجهة

لا تُظهر تبويب الدفعات إن supportEligible != true.
لا تملأ مبلغ الدفعة مسبقاً. حقل المبلغ + رقم العملية + صورة الإشعار عند «إتمام الصرف».
البنك قيد المراجعة: انسخ «تم رفع البيانات، في انتظار التوثيق» — لا تطلب الرفع ثانية إلا إذا طُلب تحديث.
الأهلية بعد هاتف موثّق وملف مكتمل. البنك ليس شرطاً لهذه الخطوة.
الدورة: مفتاح فريد (farmer, stage, cycle) للصفوف غير المحذوفة. بعد الحذف/الاستعادة لا تُنشئ دفعة مكررة يدوياً — استخدم API.
الحذف النهائي للمزارع: المالك فقط.
لا تغلف NavigationBar بـ Center. في ListView استخدم CompactLoader لا CircularProgressIndicator بعرض الشاشة.

4. اللغة والوضع الداكن

packages/shared_ui/lib/src/l10n.dart — الدالة t(context, ar, en). اللغة الافتراضية عربية حتى تنجح اختبارات الويدجت.

بدّل اللغة من الدخول أو الملف. تُحفظ في التخزين الآمن nidaa.lang.
منشورات الإرشاد تبقى بنص المؤلف. الإشعارات تختار titleEn/bodyEn عند الإنجليزية.
الوضع الداكن محلي على الجهاز، ليس من الخادم.

5. كيف تضيف ميزة

أضف المسار في Nest ثم الدالة في BridgeRepository وHttpBridgeRepository.
حدّث النموذج في models.dart مع fromJson يتحمّل النصوص للأرقام.
أضف الشاشة في shared_ui واستخدم t() لكل نص واجهة.
اربط التبويب في ShellPage بشرط الدور/الأهلية.
لا تبنِ APK المزارع والإدارة معاً (OOM). ابنِ واحداً ثم انسخ إلى infra/caddy/apk/.

حسابات التجريب الحالية

مزارع أحمد   0120000001     LabBridge#2026
مزارعة فاطمة 0120000004     LabBridge#2026
مزارع عمر    0120000005     موقوف — لا يدخل
مشرف         admin.lab@nidaa.local
مالك         owner.lab@nidaa.local

تقرير المنتج بالشاشات: report.html. كتالوج REST: frontend-api.html.

1. Architecture — do not duplicate screens

Monorepo. Both apps are thin; UI and networking are shared.

apps/farmer_app     org.nidaa.user     AppKind.farmer
apps/admin_app      org.nidaa.admin    AppKind.admin
packages/shared_ui  BridgeApp + every screen
packages/core       HttpBridgeRepository + models

Each main.dart builds HttpBridgeRepository() then BridgeApp(kind: ..., repository: ...).

Lab origin is packages/core/lib/src/lab_url.dart → http://174.138.29.61:18080/v1.

Field APKs are built with --dart-define=USE_HTTP=true and the Google web client id.

Talk to the server only through BridgeRepository. Never call http from a widget. IDs are strings. Tokens refresh on 401. Show messageAr/messageEn from errors. Use mediaAccessUrl for files.

2. Auth differs by app

Farmer: phone + password, role farmer only. Admin: email + password, admin or owner only. Reject the wrong role locally even if the token is valid.

@nidaa.local skips OTP in the lab. Omar 0120000005 is banned — login must fail. Persist tokens in secure storage; restore on launch via /auth/me.

3. Screen map

ShellPage builds tabs from kind, role, and supportEligible. Payments tab is farmer-only and eligibility-gated. Owner dashboard is owner-only. QR scan is an app-bar action on admin.

Do not preset payment amounts. Amount + txn number + receipt image at payout.
Pending bank copy: data uploaded, waiting for verification.
Eligibility needs a verified phone and a complete profile — not a bank account.
Never wrap NavigationBar in Center. Use CompactLoader inside lists.
Hard delete is owner-only.

4. Locale

t(context, ar, en) in l10n.dart. Default locale is Arabic (widget tests). Published posts stay as authored. Notifications pick English fields when the UI is English. Dark mode is local.

5. Adding a feature

Nest route → BridgeRepository + HttpBridgeRepository.
Model fromJson that stringifies bigints.
Screen in shared_ui with t() on every chrome string.
Gate the tab in ShellPage.
Do not build both APKs in parallel (OOM). Copy the APK to infra/caddy/apk/.

Farmer Ahmed    0120000001     LabBridge#2026
Farmer Fatima   0120000004     LabBridge#2026
Farmer Omar     0120000005     banned
Admin           admin.lab@nidaa.local
Owner           owner.lab@nidaa.local

Product report: report.html. REST catalog: frontend-api.html.

دليل مبرمج الواجهة (فلاتر)

Frontend engineer guide (Flutter)