ryan/lunarfront-app
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add lessons Phase 3: enrollments with capacity and time conflict checks

Browse Source 
Links members to schedule slots via enrollments. Enforces max_students
capacity on slots and prevents members from double-booking the same
day/time. Supports status transitions and filtering. 11 new tests
(51 total lessons tests).
This commit is contained in:
Ryan Moon
2026-03-30 09:23:43 -05:00
parent f777ce5184
commit 93405af3b2
8 changed files with 489 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

202
packages/backend/api-tests/suites/lessons.ts
View File

@@ -484,4 +484,206 @@ suite('Lessons', { tags: ['lessons'] }, (t) => {
})
t.assert.status(second, 201)
})
// ─── Enrollments: CRUD ───
t.test('creates an enrollment', { tags: ['enrollments', 'create'] }, async () => {
const acct = await t.api.post('/v1/accounts', { name: 'Enrollment Account', billingMode: 'consolidated' })
const member = await t.api.post(`/v1/accounts/${acct.data.id}/members`, { firstName: 'Emma', lastName: 'Chen' })
const instructor = await t.api.post('/v1/instructors', { displayName: 'Enrollment Instructor' })
const lessonType = await t.api.post('/v1/lesson-types', { name: 'Enrollment Type', durationMinutes: 30 })
const slot = await t.api.post('/v1/schedule-slots', {
instructorId: instructor.data.id,
lessonTypeId: lessonType.data.id,
dayOfWeek: 2,
startTime: '16:00',
})
const res = await t.api.post('/v1/enrollments', {
memberId: member.data.id,
accountId: acct.data.id,
scheduleSlotId: slot.data.id,
instructorId: instructor.data.id,
startDate: '2026-01-15',
monthlyRate: 120,
notes: 'Beginner piano student',
})
t.assert.status(res, 201)
t.assert.equal(res.data.status, 'active')
t.assert.equal(res.data.memberId, member.data.id)
t.assert.equal(res.data.monthlyRate, '120.00')
t.assert.equal(res.data.startDate, '2026-01-15')
t.assert.equal(res.data.makeupCredits, 0)
})
t.test('rejects enrollment without required fields', { tags: ['enrollments', 'create', 'validation'] }, async () => {
const res = await t.api.post('/v1/enrollments', {})
t.assert.status(res, 400)
})
t.test('enforces slot capacity', { tags: ['enrollments', 'create', 'capacity'] }, async () => {
const acct = await t.api.post('/v1/accounts', { name: 'Capacity Account', billingMode: 'consolidated' })
const m1 = await t.api.post(`/v1/accounts/${acct.data.id}/members`, { firstName: 'Student', lastName: 'One' })
const m2 = await t.api.post(`/v1/accounts/${acct.data.id}/members`, { firstName: 'Student', lastName: 'Two' })
const instructor = await t.api.post('/v1/instructors', { displayName: 'Capacity Instructor' })
const lessonType = await t.api.post('/v1/lesson-types', { name: 'Capacity Type', durationMinutes: 30 })
const slot = await t.api.post('/v1/schedule-slots', {
instructorId: instructor.data.id,
lessonTypeId: lessonType.data.id,
dayOfWeek: 3,
startTime: '14:00',
maxStudents: 1,
})
const first = await t.api.post('/v1/enrollments', {
memberId: m1.data.id,
accountId: acct.data.id,
scheduleSlotId: slot.data.id,
instructorId: instructor.data.id,
startDate: '2026-01-15',
})
t.assert.status(first, 201)
const second = await t.api.post('/v1/enrollments', {
memberId: m2.data.id,
accountId: acct.data.id,
scheduleSlotId: slot.data.id,
instructorId: instructor.data.id,
startDate: '2026-01-15',
})
t.assert.status(second, 409)
})
t.test('prevents member from enrolling in conflicting time', { tags: ['enrollments', 'create', 'conflict'] }, async () => {
const acct = await t.api.post('/v1/accounts', { name: 'Time Conflict Account', billingMode: 'consolidated' })
const member = await t.api.post(`/v1/accounts/${acct.data.id}/members`, { firstName: 'Busy', lastName: 'Student' })
const i1 = await t.api.post('/v1/instructors', { displayName: 'Conflict Instructor A' })
const i2 = await t.api.post('/v1/instructors', { displayName: 'Conflict Instructor B' })
const lt = await t.api.post('/v1/lesson-types', { name: 'Conflict LT', durationMinutes: 30 })
const slot1 = await t.api.post('/v1/schedule-slots', {
instructorId: i1.data.id, lessonTypeId: lt.data.id, dayOfWeek: 1, startTime: '10:00',
})
const slot2 = await t.api.post('/v1/schedule-slots', {
instructorId: i2.data.id, lessonTypeId: lt.data.id, dayOfWeek: 1, startTime: '10:00',
})
const first = await t.api.post('/v1/enrollments', {
memberId: member.data.id, accountId: acct.data.id,
scheduleSlotId: slot1.data.id, instructorId: i1.data.id, startDate: '2026-01-15',
})
t.assert.status(first, 201)
const second = await t.api.post('/v1/enrollments', {
memberId: member.data.id, accountId: acct.data.id,
scheduleSlotId: slot2.data.id, instructorId: i2.data.id, startDate: '2026-01-15',
})
t.assert.status(second, 409)
})
t.test('gets enrollment by id', { tags: ['enrollments', 'read'] }, async () => {
const acct = await t.api.post('/v1/accounts', { name: 'Get Enrollment Account', billingMode: 'consolidated' })
const member = await t.api.post(`/v1/accounts/${acct.data.id}/members`, { firstName: 'Get', lastName: 'Student' })
const instructor = await t.api.post('/v1/instructors', { displayName: 'Get Enrollment Instructor' })
const lt = await t.api.post('/v1/lesson-types', { name: 'Get Enrollment Type', durationMinutes: 30 })
const slot = await t.api.post('/v1/schedule-slots', {
instructorId: instructor.data.id, lessonTypeId: lt.data.id, dayOfWeek: 4, startTime: '15:00',
})
const created = await t.api.post('/v1/enrollments', {
memberId: member.data.id, accountId: acct.data.id,
scheduleSlotId: slot.data.id, instructorId: instructor.data.id, startDate: '2026-02-01',
})
const res = await t.api.get(`/v1/enrollments/${created.data.id}`)
t.assert.status(res, 200)
t.assert.equal(res.data.id, created.data.id)
})
t.test('returns 404 for missing enrollment', { tags: ['enrollments', 'read'] }, async () => {
const res = await t.api.get('/v1/enrollments/a0000000-0000-0000-0000-999999999999')
t.assert.status(res, 404)
})
t.test('updates an enrollment', { tags: ['enrollments', 'update'] }, async () => {
const acct = await t.api.post('/v1/accounts', { name: 'Update Enrollment Account', billingMode: 'consolidated' })
const member = await t.api.post(`/v1/accounts/${acct.data.id}/members`, { firstName: 'Update', lastName: 'Student' })
const instructor = await t.api.post('/v1/instructors', { displayName: 'Update Enrollment Instructor' })
const lt = await t.api.post('/v1/lesson-types', { name: 'Update Enrollment Type', durationMinutes: 30 })
const slot = await t.api.post('/v1/schedule-slots', {
instructorId: instructor.data.id, lessonTypeId: lt.data.id, dayOfWeek: 5, startTime: '17:00',
})
const created = await t.api.post('/v1/enrollments', {
memberId: member.data.id, accountId: acct.data.id,
scheduleSlotId: slot.data.id, instructorId: instructor.data.id, startDate: '2026-02-01',
})
const res = await t.api.patch(`/v1/enrollments/${created.data.id}`, {
monthlyRate: 150,
notes: 'Updated rate',
endDate: '2026-06-30',
})
t.assert.status(res, 200)
t.assert.equal(res.data.monthlyRate, '150.00')
t.assert.equal(res.data.notes, 'Updated rate')
t.assert.equal(res.data.endDate, '2026-06-30')
})
// ─── Enrollments: Status Transitions ───
t.test('status lifecycle: active → paused → active → cancelled', { tags: ['enrollments', 'status'] }, async () => {
const acct = await t.api.post('/v1/accounts', { name: 'Status Account', billingMode: 'consolidated' })
const member = await t.api.post(`/v1/accounts/${acct.data.id}/members`, { firstName: 'Status', lastName: 'Student' })
const instructor = await t.api.post('/v1/instructors', { displayName: 'Status Instructor' })
const lt = await t.api.post('/v1/lesson-types', { name: 'Status Type', durationMinutes: 30 })
const slot = await t.api.post('/v1/schedule-slots', {
instructorId: instructor.data.id, lessonTypeId: lt.data.id, dayOfWeek: 6, startTime: '09:00',
})
const created = await t.api.post('/v1/enrollments', {
memberId: member.data.id, accountId: acct.data.id,
scheduleSlotId: slot.data.id, instructorId: instructor.data.id, startDate: '2026-01-01',
})
t.assert.equal(created.data.status, 'active')
const paused = await t.api.post(`/v1/enrollments/${created.data.id}/status`, { status: 'paused' })
t.assert.equal(paused.data.status, 'paused')
const resumed = await t.api.post(`/v1/enrollments/${created.data.id}/status`, { status: 'active' })
t.assert.equal(resumed.data.status, 'active')
const cancelled = await t.api.post(`/v1/enrollments/${created.data.id}/status`, { status: 'cancelled' })
t.assert.equal(cancelled.data.status, 'cancelled')
})
// ─── Enrollments: List, Filter ───
t.test('lists enrollments with pagination', { tags: ['enrollments', 'read', 'pagination'] }, async () => {
const res = await t.api.get('/v1/enrollments', { limit: 100 })
t.assert.status(res, 200)
t.assert.ok(res.data.pagination)
t.assert.ok(res.data.data.length >= 1)
})
t.test('filters enrollments by instructor', { tags: ['enrollments', 'filter'] }, async () => {
const acct = await t.api.post('/v1/accounts', { name: 'Filter Enrollment Account', billingMode: 'consolidated' })
const member = await t.api.post(`/v1/accounts/${acct.data.id}/members`, { firstName: 'Filter', lastName: 'Student' })
const instructor = await t.api.post('/v1/instructors', { displayName: 'Filter Enrollment Instructor' })
const lt = await t.api.post('/v1/lesson-types', { name: 'Filter Enrollment Type', durationMinutes: 30 })
const slot = await t.api.post('/v1/schedule-slots', {
instructorId: instructor.data.id, lessonTypeId: lt.data.id, dayOfWeek: 0, startTime: '11:00',
})
await t.api.post('/v1/enrollments', {
memberId: member.data.id, accountId: acct.data.id,
scheduleSlotId: slot.data.id, instructorId: instructor.data.id, startDate: '2026-03-01',
})
const res = await t.api.get('/v1/enrollments', { instructorId: instructor.data.id, limit: 100 })
t.assert.status(res, 200)
t.assert.ok(res.data.data.every((e: any) => e.instructorId === instructor.data.id))
})
t.test('filters enrollments by status', { tags: ['enrollments', 'filter'] }, async () => {
const res = await t.api.get('/v1/enrollments', { status: 'active', limit: 100 })
t.assert.status(res, 200)
t.assert.ok(res.data.data.every((e: any) => e.status === 'active'))
})
})

