# ▶ START — إقلاع المشروع (املأ التصاميم + الـ brief، وقول للمساعد «نفّذ START»)

> نقطة البداية الوحيدة لمشروع جديد. تملأ **قائمة روابط Figma** (لكل جمهور: `audience` + `platform`) + **ملف الـ brief**.
> **START يجهّز كل شيء حتى الخطط ثم يقف** — يبني الموقع التعريفي، يعمل الـ schema (وتوافق عليه)،
> يبني طبقة الداتا بيز كاملة، ويكتب كل الخطط (API + CRUD + اسبرينتات) — **ولا ينفّذ الاسبرينتات**.
> بعد كده **أنت** تراجع الخطط وتعدّلها وتنفّذ كل اسبرينت بنفسك (في Cursor عادي).

---

## 1) المدخلات (املأها)

```yaml
# التصاميم — رابط واحد أو أكثر. كل رابط له audience (الجمهور) + platform (المنصة).
FIGMA:
  - audience: user
    platform: app
    url: https://www.figma.com/design/pIFyEHCimnG9rIRh3TMnHC/HR?node-id=0-1&p=f&m=dev
  - audience: provider
    platform: app
    url: https://www.figma.com/design/pIFyEHCimnG9rIRh3TMnHC/HR?node-id=0-1&p=f&m=dev
  # audience = الجمهور (user / provider / admin / …). platform = المنصة (app / web / …).
  #
  # مهم للدمج:
  #   • نفس الـ audience واختلفت الـ platform (مثلاً app + web للمستخدم) = **نفس المنتج ونفس الميزات** →
  #     ادمجهما وأزل التكرار؛ **API واحد يخدم الاثنين**. لا تعاملهما كمشروعين ولا تكرّر الـ endpoints.
  #   • audience مختلف (user + provider) = تدفقات مختلفة (مع مشترك).
  #   • تصميم واحد؟ اترك عنصراً واحداً.

BRIEF:        docs/project/brief.md            # المرجع الوظيفي (BRD) — md أو pdf: الأعمال/القواعد/متطلبات الأدمن

# اختياري — اتركه فارغاً ليستنتجه المساعد من المراجع:
APP_NAME_AR:  <اسم التطبيق بالعربي>
APP_NAME_EN:  <app name in English>
SURFACES:     api + dashboard                  # ماذا نبني؟ الافتراضي: الاثنان
```

> **المراجع = كل التصاميم + الـ brief.** حطّ الـ BRD في:
>
> ```
> docs/project/brief.md
> ```
>
> وهات **كل** روابط
>
> ```
> Figma
> ```
>
> (رابط لكل جمهور). المساعد يقرأ **كل تصميم كامل شاشة-شاشة** (نفس طريقة قراءة التصميم الواحد)، يقارنها بالـ brief، ويدمج الكل في:
>
> ```
> docs/project/analysis.md
> ```
>
> المنظّم — اللي الـ plans/schema/DB بتتبني منه. لا تصميم يغني عن الـ brief (قواعد الأعمال)، ولا الـ brief يغني عن التصاميم (الشاشات).



## 2) كيف تشغّله

في Cursor اكتب:

```
نفّذ START
```

المساعد يتوقّف **مرتين**: (1) عند **بوابة الـ schema** للموافقة، و(2) **بعد كتابة كل الخطط** ليسلّمها لك للتنفيذ اليدوي.

---



## 3) عقد التنفيذ للمساعد (Agent execution contract)

أنت مُعطى قائمة `FIGMA` (رابط لكل audience) + `BRIEF`. اتبع الـ playbooks القانونية — لا تكرّر خطواتها:

- التنسيق + البوابة + ترتيب الخطط → `[../build/README.md](../build/README.md)`
- القواعد الذهبية (قراءة التصميم كامل، reuse/alter/new، تمثيل الملفات) → `[../build/build-schema.md](../build/build-schema.md)`

