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

package/README.md

@@ -0,0 +1,117 @@
+# hcm-clocking-event-rule-nodejs
+
+## Descrição
+
+
+
+
+Uma biblioteca de utilitários para implementação de regras no Ponto X, desenvolvida em Node.js/TypeScript.
+
+## Principais artefatos
+
+O projeto exporta diversas entidades e utilitários, incluindo:
+
+- Contextos, contratos e colaboradores (`Context`, `Contract`, `EmploymentRelationship`, etc)
+- Informações completas do dia como horários, escalas, feriados, etc (`Workshift`, `Holiday`, etc)
+- Utilitários de data e objeto (`DateUtils`, `ObjectUtils`)
+- Históricos e programações
+- Situações, escalas, feriados, logs, etc.
+
+
+## Estrutura do Projeto
+
+- `src/` — Código-fonte principal
+- `src/data/` — Entidades de domínio
+- `src/utils/` — Utilitários
+- `src/test/` — Testes automatizados e builders
+
+## Documentação
+
+As informações sobre as entidades e utilitários estão documentadas diretamente no código, a documentação em formato html será gerada automaticamente e disponibilizada no arquivo docs.zip após a execução do comando de build.
+
+Após a instalação da biblioteca, você pode acessar a documentação descompactando o arquivo de documentação localizado em: `/<lamda>/node_modules/hcm-clocking-event-rule-nodejs/docs.zip`.
+
+## Instalação
+Para instalar a biblioteca, execute o seguinte comando:
+
+```bash
+npm install hcm-clocking-event-rule-nodejs
+```
+
+## Uso
+Para utilizar a biblioteca, importe os módulos necessários no seu projeto Node.js/Javascript. Por exemplo:
+
+Exemplo: Lamda em Node.js
+
+```javascript
+    const { Context } = require('hcm-clocking-event-rule-nodejs');
+
+    exports.handler = async (event) => {
+        return sendRes(200, event);
+    };
+
+    const sendRes = (status, event) => {
+
+    const { Context, TimeEvaluationRule } = require('hcm-clocking-event-rule-nodejs');
+    // Cria uma nova instância do contexto com o evento recebido
+    let context = new Context(event);
+    try{
+        // Executa a regra de apuração
+        const rule = new TimeEvaluationRule(context);
+        rule.execute();
+    } catch (error) {
+        context.logError(`Erro: ${error.message}, stack: ${error.stack}`);
+    }
+
+    // Obtém o resultado do corpo do contexto
+    const result =  context.getBodyResult();
+    var response = {
+        statusCode: status,
+        headers: {
+        "Content-Type": "application/json"
+        },
+        body: result
+    };
+    }
+```
+
+Exemplo: TimeEvaluationRule.js
+```javascript
+const { DateUtils, DateIntervalUtils, DateInterval } = require('hcm-clocking-event-rule-nodejs');
+
+class TimeEvaluationRule {
+   constructor(context) {
+    this.context = context;
+   }
+
+   execute() {
+    try{
+      //Iterar sobre os contratos do contexto e executar alguma lógica
+      this.context.contracts.forEach((contract) => {
+        //Iterar sobre as apurações do contrato do colaborador
+        contract.timeEvaluation.forEach((timeEvaluation) => {
+        try{
+            this.timeEvaluation(timeEvaluation, contract); 
+        } catch (error) {
+            timeEvaluation.invalidate(`Erro: ${error.message}, stack: ${error.stack}`);
+        }
+             
+        });
+      });
+    } catch (error) {
+        this.context.logError(`Erro: ${error.message}, stack: ${error.stack}`);
+    } 
+   }
+
+    /**
+    * Método para processar as apurações.
+    * @param {TimeEvaluation} timeEvaluation - Apuração
+    * @param {Contract} contract - O contrato do colaborador
+    */
+   timeEvaluation(timeEvaluation, contract){
+        // Implementar a lógica de customização....
+   }
+
+}
+
+```

