qaryaty-smart-village README

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

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

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

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

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

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

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

Node.js: إصدار v18+ (يوصى بـ v20 أو v22).
pnpm: إصدار v9+ أو v11+.

🚀 خطوات التثبيت والتشغيل (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

73 ·GitHub

Qaryaty-smart-village

这是什么？

Qaryaty（Smart Village）是一个移动优先的 PWA，用于订购和跟踪村庄里的日常本地服务，比如面包房、生鲜蔬果、烤鱼、超市、手艺人、学校配送和家常饭菜，并带有实时订单跟踪、智能购物车和奖励系统。

这是原生应用，还是我在浏览器里打开的网站？

它是一个以渐进式 Web 应用（PWA）形式构建的 Web 应用，也就是说它运行在浏览器中，但也可以通过 Service Worker 作为独立应用安装到手机上，并支持离线使用。

怎么在本地把它跑起来？

用 pnpm 安装依赖，然后运行 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 可以让首单享受全额折扣。

应用状态在底层是如何组织的？

应用使用了四个 Zustand store：useCartStore 管理购物车，useOrderStore 管理订单跟踪和评分，useUserStore 管理个人资料/收藏/积分，useUIStore 管理标签页、通知和搜索历史。

What are similar projects?

truanayangi, Ledgerify, workbox, openGym, soybean-admin, bible-strong-avatar-lab, vuestic-admin, commerce

Which topics is it in?

service-worker, progressive-web-app, pnpm, responsive, ecommerce, state-management, pwa, offline-first, tailwindcss, vite, beginner-friendly, offline

Creator: alhinawi
Size: 0.3 MB
Stars: 73
Updated: CommitAug 21
Age: 2mo
Commits · 90 Days