Functional breakdown of training admin and customer/mobile capabilities, lifecycle states, and runtime behavior.

Training - Feature Guide

1. Feature Overview

Training module provides a complete enrollment-oriented learning surface:

Admin operations: training, sessions, cohorts, waitlist, enrollment moderation
Customer/mobile operations: enrollment request, enrollment tracking, session access, cancellation request
Runtime/worker operations: synchronous order initiation + async payment finalization and training worker contracts

The module is commerce-linked and product-driven (productType = "training").

2. Route Ownership and Surfaces

Surface	Prefix	Owner module/controller
Admin training	`/api/admin/training`	`TrainingAdminModule` / `TrainingAdminController`
Admin sessions	`/api/admin/training/:trainingId/sessions`	`SessionAdminModule` / `SessionAdminController`
Admin cohorts	`/api/admin/training/:trainingId/cohorts`	`CohortAdminModule` / `CohortAdminController`
Admin enrollments	`/api/admin/training/enrollments`	`TrainingEnrollmentAdminModule` / `TrainingEnrollmentAdminController`
Customer	`/api/training`	`TrainingCustomerModule` / `TrainingCustomerController`
Mobile-composed customer	`/api/mobile/training`	`mobile.module.ts` via `TrainingCustomerAggregateModule`

Swagger tags:

Training (Admin)
Training Session (Admin)
Training Cohort (Admin)
Training Enrollment (Admin)
Training Enrollment (Mobile)

3. Admin Feature Matrix

Domain	Capabilities
Training management	List/detail/create/update/archive training; enrollment form-config read/update
Session management	List/create/detail/update/delete sessions; reorder; toggle recording availability
Cohort management	List/create/detail/update/cancel cohorts; assign cohort sessions
Waitlist management	Read cohort waitlist; promote waitlist entry
Enrollment admin	List/filter enrollments; detail with order/user/training metadata; update status

Admin control characteristics:

permission-guarded (@Permissions(...)) on all admin endpoints
action-scoped redis sliding-window throttling
explicit DTO validation and structured response wrappers

4. Customer/Mobile Feature Matrix

Feature	Endpoint(s)	Behavior
Enrollment request	`POST /training/enroll`	Creates/updates pending enrollment, creates training order, and returns payment-init payload
Enrollment list/detail	`GET /training/enrollments`, `GET /training/enrollments/:id`	Paginated self-service visibility
Cohort/session lookup	`GET /training/cohorts/:cohortId`, `GET /training/sessions/:sessionId`	Supports enrollment UX with typed detail payloads
Accessible sessions list	`GET /training/:trainingId/sessions`	Returns sessions; pending status gets payment-status note
Session content access	`GET /training/:trainingId/sessions/:sessionId/content`	Resolves recording/live access path
Cancellation request	`POST /training/enrollments/:id/request-cancellation`	Allows enrolled cancellation; pending cancellation rejected

Customer characteristics:

JWT-required
request throttling with customer-specific rate-limit keyspace
error-code based domain contract for UI flow branching

5. Key Business Rules

Training endpoints only accept products with productType = "training".
Product must be published + sellable for enrollment.
Enrollment cannot duplicate an active non-cancelled enrollment for same user/product.
DB uniqueness guard: only one enrolled row per (user_id, product_id) is allowed.
Pending enrollment compatibility is preserved: pending rows may exist with orderId = null before payment completion.
Cohort/session references in enrollment payload must belong to requested training.
Required dynamic form fields must be present when configured in form schema.
Session content access requires enrolled state.
If recording exists and is available, recording path wins.
If no recording, live-only access requires session.status = "live".
Pending enrollments cannot be cancelled by customer flow.
Cohort seat counters are adjusted on enrolled/cancelled transitions.

6. State Models

6.1 Training status lifecycle

6.2 Enrollment status lifecycle

6.3 Cohort status lifecycle

6.4 Customer journey

7. Feature-Level Caching and Rate Limits

7.1 Cache keyspaces

training:admin:list:
training:admin:detail:
training:session:admin:list:
training:session:customer:list:
training:cohort:admin:list:
training:cohort:waitlist:
training:enrollment:list:
training:enrollment:detail:
training:enrollment:admin:list:
training:enrollment:admin:detail:
training:product-access:user:

7.2 Rate-limit behavior

Admin key prefix: rl:training:admin:
Customer key prefix: rl:training:customer:
Exceeded window -> RateLimitExceededException (RATE_LIMIT_EXCEEDED)
Redis check failure -> request allowed + warning logged

8. Queue and Worker Behavior

8.1 Order-driven enrollment completion

Current enrollment path is order-driven:

customer enrollment API creates pending enrollment + training order/payment initiation synchronously
payment redirect verification enqueues order.payment_success / order.payment_failed
order processor finalizes training_enrollment and product_access based on payment outcome

8.2 Training queue contract

Training queue contracts exist in @bullhouse/jobs:

queue: training
jobs:
- training.create_enrollment
- training.cancel_enrollment

TrainingProcessor handles both and logs standardized runtime events:

[start]
[success]
[skip]
[failure]

9. Error UX Mapping

Error code	Typical UI action
`TRAINING_PRODUCT_REQUIRED`	Show "unsupported product" message and exit enrollment flow
`TRAINING_PRODUCT_UNAVAILABLE`	Disable enroll CTA and show unavailable state
`TRAINING_ALREADY_ENROLLED`	Redirect to existing enrollment view
`TRAINING_INVALID_FORM_DATA`	Highlight required form fields
`TRAINING_COHORT_FULL`	Offer waitlist or alternative cohort selection
`TRAINING_COHORT_CLOSED`	Disable cohort option
`TRAINING_SESSION_NOT_LIVE`	Show schedule/coming-soon state
`TRAINING_RECORDING_NOT_AVAILABLE`	Show no-recording-available message
`TRAINING_ENROLLMENT_CANCEL_NOT_ALLOWED`	Disable cancellation action for pending rows
`RATE_LIMIT_EXCEEDED`	Show retry-later toast/banner

10. Release/QA Checklist

Admin CRUD for training/session/cohort/enrollment verified with permission guards.
Cohort seat count transitions validated for enroll/cancel/admin status updates.
Enrollment idempotency validated for repeated request submission.
Session access behavior validated for pending vs enrolled states.
Recording/live access branch validated against session status and URLs.
Waitlist promote flow validated for mismatch/not-found/idempotent cases.
Cache invalidation verified for enrollment/session/cohort/product-access writes.
/api/mobile/training/* routes verified against customer contract and DTOs.

apps/fumadocs/content/docs/developer/payment/training-enrollment-flow.mdx
apps/fumadocs/content/docs/developer/payment/cart-checkout-flow.mdx
apps/fumadocs/content/docs/developer/payment/course-booklet-flow.mdx

Time fields in this module are stored as timezone-aware values and should be handled as ISO-8601 instants by API consumers.

Training Module Feature Guide