19
packages/backend/src/db/migrations/0030_enrollments.sql Normal file
View File

@@ -0,0 +1,19 @@
-- Phase 3: Enrollments — member enrollment in a schedule slot
CREATE TYPE "enrollment_status" AS ENUM ('active', 'paused', 'cancelled', 'completed');
CREATE TABLE "enrollment" (
"id" uuid PRIMARY KEY DEFAULT gen_random_uuid(),
"member_id" uuid NOT NULL REFERENCES "member"("id"),
"account_id" uuid NOT NULL REFERENCES "account"("id"),
"schedule_slot_id" uuid NOT NULL REFERENCES "schedule_slot"("id"),
"instructor_id" uuid NOT NULL REFERENCES "instructor"("id"),
"status" enrollment_status NOT NULL DEFAULT 'active',
"start_date" date NOT NULL,
"end_date" date,
"monthly_rate" numeric(10,2),
"makeup_credits" integer NOT NULL DEFAULT 0,
"notes" text,
"created_at" timestamptz NOT NULL DEFAULT now(),
"updated_at" timestamptz NOT NULL DEFAULT now()
);

7
packages/backend/src/db/migrations/meta/_journal.json
View File

@@ -211,6 +211,13 @@
"when": 1774890000000,
"tag": "0029_schedule_slots",
"breakpoints": true
},
{
"idx": 30,
"version": "7",
"when": 1774900000000,
"tag": "0030_enrollments",
"breakpoints": true
}
]
}

