@seniorsistemas/hcm-clocking-event-rule-nodejs 0.35.0

package/src/data/schedules/workshiftChange.ts

@@ -0,0 +1,76 @@
+import { ObjectUtils } from "src/utils/object.utils";
+import { WorkshiftBase, WorkshiftBaseParams } from "../foundation/workshiftBase";
+
+/**
+ * @hidden
+ * Histórico de escala do colaborador.
+ * O histórico de escala é utilizado para verificar o escala do colaborador em uma data específica.
+ */
+export interface WorkshiftChangeParams extends WorkshiftBaseParams {
+    /**
+     * Data final da troca de escala.
+     */
+    endDate: Date;
+}
+
+/**
+ * Representa uma programação de troca de escala.
+ * 
+ * @example
+ * ```typescript
+ * workshiftChange.startDate; // Retorna a data inicial da troca de escala.
+ * workshiftChange.endDate; // Retorna a data final da troca de escala.
+ * workshiftChange.workshift; // Retorna a escala associada à troca.
+ * workshiftChange.workshift.code; // Retorna o código da escala.
+ * ```
+ * @see {@link Workshift}
+ * 
+ */
+export class WorkshiftChange extends WorkshiftBase {
+
+    /**
+     * Data final da troca de escala.
+     */
+    protected readonly _endDate: Date;
+
+    /**
+     * @hidden
+     * Construtor da classe WorkshiftChange.
+     * @param params Parâmetros necessários para a criação de WorkshiftChange.
+     */
+    constructor(params: WorkshiftChangeParams) {
+        super(params);
+        this._endDate = ObjectUtils.toDateOrThrow(params.endDate, "WorkshiftChange.endDate");
+    }
+
+    /**
+     * Data final da troca de escala.
+     * @example
+     * ```typescript
+     * let endDate = workshiftChange.endDate; // Retorna a data final da troca de escala.
+     * ```
+     * 
+     * @returns Data final da troca de escala.
+     * 
+     */
+    get endDate(): Date {
+        return this._endDate;
+    }
+
+    /**
+     * Clona a instância de WorkshiftChange.
+     * 
+     * @returns Uma nova instância de WorkshiftChange com os mesmos parâmetros.
+     */
+    public static clone(object: WorkshiftChange): WorkshiftChange {
+        const workshiftChangeParams: WorkshiftChangeParams = {
+            startDate: object.startDate,
+            endDate: object.endDate,
+            workshiftId: object.workshiftId,
+            workshiftGroupId: object.workshiftGroupId
+        };
+        return new WorkshiftChange(workshiftChangeParams);
+    }
+
+    
+}

package/src/data/timeEvaluation/adjustmentReason.ts

@@ -0,0 +1,46 @@
+/**
+ * @hidden
+ * Parâmetros para criar um motivo de AdjustmentReason.
+ * @param code código do motivo de acerto.
+ * @typedef {Object} AdjustmentReasonParams
+ */
+export interface AdjustmentReasonParams {
+    code: number;
+}
+
+/**
+ * Representa um motivo de acerto.
+ * Um motivo de acerto é utilizado para justificar ajustes em horários ou datas de trabalho.
+ * @example
+ * ```typescript
+ * adjustmentReason.code; // Retorna o código do motivo de acerto.
+ * ```
+ */
+export class AdjustmentReason {
+    /**
+     * Código do motivo de acerto.
+     * @param code código do motivo de acerto.
+     */
+    private readonly _code: number;
+
+    /**
+     * @hidden
+     */
+    constructor(params: AdjustmentReasonParams) {
+        this._code = params.code;
+    }
+
+    /**
+     * Código do motivo de acerto.
+     * 
+     * @example
+     * ```typescript
+     * let code = adjustmentReason.code; // Retorna o código do motivo de acerto.
+     * ```
+     * @returns Código do motivo de acerto.
+     */
+    get code(): number {
+        return this._code;
+    }
+}
+

