# الصفحة الرئيسية بالتطبيق: الأقسام وترتيبها — تسليم لمبرمج التطبيق

> **الحالة (2026-10-29):** الشغل موجود على `dev`، **ولسا ما نزل على الموقع الحي**. فيك تبلّش تكتب الكود من هلأ،
> بس الحقول الجديدة (`strips` و`backgrounds` والمفتاح `featured_categories`) ما رح تطلع على `kapitano.shop` إلا بعد ما ننزّل.
> كل الـendpoints القديمة شغّالة متل ما هي، والنسخ القديمة من التطبيق ما بيصير فيها شي.

---

## 1. شو الجديد؟

من لوحة التحكم (المنتجات ← **الأقسام**) صار الأدمن يقدر:

1. **يعمل قسم بالاسم اللي بدو ياه، ويختار شو بيعرض:**
   - منتجات بيختارها بإيده؛
   - الأكثر مبيعاً؛
   - المنتجات الجديدة؛
   - منتجات فئة معيّنة (مع فئاتها الفرعية)؛
   - منتجات ماركة معيّنة؛
   - المنتجات اللي عليها حسم.

   بالأنواع اللي بتتعبّى لحالها، المنتجات اللي بيختارها بإيده بتطلع أول.
2. **يعمل قسم فئات أو متاجر أو ماركات** بيختار شو فيه وبيرتّبه (من 2026-10-29، الفقرة 4أ).
3. **يرتّب كل أقسام الصفحة الرئيسية**، ومنها شريط الفئات المميزة، ويخفي أي قسم أو يحذفه. الحذف نهائي.
4. **يختار لون خلفية كل قسم** بحرية (الفقرة 5).

**صفقة اليوم، والتريندات، والأكثر مبيعاً، والمنتجات الجديدة صاروا أقسام عادية من هالأقسام.**
وكمان **شريط الفئات المميزة وشريط المتاجر وشريط الماركات** صاروا أقسام عادية (من نوع فئات ومتاجر وماركات).
يعني الأدمن بيعدّلهم ويحذفهم متل أي قسم، وبيجوا كلهم من نفس المكان. ما ضل ولا قسم أساسي.

كل قسم منتجات إله زر **"عرض الكل"**، بيفتح كل منتجات القسم.

الموقع صار يعرض كل هالشي. **بدنا التطبيق يعرض نفس الشي.**

---

## 2. الأقسام: `GET api/v2/home-sections`

- **الهيدرز:** نفس العادة (`System-Key` و`App-Language`).
- **تسجيل الدخول:** ما في داعي، والجواب نفسه لكل الناس.
- **الكاش:** محفوظ على السيرفر، وأي تعديل من الأدمن بيوصل بالطلب الجاي.

```json
{
  "data": [
    {
      "id": 15,
      "title": "صفقة اليوم",
      "title_ar": "صفقة اليوم",
      "title_en": "Today's Deal",
      "type": "manual",
      "products": [
        {
          "id": 1988,
          "slug": "...",
          "name": "...",
          "usd_price": 9.44,
          "thumbnail_image": "https://kapitano.shop/public/uploads/all/....png",
          "has_discount": true,
          "discount": "-10%",
          "stroked_price": "1,305 ل.س",
          "main_price": "1,170 ل.س",
          "rating": 0,
          "sales": 3,
          "current_stock": 3,
          "is_wholesale": false,
          "links": { "details": "https://kapitano.shop/api/v2/products/1988" }
        }
      ],
      "links": {
        "all": "https://kapitano.shop/api/v2/home-sections/15/products",
        "web": "https://kapitano.shop/section/todays-deal"
      }
    }
  ],
  "layout": ["featured_categories", "custom_16", "custom_15", "custom_18", "best_sellers", "brands", "custom_19"],
  "success": true,
  "status": 200
}
```

| الحقل | المعنى |
|---|---|
| `data` | الأقسام **الظاهرة بس**. القسم المخفي أو المحذوف أو اللي ما فيه ولا منتج ظاهر للزبون ما بيجي أصلاً. |
| `data[].id` | رقم القسم، ثابت طول عمر القسم. منيح تستعمله كـkey للـwidget. |
| `data[].title` | اسم القسم **بلغة `App-Language`**. إذا الأدمن ترك لغة فاضية، بيجي اسمه باللغة التانية. `title_ar` و`title_en` موجودين إذا احتجتهم، وواحد منهم ممكن يكون `""`. |
| `data[].type` | شو بيعرض القسم: `manual` (منتجات مختارة)، `best_selling`، `newest`، `category`، `brand`، `on_sale`. **للمعلومة بس:** المنتجات جاية جاهزة، وما في داعي تتصرّف حسبه. |
| `data[].products` | المنتجات **مرتّبة ومقصوصة** عالعدد اللي اختاره الأدمن (1 لـ50) للصفحة الرئيسية. **نفس كارت المنتج** (`ProductMiniCollection`) تبع `products/todays-deal` و`products/search`، فاستعمل نفس widget الكارت. المنتجات الرقمية والمنتجات غير المنشورة مشالة. |
| `data[].links.all` | رابط **"عرض الكل"** للقسم (الفقرة 3). |
| `data[].links.web` | نفس صفحة "عرض الكل" بس عالموقع (`kapitano.shop/section/ramadan-offers`)، إذا بدك زر مشاركة. |
| `layout` | **ترتيب الصفحة الرئيسية** (الفقرة 4). |

