# Course Lesson — Free Preview Update

Adds a per-lesson "free preview" range to recorded-course video lectures
(`course_lessons`, `type = 'lesson'`), so a trainer can mark part of a real
curriculum video as watchable by guests/non-enrolled users, instead of the
only prior free-content option (`courses.demo_video`, a single separate
trailer clip).

## What changed

### Data model

New nullable columns on `course_lessons` (migration
`2026_09_23_000003_add_free_preview_to_course_lessons_table.php`), `type =
'lesson'` only — quiz rows never use them:

| Column | Type | Meaning |
|---|---|---|
| `is_free_preview` | boolean, default `false` | Whether this lesson has a free-to-watch range |
| `free_preview_from_seconds` | unsigned int, nullable | Start of the free range, in seconds into the video |
| `free_preview_to_seconds` | unsigned int, nullable | End of the free range, in seconds |

### Authoring (trainer)

`POST /api/v1/trainer/courses/{course}/lessons/video` and
`PUT /api/v1/trainer/lessons/video/{lesson}` accept the three new fields:

```json
{
  "is_free_preview": true,
  "free_preview_from_seconds": 0,
  "free_preview_to_seconds": 30
}
```

Validation (`VideoLessonRequest`):
- `is_free_preview` — boolean, optional.
- `free_preview_from_seconds` — required when `is_free_preview` is `true`, integer ≥ 0.
- `free_preview_to_seconds` — required when `is_free_preview` is `true`, integer, must be greater than `free_preview_from_seconds`.

The quiz endpoint (`.../lessons/quiz`) rejects all three fields as
`prohibited` (`QuizLessonRequest`), same as it already does for
`video`/`duration_seconds`.

### Exposure

- **Trainer / Admin** (`Trainer\Course\LessonResource`, `Admin\Course\LessonResource`) — always see `is_free_preview`, `free_preview_from_seconds`, `free_preview_to_seconds` for `type: "lesson"` items, regardless of the flag.
- **Public course page** (`GET /api/v1/user/courses/{course}`, guests and authenticated users alike, `User\Course\CourseCardResource`) — each item in `lessons[]` now includes `video`, `free_preview_from_seconds`, `free_preview_to_seconds` **only when `is_free_preview` is true**. Lessons without the flag keep the existing minimal shape (`id`, `type`, `title`, `sort_order`, `materials`) — no video URL leaks for locked lessons.
- **Enrolled curriculum** (`CurriculumItemResource`) is unchanged — the real, fully-unlocked video for an enrolled learner still comes from there, gated by progression as before.

### Enforcement model

The backend does not trim or transcode video — it hands the client the full
video URL plus the free range. The player is responsible for seeking to
`free_preview_from_seconds` and stopping playback at `free_preview_to_seconds`
for a non-enrolled viewer. This mirrors how `courses.demo_video` already
works and needs no new media-processing infrastructure.

## Files touched

- `database/migrations/2026_09_23_000003_add_free_preview_to_course_lessons_table.php` (new)
- `app/Models/CourseLesson.php` — casts for the three new columns
- `app/Http/Requests/Trainer/Course/VideoLessonRequest.php` — validation rules
- `app/Http/Requests/Trainer/Course/QuizLessonRequest.php` — prohibited rules
- `app/Http/Controllers/Api/V1/Trainer/VideoLessonController.php` — `fillableKeys()`
- `app/Http/Resources/Trainer/Course/LessonResource.php`
- `app/Http/Resources/Admin/Course/LessonResource.php`
- `app/Http/Resources/User/Course/CourseCardResource.php`
- `lang/en/attributes.php`, `lang/ar/attributes.php` — validation attribute labels
- `tests/Feature/Education/LessonFreePreviewTest.php` (new)
- `docs/postman-collection.json`, `docs/api/{admin,user,trainer,README}.md` — regenerated (`postman:generate`, `postman:markdown`, `postman:frontend-guide`)

## Tests

`tests/Feature/Education/LessonFreePreviewTest.php`:
- Trainer can flag a video lesson as a free preview with a valid range.
- `free_preview_from_seconds`/`free_preview_to_seconds` are required once `is_free_preview` is true.
- `free_preview_to_seconds` must be greater than `free_preview_from_seconds`.
- The quiz endpoint rejects all three fields.
- The public course-show payload exposes `video` + range only for free-preview lessons, and omits them entirely for locked ones.

Full `tests/Feature/Education` suite (335 tests) passes; `vendor/bin/pint --dirty` is clean.