36
packages/backend/src/db/schema/lessons.ts
View File

@@ -4,12 +4,15 @@ import {
varchar,
text,
time,
date,
numeric,
timestamp,
boolean,
integer,
pgEnum,
} from 'drizzle-orm/pg-core'
import { users } from './users.js'
import { accounts, members } from './accounts.js'
// --- Enums ---
@@ -57,6 +60,37 @@ export const scheduleSlots = pgTable('schedule_slot', {
updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
})
export const enrollmentStatusEnum = pgEnum('enrollment_status', [
'active',
'paused',
'cancelled',
'completed',
])
export const enrollments = pgTable('enrollment', {
id: uuid('id').primaryKey().defaultRandom(),
memberId: uuid('member_id')
.notNull()
.references(() => members.id),
accountId: uuid('account_id')
.notNull()
.references(() => accounts.id),
scheduleSlotId: uuid('schedule_slot_id')
.notNull()
.references(() => scheduleSlots.id),
instructorId: uuid('instructor_id')
.notNull()
.references(() => instructors.id),
status: enrollmentStatusEnum('status').notNull().default('active'),
startDate: date('start_date').notNull(),
endDate: date('end_date'),
monthlyRate: numeric('monthly_rate', { precision: 10, scale: 2 }),
makeupCredits: integer('makeup_credits').notNull().default(0),
notes: text('notes'),
createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
})
// --- Type exports ---
export type Instructor = typeof instructors.$inferSelect
@@ -65,3 +99,5 @@ export type LessonType = typeof lessonTypes.$inferSelect
export type LessonTypeInsert = typeof lessonTypes.$inferInsert
export type ScheduleSlot = typeof scheduleSlots.$inferSelect
export type ScheduleSlotInsert = typeof scheduleSlots.$inferInsert
export type Enrollment = typeof enrollments.$inferSelect
export type EnrollmentInsert = typeof enrollments.$inferInsert

