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

package/src/data/histories/leaveHistory.ts

@@ -0,0 +1,227 @@
+import { ObjectUtils } from "../../utils/object.utils";
+import { ContextReference } from "../context/contextReference";
+import { Situation } from "../foundation/situation";
+
+/**
+ * @hidden
+ * Parâmetros necessários para criar uma instância de LeaveHistory.
+ */
+export interface LeaveHistoryParams {
+    startDate: Date;
+    endDate: Date | null;
+    startTime: number;
+    timeEvaluationStartDate: Date | null;
+    timeEvaluationEndDate: Date | null;
+    endTime: number;
+    situationId: string;
+}
+
+/**
+ * Representa um histórico de afastamento.
+ * O histórico de afastamento é utilizado para verificar o afastamento do colaborador em uma data específica.
+ * @example
+ * ```typescript
+ * leaveHistory.startDate; // Retorna a data inicial do histórico de afastamento.
+ * leaveHistory.endDate; // Retorna a data final do histórico de afastamento ou null se não estiver definida.
+ * leaveHistory.startTime; // Retorna a hora inicial do afastamento em minutos desde a meia-noite (08:00 = 480 min).
+ * leaveHistory.endTime; // Retorna a hora final do afastamento em minutos desde a meia-noite (08:00 = 480 min).
+ * leaveHistory.timeEvaluationStartDate; // Retorna a data inicial da apuração do afastamento ou null se o afastamento não foi aplicado ao dia apurado.
+ * leaveHistory.timeEvaluationEndDate; // Retorna a data final da apuração do afastamento ou null seo afastamento não foi aplicado ao dia apurado.
+ * leaveHistory.situation; // Retorna a situação do afastamento.
+ * leaveHistory.startDateTime; // Retorna a data e hora inicial do afastamento, no formado de Date.
+ * leaveHistory.endDateTime; // Retorna a data e hora final do afastamento ou null se não houver data final, no formado de Date.
+ * ```
+ */
+export class LeaveHistory {
+    private readonly _startDate: Date;
+    private readonly _endDate: Date | null;
+    private readonly _startTime: number;
+    private readonly _endTime: number;
+    private readonly _timeEvaluationStartDate: Date | null;
+    private readonly _timeEvaluationEndDate: Date | null;
+    private readonly _situationId: string;
+
+    /**
+     * @hidden
+     * @param params Parâmetros necessários para criar uma instância de LeaveHistory.
+     */
+    constructor(params: LeaveHistoryParams) {
+        this._startDate = ObjectUtils.toDateOrThrow(params.startDate, "LeaveHistory.startDate");
+        this._endDate = ObjectUtils.toDateOrNull(params.endDate);
+        this._startTime = params.startTime;
+        this._endTime = params.endTime;
+        this._timeEvaluationStartDate = ObjectUtils.toDateOrNull(params.timeEvaluationStartDate);
+        this._timeEvaluationEndDate = ObjectUtils.toDateOrNull(params.timeEvaluationEndDate);
+        this._situationId = params.situationId;
+    }
+
+    /**
+     * Data inicial do histórico de afastamento.
+     * 
+     * @example
+     * ```typescript
+     * let startDate = leaveHistory.startDate; // Retorna a data inicial do histórico de afastamento.
+     * ```
+     * 
+     * @returns Data inicial do histórico de afastamento.
+     */
+    get startDate(): Date {
+        return this._startDate;
+    }
+
+    /**
+     * Data da final de afastamento, opcional.
+     * 
+     * @example
+     * ```typescript
+     * let endDate = leaveHistory.endDate; // Retorna a data final do afastamento ou null se não estiver definida.
+     * ```
+     * 
+     * @returns Data final do afastamento.
+     */
+    get endDate(): Date | null {
+        return this._endDate;
+    }
+
+    /**
+     * Hora inicial do afastamento. Formatado em quantidade de minutos desde a meia-noite.
+     * 
+     * @example
+     * ```typescript
+     * let startTime = leaveHistory.startTime; // Retorna a hora inicial do afastamento em minutos desde a meia-noite.
+     * startTime; // Exemplo: 480 representa 08:00.
+     * ```
+     * 
+     * @returns Hora inicial do afastamento.
+     */
+    get startTime(): number {
+        return this._startTime;
+    }
+
+    /**
+     * Hora final do afastamento. Formatado em quantidade de minutos desde a meia-noite.
+     * 
+     * @example
+     * ```typescript
+     * let endTime = leaveHistory.endTime; // Retorna a hora final do afastamento em minutos desde a meia-noite.
+     * endTime; // Exemplo: 1020 representa 17:00.
+     * ```
+     * 
+     * @returns Hora final do afastamento.
+     */
+    get endTime(): number {
+        return this._endTime;
+    }
+
+    /**
+     * @hidden
+     * Identificador da situação do afastamento.
+     * @returns Identificador da situação do afastamento.
+     */
+    private get situationId(): string {
+        return this._situationId;
+    }
+
+    /**
+     * A partir de qual data na apuração calculada o afastamento foi utilizado no cálculo da apuração, para gerar alguma alteração.
+     * Cenários: 
+     *  - Afastamentos em DSR, não são aplicados. 
+     *  - Afastamento em DSR podem ser aplicados em datas diferentes.
+     *  - Históricos não aplicados no dia retornam null.
+     * 
+     * @example
+     * ```typescript
+     * let timeEvaluationStartDate = leaveHistory.timeEvaluationStartDate; // Retorna a menor data de apuração que o histórico foi aplicado, ou null se não foi aplicado.
+     * ```
+     * @returns Menor data de apuração que o histórico foi aplicado, e null, se não foi aplicado.
+     */
+    get timeEvaluationStartDate(): Date | null {
+        return this._timeEvaluationStartDate;
+    }
+
+    /**
+     * Até qual data na apuração calculada o afastamento foi utilizado no cálculo da apuração, para gerar alguma alteração.
+     * Cenários: 
+     *  - Afastamentos em DSR, não são aplicados.
+     *  - Data final de um afastamento sem data final, é a maior data de apuração.
+     *  - Históricos não aplicados no dia retornam null.
+     * 
+     * @example
+     * ```typescript
+     * let timeEvaluationEndDate = leaveHistory.timeEvaluationEndDate; // Retorna a maior data de apuração que o histórico foi aplicado, ou null se não foi aplicado.
+     * ```
+     * 
+     * @returns Maior data de apuração que o histórico foi aplicado, e null se não foi aplicado.
+     */
+    get timeEvaluationEndDate(): Date | null {
+        return this._timeEvaluationEndDate;
+    }
+
+    /**
+     * Situação do afastamento.
+     * 
+     * @example
+     * ```typescript
+     * let situation = leaveHistory.situation; // Retorna a situação do afastamento.
+     * sitation.code; // Retorna o código da situação.
+     * ```
+     * @returns Situação do afastamento.
+     */
+    get situation(): Situation {
+        const situation = ContextReference.getGlobalInstance().getSituationById(this._situationId);
+        if (!situation) {
+            throw new Error(`Situação com ID ${this._situationId} não encontrada no contexto.`);
+        }
+        return situation;
+    }
+
+    /**
+     * Data e hora inicial do afastamento, no formato de Date. 
+     * 
+     * @example
+     * ```typescript
+     * let startDateTime = leaveHistory.startDateTime; // Retorna a data e hora inicial do afastamento.
+     * startDateTime.toISOString(); // Formato ISO da data e hora, por exemplo: "2023-10-01T08:00:00.000Z".
+     * ```
+     * @returns Data e hora inicial do afastamento.
+     */
+    get startDateTime(): Date {
+        const date = new Date(this._startDate);
+        date.setMinutes(this._startTime);
+        return date;
+    }
+
+    /**
+     * Data e hora final do afastamento, no formato de Date.
+     * 
+     * @example
+     * ```typescript
+     * let endDateTime = leaveHistory.endDateTime; // Retorna a data e hora final do afastamento, ou null se não houver data final.
+     * endDateTime ? endDateTime.toISOString() : null; // Formato ISO da data e hora, por exemplo: "2023-10-01T17:00:00.000Z".
+     * ```
+     * 
+     * @returns Data e hora final do afastamento, ou null se não houver data final.
+     */
+    get endDateTime(): Date | null {
+        if (this._endDate === null) {
+            return null;
+        }
+        const date = new Date(this._endDate);
+        date.setMinutes(this._endTime);
+        return date;
+    }
+
+    public static clone(leaveHistory: LeaveHistory): LeaveHistory {
+        const leaveHistoryParams = {
+            startDate: leaveHistory.startDate,
+            endDate: leaveHistory.endDate,
+            startTime: leaveHistory.startTime,
+            endTime: leaveHistory.endTime,
+            situationId: leaveHistory.situationId,
+            timeEvaluationStartDate: leaveHistory.timeEvaluationStartDate,
+            timeEvaluationEndDate: leaveHistory.timeEvaluationEndDate
+        };
+        return new LeaveHistory(leaveHistoryParams)
+    }
+}
+