package/catalog-info.yaml

@@ -0,0 +1,19 @@
+apiVersion: backstage.io/v1alpha1
+
+kind: Component
+
+metadata:
+  annotations:
+    grafana/tag-selector: gestao-pessoas-hcm-clocking-event-rule-nodejs
+    sonarqube.org/project-key: gestao-pessoas-hcm-clocking-event-rule-nodejs
+    argocd/app-name: hcm-clocking-event-rule-nodejs-prod-hcm
+  description: ''
+  links:
+  - title: Documentação
+    url: https://wiki.senior.com.br/
+  name: hcm-clocking-event-rule-nodejs
+
+spec:
+  lifecycle: production
+  owner: gestao-pessoas
+  type: service

package/jest.config.js

@@ -0,0 +1,17 @@
+const { pathsToModuleNameMapper } = require('ts-jest');
+const { compilerOptions } = require('./tsconfig.json');
+
+module.exports = {
+  preset: 'ts-jest',
+  testEnvironment: 'node',
+  testMatch: ['**/test/**/?(*.)+(spec|test).[jt]s?(x)'],
+  moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx', 'json', 'node'],
+  collectCoverage: true,
+  coverageDirectory: 'coverage',
+  coverageReporters: ['html','json', 'lcov', 'text', 'clover', 'text-summary'],
+  testPathIgnorePatterns: ['/node_modules/', '/dist/'],
+  moduleNameMapper: pathsToModuleNameMapper(compilerOptions.paths || {}, {
+    prefix: '<rootDir>/',
+  }),
+  moduleDirectories: ['node_modules', 'src']
+};

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@seniorsistemas/hcm-clocking-event-rule-nodejs",
+  "version": "0.35.0",
+  "description": "Uma biblioteca de utilitários implementação de regra no pontoX",
+  "main": "index.js",
+  "types": "index.d.ts",
+  "scripts": {
+    "build": "tsc && tsc-alias && npm run copy-extras && npm run docs",
+    "build:win": "tsc && tsc-alias && npm run copy-extras:win",
+    "docs": "typedoc && zip -r dist/docs.zip docs",
+    "docs:win": "typedoc",
+    "test": "cross-env TZ=UTC jest --coverage",
+    "test:dev": "cross-env TZ=UTC jest",
+    "test:coverage": "cross-env TZ=UTC jest --coverage",
+    "coverage": "cross-env TZ=UTC jest --coverage",
+    "copy-extras": "cp package.json dist && cp README.md dist",
+    "copy-extras:win": "copy package.json dist && copy README.md dist"
+  },
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "@types/node": "^22.0.0",
+    "@types/winston": "^2.4.4",
+    "cross-env": "^7.0.3",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.2.6",
+    "tsc-alias": "^1.8.13",
+    "typedoc": "^0.28.5",
+    "typescript": "^5.8.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "commonjs",
+  "dependencies": {
+    "find-up": "5.0.0",
+    "winston": "^3.17.0"
+  },
+  "keywords": [
+    "Gestão do Ponto X",
+    "Customização",
+    "Regra de customização",
+    "Controle de ponto",
+    "nodejs",
+    "typescript",
+    "Senior HCM",
+    "Senior Sistemas"
+  ]
+}

package/prompt.md

@@ -0,0 +1,15 @@
+ # Lista de prompts do projeto
+ 
+ ## Gerar uma classe baseado no json 
+ - nome deve ser jobPosition
+ - o construtor deve receber uma interface com o nome jobPositionParams, deve ser gerado no mesmo arquivo
+ - os métodos deve ser privados e readonly, com o prefixo _
+ - gerar gets para todos os metodos
+ - adicionar no path src\data\histories
+ - documentar os métodos e atributos em protuguês
+{
+    "key": "1_1",
+    "code": 1,
+    "structureCode": 1
+},
+ 

package/run_build_win.bat