61
packages/backend/src/routes/v1/lessons.ts
View File

@@ -7,8 +7,11 @@ import {
LessonTypeUpdateSchema,
ScheduleSlotCreateSchema,
ScheduleSlotUpdateSchema,
EnrollmentCreateSchema,
EnrollmentUpdateSchema,
EnrollmentStatusUpdateSchema,
} from '@lunarfront/shared/schemas'
import { InstructorService, LessonTypeService, ScheduleSlotService } from '../../services/lesson.service.js'
import { InstructorService, LessonTypeService, ScheduleSlotService, EnrollmentService } from '../../services/lesson.service.js'
export const lessonRoutes: FastifyPluginAsync = async (app) => {
// --- Instructors ---
@@ -147,4 +150,60 @@ export const lessonRoutes: FastifyPluginAsync = async (app) => {
if (!slot) return reply.status(404).send({ error: { message: 'Schedule slot not found', statusCode: 404 } })
return reply.send(slot)
})
// --- Enrollments ---
app.post('/enrollments', { preHandler: [app.authenticate, app.requirePermission('lessons.edit')] }, async (request, reply) => {
const parsed = EnrollmentCreateSchema.safeParse(request.body)
if (!parsed.success) {
return reply.status(400).send({ error: { message: 'Validation failed', details: parsed.error.flatten(), statusCode: 400 } })
}
const result = await EnrollmentService.create(app.db, parsed.data)
if ('error' in result) {
return reply.status(409).send({ error: { message: result.error, statusCode: 409 } })
}
return reply.status(201).send(result)
})
app.get('/enrollments', { preHandler: [app.authenticate, app.requirePermission('lessons.view')] }, async (request, reply) => {
const query = request.query as Record<string, string | undefined>
const params = PaginationSchema.parse(query)
const filters = {
memberId: query.memberId,
accountId: query.accountId,
instructorId: query.instructorId,
status: query.status?.split(',').filter(Boolean),
}
const result = await EnrollmentService.list(app.db, params, filters)
return reply.send(result)
})
app.get('/enrollments/:id', { preHandler: [app.authenticate, app.requirePermission('lessons.view')] }, async (request, reply) => {
const { id } = request.params as { id: string }
const enrollment = await EnrollmentService.getById(app.db, id)
if (!enrollment) return reply.status(404).send({ error: { message: 'Enrollment not found', statusCode: 404 } })
return reply.send(enrollment)
})
app.patch('/enrollments/:id', { preHandler: [app.authenticate, app.requirePermission('lessons.edit')] }, async (request, reply) => {
const { id } = request.params as { id: string }
const parsed = EnrollmentUpdateSchema.safeParse(request.body)
if (!parsed.success) {
return reply.status(400).send({ error: { message: 'Validation failed', details: parsed.error.flatten(), statusCode: 400 } })
}
const enrollment = await EnrollmentService.update(app.db, id, parsed.data)
if (!enrollment) return reply.status(404).send({ error: { message: 'Enrollment not found', statusCode: 404 } })
return reply.send(enrollment)
})
app.post('/enrollments/:id/status', { preHandler: [app.authenticate, app.requirePermission('lessons.edit')] }, async (request, reply) => {
const { id } = request.params as { id: string }
const parsed = EnrollmentStatusUpdateSchema.safeParse(request.body)
if (!parsed.success) {
return reply.status(400).send({ error: { message: 'Validation failed', details: parsed.error.flatten(), statusCode: 400 } })
}
const enrollment = await EnrollmentService.updateStatus(app.db, id, parsed.data.status)
if (!enrollment) return reply.status(404).send({ error: { message: 'Enrollment not found', statusCode: 404 } })
return reply.send(enrollment)
})
}