**حدود START: من الخطوة 0 حتى كتابة الخطط (الخطوة 7) ثم قف. لا تبني أي كود اسبرينت (API / CRUD / tests / Postman).**

### الخطوة 0 — تأكد إن البيئة جاهزة (سريع — بدون أي تعديل على كود الـ base)

تأكد **فقط** إن `.env` مضبوط، وDB **مخصّصة للمشروع ونضيفة** (مش مشتركة/متلوّثة — DB نضيفة تسرّع
`migrate/seed/schema:check` كتير)، و`APP_KEY` موجود، و`TELESCOPE_ENABLED=false` للسرعة في التطوير.
**لا تدخل في أي «سايكل تصليح» للـ base ولا تعدّل كوده** — الـ base يُفترض جاهز؛ لو فيه عطل بيئة فعلي فقط، أبلغ المطوّر وقف.

**وتأكد إن أدوات قراءة المصادر شغّالة:**

- **Figma** — سيرفر fileKey-based متّصل (الأفضل/headless)، أو تطبيق Figma desktop مفتوح بـ Dev Mode؛ لو مفيش أي سيرفر → اطلب من المطوّر.
- **PDF** — جرّب الـ Read tool (يرندر الصفحات بصرياً)؛ لو poppler/`pdftoppm` مش متثبّت استخدم `pdftotext -layout`، وهات الدياجرامات/السكرينشوتات من Figma لو الـ PDF رجع نص فقط. (التفاصيل في `[../build/build-schema.md](../build/build-schema.md)` §1.)

> صحة الـ base (الباگات/الـ green) مسؤولية لمرة واحدة على مستوى الـ base repo — مش جزء من START.



### الخطوة 1 — الهوية (املأها تلقائياً)

اقرأ **كل** روابط `FIGMA` + `BRIEF`، واملأ `[../project/brand-identity.md](../project/brand-identity.md)`
(الاسم، الألوان، الخطوط، الشعار، روابط Figma، الوصف، الإحصائيات) من التصميم — لا تترك `<?>` إلا لِما يتعذّر معرفته فعلاً.

> - **اللوجو:** دوّر عليه الأول في `docs/project-init/assets/` (أصول المشروع)؛ لو ملقتهوش **هاته من التصميم (Figma)** مع صور المشروع العامة.
> - **ألوان الموقع التعريفي تُؤخذ من التصميم (Figma) نفسه — مش مشتقّة من اللوجو.**



### الخطوة 2 — التحليل: ادمج (كل التصاميم + الـ brief) → `analysis.md` منظّم

اقرأ **كل** المراجع بالكامل، مايغنيش واحد عن التاني:

- **الـ brief الوظيفي** (`docs/project/brief.md`/pdf) = مصدر الحقيقة للأعمال/القواعد/الأنواع/متطلبات الأدمن. (اقرأه كامل؛ لو pdf فبصرياً — دياجرامات/جداول مش نص فقط.)
- **كل تصميم** `FIGMA` = مصدر الحقيقة للشاشات/الحقول/التدفقات/الأكشنز. **امشِ على كل شاشة في كل تصميم شاشة-شاشة** (نفس طريقة قراءة التصميم الواحد)، ما تكتفيش بواحد.
  - **الدمج حسب audience/platform:** تصاميم بنفس الـ audience واختلفت الـ platform (تطبيق + ويب لنفس المستخدم) = **نفس الميزات** → ادمجها وأزل التكرار، **endpoints واحدة تخدم الاثنين**. تصاميم بـ audience مختلف (user + provider) = تدفقات مختلفة (مع مشترك). سجّل platform لكل شاشة في الخريطة.

- راجع جداول base الموجودة (reuse/alter/new).

