# Products by category on the home screen (المنتجات حسب التصنيف) — mobile app contract

The website's homepage shows, under the other sections, one row per category chosen by the
admin: the category name, a **"عرض الكل"** button and a horizontal list of up to **six products**.
The admin sets it in **Website Setup → Home Page → "المنتجات حسب التصنيف"**:

- which categories, and **in which order** (the up/down arrows);
- for each category, optionally, **which products are shown** and in which order
  ("المنتجات المعروضة (يكمل الباقي حتى ستة منتجات تلقائياً)"). Picked products come first; if fewer
  than six are picked (or none: "تلقائي"), the rest is filled with other products of that category.

The app gets exactly the same rows, with the same products, in **one request**.

Base: `/api/v2`, usual headers (`System-Key`, `App-Language`). No sign-in needed (a guest gets the
same answer). **No existing endpoint changed.**

## 1. The endpoint — `GET categories/home/products` (new)

```json
{
  "data": [
    {
      "id": 134,
      "slug": "electronics",
      "name": "الإلكترونيات والكهربائيات",
      "banner": "https://kapitano.shop/public/uploads/all/pnJ6RJ11....png",
      "cover_image": "https://kapitano.shop/public/uploads/all/pnJ6RJ11....png",
      "icon": "https://kapitano.shop/public/uploads/all/pnJ6RJ11....png",
      "products": [
        {
          "id": 3843,
          "slug": "saaak-namos-shhn-usb",
          "name": "صاعق ناموس شحن usb",
          "usd_price": 9.44,
          "thumbnail_image": "https://kapitano.shop/public/uploads/all/itKrtPNZ....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/3843" }
        }
      ]
    },
    {
      "id": 304,
      "slug": "audio-devices",
      "name": "السماعات ومكبرات الصوت",
      "...": "...",
      "products": [ "... up to 6 ..." ]
    }
  ],
  "success": true,
  "status": 200
}
```

| key | meaning |
|---|---|
| `data` | the rows, **already in the admin's order** — draw them in the order received, never sort. Can be empty (`[]`): then show no section at all. |
| `id`, `slug`, `name` | the category. `name` is in the `App-Language` language. |
| `banner`, `cover_image`, `icon` | category images (`""` when none). The website shows none of them in this section; use them only if the design wants one. |
| `products` | 1 to 6 products, **already in the right order** (picked ones first). Every item is the same product card object the app already reads from `products/search`, `products/category/{slug}`, `products/todays-deal`… (`ProductMiniCollection`) — reuse the existing product card widget. |

Rules the backend already applies (the app does nothing about them):

- A category hidden from customers (Admin → Categories, "Shown to customers" off) is left out.
- Only products on sale (published and approved) are returned; a picked product that is not on
  sale any more is skipped and the row is topped up.
- A category with no product on sale is left out (no empty row).
- The automatic products are random and cached for up to a day, like on the website, so two
  phones may see a different fill; the picked ones are always the same and first.
- The answer follows the admin's changes after they save the Home Page settings.

## 2. What to draw (same as the website)

For each row of `data`, in order:

1. A header line: the category `name` (bold) on the start side, and a **"عرض الكل"** button on the
   end side.
2. Under it, a horizontal scrolling list of the `products`, using the existing product card
   (photo, name, `main_price`, `stroked_price` crossed out when `has_discount`, the `discount`
   badge). Tapping a card opens the product as it does everywhere else (by `slug`).
3. **"عرض الكل"** opens the existing category products screen of that category:
   `GET products/category/{slug}` with the row's **`slug`** — the same screen opened from the
   categories page (it already lists the products staff put first in that category).

Place the section on the home screen where it fits the design (on the website it comes after the
other product sections). Load it with the rest of the home screen; it is a single request.

> Do not build this section from `categories/home` + one `products/category/{slug}` call per
> category: `categories/home` does not keep the admin's order and does not know the products the
> admin picked for the homepage, and `products/category/{slug}` returns the category page's list,
> not the homepage row. Also note that `links.products` in the category objects of
> `categories/*` carries the category **id** while `products/category/{slug}` expects the
> **slug** — always build that URL from `slug`.

## 3. Checklist for the app

- [ ] Call `GET /api/v2/categories/home/products` when the home screen loads (and on pull-to-refresh).
- [ ] Draw one row per item of `data`, in the order received; nothing when `data` is empty.
- [ ] Row header: category `name` + "عرض الكل" → category products screen with `slug`.
- [ ] Products: horizontal list of the existing product card, in the order received.
- [ ] Test: in the admin, move a category up/down and pick products for a row, save, reload the
  app home screen — the rows and the first products must match the website's homepage.