**لا تعيد ترتيب أي شي.** الأقسام والمنتجات جايين بالترتيب الصح.

---

## 3. عرض الكل: `GET api/v2/home-sections/{id}/products?page=1`

نفس الهيدرز. بيرجّع **كل** منتجات القسم بنفس ترتيبه، **20 بكل صفحة**، وبنفس شكل
`products/featured`: `data` (كروت المنتجات) و`links` و`meta` (`current_page`، `last_page`، `per_page`، `total`).

- اعرض زر **"عرض الكل"** بجنب عنوان كل قسم، وهو بيفتح شاشة فيها المنتجات من `links.all`.
- كمّل الصفحات طول ما `links.next` مش `null`.
- إذا القسم انخفى أو انحذف بالنص، بيرجع **404**: سكّر الشاشة أو اعرض رسالة إنه ما عاد موجود.
- **من 2026-10-30:** الجواب صار فيه كمان `section` (رقم القسم، `slug`، واسمه `title`)، لتحط الاسم فوق الشاشة.

---

## 3أ. الرابط العميق للقسم: `kapitano://section/<slug>` (من 2026-10-30)

كل قسم منتجات إله رابط على الموقع لصفحة "عرض الكل": `kapitano.shop/section/<slug>`، مثلاً `kapitano.shop/section/trending`. هاد الرابط اللي بيحطوه بالحملات وإعلانات فيسبوك وإنستغرام، وبدنا يفتح **شاشة "عرض الكل" بالتطبيق**.

**المطلوب منك:**
1. شاشة جديدة لرابط **`kapitano://section/<slug>`** (و`https://kapitano.shop/section/<slug>` لما يفتح من الـUniversal Links / App Links)، بتفتح "عرض الكل" تبع القسم.
2. الشاشة بتطلب **`GET api/v2/home-sections/<slug>/products?page=1`**. الـ`slug` هو آخر جزء من الرابط، والرقم كمان بيشتغل مكانه. الجواب نفس جواب الفقرة 3 بالظبط، ومعه `section`:
   ```json
   "section": { "id": 16, "slug": "trending", "title": "تريندات", "title_ar": "تريندات", "title_en": "Trending" }
   ```
   حط `section.title` عنوان للشاشة.
3. إذا رجع **404** (القسم مخفي أو محذوف أو الرابط غلط): اعرض "القسم غير موجود" مع زر للرئيسية، متل أي صفحة مش موجودة.
4. **أندرويد:** ضيف `/section/*` على الـmanifest (App Links)، وخلّي النسخة الجديدة تفتح `kapitano://section/...`.

**أنا مطفّي هالروابط من جهة الموقع** لحتى تنزل نسختك على المتاجر. لو شغّلناها قبل، بيفتح التطبيق القديم على "الصفحة غير موجودة". فلما تنزل النسخة **خبّرنا**، ومنشغّلها من عنا (ومنرفع ملف آبل مع `/section/*`).

أقسام الفئات والمتاجر والماركات **ما إلها رابط خاص**. "عرض الكل" فيها بيروح لـ `/categories` و`/sellers` و`/brands`، وهدول بيفتحوا بالتطبيق من قبل.

---

## 4. الترتيب: `layout`

ارسم أقسام الرئيسية بترتيب `layout` من فوق لتحت:

| المفتاح | القسم بالتطبيق |
|---|---|
| `custom_<id>` | العنصر اللي إله نفس الـ`id` بـ`data` (مثلاً `custom_15` ← `data[].id == 15`). **كل أقسام المنتجات بتجي هيك**، ومنها صفقة اليوم والتريندات والأكثر مبيعاً والمنتجات الجديدة. |
| `best_sellers` | شريط المتاجر (`GET shops`) |
| `brands` | شريط الماركات (`GET brands`) |
| `featured_categories` | شريط الفئات المميزة. من 2026-10-29. |
| `strip_<id>` | شريط جديد عمله الأدمن (فئات أو متاجر أو ماركات): العنصر اللي إله نفس الـ`key` بـ`strips` (الفقرة 4أ). |