package/src/data/histories/timeEvaluationHistory.ts

@@ -0,0 +1,191 @@
+import { ObjectUtils } from "../../utils/object.utils";
+import { TimeEvaluationSituationDefinitionHistory } from "../definition/timeEvaluationSituationDefinitionHistory";
+import { ContextReference } from "../context/contextReference";
+
+/**
+ * @hidden
+ * Histórico de apuração do colaborador.
+ * O histórico de apuração é utilizado para verificar a apuração do colaborador em uma data específica.
+ */
+export interface TimeEvaluationHistoryParams {
+    startDate: Date;
+    endDate: Date | null;
+    type: TimeEvaluationType;
+    situationDefinitionKey: string[];
+}
+
+/**
+ * Representa o histórico de apuração do colaborador.
+ * O histórico de apuração é utilizado para verificar a apuração do colaborador em uma data específica.
+ * 
+ * @example
+ * ```typescript
+ * timeEvaluationHistory.startDate; // Retorna a data inicial do histórico de apuração.
+ * timeEvaluationHistory.endDate; // Retorna a data final do histórico de apuração do colaborador ou null se não estiver definida.
+ * timeEvaluationHistory.type; // Retorna o tipo de apuração do colaborador.
+ * const situationDefinitions = timeEvaluationHistory.situationDefinition; // Retorna uma lista de históricos de definição de situação conforme o período de apuração.
+ * ```
+ * @see {@link TimeEvaluationSituationDefinitionHistory}
+ * 
+ */
+export class TimeEvaluationHistory {
+    private readonly _startDate: Date;
+    private readonly _endDate: Date | null;
+    private readonly _type: TimeEvaluationType;
+    private readonly _situationDefinitionKey: string[];
+
+    /**
+     * @hidden
+     * @param params Parâmetros necessários para criar uma instância de TimeEvaluationHistory.
+     */
+    constructor(params: TimeEvaluationHistoryParams) {
+        this._startDate = ObjectUtils.toDateOrThrow(params.startDate, "TimeEvaluationHistory.startDate");
+        this._endDate = ObjectUtils.toDateOrNull(params.endDate);
+        this._type = params.type;
+        this._situationDefinitionKey = params.situationDefinitionKey;
+    }
+
+    /**
+     * Data inicial do histórico de apuração do colaborador.
+     * 
+     * @example
+     * ```typescript
+     * let startDate = timeEvaluationHistory.startDate; // Retorna a data inicial do histórico de apuração do colaborador.
+     * ```
+     * @returns Data inicial do histórico de apuração do colaborador.
+     */
+    get startDate(): Date {
+        return this._startDate;
+    }
+
+    /**
+     * Data final do histórico de apuração do colaborador.
+     * 
+     * @example
+     * ```typescript
+     * let endDate = timeEvaluationHistory.endDate; // Retorna a data final do histórico de apuração do colaborador.
+     * ```
+     * @returns Data final do histórico de apuração do colaborador.
+     */
+    get endDate(): Date | null {
+        return this._endDate;
+    }
+
+    /**
+     * Tipo de apuração do colaborador.
+     * 
+     * @example
+     * ```typescript
+     * let evaluationType = timeEvaluationHistory.type; // Retorna o tipo de apuração do colaborador.
+     * ```
+     * 
+     * @returns Tipo de apuração do colaborador.
+     * @see {@link TimeEvaluationType}
+     */
+    get type(): TimeEvaluationType {
+        return this._type;
+    }
+
+    /**
+     * @hidden
+     * Chaves de definição de situação do histórico de apuração.
+     */
+    private get situationDefinitionKey(): string[] {
+        return this._situationDefinitionKey;
+    }
+
+    /**
+     * Definição de situação do histórico de apuração.
+     * 
+     * @example
+     * ```typescript
+     * const situationDefinitions = timeEvaluationHistory.situationDefinition; // Retorna uma lista de históricos de definição de situação conforme o período de apuração.
+     * situationDefinitions.forEach(definition => {
+     *   console.log(definition.code); // Exibe o código da definição de situação.
+     * });
+     * 
+     * ```
+     * @returns Retorna uma lista de históricos de definição de situação conforme o período de apuração.
+     */
+    get situationDefinition(): TimeEvaluationSituationDefinitionHistory[] {
+        // Definição de situação é opcional no histórico de apuração
+        if (!this._situationDefinitionKey) {
+            return [];
+        }
+
+        const timeEvaluationHistory: TimeEvaluationSituationDefinitionHistory[] = [];
+
+        this._situationDefinitionKey.forEach(key => {
+            timeEvaluationHistory.push(ContextReference.getGlobalInstance().getTimeEvaluationSituationDefinitionHistory(key));
+        });
+
+        return timeEvaluationHistory;
+    }
+
+    /**
+     * Busca uma definição de situação baseado numa data específica.
+     * A data deve estar dentro do intervalo de início e fim da apuração.
+     * 
+     * @example
+     * ```typescript
+     * const date = new Date("2025-06-01");
+     * const situationDefinition = timeEvaluationHistory.findSituationDefinitionByDate(date);
+     * if (situationDefinition) {
+     *   console.log(situationDefinition.code); // Exibe o código da definição de situação encontrada.
+     * } else {
+     *  console.log("Nenhuma definição de situação encontrada para essa data.");
+     * }
+     * ```
+     * 
+     * 
+     * @param date Data para buscar a definição de situação.
+     * @returns TimeEvaluationSituationDefinitionHistory baseado na data fornecida ou null se não houver definição de situação para essa data.
+     */
+    findSituationDefinitionByDate(date: Date): TimeEvaluationSituationDefinitionHistory | null {
+        const situationDefinitions = this.situationDefinition;
+        for (const definition of situationDefinitions) {
+            if (definition.startDate <= date && (definition.endDate === null || definition.endDate >= date)) {
+                return definition;
+            }
+        }
+        return null;
+    }
+
+    /**
+     * Clona o histórico de apuração.
+     * 
+     * @returns Uma nova instância de TimeEvaluationHistory com os mesmos valores.
+     */
+    public static clone(object: TimeEvaluationHistory): TimeEvaluationHistory {
+        const timeEvaluationHistoryParams = {
+            startDate: object.startDate,
+            endDate: object.endDate,
+            type: object.type,
+            situationDefinitionKey: object.situationDefinitionKey
+        };
+        return new TimeEvaluationHistory(timeEvaluationHistoryParams);
+    }
+}
+
+/** 
+ * Enumeração para os tipos de apuração.
+ * @enum
+ */
+export enum TimeEvaluationType {
+    /**
+     * Apuração normal.
+     */
+    NORMAL = "NORMAL",
+    /**
+     * Dispensado do ponto.
+     */
+    DISMISSEDFROMTIMECONTROL = "DISMISSEDFROMTIMECONTROL",
+    /**
+     * Sem controle de ponto.
+     */
+    NOTIMECONTROL = "NOTIMECONTROL",
+    /**
+     * Ponto por exceção.
+     */
+    CLOCKINGEVENTBYEXCEPTION = "CLOCKINGEVENTBYEXCEPTION",
+}

