@driveup/schema 0.2.7 → 0.3.0

package/lib/profile/company/course/appointment.entity.d.ts

@@ -0,0 +1,271 @@
+import { Activity, Appointment, Period, RecurringAppointment } from '@driveup/common';
+import { CompanyCourseLessonEntity } from './lesson.entity';
+import { StudentTrainingAppointmentEntity } from '../../student/program/training/appointment.entity';
+import { CompanyInstructorEntity } from '../instructor/instructor.entity';
+import { TrackableEntity } from '../../../utils/trackable';
+import { IDateAssignment, IDateDuration, IDateUpdate, WeekDay } from '@driveup/shared';
+import { DateTime } from 'luxon';
+/**
+ * Represents a series of training appointment offers managed by the company.
+ *
+ * This entity defines appointment templates that serve as available time slots
+ * for student training sessions. Companies manage these appointments to organize
+ * their course training schedules, which students can then book.
+ *
+ * Supports both single and recurring appointments with flexible scheduling options
+ * including:
+ * - Weekly repetitions on specific weekdays
+ * - Custom date ranges for recurring appointments
+ * - Exception handling for skipped dates
+ * - Per-date overrides for time, instructor, and duration
+ *
+ * @remarks
+ * This is a company-managed entity that creates the foundation for student
+ * training bookings. Each appointment definition can generate multiple actual
+ * student appointments based on its repetition settings.
+ *
+ * @see {@link CompanyCourseLessonEntity} for the associated course lesson
+ * @see {@link StudentTrainingEntity} for student bookings
+ */
+export declare class CompanyCourseScheduleEntity extends TrackableEntity<RecurringAppointment> {
+    /**
+     * Company course lesson
+     */
+    lessonId: number;
+    /**
+     * In-charge instructor for the appointment
+     * For driving courses, can be empty
+     */
+    instructorId: number;
+    /**
+     * Represents the lesson start date for single appointments by student trainings.
+     * @remarks By recurring appoitmnets this field represents start of sierie
+     */
+    startDate: Date;
+    /**
+     * Represents the lesson end date for single appointments by student trainings.
+     * @remarks By recurring appoitmnets this field represents end of sierie (repeat until this date)
+     */
+    endDate: Date;
+    /**
+     * Duration of the appointment in minutes
+     * By fix courses this value is inherited from lesson
+     */
+    duration: number;
+    /**
+     * Indicates if the appointment is recurring
+     */
+    repetition: boolean;
+    /**
+     * Weekdays on which the appointment recurs
+     */
+    weekdays: WeekDay[];
+    /**
+     * Skipped dates for this recurring appointment
+     */
+    skippedDates: Date[];
+    /**
+     * Changed dates for this recurring appointment
+     */
+    updates: IDateUpdate[];
+    /**
+     * Different instructors for specific dates
+     */
+    instructors: IDateAssignment[];
+    /**
+     * Different durations for specific dates
+     */
+    durations: IDateDuration[];
+    /**
+     * Course lesson
+     */
+    lesson: Promise<CompanyCourseLessonEntity>;
+    /**
+     * Company instructor relation
+     */
+    instructor: Promise<CompanyInstructorEntity>;
+    /**
+     * Student training appointments relation
+     * - Will not be used for driving courses
+     */
+    studentSchedule: Promise<StudentTrainingAppointmentEntity[]>;
+    /**
+     * Creates a new CompanyCourseScheduleEntity instance
+     * @param props - Partial properties to initialize the entity with
+     */
+    constructor(props?: Partial<CompanyCourseScheduleEntity>);
+    /**
+     * Converts the entity to a RecurringAppointment model instance
+     * @returns Promise resolving to RecurringAppointment model with lesson, instructor, and scheduling details
+     */
+    toModel(): Promise<RecurringAppointment<any>>;
+    /**
+     * Returns a summary representation of the appointment
+     * @returns Promise resolving to RecurringAppointment model (same as toModel())
+     */
+    toSummary(): Promise<RecurringAppointment<any>>;
+    /**
+     * Retrieves all tracked activities for this appointment
+     * Includes creation and update timestamps and associated users
+     * @returns Promise resolving to array of Activity objects filtered to exclude null values
+     */
+    getActivities(): Promise<Activity[]>;
+    getCompany(): Promise<import("../company.entity").CompanyEntity>;
+    getCourse(): Promise<import("./course.entity").CompanyCourseEntity>;
+    getInstructor(): Promise<CompanyInstructorEntity>;
+    getInstructorByDate(date: Date): Promise<CompanyInstructorEntity>;
+    /************************* Manage student appointments *************************/
+    /**
+     * Get list of related student training appointments, which's training is not terminated
+     * @param date Date - defaulted to this.startDate - Must be provided for flexible course appointments
+     * @returns StudentTrainingAppointmentEntity[]
+     */
+    getStudentAppointments(date?: Date): Promise<StudentTrainingAppointmentEntity[]>;
+    /**
+     * Get total number of students who attended the appointment in the given date
+     * @param date Date - defaulted to this.startDate - Must be provided for flexible course appointments
+     */
+    getTotalAttended(date?: Date): Promise<number>;
+    /**
+     * Get total number of students who where absent in the appointment in the given date
+     * @param date Date - defaulted to this.startDate - Must be provided for flexible course appointments
+     */
+    getTotalAbsent(date?: Date): Promise<number>;
+    /**
+     * Get the count of taken seats for this appointment
+     * - Only applicable for preparation catalog type courses. Returns null for other catalog types.
+     * @param startDate Date - Optional - Only send for flexible courses to specify the desired appointment's startDate
+     * @returns number - count of registered student appointments for this appointment
+     */
+    getTakenSeats(startDate?: Date): Promise<number>;
+    /**
+     * Get the count of present students for this appointment
+     * - Only applicable for preparation catalog type courses. Returns null for other catalog types.
+     * @param startDate Date - Optional - Only send for flexible courses to specify the desired appointment's startDate
+     * @returns number - count of attended student appointments for this appointment
+     */
+    getTotalPresentStudents(startDate?: Date): Promise<number>;
+    /************************* Flexible courses *************************/
+    /**
+     * Finds if there is an appointment in the given date (checking all of the updates), and returning it if is found
+     * @param date Date - the date to check if belongs to an existing appointment
+     * @returns Appointment if an appointment is found in the given date, null otherwise
+     */
+    getAppointment(date: Date): Promise<Appointment>;
+    /**
+     * Load all appointments of the definition within the given period
+     * @description currently only works for flexible course schedules, and will return an empty array if the related course is fixed. but can and must be extended in the future to return the entire appointment list of the schedule, even if the appointment is fixed, or for another product type entirely.
+     * @param period Period
+     * @param instructorIds number[] - instructorId to filter by (return only appointments related to this instructor id)
+     * @param searchPhrase string - optional search phrase to filter appointments by (course title / part title / registered student name)
+     * @returns All appointments of the definition within the given period, filtered by instructorId if provided
+     */
+    getAppointments(period: Period, instructorIds?: number[], searchPhrase?: string): Promise<Appointment[]>;
+    /**
+     * Check if there is one appointment with empty seats
+     *
+     * If the definition has no appointments in the given period, returns true.
+     * Since the functions is supposed to return wether any of the definition's appointments have empty seats
+     */
+    hasAppointmentWithEmptySeats(period: Period): Promise<boolean>;
+    /**
+     *
+     * @param period Period
+     * @returns DateTime if a first appointment is found, null otherwise
+     */
+    getFirstAppointmentDateInPeriod(period: Period): DateTime;
+    /**
+     * @description Get detailed information about an appointment
+     * @param date - DateTime - is presumed to be related to an appointment in this definition
+     * @param filteredInstructorIds - number - optional - instrucotr id to filter the appointment by
+     * @returns Appointment - appointment information (id, start and end date, instructor information)
+     */
+    getAppointmentInformation(date: DateTime, filteredInstructorIds?: number[]): Promise<Appointment>;
+    /**
+     * @description Only for repeted definitions (repetition = true)
+     * @description Finds the final date of the appointment, considering any date updates (updates in the startDate)
+     * @description If no date updates are found, the original date will be returned
+     * @param date DateTime - original date of the appointment (default return value, if no date updates are found)
+     * @returns DateTime - final date of the appointment
+     */
+    getUpdatedDate(date: DateTime): DateTime;
+    /**
+     * @description Only for repeted definitions (repetition = true)
+     * @description Checks wether or not the appointment related to the given date has been removed from schedule (pushed in the skippedDates array)
+     * @param date DateTime - date of the appointment
+     * @returns DateTime - true if the appointment is skipped, false otherwise
+     */
+    isDateSkipped(date: DateTime): boolean;
+    /**
+     * @description Only for repeted definitions (repetition = true)
+     * @description Finds the final duration of the appointment, considering any duration updates
+     * @description If no duration updates are found, this.duration will be returned by default
+     * @param date DateTime - date of the appointment
+     * @returns number - duration of the appointment (in minutes)
+     */
+    getAppointmentDuration(date: DateTime): number;
+    /**
+     * @description Checks weather or not there is a student with a matching name registered in this schedule for the given appointment
+     * @description Currently only works for flexible course trainings (MVP logic), and will always return false for fixed course trainings
+     * Must be renamed and extended in the future to support fixed course trainings as well, but will remain as is for the sake of MVP Migration
+     * @param appointment Appointment - appointment to check for registered students
+     * @param studentName string - name of the student to check for registration
+     * @returns boolean - Weather or not there a student with the given name registered for the appointment
+     */
+    isStudentRegistered(appointment: Appointment, studentName: string): Promise<boolean>;
+    /**
+     * @description Doesn't check for the definition's endDate, or updates and skippedDates
+     * @returns the next appointment based on repetition logic and weekdays assigned
+     */
+    getNextAppointmentDate(date: DateTime): DateTime;
+    /**
+     * Get the instructor registered for the appointment (works for repeated and single appointments)
+     * @param date Date - the date of the appointment
+     * @returns Instructor - simple instructor model
+     */
+    getAppointmentInstructor(date: DateTime): Promise<{
+        id: number;
+        name: string;
+        image: string;
+        phone: string;
+        role: import("@driveup/shared").Role;
+        status: import("@driveup/shared").AccountStatus;
+        canReinstate: boolean;
+        calendarLinks: import("@driveup/common").Link[];
+    }>;
+    /**
+     * @param date DateTime - is presumed to belong to an existing appointment
+     * @returns number - instructor id for the appointment of the given date
+     */
+    getAppointmentInstructorId(date: DateTime): number;
+    /**
+     * Find instructor by id and map with simple information to User model
+     * @param id instructor id
+     * @returns Object - For the MVP it returns an object mapped like CompanyInstructorMapper.toSimple with the same interface. should be replaced with Person model in the future
+     */
+    getInstructorById(id: number): Promise<{
+        id: number;
+        name: string;
+        image: string;
+        phone: string;
+        role: import("@driveup/shared").Role;
+        status: import("@driveup/shared").AccountStatus;
+        canReinstate: boolean;
+        calendarLinks: import("@driveup/common").Link[];
+    }>;
+    /**
+     * Get total number of appointments that have any update (duration/instructor/date) after the given date
+     * @param from Date - if null, from definition start date
+     * @returns number - total updated appointments
+     */
+    getTotalUpdatedAppointments(from: Date): number;
+    getRemainingSeats(date: Date): Promise<number>;
+    /**
+     * This method must be called anytime when definition's endDate is changed to a value other than null/undefined
+     *
+     * Removes all 'updates', 'skippedDates', 'instructors' and 'durations' after the definition's endDate
+     *
+     * - Does not save the definition
+     */
+    removeUpdatesAfterEndDate(): boolean;
+}