---
feature: Trainer course lifecycle
slug: courses
surface: trainer
consumer: flutter
version: 1.0.1
status: ready
brd_version: "v1.0 + additional requirements"
brd_ids: [TRR-017, TRR-018, TRR-019, TRR-020, TRR-021, TRR-024, TRR-027]
business_rules: [BR-CRS-01, BR-CRS-02, BR-CRS-04, BR-CRS-06, BR-CRS-07]
decisions: [D2, D3, DEC-10, DEC-11, DEC-12, DEC-34]
schema_tables: [courses, course_requests, enrollments]
related_docs: [course-create.md]
last_updated: 2026-11-15
---

## Quick reference

**1.0.1 · ready (Batch 1a, trainer side) · Bearer trainer token**. IDs are UUIDs; all endpoints are under `/api/v1/trainer`.

| Method | Path | Purpose |
|---|---|---|
| GET | `/courses?tab=published` | Own courses by tab, paginated |
| GET | `/courses/{course}` | Own course details |
| PUT | `/courses/{course}` | Edit draft/rejected, request published changes, or update session link |
| POST | `/courses/{course}/submit` | Submit draft or edited rejected course |
| GET | `/courses/{course}/enrollments` | Confirmed enrollee summary and names |
| POST | `/courses/{course}/date` | Set initial date after minimum is reached |

Tabs: `under_review`, `published`, `rejected`, `completed`, `cancelled` (also `draft`). Published includes `awaiting_date` and `suspended`. Unknown tabs return 422. Threshold presentation uses `threshold.state`: `awaiting_minimum` means **Waiting for minimum**, `awaiting_date` means minimum reached, and `date_set` means scheduled. `minimum_progress` gives confirmed/minimum.

Errors: `COURSE_MINIMUM_ABOVE_SEATS`, `COURSE_SEATS_BELOW_CONFIRMED`, `COURSE_PRICE_LOCKED`, `COURSE_ADMIN_CHANGE_REQUIRED`, `INVALID_STATE_TRANSITION`, `PERMISSION_DENIED`, `BUSINESS_RULE_VIOLATED` (422). Invalid request fields return 422; another trainer's course returns 404.

Open decisions: DEC-10 and DEC-11 assumptions below. The admin side (review, edit review, completion, cancellation) is in [admin/courses.md](../admin/courses.md). Owner completion, cancellation requests and the center workflow are outside this batch; their action flags remain false where no endpoint exists.

## Flow and permissions

Independent trainers view their courses, edit drafts or rejected courses and submit them; rejected edits remain rejected until submitted. Published substantive edits create one under-review request while the approved version stays live (D2). An external course's `session_link` is updated immediately without review. A pending edit blocks a second substantive request, not an operational link update. Seats cannot fall below confirmed enrollments; price is locked after the first confirmed enrollment (DEC-34). Published date, time, venue, type and related scheduling changes require an administrator.

Affiliated trainers use these same endpoints for their own courses. They can create and edit drafts, view their courses and enrollees, and update an external session link. The center owns the course, reviews/submits drafts, requests substantive changes and sets the initial threshold date; those center endpoints are outside this batch. Affiliated trainers cannot submit, request published substantive edits or assign the threshold date through trainer endpoints.

Only confirmed enrollments count toward capacity and the minimum. On reaching the minimum, the course moves to `awaiting_date`, remains sellable, and its owner receives `course.minimum_reached`. An independent trainer sets the initial date; confirmed enrollees receive `course.date_set`. A repeated payment callback or identical date assignment does not send the notification twice. Notification payload metadata contains `course_id` (UUID); delivery uses the existing database channel.

## Requests and validation

See [course-create](course-create.md) for create fields. `PUT` accepts partial fields; `session_link` is nullable, URL, max 1000 characters, and only applies to external courses. Substantive fields include name, description, category, price, seats and sessions. Published changes to `type`, city, scheduling or venue return `COURSE_ADMIN_CHANGE_REQUIRED` (including type changes after confirmed enrollment). The current approved values do not change until review. Price is a two-decimal string; seats must be at least the confirmed count and minimum threshold.

`GET /courses` accepts `tab`, `status` and `per_page` (1–50). `tab` groups statuses (`published` = published + awaiting date + suspended); `status` is an exact match and is ignored when `tab` is sent. `GET /courses/{course}/enrollments` accepts `per_page` (1–50). The latter returns `summary.seats`, `confirmed_count`, `remaining_seats`, `min_enrollments` and a paginated `enrollments` list containing UUID, trainee name, status and confirmation date; no payment data is exposed.