ادمج الكل في `[../project/analysis.md](../project/analysis.md)` **منظّم** بصيغة القالب، يحتوي: خريطة الشاشات (مع العدد، **وعمود Audience لكل شاشة**) · كل كيان/عمود **REUSE/ALTER/NEW** (وهل هو مشترك ولا خاص بدور) · قرار الملفات · قائمة الـ APIs · **كل CRUD** · seed حقيقي · open questions · الباكلوج — **بتغطية 100% لكل الجماهير** (checklist).

> عند التعارض: **الفيجما تكسب في الشاشات/الحقول، والـ brief يكسب في قواعد الأعمال** — وسجّل الفرق كـ `<?>`. (لو المطوّر حطّ `analysis.md` جاهز، اعتبره مسودّة: تحقّق منه وأكمله من المرجعين، ما تمسحش محتواه.)

> **انتبه:** (1) شاشات بنفس الاسم (مثل «تفاصيل الطلب») **مش مكررة** — فرّغ محتوى كل واحدة وقارنها واكتبها كصف منفصل
> مع ذكر الفرق. (2) الشاشة الواحدة فيها **أكشنز كتير** (قبول/رفض/تم الاستلام…) — كل أكشن = endpoint مستقل + نموذج حالات (Enum + انتقالات).



### الخطوة 3 — 🎨 الموقع التعريفي كامل (أول حاجة تتبني)

نفّذ `[landing-site.md](./landing-site.md)`: غيّر **الألوان والمحتوى واللوجو وكل حاجة** من `[brand-identity.md](../project/brand-identity.md)`
(CSS variables `--safe-*` + الخطوط + النصوص/الإحصائيات + الشعار) — تلقائياً، **وما تسيبش أي لون/نص/لوجو من الـ base كما هو**.

### الخطوة 4 — الـ Schema

حسب `[../build/build-schema.md](../build/build-schema.md)`: اكتب `database/schema/<feature>.json`
وسجّل الفيتشر في `database/schema/features.json`. اجعله يظهر على `/schema-designer`.

### الخطوة 5 — 🛑 البوابة (توقّف وانتظر موافقتك)

**قبل العرض:** كل الـ open questions (`<?>`) في `analysis.md` لازم تتقفل — لا بوابة على schema ناقص.
اعرض: الـ schema على `/schema-designer` + خريطة reuse/alter/new + قرار الملفات + عدد الشاشات.
**لا تولّد أي كود** حتى يردّ المطوّر بـ «موافق» / «approved».

> **إلزامي عند الاستئناف:** بمجرد أن يقول المطوّر «كمل»/«موافق»، **أعد قراءة**
> `database/schema/<feature>.json` **+** `database/schema/features.json` **من القرص قبل أي خطوة تالية.**
> المطوّر عادةً يعدّل الـ schema على `/schema-designer` ويحفظها أثناء التوقّف — الملف المحفوظ هو مصدر الحقيقة.
> قارن المحفوظ بنسختك قبل البوابة، اعتمد **كل** تعديل (أعمدة/أنواع/علاقات/reuse-alter-new)، وابنِ من الملف الحالي.



### الخطوة 6 — طبقة الداتا بيز كاملة (بعد «كمل»)

نفّذ `[../build/build-database.md](../build/build-database.md)` **لكل الـ schema المعتمد**:

- كل الـ migrations (للجدول الموجود **ALTER** بإضافة أعمدة، **ممنوع جدول مكرر**) · models (+ translation models) · factories · relations.
- **seeders لكل جدول** بداتا حقيقية **مترابطة بالكامل** (الـ FKs من صفوف موجودة فعلاً) + **عدّل محتوى seeders الـ base** (settings / pages / sliders …) لتناسب **هوية المشروع**.
- تحقّق: `migrate:fresh --seed` أخضر · `php artisan schema:check` · `pint` · `dump-autoload -o`. ثم **commit** لطبقة الداتا.



### الخطوة 7 — الخطط (كل أنواعها) ثم 🛑 قف — لا تنفّذ

