feat: full site build — Project/Melody schema (Option A), admin CRUD, public sections, uploads, email+SMTP, internal analytics, legal pages, docs

2026-08-05 20:53:40 +02:00
parent d87f3033c6
commit c26f41511f
122 changed files with 15068 additions and 41 deletions
@@ -0,0 +1,75 @@
+# 🧱 الستاك الموصى به — diyaa.de
+
+> القرار: **Next.js فل ستاك + PostgreSQL + Prisma**. كل شي بمشروع واحد، مكوّنات قابلة لإعادة الاستخدام، ومكتبات محليّة (self-hosted) قدر الإمكان.
+>
+> **تحديث 2026-08-05:** المخطط اعتُمد على **الخيار A** — جدول `Project` موحّد + `Melody` منفصل (تفاصيله بـ `ARCHITECTURE.md §3`). الاحصائيات: **عدّادات داخلية أولاً** بدل Umami. راجع قرارات المراجعة بـ `REVIEW-2026-08-05.md`.
+
+---
+
+## الخلاصة السريعة
+
+| الطبقة | الاختيار | ليش |
+|--------|---------|-----|
+| **Framework** | Next.js 14 (App Router) — *موجود* | فرونت + باك اند بمشروع واحد، Server Actions & Route Handlers |
+| **اللغة** | TypeScript (strict) — *موجود* | أمان أنواع، أسهل للـ agents يفهموا الكود |
+| **التنسيق** | **Tailwind CSS** | معيار مطلوب، utility-first، متناسق |
+| **مكوّنات UI** | **shadcn/ui** (Radix + Tailwind) | مكوّنات محليّة (بتتنسخ للريبو مش package)، قابلة للتعديل الكامل |
+| **قاعدة البيانات** | **PostgreSQL** | علاقات قوية (أعمال ↔ تصنيفات ↔ ألحان)، ممتاز محلياً وعلى السيرفر |
+| **ORM** | **Prisma** | Schema واحد = مصدر الحقيقة، migrations منظّمة، type-safe |
+| **المصادقة (Admin)** | **Auth.js (NextAuth v5)** بـ Credentials | لوحة تحكم لك وحدك، بدون طرف ثالث |
+| **رفع الملفات** | تخزين محلي على الـ VPS (volume) + معالجة بـ **sharp** | صور الأعمال والسكرين شوتس والصوت — self-hosted، بدون S3 إلزامي |
+| **الصوت (الألحان)** | `<audio>` عنصر أصلي + مشغّل مخصّص (wavesurfer.js اختياري، محلي) | تشغيل الألحان بدون خدمة خارجية |
+| **الإيميلات** | **Nodemailer + SMTP** (STRATO أو أي مزوّد) | تحكّم كامل، بدون API طرف ثالث |
+| **قوالب الإيميل** | **React Email** | قوالب بمكوّنات React، متسقة مع باقي الستاك |
+| **الاحصائيات** | **عدّادات داخلية بسيطة** أولاً (Umami self-hosted لاحقاً لو لزم) | أخف، خصوصية أعلى، بدون خدمة إضافية للإطلاق الأول |
+| **الفاليديشن** | **Zod** | تحقّق من الفورمات والـ API، متكامل مع Prisma/TS |
+| **الفورمات** | **React Hook Form + Zod** | إدارة نماذج لوحة التحكم |
+| **النشر** | Docker + Traefik + Makefile — *موجود* | نفس المنظومة الحالية، بنضيف عليها Postgres |
+
+---
+
+## ليش Next.js فل ستاك (مش باك اند منفصل)؟
+
+- مشروع واحد = صيانة أسهل وتوثيق أوضح للـ agents.
+- **Server Actions** بتلغي الحاجة لطبقة API منفصلة لمعظم عمليات لوحة التحكم.
+- **Route Handlers** (`app/api/...`) لأي endpoints عامة (مثلاً webhook، رفع، RSS للألحان).
+- كل شي TypeScript من الداتابيس للواجهة = نوع واحد يمشي من `Prisma` لـ `React`.
+
+## ليش PostgreSQL + Prisma؟
+
+- بياناتك **علائقية**: عمل واحد ينتمي لتصنيف، تطبيق إله كذا سكرين شوت، لحن إله تصنيف (عربي/شرقي). Postgres مثالي لهيك.
+- Prisma بيخلّي `schema.prisma` **مصدر الحقيقة الوحيد** للبنية — وهاد بيخدم شرط التوثيق.
+- migrations منظّمة → تشتغل نفسها محلياً وعلى السيرفر.
+
+## مبدأ "كل المكتبات محليّة"
+
+- **shadcn/ui**: بتتنسخ داخل `components/ui/` — مش dependency خارجي، تحت سيطرتك بالكامل.
+- الخطوط: self-hosted عبر `next/font` (بدون Google Fonts CDN).
+- الأيقونات: `lucide-react` (bundled محلياً).
+- مشغّل الصوت والاحصائيات: self-hosted على نفس الـ VPS.
+- تجنّب أي CDN وقت التشغيل — كل شي يتحزّم مع الـ build.
+
+---
+
+## حزم مقترحة للتثبيت (مرجع)
+
+```
+# UI
+tailwindcss postcss autoprefixer
+# shadcn/ui يُهيّأ عبر: npx shadcn@latest init
+class-variance-authority clsx tailwind-merge lucide-react tailwindcss-animate
+# DB
+prisma @prisma/client
+# Auth
+next-auth@beta
+# Forms & validation
+react-hook-form zod @hookform/resolvers
+# Email
+nodemailer @react-email/components @react-email/render
+# Media
+sharp
+# (اختياري) مشغّل صوت
+wavesurfer.js
+```
+
+> ⚠️ لا تثبّت شي إلا وقت الحاجة الفعلية للـ feature المرتبط فيه، وحدّث `PROJECT-STATE.md` بعد كل إضافة.