package/src/data/timeEvaluation/clockingEvent.ts

@@ -0,0 +1,198 @@
+import { ObjectUtils } from "../../utils/object.utils";
+import { DateUtils } from '../../utils/dateUtils';
+
+/**
+ * @hidden
+ * Interface para os parâmetros de ClockingEvent.
+ */
+export interface ClockingEventParams {
+    clockingEventDate: Date;
+    clockingEventTime: number;
+    functionCode: number;
+    originType: ClockingEventOriginType;
+    useType: ClockingUseType;
+}
+
+/**
+ * Enumeração para os tipos de origem de marcação.
+ * @enum {string}
+ */
+export enum ClockingEventOriginType {
+    /**
+     * Marcação digitada.
+     */
+    TYPED = "TYPED",
+    /**
+     * Marcação eletrônica.
+     */
+    ELECTRONIC = "ELECTRONIC",
+    /**
+     * Marcação gerada.
+     */
+    GENERATED = "GENERATED"
+}
+
+/**
+ * Enumeração para tipo de uso de marcação.
+ * @enum {string}
+ * Possíveis valores:
+ * - `CLOCKING`: Evento padrão de marcação de ponto.
+ * - `WAITING`: Evento de espera para motoristas.
+ * - `REQUIRED_STOP`: Evento de parada obrigatória para motoristas.
+ * - `DRIVING`: Evento de direção para motoristas.
+ */
+export enum ClockingUseType {
+  /**
+   * Evento padrão de marcação de ponto.
+   */
+  CLOCKING = "CLOCKING",
+  /**
+   * Evento de pausa abonada.
+   */
+  PAID_BREAK = "PAID_BREAK",
+  /**
+   * Evento de espera para motoristas.
+   */
+  WAITING = "WAITING",
+  /**
+   * Evento de parada obrigatória para motoristas.
+   */
+  REQUIRED_STOP = "REQUIRED_STOP",
+  /**
+   * Evento de direção para motoristas.
+   */
+  DRIVING = "DRIVING",
+}
+
+
+/**
+ * Representa uma marcação de ponto.
+ * 
+ * @example
+ * ```typescript
+ * clockingEvent.clockingEventDateTime; // Retorna a data e hora da marcação.
+ * clockingEvent.clockingEventDate; // Retorna a data da marcação.
+ * clockingEvent.clockingEventTime; // Retorna a hora da marcação.
+ * clockingEvent.functionCode; // Retorna o código da função do relógio coletor.
+ * clockingEvent.originType; // Retorna a origem da marcação.
+ * clockingEvent.useType; // Retorna o tipo de uso da marcação.
+ * ```
+ * 
+ * @see {@link ClockingEventOriginType}
+ * @see {@link ClockingUseType}
+ */
+export class ClockingEvent {
+    /**
+     * Data da marcação.
+     */
+    private readonly _clockingEventDate: Date;
+    /**
+     * Hora da marcação.
+     */
+    private readonly _clockingEventTime: number;
+    /**
+     * Código da função do relógio coletor.
+     */
+    private readonly _functionCode: number;
+    /**
+     * Origem da marcação.
+     */
+    private readonly _originType: ClockingEventOriginType;
+    /**
+     * Tipo de uso da marcação.
+     */
+    private readonly _useType: ClockingUseType;
+
+    /**
+     *  @hidden
+     */
+    constructor(params: ClockingEventParams) {
+        this._clockingEventDate = ObjectUtils.toDateOrThrow(params.clockingEventDate, "clockingEvent.clockingEventDate");
+        this._clockingEventTime = params.clockingEventTime;
+        this._functionCode = params.functionCode;
+        this._originType = params.originType;
+        this._useType = params.useType;
+    }
+
+    /**
+     * Retorna a data e hora da marcação.
+     * 
+     * @example
+     * ```typescript
+     * let clockingDateTime = clockingEvent.clockingEventDateTime; // Retorna a data e hora da marcação.
+     * ```
+     * @return Data e hora da marcação.
+     */
+    get clockingEventDateTime(): Date {
+        return DateUtils.addMinutes(this._clockingEventDate, this._clockingEventTime);
+    }
+
+    /**
+     * Data da marcação.
+     * @example
+     * ```typescript
+     * let clockingDate = clockingEvent.clockingEventDate; // Retorna a data da marcação.
+     * ```
+     */
+    get clockingEventDate(): Date {
+        return this._clockingEventDate;
+    }
+
+    /**
+     * Hora da marcação em quantidade de minutos desde a meia-noite (08:00 = 480 min).
+     * @example
+     * ```typescript
+     * let clockingTime = clockingEvent.clockingEventTime; // Retorna a hora da marcação (08:00 = 480 min).
+     * ```
+     * @return Hora da marcação em minutos desde a meia-noite.
+     */
+    get clockingEventTime(): number {
+        return this._clockingEventTime;
+    }
+
+    /**
+     * Código da função do relógio coletor.
+     * @example
+     * ```typescript
+     * let functionCode = clockingEvent.functionCode; // Retorna o código da função do relógio coletor.
+     * ```
+     * @return Código da função do relógio coletor.
+     * 
+     */
+    get functionCode(): number {
+        return this._functionCode;
+    }
+
+    /**
+     * Origem da marcação.
+     * @example
+     * ```typescript
+     * let originType = clockingEvent.originType; // Retorna a origem da marcação.
+     * ```
+     * @return Origem da marcação.
+     * @see {@link ClockingEventOriginType}
+     */
+    get originType(): ClockingEventOriginType {
+        return this._originType;
+    }
+
+    /**
+     * Tipo de uso do evento de marcação.
+     * 
+     * Possíveis valores:
+     * - ClockingUseType.CLOCKING: Evento padrão de marcação de ponto.
+     * - (outros valores, se existirem)
+     * 
+     * @example
+     * ```typescript
+     * let useType = clockingEvent.useType; // Retorna o tipo de uso da marcação.
+     * ```
+     * @return Tipo de uso da marcação.
+     * @see {@link ClockingUseType}
+     */
+    get useType(): ClockingUseType {
+        return this._useType;
+    }
+}
+
+