**ادرس المشروع كامل الأول** (كل الشاشات + التحليل + كل جداول الـ schema)، واضمن **تغطية 100%**: ملف `cruds/<entity>.md`
**لكل** جدول يُدار من الداش بورد، وملف API لكل endpoint/أكشن. اعمل checklist (جداول الـ schema × ملفات الـ CRUD؛ الشاشات × ملفات الـ API)
وتأكد مفيش حاجة ناقصة قبل ما تكمّل. ثم اكتب **كل** الخطط، **من غير ما تبني كود الاسبرينتات**:

- **فولدر لكل audience** ثم لكل flow، ملف لكل API → `docs/project/api/<audience>/<flow>/<endpoint>.md` (قالب `[api-plan-template.md](./api-plan-template.md)`) — مكتفٍ بذاته: لوجيك مجمّع من التحليل + لينك اسكرين + request/response + **Postman request بأمثلته ودكيومنتيشنه**. (`user/` · `provider/` · `delegate/` · … + `shared/` للمشترك. نفس الـ audience/منصّة مختلفة = **endpoints واحدة** لا تُكرَّر.)
- ملف لكل CRUD داش بورد → `docs/project/cruds/<entity>.md` (قالب `[crud-plan-template.md](./crud-plan-template.md)`) — يظهر في الـ sidebar + **مترجَم بالكامل** (ar+en).
- ملف للصفحة الرئيسية للداش بورد → `docs/project/cruds/dashboard-home.md` (قالب `[dashboard-home-template.md](./dashboard-home-template.md)`) — KPIs/charts/quick links.
- ملف(ات) التقارير → `docs/project/cruds/reports.md` (قالب `[reports-template.md](./reports-template.md)`) — أداء المشروع/المالي؛ اقسمها لأكتر من صفحة لو القسم يستاهل. الإحصائيات والرسوم **علمية مدروسة**.
- خطط الاسبرينتات بالاعتماديات → `docs/project/sprints/<n>.md` (قالب `[sprint-template.md](./sprint-template.md)`؛ فيها **اسبرينت داش بورد** بملفات `cruds/`*). كل ملف اسبرينت **قابل للتنفيذ** (فيه عقد تنفيذ + برومبت جاهز + «فكّر-الأول» + اقتراح design pattern).
- **الهيكل المبدئي لكولكشن Postman** → `docs/postman/<project>.postman_collection.json` (info + variables + هيكل `audience → section → flow`: أقسام `Auth`/`Logic`/`Settings` وجواها فولدر فاضي لكل flow — على شكل `save/docs/postman/save.postman_collection.json`). كل API plan لما يتنفّذ يضيف request فيه بأمثلته ودكيومنتيشنه.
- **زرع لوحة الكانبان:** `php artisan board:sync` — يقرأ كل `sprints/*.md` ويطلّع التاسكات على `/kanban` (كلها To Do)، جاهزة تتحرّك **لايف** وقت تنفيذ كل اسبرينت.
- اكتب/حدّث `docs/project/CONTEXT.md` (الخريطة + state أولي «اللي اتعمل» + جدول الباترنز اللي تحاكيها) — الملف اللي أي جلسة تقراه أول حاجة بدل ما تعيد استكشاف المشروع.
- اكتب **README الجذر** من `[readme-template.md](./readme-template.md)` (تعريف المشروع + شجرة الاستركشر + setup + نظرة API/أدمن + روابط Figma/Postman/schema-designer/kanban)، وهيّئ `docs/project/CHANGELOG.md` (يتملّى قسم لكل سبرينت عند الـ DoD).

ثم **قف تمامًا**: اعمل commit للخطط، واطلب من المطوّر يراجعها ويعدّلها. **لا تبني أي API / CRUD / tests / Postman.**

### بعد START — تنفيذ المطوّر (يدوي، خارج START)

