#6624 - Search student by certificate number

sources/packages/backend/apps/api/src/route-controllers/student/_tests_/e2e/student.aest.controller.searchStudents.e2e-spec.ts

@@ -1,7 +1,11 @@
 import { HttpStatus, INestApplication } from "@nestjs/common";
 import request from "supertest";
 import { DataSource, Repository } from "typeorm";
-import { saveFakeStudent } from "@sims/test-utils";
+import {
+  saveFakeApplicationDisbursements,
+  saveFakeStudent,
+} from "@sims/test-utils";
+import { faker } from "@faker-js/faker";
 import { Student } from "@sims/sims-db";
 import {
   createTestingAppModule,
@@ -173,6 +177,71 @@ describe("StudentMinistryController(e2e)-searchStudents", () => {
       .expect([]);
   });
 
+  it("Should find the student by certificate number when there is an exact match.", async () => {
+    // Arrange
+    const student = await saveFakeStudent(appDataSource);
+    const documentNumber = faker.number.int({ min: 100000000, max: 999999999 });
+    await saveFakeApplicationDisbursements(
+      appDataSource,
+      { student },
+      { firstDisbursementInitialValues: { documentNumber } },
+    );
+    const token = await getAESTToken(AESTGroups.BusinessAdministrators);
+
+    // Act/Assert
+    await request(app.getHttpServer())
+      .post(endpoint)
+      .send({ documentNumber: documentNumber.toString() })
+      .auth(token, BEARER_AUTH_TYPE)
+      .expect(HttpStatus.OK)
+      .expect([
+        {
+          id: student.id,
+          firstName: student.user.firstName,
+          lastName: student.user.lastName,
+          birthDate: student.birthDate,
+          sin: student.sinValidation.sin,
+        },
+      ]);
+  });
+
+  it("Should not find the student by certificate number when there is only a partial match.", async () => {
+    // Arrange
+    const student = await saveFakeStudent(appDataSource);
+    const documentNumber = faker.number.int({ min: 100000000, max: 999999999 });
+    await saveFakeApplicationDisbursements(
+      appDataSource,
+      { student },
+      { firstDisbursementInitialValues: { documentNumber } },
+    );
+    const token = await getAESTToken(AESTGroups.BusinessAdministrators);
+
+    // Act/Assert
+    await request(app.getHttpServer())
+      .post(endpoint)
+      .send({ documentNumber: documentNumber.toString().substring(0, 8) })
+      .auth(token, BEARER_AUTH_TYPE)
+      .expect(HttpStatus.OK)
+      .expect([]);
+  });
+
+  it("Should throw a bad request error when the certificate number is not numeric.", async () => {
+    // Arrange
+    const token = await getAESTToken(AESTGroups.BusinessAdministrators);
+
+    // Act/Assert
+    await request(app.getHttpServer())
+      .post(endpoint)
+      .send({ documentNumber: "12A45" })
+      .auth(token, BEARER_AUTH_TYPE)
+      .expect(HttpStatus.BAD_REQUEST)
+      .expect({
+        message: ["documentNumber must be a number string"],
+        error: "Bad Request",
+        statusCode: HttpStatus.BAD_REQUEST,
+      });
+  });
+
   it("Should throw a bad request error when no search parameters are provided.", async () => {
     // Arrange
     const student = await saveFakeStudent(appDataSource);
@@ -194,6 +263,9 @@ describe("StudentMinistryController(e2e)-searchStudents", () => {
           "appNumber should not be empty",
           "sin should not be empty",
           "email should not be empty",
+          "documentNumber must be shorter than or equal to 9 characters",
+          "documentNumber must be a number string",
+          "documentNumber should not be empty",
         ],
         error: "Bad Request",
         statusCode: HttpStatus.BAD_REQUEST,

sources/packages/backend/apps/api/src/route-controllers/student/_tests_/e2e/student.institutions.controller.searchStudents.e2e-spec.ts

@@ -13,8 +13,10 @@ import {
 import {
   createFakeInstitutionLocation,
   saveFakeApplication,
+  saveFakeApplicationDisbursements,
   saveFakeStudent,
 } from "@sims/test-utils";
+import { faker } from "@faker-js/faker";
 import {
   Application,
   ApplicationStatus,
@@ -483,6 +485,58 @@ describe("StudentInstitutionsController(e2e)-searchStudents", () => {
       );
   });
 
+  it("Should find the student by certificate number when the student has an application for the institution and there is an exact match.", async () => {
+    // Arrange
+    const student = await saveFakeStudent(appDataSource);
+    const documentNumber = faker.number.int({ min: 100000000, max: 999999999 });
+    await saveFakeApplicationDisbursements(
+      appDataSource,
+      {
+        institution: collegeF,
+        institutionLocation: collegeFLocation,
+        student,
+      },
+      { firstDisbursementInitialValues: { documentNumber } },
+    );
+
+    // Act/Assert
+    await request(app.getHttpServer())
+      .post(endpoint)
+      .send({ documentNumber: documentNumber.toString() })
+      .auth(collegeFInstitutionUserToken, BEARER_AUTH_TYPE)
+      .expect(HttpStatus.OK)
+      .expect(({ body }) =>
+        expect(body).toEqual([
+          {
+            id: student.id,
+            firstName: student.user.firstName,
+            lastName: student.user.lastName,
+            birthDate: student.birthDate,
+            sin: student.sinValidation.sin,
+          },
+        ]),
+      );
+  });
+
+  it("Should not find the student by certificate number when the student has no application for the institution.", async () => {
+    // Arrange
+    const student = await saveFakeStudent(appDataSource);
+    const documentNumber = faker.number.int({ min: 100000000, max: 999999999 });
+    await saveFakeApplicationDisbursements(
+      appDataSource,
+      { student },
+      { firstDisbursementInitialValues: { documentNumber } },
+    );
+
+    // Act/Assert
+    await request(app.getHttpServer())
+      .post(endpoint)
+      .send({ documentNumber: documentNumber.toString() })
+      .auth(collegeFInstitutionUserToken, BEARER_AUTH_TYPE)
+      .expect(HttpStatus.OK)
+      .expect([]);
+  });
+
   /**
    * Saves a student and an application for the student for College F.
    * @param applicationStatus application status.

sources/packages/backend/apps/api/src/route-controllers/student/models/student.dto.ts

@@ -8,6 +8,7 @@ import {
   IsEmail,
   IsEnum,
   IsNotEmpty,
+  IsNumberString,
   IsOptional,
   IsPositive,
   Length,
@@ -108,34 +109,70 @@ export class UpdateStudentAPIInDTO
 export class StudentSearchAPIInDTO {
   @ValidateIf(
     (input: StudentSearchAPIInDTO) =>
-      !input.lastName && !input.appNumber && !input.sin && !input.email,
+      !input.lastName &&
+      !input.appNumber &&
+      !input.sin &&
+      !input.email &&
+      !input.documentNumber,
   )
   @IsNotEmpty()
   firstName: string;
   @ValidateIf(
     (input: StudentSearchAPIInDTO) =>
-      !input.firstName && !input.appNumber && !input.sin && !input.email,
+      !input.firstName &&
+      !input.appNumber &&
+      !input.sin &&
+      !input.email &&
+      !input.documentNumber,
   )
   @IsNotEmpty()
   lastName: string;
   @ValidateIf(
     (input: StudentSearchAPIInDTO) =>
-      !input.firstName && !input.lastName && !input.sin && !input.email,
+      !input.firstName &&
+      !input.lastName &&
+      !input.sin &&
+      !input.email &&
+      !input.documentNumber,
   )
   @IsNotEmpty()
   appNumber: string;
   @ValidateIf(
     (input: StudentSearchAPIInDTO) =>
-      !input.firstName && !input.lastName && !input.appNumber && !input.email,
+      !input.firstName &&
+      !input.lastName &&
+      !input.appNumber &&
+      !input.email &&
+      !input.documentNumber,
   )
   @IsNotEmpty()
   sin: string;
   @ValidateIf(
     (input: StudentSearchAPIInDTO) =>
-      !input.firstName && !input.lastName && !input.appNumber && !input.sin,
+      !input.firstName &&
+      !input.lastName &&
+      !input.appNumber &&
+      !input.sin &&
+      !input.documentNumber,
   )
   @IsNotEmpty()
   email: string;
+  /**
+   * Certificate (financial document) number. Limited to 9 digits to fit the integer DB column.
+   */
+  @ValidateIf(
+    (input: StudentSearchAPIInDTO) =>
+      !!input.documentNumber ||
+      (!input.firstName &&
+        !input.lastName &&
+        !input.appNumber &&
+        !input.sin &&
+        !input.email),
+  )
+  @IsNotEmpty()
+  @IsNumberString({ no_symbols: true })
+  @MaxLength(9)
+  documentNumber: string;
 }
 
 export class SearchStudentAPIOutDTO {

sources/packages/backend/apps/api/src/services/student/student.service.ts

@@ -19,6 +19,7 @@ import {
   ModifiedIndependentStatus,
   SFASApplication,
   ORMCacheManager,
+  DisbursementSchedule,
 } from "@sims/sims-db";
 import { DataSource, EntityManager, Not, UpdateResult } from "typeorm";
 import { LoggerService } from "@sims/utilities/logger";
@@ -635,7 +636,7 @@ export class StudentService extends RecordDataModelService<Student> {
   /**
    * Search students based on the search criteria and institution id if provided.
    * @param searchCriteria options to search by firstName,
-   * lastName, appNumber or sin.
+   * lastName, appNumber, sin, email or documentNumber (certificate number).
    * @param institutionId id of the institution that the student applied to.
    * @returns list of student details.
    */
@@ -646,6 +647,7 @@ export class StudentService extends RecordDataModelService<Student> {
       appNumber?: string;
       sin?: string;
       email?: string;
+      documentNumber?: string;
     },
     institutionId?: number,
   ): Promise<Student[]> {
@@ -708,6 +710,25 @@ export class StudentService extends RecordDataModelService<Student> {
         email: searchCriteria.email.toLowerCase(),
       });
     }
+    if (searchCriteria.documentNumber) {
+      // Exact match on the certificate number of any disbursement of the student.
+      searchQuery.andWhere(
+        (qb) =>
+          `EXISTS ${qb
+            .subQuery()
+            .select("1")
+            .from(DisbursementSchedule, "disbursementSchedule")
+            .innerJoin(
+              "disbursementSchedule.studentAssessment",
+              "studentAssessment",
+            )
+            .innerJoin("studentAssessment.application", "certApplication")
+            .where("certApplication.student.id = student.id")
+            .andWhere("disbursementSchedule.documentNumber = :documentNumber")
+            .getQuery()}`,
+        { documentNumber: Number(searchCriteria.documentNumber) },
+      );
+    }
     return searchQuery.getMany();
   }