package/src/data/timeEvaluation/estimatedHours.ts

@@ -0,0 +1,245 @@
+import { SeparatedHours, SeparatedHoursParams } from "../timeEvaluation/separatedHours";
+
+
+/**
+ * @hidden
+ * Interface para os parâmetros do construtor da EstimatedHours.
+ */
+export interface EstimatedHoursParams {
+    meal: SeparatedHoursParams[];
+    snack: SeparatedHoursParams[];
+    work: SeparatedHoursParams[];
+}
+
+/**
+ * Representa a previsão de horas.
+ * Contém as horas previstas para refeições, lanches e trabalho.
+ * @example
+ * ```typescript
+ * estimatedHours.getWorkHours(1); // Retorna as horas de trabalho do primeiro intervalo do tipo work.
+ * estimatedHours.getWorkHours(); // Retorna o total das horas de trabalho do dia (quando não passa parâmetro).
+ * estimatedHours.getMealHours(1); // Retorna as horas de refeição do primeiro intervalo do tipo meal.
+ * estimatedHours.getSnackHours(); // Retorna o total das horas de lanche do dia (quando não passa parâmetro).
+ * ```
+ * @see {@link SeparatedHours}
+ */
+export class EstimatedHours {
+    /**
+     * Horas de refeições previstas.
+     */
+    private readonly _meal: SeparatedHours[];
+    /**
+     * Horas de lanches previstas.
+     */
+    private readonly _snack: SeparatedHours[];
+    /**
+     * Horas de trabalho previstas.
+     */
+    private readonly _work: SeparatedHours[];
+
+    /**
+     * @hidden
+     * Construtor da classe EstimatedHours.
+     * @param params Parâmetros para inicializar EstimatedHours.
+     */
+    constructor(params: EstimatedHoursParams) {
+        this._meal = [];
+        if (Array.isArray(params.meal)) {
+            for (const mealItem of params.meal) {
+                this._meal.push(
+                    new SeparatedHours(mealItem)
+                );
+            }
+        }
+
+        this._snack = [];
+        if (Array.isArray(params.snack)) {
+            for (const snackItem of params.snack) {
+                this._snack.push(
+                    new SeparatedHours(snackItem)
+                );
+            }
+        }
+        
+        this._work = [];
+        if (Array.isArray(params.work)) {
+            for (const workItem of params.work) {
+                this._work.push(
+                    new SeparatedHours(workItem)
+                );
+            }
+        }
+    }
+
+    /**
+     * Retorna as horas previstas para refeições.
+     * 
+     * @example
+     * ```typescript
+     * estimatedHours.meal; // Retorna as horas de refeição.
+     * ```
+     * 
+     * @returns Uma lista de objetos do tipo SeparatedHours que contém as horas diurnas e noturnas.
+     * @see {@link SeparatedHours}
+     */
+    get meal(): SeparatedHours[] {
+        return this._meal;
+    }
+
+    /**
+     * Retorna as horas previstas para lanches.
+     * 
+     * @example
+     * ```typescript
+     * estimatedHours.snack; // Retorna as horas de lanche.
+     * ```
+     * @returns Uma lista de objetos do tipo SeparatedHours que contém as horas diurnas e noturnas.
+     * @see {@link SeparatedHours}
+     */
+    get snack(): SeparatedHours[] {
+        return this._snack;
+    }
+
+    /**
+     * Retorna as horas previstas para horas de trabalho.
+     * 
+     * @example
+     * ```typescript
+     * estimatedHours.work; // Retorna as horas de trabalho.
+     * ```
+     * @returns Um array de objetos do tipo SeparatedHours que contém as horas diurnas e noturnas.
+     * @see {@link SeparatedHours}
+     */
+    get work(): SeparatedHours[] {
+        return this._work;
+    }
+
+    /**
+     * Retorna a previsão de horas trabalhadas.
+     * 
+     * ```
+     * Representação de previsão de horas 
+     * 
+     * 08:00 - Início do expediente
+     * 10:00 - Início do primeiro lanche
+     * 10:15 - Fim do primeiro lanche
+     * 12:00 - Início do almoço
+     * 13:30 - Fim do almoço
+     * 16:30 - Início do segundo lanche
+     * 16:45 - Fim do segundo lanche
+     * 18:00 - Fim do expediente
+     * 
+     * 08:00        10:00        10:15        12:00        13:30        16:30        16:45        18:00
+     *   |------------|------------|------------|------------|------------|------------|------------|
+     *   |   work(1)  |  snack(1)  |   work(2)  |   meal(1)  |   work(3)  |  snack(2)  |   work(4)  |
+     * ```
+     * 
+     * workHours = estimatedHours.getWorkHours(3) retorna as horas de trabalho das 13:30 às 16:30 (180 minutos).
+     * 
+     * workHours = estimatedHours.getWorkHours( ) retorna o total das horas de trabalho do dia (480 minutos).
+     * 
+     * @example
+     * ```typescript
+     * const workHours = estimatedHours.getWorkHours(1);
+     * console.log(`Horas de trabalho: ${workHours.dailyHours} horas diurnas, ${workHours.nightlyHours} horas noturnas`);
+     * ```
+     * @param index Parâmetro opcional para consultar a as horas previstas do número do intervalo. Iniciando por 1.
+     * @returns Um objeto do tipo SeparatedHours que contém as horas diurnas e noturnas.
+     */
+    public getWorkHours(index?: number): SeparatedHours {
+        return this.getHours(this._work, index);
+    }
+
+    /**
+     * Retorna a previsão de horas de refeição.
+     * 
+     * ```
+     * Representação de previsão de horas 
+     * 
+     * 08:00 - Início do expediente
+     * 10:00 - Início do primeiro lanche
+     * 10:15 - Fim do primeiro lanche
+     * 12:00 - Início do almoço
+     * 13:30 - Fim do almoço
+     * 16:30 - Início do segundo lanche
+     * 16:45 - Fim do segundo lanche
+     * 18:00 - Fim do expediente
+     * 
+     * 08:00        10:00        10:15        12:00        13:30        16:30        16:45        18:00
+     *   |------------|------------|------------|------------|------------|------------|------------|
+     *   |   work(1)  |  snack(1)  |   work(2)  |   meal(1)  |   work(3)  |  snack(2)  |   work(4)  |
+     * ```
+     * 
+     * mealHours = estimatedHours.getMealHours(1) retorna as horas da refeição das 12:00 às 13:30 (90 minutos).
+     * 
+     * @example
+     * ```typescript
+     * const mealHours = estimatedHours.getMealHours(1);
+     * console.log(`Horas de refeição: ${mealHours.dailyHours} horas diurnas, ${mealHours.nightlyHours} horas noturnas`);
+     * ```
+     * 
+     * @param index Parâmetro opcional para consultar a as horas previstas do número do intervalo. Iniciando por 1.
+     * @returns Um objeto do tipo SeparatedHours que contém as horas diurnas e noturnas.
+     */
+    public getMealHours(index?: number): SeparatedHours {
+        return this.getHours(this._meal, index);
+    }
+
+    /**
+     * Retorna a previsão de horas de lanche.
+     * 
+     * ```
+     * Representação de previsão de horas 
+     * 
+     * 08:00 - Início do expediente
+     * 10:00 - Início do primeiro lanche
+     * 10:15 - Fim do primeiro lanche
+     * 12:00 - Início do almoço
+     * 13:30 - Fim do almoço
+     * 16:30 - Início do segundo lanche
+     * 16:45 - Fim do segundo lanche
+     * 18:00 - Fim do expediente
+     * 
+     * 08:00        10:00        10:15        12:00        13:30        16:30        16:45        18:00
+     *   |------------|------------|------------|------------|------------|------------|------------|
+     *   |   work(1)  |  snack(1)  |   work(2)  |   meal(1)  |   work(3)  |  snack(2)  |   work(4)  |
+     * ```
+     *
+     * snackHours = estimatedHours.getSnackHours(2) retorna as horas do lanche das 16:30 às 16:45 (15 minutos).
+     * 
+     * @example
+     * ```typescript
+     * const snackHours = estimatedHours.getSnackHours(1);
+     * console.log(`Horas de lanche: ${snackHours.dailyHours} horas diurnas, ${snackHours.nightlyHours} horas noturnas`);
+     * ```
+     * 
+     * @param index Parâmetro opcional para consultar a as horas previstas do número do intervalo. Iniciando por 1.
+     * @returns Um objeto do tipo SeparatedHours que contém as horas diurnas e noturnas.
+     */
+    public getSnackHours(index?: number): SeparatedHours {
+        return this.getHours(this._snack, index);
+    }
+
+    private getHours(estimatedHours: SeparatedHours[], index?: number): SeparatedHours {
+        if (index == null) {
+            return estimatedHours.reduce((total, current) => {
+                total.sumSeparatedHours(current);
+                return total;
+            }, this.createEmptySeparatedHours());
+        }
+    
+        if (this.isInvalidIndex(index, estimatedHours)) {
+            return this.createEmptySeparatedHours();
+        }
+    
+        return estimatedHours[index-1] || this.createEmptySeparatedHours();
+    }
+
+    private isInvalidIndex(index: number, array: SeparatedHours[]): boolean {
+        return (index <= 0 || index > array.length);
+    }
+
+    private createEmptySeparatedHours(): SeparatedHours {
+        return new SeparatedHours({ dailyHours: 0, nightlyHours: 0 });
+    } 
+}