@@ -0,0 +1 @@
+npm run build:win --prod

package/run_link.bat

@@ -0,0 +1,3 @@
+cd dist
+npm link --only=production
+cd ..

package/run_test.bat

@@ -0,0 +1 @@
+npm run test 

package/sonar-project.properties

@@ -0,0 +1,21 @@
+sonar.projectKey=gestao-pessoas-hcm-clocking-event-rule-nodejs
+sonar.projectName=hcm-clocking-event-rule-nodejs
+sonar.projectVersion=1.0
+sonar.sourceEncoding=UTF-8
+
+sonar.sources=src
+sonar.language=ts
+sonar.exclusions=**/node_modules/**,**/*.spec.ts,**/src/app/**,**/test/**
+
+sonar.tests=src
+sonar.test.inclusions=**/*.spec.ts
+sonar.typescript.lcov.reportPaths=coverage/lcov.info
+sonar.javascript.lcov.reportPaths=coverage/lcov.info
+#sonar.coverage.exclusions=src/*,**/*.js,**/*environment*.ts,**/*module.ts,**/*routing.ts,**/*enum.ts,**/*.d.ts
+sonar.coverage.exclusions=**/*.spec.ts
+sonar.clover.reportPath=coverage/clover.xml
+
+sonar.ts.tslint.configPath=tslint.json
+
+sonar.host.url=http://sonar.senior.com.br/
+

package/src/data/changes/changes.ts

@@ -0,0 +1,92 @@
+/**
+ *  @hidden
+ */
+export class Changes {
+    public changesItems: ChangesItems[] = [];
+}
+
+/**
+ * Enumeração dos tipos de mudanças.
+ * Representa os diferentes tipos de mudanças que podem ocorrer no sistema, como situações, pendências, erros, logs e metadados.
+ *  @hidden
+ */
+export enum ChangesType {
+    SITUATION = "SITUATION",
+    PENDENCY = "PENDENCY",
+    ERROR = "ERROR",
+    LOG = "LOG",
+    METADATA = "METADATA"
+}
+/**
+ * Parameters for ChangesItems.
+ *  @hidden
+ */
+export interface ChangesItemsParams {
+    contractId: string | null;
+    type: ChangesType;
+    timeEvaluationDate: string | null;
+    key: string | null;
+    value: string;
+    sequence: number;
+}
+
+
+/**
+ * @hidden
+ * Representa os itens de mudanças no sistema, como situações, pendências, erros, logs e metadados.
+ */
+export class ChangesItems {
+    private readonly contractId: string | null;
+    private readonly type: ChangesType;
+    private readonly timeEvaluationDate: string | null;
+    private readonly key: string | null;
+    private readonly value: string;
+    private readonly sequence: number;
+
+    /**
+     * @hidden
+     */
+    constructor(params: ChangesItemsParams) {
+        this.contractId = params.contractId;
+        this.type = params.type;
+        this.timeEvaluationDate = params.timeEvaluationDate;
+        this.key = params.key;
+        this.value = params.value;
+        this.sequence = params.sequence;
+    }
+
+    getContractId(): string | null {
+        return this.contractId;
+    }
+
+    getType(): ChangesType {
+        return this.type;
+    }
+
+    getTimeEvaluationDate(): string | null {
+        return this.timeEvaluationDate;
+    }
+
+    getKey(): string | null {
+        return this.key;
+    }
+
+    getValue(): string {
+        return this.value;
+    }
+
+    getSequence(): number {
+        return this.sequence;
+    }
+
+    getChangesItems(): ChangesItemsParams {
+        return {
+            contractId: this.contractId,
+            type: this.type,
+            timeEvaluationDate: this.timeEvaluationDate,
+            key: this.key,
+            value: this.value,
+            sequence: this.sequence,
+        };
+    }
+}

package/src/data/context/context.ts