**قواعد:**
- **مفتاح ما عندك إله قسم بالتطبيق، تجاهله.**
- **السلايدر والبانرات والفلاش ديل** مش جزء من `layout`، بيضلّوا بمكانهم الحالي.
- **الفئات المميزة** بترسمها بمكان المفتاح `featured_categories`.
- **البانرات اللي كانت تحت الفئات المميزة ما بتنتقل معها.** بتضل بمكانها بالصفحة، يعني بترسمها **تحت أول مفتاح بـ`layout`** أياً كان. إذا `featured_categories` هو الأول (متل اليوم) ما بيتغير شي. إذا الأدمن نزّله لتحت، البانرات بتضل تحت القسم اللي صار أول. الموقع بيعمل نفس الشي.
- **الشريط اللي حذفه الأدمن** ما بيجي بـ`layout`، والحذف صار نهائي (ما في إرجاع). إذا انحذفت الفئات المميزة، خبّيها، والبانرات بتضل تحت أول مفتاح.
- **اقرا `layout` كلها كل مرة.** ممكن الأدمن يضيف أقسام جديدة بأي وقت.

**شكل القسم:** العنوان (`title`) فوق، وجنبه زر "عرض الكل"، وتحته carousel أفقي للمنتجات.

---

## 4أ. الأشرطة: `strips` (فئات، متاجر، ماركات)

من 2026-10-29 الأدمن بيقدر يعمل **قسم فئات** أو **قسم متاجر** أو **قسم ماركات**، ويختار شو فيه ويرتّبه. شريط الفئات المميزة وشريط المتاجر وشريط الماركات صاروا أقسام من هالنوع.

هالأقسام ما بتجي بـ`data` (التطبيق القديم كان رح يرسمها أقسام منتجات فاضية). بتجي بحقل جديد اسمه `strips`:

```json
"strips": [
  {
    "key": "featured_categories",
    "id": 93,
    "type": "categories",
    "title": "الفئات المميزة",
    "title_ar": "الفئات المميزة",
    "title_en": "Featured Categories",
    "items": [ { "id": 144, "name": "العناية والجمال", "banner": "...", "...": "..." } ],
    "links": { "all": "https://kapitano.shop/api/v2/categories", "web": "https://kapitano.shop/categories" }
  },
  { "key": "strip_96", "type": "brands", "title": "ماركات رمضان", "items": [ ... ] }
]
```

- **`key`** هو مكانه بـ`layout`. الأشرطة الثلاثة القديمة بيضل مفتاحها `featured_categories` و`best_sellers` و`brands`. أي شريط جديد مفتاحه `strip_<id>`.
- **`type`**: `categories` أو `shops` أو `brands`.
- **`items`** مرتّبين ومقصوصين عالعدد اللي اختاره الأدمن (لحد 100)، وبنفس شكل الـendpoint اللي بتعرفه:
  - `categories` متل `categories/featured`
  - `shops` متل `shops`
  - `brands` متل `brands`

  الفئة المخفية والمتجر غير الموثّق والماركة اللي لسا ما انقبلت ما بيجوا أبداً.
- **`links.all`**: قائمة الكل بالتطبيق (`categories` أو `shops` أو `brands`).
- **الرسم:**
  - شريط `categories` متل الفئات المميزة: فوقه عنوانه `title` وزر "عرض الكل"، وتحتهم صور مدوّرة وأسماء. هاد لكل أقسام الفئات، متل الموقع.
  - شريط `shops` أو `brands` متل شريط المتاجر والماركات: عنوان، و"عرض الكل"، ولوغوهات.
- **ارسم الأشرطة الثلاثة القديمة كمان من `strips`**، مش من `shops` و`brands`. هالقوائم ما بتعرف ترتيب الأدمن، أما `strips` فيه بالظبط اللي رتّبه.
- **`categories/featured`** صار يرجّع محتوى قسم الفئات المميزة بترتيبه، فالنسخ القديمة بتشوف تعديلات الأدمن عليه. وإذا انخفى القسم أو انحذف، بيرجّع قائمة فاضية.

---

## 5. لون خلفية كل قسم: `backgrounds`

من 2026-10-29 الأدمن بيختار لون خلفية **كل قسم** بحرية، ومنها شريط المتاجر والبراندات والفئات المميزة. الجواب صار فيه `backgrounds`، فيه عنصر لكل مفتاح بـ`layout`:

```json
"backgrounds": {
  "featured_categories": { "color": "#f8f9fa", "title_color": "#1b1b28" },
  "custom_16": { "color": "#10164c", "title_color": "#ffffff" },
  "custom_15": { "color": null, "title_color": "#1b1b28" },
  "brands": { "color": "#ffc519", "title_color": "#1b1b28" }
}
```

