# Display Score

## Overview

A new `displayScore` property has been added to **channels**, **content** (movies/series), and **videos**. It controls the display order on listing endpoints. Higher score = appears first. Items with score `0` (default) fall back to their natural ordering (by date).

This property is set from the **admin app** and is read-only on client endpoints (the ordering is applied server-side).

---

## Affected Endpoints

### Client Listing Endpoints (ordering applied automatically)

No query parameter changes. Results are now sorted by `displayScore DESC`, then by date.

| Entity   | Endpoints |
|----------|-----------|
| Channels | `GET /client/v1/channels`, `/tv/v1/channels`, `/mobile/v1/channels` |
| Movies   | `GET /client/v1/contents/movies`, `/tv/v1/contents/movies`, `/mobile/v1/contents/movies` |
| Series   | `GET /client/v1/contents/series`, `/tv/v1/contents/series`, `/mobile/v1/contents/series` |
| Live Videos | `GET /client/v1/videos/live`, `/tv/v1/videos/live`, `/mobile/v1/videos/live` |
| VoD Videos | `GET /client/v1/videos/vod`, `/tv/v1/videos/vod`, `/mobile/v1/videos/vod` |

### Admin Endpoints (read + write)

The `displayScore` field is included in admin GET responses and accepted in admin PUT/POST request bodies.

| Entity   | GET (list)                  | GET (detail)                | PUT (update)                |
|----------|-----------------------------|-----------------------------|-----------------------------|
| Channels | `GET /admin/v1/channels`    | `GET /admin/v1/channels/{id}` | `POST /admin/v1/channels/{id}` |
| Content  | `GET /admin/v1/contents`    | `GET /admin/v1/contents/{id}` | `PUT /admin/v1/contents/{id}` |
| Videos   | `GET /admin/v1/videos`      | `GET /admin/v1/videos/{id}`   | `PUT /admin/v1/videos/{id}` |
| Live Videos | `GET /admin/v1/videos/live` | `GET /admin/v1/videos/live/{id}` | `PUT /admin/v1/videos/{id}` |

---

## Response Shape

The `displayScore` field is an integer, present in all admin DTOs:

```json
{
  "id": "abc123",
  "name": "Example Channel",
  "displayScore": 100,
  ...
}
```

### Default Value

- `0` -- all existing items default to `0`
- Items with the same score are sorted by date (newest first)

### Sorting Behavior

```
displayScore: 100  -- appears first
displayScore: 50   -- appears second
displayScore: 0    -- appears last (sorted by date among themselves)
displayScore: 0    -- appears last (sorted by date among themselves)
```

---

## Admin Update Request

To set the display score, include `displayScore` in the update request body.

### Update Channel

```
POST /admin/v1/channels/{id}
```

```json
{
  "name": "Channel Name",
  "about": "...",
  "image": "...",
  "banner": "...",
  "mobileBanner": "...",
  "channelStatus": 1,
  "livestreamStatus": 0,
  "livestreamLimit": 0,
  "isPremium": false,
  "payToViewProductId": null,
  "displayScore": 50
}
```

### Update Content (Movie/Series)

```
PUT /admin/v1/contents/{id}
```

```json
{
  "id": "content_id",
  "channelId": "channel_id",
  "contentDetails": {
    "title": "Movie Title",
    "description": "...",
    ...
  },
  "displayScore": 75
}
```

### Update Video

```
PUT /admin/v1/videos/{id}
```

```json
{
  "videoId": "video_id",
  "channelId": "channel_id",
  "name": "Video Name",
  ...
  "displayScore": 30
}
```

---

## Admin App Implementation Notes

1. **UI field**: Add a numeric input for "Display Score" on the channel, content, and video edit forms
2. **Validation**: The value is an integer >= 0. There is no upper limit
3. **Default**: New items get `0` automatically. Only set a score when you want to promote an item
4. **Tip**: Use increments of 10 or 100 to leave room for inserting items between existing scores later

---

## Interaction with Boosted Content

When a `homepageRowId` is provided on listing endpoints, the sort order is:

1. Boosted items first (by boost priority)
2. Then by `displayScore` descending
3. Then by date descending

Display score does **not** override boosted content priority.