@@ -0,0 +1,251 @@
+import { Changes } from "./../changes/changes";
+import { Dataset } from "./../dataset/dataset";
+import { Contract } from "./../contract/contract";
+import { decompressGzipSync } from "src/utils/decompressGzipLambda";
+import { createLogger, format, transports } from "winston";
+
+const logger = createLogger({
+    level: "debug",
+    format: format.json(),
+    transports: [new transports.Console()],
+});
+
+/**
+ * Contexto de execução do processo de apuração.
+ * Representa o ambiente onde a apuração é realizada, contendo informações sobre a apuração, datas de início e fim, contratos envolvidos, usuário atual, logs de processo, etc.
+ * 
+ */
+export class Context {
+
+    private _dataset: Dataset;
+
+    /**
+     * Construtor da classe Context.
+     * A partir do contexto pode ser acessado os contratos e apurações no cenário de regra.
+     * A estrutura das classes é um contexto que possui vários contratos de apuração, cada contrato pertence a um colaborador.
+     * Dentro do contrato podem ser encontradas as apurações, que devem ser iteradas para customizar as mudanças das situações.
+     * 
+     * Ex.:
+     * ```javascript
+     * let context = new Context(event);
+     * ```
+     * 
+     * @param event Evento enviado para a função Lambda.
+     */
+    public constructor(event: any) {
+        try {
+            if (event.body) {
+                const body: string = this.getBody(event);
+
+                const pDataset = JSON.parse(body);
+
+                this.build(pDataset.input);
+            } else {
+                this.createEmpty();
+            }
+        } catch (error) {
+            this.createEmpty();
+            let message = "";
+            let stack = "";
+            if (error instanceof Error) {
+                message = error.message;
+                stack = error.stack ?? "";
+            } else if (typeof error === "string") {
+                message = error;
+            } else {
+                message = JSON.stringify(error);
+            }
+            this.logError(`Erro: ${message}, stack: ${stack}`);
+            logger.error(`Erro: ${message}, stack: ${stack}`);
+        }
+    }
+
+    private getBody(event: any) {
+        const contentEncoding = event.headers && (event.headers['Content-Encoding'] || event.headers['content-encoding']);
+        let body: string;
+
+        if (contentEncoding === 'gzip') {
+            try {
+                const compressedPayload = event.isBase64Encoded
+                    ? Buffer.from(event.body, 'base64')
+                    : Buffer.from(event.body, 'utf-8');
+                body = decompressGzipSync(compressedPayload);
+            } catch (decompressError) {
+                // Se falhar ao descomprimir, tenta tratar como texto normal
+                // prevendo uma mundança de comportamento quando entrar invocação direta de lambda.
+                body = event.body;
+            }
+        } else {
+            body = event.body;
+        }
+        return body;
+    }
+
+    private createEmpty() {
+        const dataset = Dataset.empty();
+        this.build(dataset);
+    }
+
+    static empty() {
+        return new Context({});
+    }
+
+    /**
+     * Todas as classes que possuirem métodos precisam ser reintanciadas, pois ao converter os dados para json os métodos perdem a referência.
+     * 
+     * @param pDataset 
+     */
+    private build(pDataset: Dataset) {
+        this._dataset = pDataset;
+        const datasetParams = {
+            batchId: this._dataset.batchId,
+            startDate: this._dataset.startDate,
+            endDate: this._dataset.endDate,
+            contracts: this._dataset.contracts,
+            database: this._dataset.database,
+            currentUser: this._dataset.currentUser
+        };
+
+        this._dataset = new Dataset(datasetParams);
+    }
+
+    /**
+     * ID do lote de apuração, identificador do conjunto de colaboradores que estão sendo processados.
+     * Este ID é utilizado para agrupar os contratos e apurações que pertencem ao mesmo lote de processamento.
+     */
+    get batchId(): string {
+        return this._dataset.batchId;
+    }
+
+    /**
+     * Data inicial da apuração, do qual foi o perído de cálculo de apuração.
+     * 
+     * @example
+     * ```javascript
+     * let startDate = context.startDate;
+     * context.logInfo(`Data inicial da apuração: ${startDate.toISOString()}`);
+     * ```
+     * @returns Data inicial da apuração.
+     */
+    get startDate(): Date {
+        return this._dataset.startDate;
+    }
+
+    /**
+     * Data final da apuração, do qual foi o perído de cálculo de apuração.
+     * 
+     * @example
+     * ```javascript
+     * let endDate = context.endDate;
+     * context.logInfo(`Data final da apuração: ${endDate.toISOString()}`);
+     * ```
+     * @returns Data final da apuração.
+     */
+    get endDate(): Date {
+        return this._dataset.endDate;
+    }
+
+    /**
+     * Processa as mudanças que ocorreram na customização das apurações.
+     * Tipos: Situação, Pendência, Erro, Log e Metadados. 
+     * 
+     * @example
+     * ```javascript
+     * let changes = context.processChanges();
+     * context.logInfo(`Mudanças processadas: ${JSON.stringify(changes)}`);
+     * ```
+     * 
+     * @returns Retorna as mudanças que ocorreram na customização para serem enviados ao cálculo de apuração.
+     */
+    processChanges(): Changes {
+        return this._dataset.processChanges();
+    }
+
+    /**
+     * Lista os contratos que foram calculados na apuração.
+     * O contrato de admissão representa um colaborador que foi calculado.
+     * Uma apuração pode conter vários contratos, cada contrato representa um colaborador.
+     * 
+     * @example
+     * ```javascript
+     * let contracts = context.contracts;
+     * for (const contract of contracts) {
+     *   context.logInfo(`Contrato: ${contract.id}, Colaborador: ${contract.employee.name}`);
+     * }
+     * ```
+     */
+    get contracts(): Contract[] {
+        return this._dataset.contracts;
+    }
+
+    /**
+     * Retorna o usuário corrente que está executando o processo de apuração.
+     * 
+     * @example
+     * ```javascript
+     * let currentUser = context.currentUser;
+     * context.logInfo(`Usuário corrente: ${currentUser.name}, ID: ${currentUser.id}`);
+     * ```
+     * 
+     */
+    get currentUser() {
+        return this._dataset.currentUser;
+    }
+
+    /**
+     * Cria um registro no log com o tipo INFO no processo de apuração.
+     * 
+     * @example
+     * ```javascript
+     * context.logInfo("Início do processamento de apuração.");
+     * ```
+     * 
+     *  @param message Mensagem do info.
+     */
+    public logInfo(message: string) {
+        this._dataset.logInfo(message);
+    }
+
+    /**
+     * Cria um registro log do tipo WARNING no processo de apuração.
+     * 
+     * @example
+     * ```javascript
+     * context.logWarning("Aviso: Verifique a configuração do contrato.");
+     * ```
+     * 
+     *  @param message Mensagem do warning.
+     */
+    public logWarning(message: string) {
+        this._dataset.logWarning(message);
+    }
+
+    /**
+     * Cria um log do tipo ERRO no processo de apuração.
+     * 
+     * @example
+     * ```javascript
+     * context.logError("Erro ao processar o contrato: " + contract.id);
+     * ```
+     * 
+     * @param message Mensagem do erro.
+     */
+    public logError(message: string) {
+        this._dataset.logError(message);
+    }
+
+    /**
+     * Retorna o resultado do processamento em formato JSON convertido para string, para ser adicionado no body da requisão de resposta da Lamdba.
+     * 
+     * @example
+     * ```javascript
+     * let result = context.getBodyResult();
+     * ```
+     * 
+     * @returns String JSON com o resultado do processamento.
+     */
+    getBodyResult(): string {
+        const changes = this._dataset.processChanges();
+        return JSON.stringify({ "version": this._dataset.getProjectVersionSync(), "result": changes });
+    }
+}