راجع وعدّل الخطط، ثم نفّذ **كل اسبرينت لوحده** (في Cursor عادي) عبر development-workflow:
بوابة الاسبرينت (موافقة design pattern) → build-api / build-dashboard-crud (مقاد بملفات الخطط) → build-tests → DoD (`[../build/verify.md](../build/verify.md)` §B) → build-postman → commit.

> **«START خلص» = جاهز للمراجعة والتنفيذ اليدوي:**
>
> 1. موقع تعريفي كامل (ألوان/محتوى/لوجو).
> 2. طبقة داتا بيز كاملة (schema معتمد + migrations + models + seeders مترابطة + factories + relations) — `migrate:fresh --seed` أخضر.
> 3. كل الخطط مكتوبة: `api/<audience>/<flow>/<endpoint>.md` + `cruds/<entity>.md` + `sprints/<n>.md`.
> 4. **الاسبرينتات لم تُنفَّذ** — أنت تنفّذها وتراجعها وتعدّلها بنفسك بعد START.

---



## القواعد (غير قابلة للتفاوض)

1. **لا سايكل تصليح للـ base:** الـ base يُفترض جاهز — لا تعدّل كوده أثناء START.
2. **اقرأ التصميم كامل** شاشة-شاشة — ليس من الـ PDF وحده. لو ناقص أو متعذّر → توقّف واسأل.
3. **راجع الموجود قبل الإنشاء** (reuse/alter/new)، وتأكّد من **الـ DB الفعلية** لا ملفات schema JSON فقط؛ لا تكرّر جداول base.
4. **مثّل كل ملف/صورة** (Spatie media أو جدول `*_files`).
5. **توقّفات START:** (1) بوابة الـ schema، (2) الوقفة النهائية بعد كتابة الخطط (تسليم للمطوّر). ما بينهم تابع تلقائياً. (بوابة الـ design pattern لكل اسبرينت تحصل في مرحلة التنفيذ اليدوي.)
6. **بيانات seed حقيقية مترابطة** (عربي للـ ar)، وبنفس conventions الـ base — Laravel-first بدون انحراف.
7. **START لا يبني كود الاسبرينتات** — يقف عند الخطط؛ التنفيذ + tests + DoD + Postman شغل المطوّر لكل اسبرينت.

---



### مخرجات START (يقف هنا)

```
docs/project/brand-identity.md          (مملوء)
docs/project/analysis.md                (شاشات + flows + كيانات + APIs + باكلوج)
docs/project/CONTEXT.md                 (خريطة + state + باترنز يحاكيها — يُقرأ أول كل جلسة)
README.md                               (الوجه الخارجي — تعريف + استركشر + setup + روابط)
docs/project/CHANGELOG.md                (سجل السبرينتات — يتملّى عند كل DoD)
landing                                 (موقع تعريفي بألوان/محتوى/لوجو المشروع)
database/schema/<feature>.json          (+ features.json)  ← معتمد على /schema-designer
طبقة DB: migrations (alter للموجود) · models · seeders مترابطة + معدّلة للهوية · factories · relations   (migrate:fresh --seed أخضر)
docs/project/api/<audience>/<flow>/<endpoint>.md   (خطة لكل API — فولدر لكل تطبيق/جمهور)
docs/project/cruds/<entity>.md          (خطة لكل CRUD داش بورد)
docs/project/sprints/<n>.md             (خطط الاسبرينتات بالاعتماديات + اسبرينت داش بورد)
docs/project/board.json                 (لوحة كانبان على /kanban — مزروعة بـ board:sync، تتحرّك لايف وقت التنفيذ)
docs/postman/<project>.postman_collection.json   (هيكل مبدئي — يتملّى مع تنفيذ كل API plan)
commits: بعد موافقة الـ schema + بعد طبقة الـ DB + بعد الخطط
```



### بعد START — ينفّذها المطوّر يدويًا لكل اسبرينت

```
controllers · services · requests · resources · routes · views · lang · tests · Postman collection
```