package/src/data/histories/workshiftHistory.ts

@@ -0,0 +1,66 @@
+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 a escala do colaborador em uma data específica.
+ */
+export interface WorkshiftHistoryParams extends WorkshiftBaseParams {
+    endDate: Date | null;
+}
+
+/**
+ * Representa o histórico de escala.
+ * O histórico de escala é utilizado para verificar a escala do colaborador em uma data específica.
+ * 
+ * @example
+ * ```typescript
+ * workshiftHistory.startDate; // Retorna a data inicial do histórico de escala.
+ * workshiftHistory.endDate; // Retorna a data final do histórico de escala ou null se não estiver definida.
+ * workshiftHistory.workshift; // Retorna a escala associada ao histórico.
+ * workshiftHistory.workshift.code; // Retorna o código da escala.
+ * ```
+ * @see {@link Workshift}
+ */
+export class WorkshiftHistory extends WorkshiftBase {
+
+    protected readonly _endDate: Date | null;
+
+    /**
+     * @hidden
+     * @param params Parâmetros necessários para criar uma instância de WorkshiftHistory.
+     */
+    constructor(params: WorkshiftHistoryParams) {
+        super(params);
+        this._endDate = ObjectUtils.toDateOrNull(params.endDate);
+    }
+
+
+    /**
+     * Data final do histórico de escala.
+     * @example
+     * ```typescript
+     * let endDate = workshiftBase.endDate; // Retorna a data final da escala ou null se não estiver definida.
+     * ```
+     * @returns Data final do histórico de escala ou null se não estiver definida.
+     */
+    get endDate(): Date | null {
+        return this._endDate;
+    }
+
+    /**
+     * Clona a instância de WorkshiftHistory.
+     * 
+     * @returns Uma nova instância de WorkshiftHistory com os mesmos parâmetros.
+     */
+    public static clone(object: WorkshiftHistory): WorkshiftHistory {
+        const workshiftHistory = {
+            startDate: object.startDate,
+            endDate: object.endDate,
+            workshiftId: object.workshiftId,
+            workshiftGroupId: object.workshiftGroupId
+        };
+        return new WorkshiftHistory(workshiftHistory);
+    }
+}

