feat: add occupancy module with controller, service, and related DTOs for heat map data retrieval

src/occupancy/services/occupancy.service.ts

@@ -0,0 +1,69 @@
+import { HttpException, HttpStatus, Injectable } from '@nestjs/common';
+import { GetOccupancyHeatMapBySpaceDto } from '../dto/get-occupancy.dto';
+import { SuccessResponseDto } from '@app/common/dto/success.response.dto';
+import { SpaceParamsDto } from '../dto/occupancy-params.dto';
+import { SqlLoaderService } from '@app/common/helper/services/sql-loader.service';
+import { DataSource } from 'typeorm';
+import { SQL_PROCEDURES_PATH } from '@app/common/constants/sql-query-path';
+import { BaseResponseDto } from '@app/common/dto/base.response.dto';
+
+@Injectable()
+export class OccupancyService {
+  constructor(
+    private readonly sqlLoader: SqlLoaderService,
+    private readonly dataSource: DataSource,
+  ) {}
+
+  async getOccupancyHeatMapDataBySpace(
+    params: SpaceParamsDto,
+    query: GetOccupancyHeatMapBySpaceDto,
+  ): Promise<BaseResponseDto> {
+    const { year } = query;
+    const { spaceUuid } = params;
+
+    try {
+      const data = await this.executeProcedure(
+        'proceduce_select_fact_space_occupancy',
+        [spaceUuid, year],
+      );
+      const formattedData = data.map((item) => ({
+        ...item,
+        event_date: new Date(item.event_date).toLocaleDateString('en-CA'), // YYYY-MM-DD
+      }));
+      return this.buildResponse(
+        `Occupancy heat map data fetched successfully for ${spaceUuid ? 'space' : 'community'}`,
+        formattedData,
+      );
+    } catch (error) {
+      console.error('Failed to fetch occupancy heat map data', {
+        error,
+        spaceUuid,
+      });
+      throw new HttpException(
+        error.response?.message || 'Failed to fetch occupancy heat map data',
+        error.status || HttpStatus.INTERNAL_SERVER_ERROR,
+      );
+    }
+  }
+
+  private buildResponse(message: string, data: any[]) {
+    return new SuccessResponseDto({
+      message,
+      data,
+      statusCode: HttpStatus.OK,
+    });
+  }
+  private async executeProcedure(
+    procedureFileName: string,
+    params: (string | number | null)[],
+  ): Promise<any[]> {
+    const query = this.loadQuery(
+      'fact_space_occupancy_count',
+      procedureFileName,
+    );
+    return await this.dataSource.query(query, params);
+  }
+  private loadQuery(folderName: string, fileName: string): string {
+    return this.sqlLoader.loadQuery(folderName, fileName, SQL_PROCEDURES_PATH);
+  }
+}