- `color`: خلفية القسم (`#rrggbb`). إذا `null` فالخلفية بيضا.
- `title_color`: لون العنوان وزر "عرض الكل" والأسهم. بيجي أبيض على اللون الغامق، وغامق على الفاتح، فما في داعي تحسبه.
- كروت المنتجات والمتاجر والبراندات بتضل بيضا على أي لون.
- قبل ما الأدمن يحفظ أول لون، أول قسم منتجات بيجي `#10164c` والباقي أبيض، يعني متل الشكل القديم.

**القاعدة القديمة** ("أول قسم منتجات كحلي") انلغت. استعملوا `backgrounds` بدالها. نسخ التطبيق القديمة اللي ما بتقرأ `backgrounds` بتضل تلوّن أول قسم منتجات بالكحلي، وما بيخرب شي.

---

## 6. إذا عم تستعمل `POST app/data`

في مجموعة اسمها **`custom_home_sections`**، وجوابها **نفس جواب `GET home-sections` بالظبط** (`data` بأسماء الأقسام ومنتجاتها ونوعها وروابطها، و`layout` و`strips` و`backgrounds`)،
ولها ختم (stamp) متل باقي المجموعات. اطلبها مع مجموعات الصفحة الرئيسية بنفس الطلب الواحد.

- إذا رجعت `null`: المحتوى ما تغيّر، فاستعمل النسخة المحفوظة عندك.
- إذا إجت بـ`_deferred`: اطلب `GET home-sections` لحاله.
- **اسم القسم** (`title`) بيجي بلغة هيدر `App-Language` اللي بتبعته مع طلب `app/data` نفسه. إذا المستخدم غيّر لغة التطبيق، اطلب المجموعة من جديد، أو استعمل `title_ar` و`title_en` اللي بيجوا مع كل قسم.

الشرح الكامل بـ`docs/api/app-data-sync.md`.

**التطبيق الجديد ما بيحتاج** يطلب `todays_deal_products` ولا `featured_products` ولا `best_selling_products`:
كل أقسام المنتجات صاروا بـ`custom_home_sections`.

---

## 7. شو ما تغيّر (للنسخ القديمة من التطبيق)

- **`products/todays-deal` و`products/featured` و`products/best-seller` وقائمة المنتجات الجديدة (`products/search?sort_key=new_arrival`):**
  شغّالين، وبيقروا من الأقسام اللي بتقابلهم. سجّلنا كل أجوبة التطبيق قبل التعديل وبعده، وطلعت **نفسها حرف بحرف**.
  إذا الأدمن حذف أو خبّى واحد من هالأقسام، الرابط تبعه بيرجّع قائمة فاضية، فبيختفي من النسخ القديمة كمان.
- **حقلي `todays_deal` و`featured` جوّا كارت المنتج** (تطبيق التاجر و`ProductCollection`): لسا موجودين، وبيرجّعوا 0 أو 1 متل قبل.
- **"مميز بمتجري" بتطبيق التاجر** (`seller_featured`، `change_featured_status`، `shops/products/featured/{id}`): شغلة تانية وما تغيّرت.

---

## 8. قائمة الشغل للتطبيق

- [ ] طلب `GET api/v2/home-sections` (أو مجموعة `custom_home_sections` بـ`app/data`).
- [ ] رسم أقسام الرئيسية بترتيب `layout`: `custom_<id>` ← القسم من `data`، وأي مفتاح موجود بـ`strips` (`featured_categories` و`best_sellers` و`brands` و`strip_<id>`) ← الشريط من `strips`. وتجاهل أي مفتاح مش معروف.
- [ ] البانرات اللي كانت تحت الفئات المميزة تحت أول مفتاح بـ`layout`.
- [ ] كل قسم: العنوان `title`، وزر "عرض الكل"، وcarousel المنتجات بنفس widget الكارت.
- [ ] شاشة "عرض الكل": `links.all` مع الصفحات، و404 ← القسم ما عاد موجود.
- [ ] خلفية كل قسم ولون عنوانه من `backgrounds`.
- [ ] شاشة الرابط العميق `kapitano://section/<slug>` (الفقرة 3أ)، و`/section/*` بالـmanifest تبع أندرويد. وخبّرنا لما تنزل النسخة.
- [ ] تجربة: الأدمن بيعمل قسم ← بيضيف منتجات ← بيغيّر الترتيب ← بيخفي القسم ← بيحذفه. وكل خطوة لازم تبين بالتطبيق بالطلب الجاي.

---

## 9. أسئلة؟

- تفاصيل الـendpoints بالإنكليزي: `docs/api/custom-home-sections.md`
- `app/data`: `docs/api/app-data-sync.md`