package/src/data/hourBank/hourBank.ts

@@ -0,0 +1,43 @@
+/**
+ * @hidden
+ * Interface para os parâmetros do construtor de HourBank.
+ */
+export interface HourBankParams {
+    code: number;
+}
+
+/**
+ * Representa um banco de horas.
+ * @example
+ * ```typescript
+ * console.log(hourBank.code); // Retorna 123.
+ * ```
+ * 
+ */
+export class HourBank {
+    /**
+     * Código do banco de horas.
+     * @param code Código do banco de horas.
+     */
+    private readonly _code: number;
+
+    /**
+     * @hidden
+     * @param params Parâmetros necessários para criar uma instância do banco de horas.
+     */
+    constructor(params: HourBankParams) {
+        this._code = params.code;
+    }
+
+    /**
+     * Retorna o código do banco de horas.
+     * @example
+     * ```typescript
+     * let code = hourBank.code; // Retorna o código do banco de horas.
+     * ```
+     * @return Código do banco de horas.
+     */
+    get code(): number {
+        return this._code;
+    }
+}

package/src/data/hourBank/hourBankAccount.ts

@@ -0,0 +1,77 @@
+import { ObjectUtils } from "../../utils/object.utils";
+import { HourBank } from "./hourBank";
+/**
+ * @hidden
+ * Interface para os parâmetros do construtor de HourBankAccount.
+ */
+export interface HourBankAccountParams {
+    hourBank: HourBank;
+    creationDate: Date;
+    extinctionDate?: Date | null;
+}
+
+/**
+ * Representa uma conta de banco de horas de um colaborador.
+ * 
+ * @example
+ * ```typescript
+ * hourBankAccount.hourBank.code; // Retorna o código do banco de horas associado.
+ * hourBankAccount.creationDate; // Retorna a data de criação da conta de banco de horas.
+ * hourBankAccount.extinctionDate; // Retorna a data de extinção da conta de banco de horas, se existir.
+ * ```
+ * @see {@link HourBank}
+ */
+export class HourBankAccount {
+    private readonly _hourBank: HourBank;
+    private readonly _creationDate: Date;
+    private readonly _extinctionDate: Date | null;
+
+    /**
+     * @hidden
+     * @param params Parâmetros necessários para criar uma instância de conta de banco de horas.
+     */
+    constructor(params: HourBankAccountParams) {
+        this._hourBank = params.hourBank;
+        this._creationDate = ObjectUtils.toDateOrThrow(params.creationDate, "hourBankAccount.creationDate");
+        this._extinctionDate = ObjectUtils.toDateOrNull(params.extinctionDate);
+    }
+
+    /**
+     * Retorna o banco de horas associado.
+     * @example
+     * ```typescript
+     * let hourBank = hourBankAccount.hourBank; // Retorna a conta de banco de horas associado.
+     * hourBank.code; // Retorna o código da conta de banco de horas.
+     * ```
+     * @return O banco de horas associado à conta de banco de horas.
+     * @see {@link HourBank}    
+     */
+    get hourBank(): HourBank {
+        return this._hourBank;
+    }
+
+    /**
+     * Retorna a data de criação.
+     * @example
+     * ```typescript
+     * let creationDate = hourBankAccount.creationDate; // Retorna a data de criação da conta de banco de horas.
+     * ```
+     * @return A data de criação da conta de banco de horas.
+     */
+    get creationDate(): Date {
+        return this._creationDate;
+    }
+
+    /**
+     * Retorna a data de extinção, se existir.
+     * 
+     * @example
+     * ```typescript
+     * let extinctionDate = hourBankAccount.extinctionDate; // Retorna a data de extinção da conta de banco de horas ou null se não existir.
+     * ```
+     * @return A data de extinção da conta de banco de horas ou null se não existir.
+     */
+    get extinctionDate(): Date | null {
+        return this._extinctionDate;
+    }
+}

package/src/data/log/log.ts

@@ -0,0 +1,38 @@
+/**
+ * @hidden
+ * @enum
+ */
+export enum LogType {
+    ERROR = "ERROR",
+    WARNING = "WARNING",
+    INFO = "INFO",
+}
+
+/**
+ * @hidden
+ */
+export interface LogParams {
+    type: LogType;
+    message: string;
+}
+
+/**
+ * @hidden
+ */
+export class Log {
+    private readonly _type: LogType;
+    private readonly _message: string;
+
+    constructor(params: LogParams) {
+        this._type = params.type;
+        this._message = params.message;
+    }
+
+    get type(): LogType {
+        return this._type;
+    }
+
+    get message(): string {
+        return this._message;
+    }
+}