qaryaty-smart-village README

The project's README from github.com/alhinawi/qaryaty-smart-village. As one markdown file: README.md.

🏡 قريتي - تطبيق القرية الذكية (Qaryati - Smart Village)

خدمات القرية الذكية في جيبك — تطبيق ويب متطور وسريع مبني بأحدث تقنيات React 19 وTypeScript وVite وZustand لإتاحة كافة خدمات ومحلات أهالي القرية بسهولة وسرعة.

📖 نظرة عامة (Overview)

قريتي هو تطبيق ويب تجاوبي بالكامل (Mobile-First & Fully Responsive) موجه لأهالي القرى، يتيح طلب الخدمات اليومية (مخبز، خضار وفواكه، شوي سمك، سوبرماركت، حرفيين، توصيل مدارس، أكل بيتي) مع تتبع فوري للطلبات، وسلة مشتريات ذكية، ونظام مكافآت ونقاط، وتقييمات حقيقية للمزودين.

✨ المميزات الرئيسية (Key Features)

  1. تصميم Mobile-First وتجاوبي شامل (Responsive Design):
    • متوافق من أصغر شاشات الموبايل (320px, 360px, 390px, 430px) وحتى الشاشات الكبيرة (768px, 1024px, 1280px, 1440px+).
  2. إدارة الحالة باستخدام Zustand (State Management):
    • useCartStore: إدارة سلة التسوق، حساب الإجمالي، وتأثير الهزّة التفاعلي (Wiggle animation).
    • useOrderStore: تتبع مراحل الطلب (استلام، تجهيز، في الطريق، تم التسليم) وتقييم الخدمات.
    • useUserStore: بيانات الحساب، نظام المفضلة، ونقاط المكافآت.
    • useUIStore: التبويبات النشطة، الإشعارات الفورية، وسجل البحث المحفوظ.
  3. التحقق من البيانات بواسطة Zod (Validation):
    • التحقق الصارم من أرقام الموبايل المصرية وعناوين القرية وصحة أكواد الخصم.
  4. دعم PWA والعمل بدون إنترنت (Progressive Web App):
    • إمكانية التثبيت كتطبيق مستقل على أجهزة الموبايل مع Service Worker.
  5. نظام تقييم ومكافآت (Ratings & Reward Points):
    • تقييم 5 نجوم بعد إتمام الطلب مع كسب نقاط مكافآت لاستبدالها بتوصيل مجاني.
  6. سجل بحث وتفضيلات محفوظة (localStorage Persistence):
    • حفظ آخر 5 عمليات بحث واقتراحها تلقائياً.
  7. كود الخصم الترويجي:
    • استخدام كود QARYA1 للحصول على خصم 100% على أول طلب.

🛠️ متطلبات التشغيل (Prerequisites)

🚀 خطوات التثبيت والتشغيل (Getting Started)

1. تثبيت الحزم (Install Dependencies)

pnpm install

2. تشغيل السيرفر المحلي (Run Development Server)

pnpm run dev

سيعمل التطبيق على المنفذ الافتراضي: http://localhost:5173/

3. بناء نسخة الإنتاج (Production Build)

pnpm run build

📁 هيكل المشروع (Project Structure)