`POST /courses/{course}/date` requires `starts_on` (Y-m-d, today or later), `start_time` (H:i), and `duration_minutes` (15–1440). It is valid only after the minimum is reached. An identical replay succeeds; a different second assignment is rejected.

## Actions and states

Each course always contains `can_view`, `can_edit`, `can_resubmit`, `can_request_edit`, `can_complete`, `can_cancel_request`, `can_view_enrollees`, `can_view_reason`, `can_submit`, `can_update_session_link` and `can_set_date`. Flags reflect the trainer type and implemented operations. Under review is view only; rejected allows edit and independent resubmit and displays the rejection reason; published permits independent substantive requests and enrollee viewing; completed permits viewing and enrollee viewing; cancelled permits viewing. The operational link is available for published external courses including `awaiting_date`. Completion and cancellation flags are false in this batch. Optional values such as rejection reason and threshold are null when absent.

## Real responses

Captured from passing feature tests; UUIDs and dates vary. Date assignment response:

```json
{
  "status": "success",
  "message": "Updated successfully",
  "data": {
    "id": "a33b5b72-f98e-45b0-9f44-e05cb641a694",
    "code": "8YEVVUIMCRJ6ZCOEZKWY",
    "status": {
      "value": "published",
      "label": "منشور"
    },
    "type": {
      "value": "in_person",
      "label": "حضوري"
    },
    "name": "دورة 676696",
    "description": "وصف الدورة",
    "images": [
      "https://ui-avatars.com/api/?name=N&background=f3f4f6&color=9ca3af&size=200"
    ],
    "category": {
      "id": "a33b5b72-f773-4ed1-aa03-a8714afdb970",
      "name": "تصنيف 209191"
    },
    "city": {
      "id": "a33b5b72-f8ce-4f3c-bef8-660153768b1e",
      "name": "مدينة 924616"
    },
    "is_free": false,
    "price": "100.00",
    "proposed_price": null,
    "seats": 10,
    "confirmed_count": 1,
    "remaining_seats": 9,
    "start_mode": {
      "value": "threshold",
      "label": "الحد الأدنى"
    },
    "min_enrollments": 1,
    "minimum_reached_at": "2026-11-15T14:35:26+00:00",
    "minimum_progress": {
      "confirmed": 1,
      "minimum": 1
    },
    "threshold": {
      "state": "date_set",
      "minimum": 1,
      "confirmed": 1,
      "remaining_to_minimum": 0,
      "reached": true,
      "minimum_reached_at": "2026-11-15T14:35:26+00:00",
      "date_deadline_at": null,
      "date_set_at": "2026-11-15T14:35:26+00:00",
      "expected_duration": null
    },
    "sessions_count": 1,
    "starts_on": "2026-11-25",
    "start_time": "18:30",
    "duration_minutes": 90,
    "ends_at": "2026-11-25T20:00:00+00:00",
    "external_link": null,
    "session_link": null,
    "access_instructions": null,
    "venue": {
      "name": null,
      "address": null,
      "map_url": null,
      "notes": null
    },
    "rejection_reason": null,
    "points": null,
    "submitted_at": null,
    "can_view": true,
    "can_view_enrollments": true,
    "can_edit": true,
    "can_submit": false,
    "can_resubmit": false,
    "can_request_edit": true,
    "can_update_session_link": false,
    "can_set_date": false,
    "can_complete": false,
    "can_cancel_request": false,
    "can_view_enrollees": true,
    "can_view_reason": false,
    "created_at": "2026-11-15T14:35:26+00:00"
  }
}
```

Enrollees response:

```json
{
  "status": "success",
  "message": "",
  "data": {
    "summary": {
      "seats": 10,
      "confirmed_count": 1,
      "remaining_seats": 9,
      "min_enrollments": null
    },
    "enrollments": {
      "data": [
        {
          "id": "a33b5b54-e841-4fa7-85e2-c8d18f755f1a",
          "trainee": {
            "name": "Tyshawn King"
          },
          "status": {
            "value": "confirmed",
            "label": "مؤكد"
          },
          "enrolled_at": "2026-11-15T14:35:06+00:00"
        }
      ],
      "links": {
        "first": "http://localhost/api/v1/trainer/courses/a33b5b54-e739-47c2-b703-d16481c3fdac/enrollments?page=1",
        "last": "http://localhost/api/v1/trainer/courses/a33b5b54-e739-47c2-b703-d16481c3fdac/enrollments?page=1",
        "prev": null,
        "next": null
      },
      "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 1,
        "links": [
          {
            "url": null,
            "label": "&laquo; Previous",
            "page": null,
            "active": false
          },
          {
            "url": "http://localhost/api/v1/trainer/courses/a33b5b54-e739-47c2-b703-d16481c3fdac/enrollments?page=1",
            "label": "1",
            "page": 1,
            "active": true
          },
          {
            "url": null,
            "label": "Next &raquo;",
            "page": null,
            "active": false
          }
        ],
        "path": "http://localhost/api/v1/trainer/courses/a33b5b54-e739-47c2-b703-d16481c3fdac/enrollments",
        "per_page": 15,
        "to": 1,
        "total": 1
      }
    }
  }
}
```

## Errors

| HTTP | Code | Meaning |
|---|---|---|
| 422 | `COURSE_MINIMUM_ABOVE_SEATS` | Minimum exceeds seats. |
| 422 | `COURSE_SEATS_BELOW_CONFIRMED` | Seats below confirmed count. |
| 422 | `COURSE_PRICE_LOCKED` | Price changed after a confirmed enrollment. |
| 422 | `COURSE_ADMIN_CHANGE_REQUIRED` | Published schedule, type or venue change requires admin. |
| 422 | `INVALID_STATE_TRANSITION` | State does not allow the action, or a different date/edit is already pending. |
| 422 | `PERMISSION_DENIED` | Center-owned action attempted by affiliated trainer. |
| 422 | `BUSINESS_RULE_VIOLATED` | Other business rule fails. |
| 422 | validation errors | Invalid shape or unknown tab. |
| 404 | — | Course does not belong to this trainer. |

## Open decisions

- **DEC-10 (open):** batch assumption: published date, time, hall and type changes are admin-only; assigning the first date after the threshold is a separate action.
- **DEC-11 (open):** batch assumption: end time = date + start time + duration. Only manual completion is planned for this batch; auto-completion is Sprint 3. The completion endpoint and its side effects are outside this implementation.

### Known limits of this batch

- **Threshold state:** a threshold course stays `published` until its minimum is reached, then becomes `awaiting_date`. There is no separate "waiting for minimum" status; read `threshold.state` (`awaiting_minimum` / `awaiting_date` / `date_set`) and `minimum_progress`.
- **Unchanged admin-only fields:** re-sending `type`, `city_id`, schedule, threshold or venue fields with their current value on a published course is not a change and is not refused (BR-CRS-07 / DEC-10).
- **Affiliated trainers** cannot set a threshold course date (`PERMISSION_DENIED`); the center endpoint arrives with the training-center batch, until then such courses stay `awaiting_date`.
- **Deadlines are stored, not enforced:** `minimum_deadline_at` and `date_deadline_at` are returned but nothing acts when they pass (no scheduler in this batch).

## Acceptance and integration checklist

- TRR-017/019/021: use tabs and action flags; display rejection reason and keep the approved version visible while edits await review.
- TRR-024/BR-CRS-04: display confirmed counts and names only; show threshold progress and date state.
- TRR-027/WF-04: send operational link separately when it must apply immediately.
- No migration ships with this batch. Feature tests ran on SQLite; the `lockForUpdate` paths (payment confirmation, date assignment, published edit) have not been exercised under concurrent load on MySQL. Notification delivery was tested with fakes, not a real delivery service.

## Version history

| Version | Date | Type | Summary | App action required |
|---|---|---|---|---|
| 1.0.1 | 2026-11-15 | Fix | Unchanged admin-only fields no longer refused; `status` filter exact; limits documented. | None. |
| 1.0.0 | 2026-11-15 | Initial | Trainer lifecycle, edit requests, threshold scheduling and enrollees. | Integrate tabs, flags and typed errors. |

## Changelog

### 1.0.1 — 2026-11-15
- **Fixed:** re-sending an admin-only field (`type`, `city_id`, schedule, threshold, venue) with its current value on a published course is no longer refused with `COURSE_ADMIN_CHANGE_REQUIRED`.
- **Changed:** `GET /courses?status=` is an exact match; use `tab=published` for the grouped tab. Known limits documented. **Breaking:** No.

### 1.0.0 — 2026-11-15

Added trainer course lifecycle endpoints and contracts (TRR-017..021, TRR-024, TRR-027; D2, DEC-34). App action: integrate flags and typed errors.