130
packages/backend/src/services/lesson.service.ts
View File

@@ -1,6 +1,6 @@
import { eq, and, count, type Column, type SQL } from 'drizzle-orm'
import { eq, and, ne, count, type Column, type SQL } from 'drizzle-orm'
import type { PostgresJsDatabase } from 'drizzle-orm/postgres-js'
import { instructors, lessonTypes, scheduleSlots } from '../db/schema/lessons.js'
import { instructors, lessonTypes, scheduleSlots, enrollments } from '../db/schema/lessons.js'
import type {
InstructorCreateInput,
InstructorUpdateInput,
@@ -8,6 +8,8 @@ import type {
LessonTypeUpdateInput,
ScheduleSlotCreateInput,
ScheduleSlotUpdateInput,
EnrollmentCreateInput,
EnrollmentUpdateInput,
PaginationInput,
} from '@lunarfront/shared/schemas'
import {
@@ -279,3 +281,127 @@ export const ScheduleSlotService = {
return slot ?? null
},
}
export const EnrollmentService = {
async create(db: PostgresJsDatabase<any>, input: EnrollmentCreateInput) {
// Check slot capacity for group lessons
const slot = await ScheduleSlotService.getById(db, input.scheduleSlotId)
if (!slot) return { error: 'Schedule slot not found' }
const [{ activeCount }] = await db
.select({ activeCount: count() })
.from(enrollments)
.where(
and(
eq(enrollments.scheduleSlotId, input.scheduleSlotId),
eq(enrollments.status, 'active'),
),
)
if (activeCount >= slot.maxStudents) {
return { error: 'Schedule slot is at capacity' }
}
// Check member not already enrolled in a slot at same day/time
const memberSlots = await db
.select({
dayOfWeek: scheduleSlots.dayOfWeek,
startTime: scheduleSlots.startTime,
})
.from(enrollments)
.innerJoin(scheduleSlots, eq(enrollments.scheduleSlotId, scheduleSlots.id))
.where(
and(
eq(enrollments.memberId, input.memberId),
eq(enrollments.status, 'active'),
),
)
const hasConflict = memberSlots.some(
(s) => s.dayOfWeek === slot.dayOfWeek && s.startTime === slot.startTime,
)
if (hasConflict) {
return { error: 'Member already has a lesson at this day and time' }
}
const [enrollment] = await db
.insert(enrollments)
.values({
memberId: input.memberId,
accountId: input.accountId,
scheduleSlotId: input.scheduleSlotId,
instructorId: input.instructorId,
status: 'active',
startDate: input.startDate,
endDate: input.endDate,
monthlyRate: input.monthlyRate?.toString(),
notes: input.notes,
})
.returning()
return enrollment
},
async getById(db: PostgresJsDatabase<any>, id: string) {
const [enrollment] = await db
.select()
.from(enrollments)
.where(eq(enrollments.id, id))
.limit(1)
return enrollment ?? null
},
async list(db: PostgresJsDatabase<any>, params: PaginationInput, filters?: {
memberId?: string
accountId?: string
instructorId?: string
status?: string[]
}) {
const conditions: SQL[] = []
if (filters?.memberId) conditions.push(eq(enrollments.memberId, filters.memberId))
if (filters?.accountId) conditions.push(eq(enrollments.accountId, filters.accountId))
if (filters?.instructorId) conditions.push(eq(enrollments.instructorId, filters.instructorId))
if (filters?.status?.length) {
const { inArray } = await import('drizzle-orm')
conditions.push(inArray(enrollments.status, filters.status as any))
}
const where = conditions.length > 0 ? and(...conditions) : undefined
const sortableColumns: Record<string, Column> = {
start_date: enrollments.startDate,
status: enrollments.status,
created_at: enrollments.createdAt,
}
let query = db.select().from(enrollments).where(where).$dynamic()
query = withSort(query, params.sort, params.order, sortableColumns, enrollments.createdAt)
query = withPagination(query, params.page, params.limit)
const [data, [{ total }]] = await Promise.all([
query,
db.select({ total: count() }).from(enrollments).where(where),
])
return paginatedResponse(data, total, params.page, params.limit)
},
async update(db: PostgresJsDatabase<any>, id: string, input: EnrollmentUpdateInput) {
const values: Record<string, unknown> = { ...input, updatedAt: new Date() }
if (input.monthlyRate !== undefined) values.monthlyRate = input.monthlyRate.toString()
const [enrollment] = await db
.update(enrollments)
.set(values)
.where(eq(enrollments.id, id))
.returning()
return enrollment ?? null
},
async updateStatus(db: PostgresJsDatabase<any>, id: string, status: string) {
const [enrollment] = await db
.update(enrollments)
.set({ status: status as any, updatedAt: new Date() })
.where(eq(enrollments.id, id))
.returning()
return enrollment ?? null
},
}