qaryati-smart-village/
├── public/                 # الملفات الثابتة والأيقونات
├── src/
│   ├── assets/             # الصور والأيقونات
│   ├── components/
│   │   ├── layout/         # Header, BottomNav, PageWrapper, SplashScreen, Drawers
│   │   ├── shared/         # ServiceCard, ShopCard, CategoryChip, RatingModal
│   │   └── ui/             # Button, Input, Modal, Badge, Skeleton, EmptyState, Toast
│   ├── data/               # services.ts, shops.ts, categories.ts, features.ts
│   ├── hooks/              # useLocalStorage, useModal, useCart, useOrders, useSplashScreen
│   ├── pages/
│   │   ├── Home/           # الصفحة الرئيسية بكافة أقسامها
│   │   ├── Orders/         # صفحة سجل وتتبع الطلبات
│   │   ├── Favorites/      # صفحة الخدمات المفضلة
│   │   ├── Messages/       # صفحة المحادثات المباشرة
│   │   └── Profile/        # صفحة الحساب ونقاط المكافآت
│   ├── stores/             # Zustand Stores (useCartStore, useOrderStore, useUIStore, useUserStore)
│   ├── types/              # TypeScript Interfaces & Types
│   ├── utils/              # helpers.ts, theme.ts, validators.ts (Zod)
│   ├── App.tsx             # التطبيق الرئيسي وتوزيع التبويبات والصفحات
│   ├── main.tsx            # نقطة انطلاق التطبيق
│   └── index.css           # ملف التنسيقات الأساسي والتصميم التجاوبي
├── index.html              # ملف الـ HTML الأساسي مع وسوم الـ SEO
├── package.json            # تعريف الحزم والتبعيات
├── tsconfig.json           # إعدادات TypeScript الصارمة
└── vite.config.ts          # إعدادات Vite و PWA

📜 الترخيص (License)

هذا المشروع مخصص لأغراض التطوير والعرض لصالح مشروع قريتي - القرية الذكية.

Qaryaty

qaryaty-smart-village (alhinawi/qaryaty-smart-village)

Searching Database…

73 ·GitHub
Qaryaty-smart-village
Что это?Qaryaty (Smart Village) — это mobile-first PWA для заказа и отслеживания повседневных местных деревенских услуг: пекарня, овощи, рыба на гриле, супермаркет, мастера-ремесленники, доставка в школу и домашняя еда; есть отслеживание заказов в реальном времени, умная корзина и система вознаграждений.
Это нативное приложение или сайт, который я открываю в браузере?Это веб-приложение, сделанное как Progressive Web App (PWA): оно работает в браузере, но может устанавливаться на телефон как отдельное приложение с офлайн-поддержкой через Service Worker.
Как запустить его локально?Установите зависимости через pnpm, затем запустите dev-сервер Vite (pnpm run dev); продакшен-сборка делается командой 'tsc -b && vite build'.
Что нужно установить перед запуском?Нужны Node.js v18+ (рекомендуется v20 или v22) и pnpm v9+ или v11+.
Можно ли это использовать с точки зрения лицензии, или это просто демо?В README сказано, что проект предназначен только для разработки и демонстрации в рамках проекта Qaryaty Smart Village, то есть он не под стандартной открытой лицензией и, возможно, не рассчитан на повторное использование в продакшене.
Работает ли он без подключения к интернету?Да, как PWA он поддерживает офлайн-работу через Service Worker после установки.
Какие услуги реально можно заказать через приложение?Приложение закрывает повседневные нужды деревни: пекарня, овощи и фрукты, рыба на гриле, супермаркет, мастера-ремесленники, доставка в школу и домашняя еда.
Как устроена система вознаграждений?После выполнения заказа пользователи оценивают его максимум на 5 звёзд и получают бонусные баллы, которые можно обменять на бесплатную доставку.
Есть ли промокод, чтобы попробовать?Да, код QARYA1 даёт скидку 100% на первый заказ.
Как устроено состояние приложения внутри?Приложение использует четыре стора Zustand: useCartStore для корзины, useOrderStore для отслеживания заказов и оценок, useUserStore для профиля/избранного/баллов и useUIStore для вкладок, уведомлений и истории поиска.
What are similar projects?truanayangi, workbox, openGym, soybean-admin, bible-strong-avatar-lab, vuestic-admin, commerce, ace-step-ui
Which topics is it in?service-worker, progressive-web-app, pnpm, ecommerce, responsive, state-management, pwa, offline-first, tailwindcss, vite, offline, beginner-friendly
Creator
alhinawi
Size
0.3 MB
Stars
73
Updated
CommitAug 21
Age
2mo
Commits · 90 Days