hot-update: confirm service (#66)

This pull request introduces a new feature for handling payment evidence
uploads and verification for student applications, along with several
related database and codebase changes. The most important changes
include the addition of a new `ApplicationPaymentEvidence` model and
migration, new API endpoints and services for uploading and verifying
payment evidence, updates to guards and DTOs, and integration with
external slip verification APIs.

**Payment Evidence Feature**

* Added new `ApplicationPaymentEvidence` model to `prisma/schema.prisma`
and corresponding migration, including fields for transaction details,
sender/receiver info, and relations to `ApplicationFile` and
`StudentApplication`.
[[1]](diffhunk://#diff-5b443964f4f3a611682db8f7e02177b0a8c632b2039e2bd5e4dd7347815c565cR25-R56)
[[2]](diffhunk://#diff-b1bfc9c3a4233a21db170e15c39c55027003c5037182b38e3ea66b76018bfc05R1-R32)
* Updated `ApplicationFile` and `StudentApplication` models to reference
`ApplicationPaymentEvidence`, enabling linkage between files,
applications, and payment evidence.
[[1]](diffhunk://#diff-5b443964f4f3a611682db8f7e02177b0a8c632b2039e2bd5e4dd7347815c565cR159-R160)
[[2]](diffhunk://#diff-5b443964f4f3a611682db8f7e02177b0a8c632b2039e2bd5e4dd7347815c565cR340-R341)

**API & Service Implementation**

* Introduced `ApplicationPaymentEvidenceModule`, controller, service,
and DTOs for handling evidence uploads, including file validation and
integration with external slip verification APIs.
[[1]](diffhunk://#diff-089f4f2474b64391c42b6e66aed33977e132058d92108f0a63234a7862e1f8b8R23)
[[2]](diffhunk://#diff-089f4f2474b64391c42b6e66aed33977e132058d92108f0a63234a7862e1f8b8R93)
[[3]](diffhunk://#diff-a35fd0ab81ffbac22de2874e1f05d690305f47f7c8629195016e005e8fe0233fR1-R11)
[[4]](diffhunk://#diff-985549e5c9228c6b1ac8358d2ec77c51acc7c5f6a28406237a8f587556aee772R1-R29)
[[5]](diffhunk://#diff-345a1edb7b7bf627f21d29b08856bc426eba54457b1eefa5f4461e4aae37889fR1-R137)
[[6]](diffhunk://#diff-b5dd2cd364a4b7c9c838c81ca8af220c73382ddce53f0ff96d50816dce772bfaR1-R6)
[[7]](diffhunk://#diff-4ef0a476aa1e31d1b3206096eb0e970fd2af11e376e3aaa2c0af2ded679d318eR1-R97)
* Added new guard `ApplicationPassGuard` to ensure only eligible
applications can upload payment evidence.

**Guard & Controller Updates**

* Renamed and updated guards and controller usages from
`AnnouncePeriodGuard` to `AnnounceAndConfirmPeriodGuard` for improved
clarity and coverage of confirmation periods.
[[1]](diffhunk://#diff-b229fbd3353d6fac838a965103a6fd141764b11211244fe15edae38db6e6ab2dL10-R10)
[[2]](diffhunk://#diff-279a2a4d44bc0c2b500f1bc2ad9fac62b393b5c9fc7fe2bc56ef12062fe381cfL4-R4)
[[3]](diffhunk://#diff-279a2a4d44bc0c2b500f1bc2ad9fac62b393b5c9fc7fe2bc56ef12062fe381cfL63-R63)
[[4]](diffhunk://#diff-34558e215c546c8fe49eaf7b2355ef614e90378a75ce2d8b3faf13e0006fe037L3-R3)

**Configuration & Validation**

* Added external API keys to configuration for slip verification
integration.
* Updated DTOs for staff status and confirmation to improve validation
and naming consistency.
[[1]](diffhunk://#diff-739bf614d12f2b84c455b0a31584cb09207cd50708f4ffd3c6e3260bbbbda4a5L2-R2)
[[2]](diffhunk://#diff-739bf614d12f2b84c455b0a31584cb09207cd50708f4ffd3c6e3260bbbbda4a5R43-R45)

**Miscellaneous**

* Minor UI update: Adjusted DB diagram iframe width in `README.md`.
* Fixed controller to return result for change-result endpoint in staff
status.

Author: ImJustNon

README.md

@@ -61,7 +61,7 @@
 </ul>
 
 <h3>DB-Diagram (Prototype)</h3>
-<iframe width="560" height="315" src='https://dbdiagram.io/e/69ae7fb9cf54053b6f3980fa/69ae7fffcf54053b6f398582'> </iframe>
+<iframe width="500" height="315" src='https://dbdiagram.io/e/69ae7fb9cf54053b6f3980fa/69ae7fffcf54053b6f398582'> </iframe>
 
 <h3>API Flow Design (Prototype)</h3>
 <a href="https://www.figma.com/board/ZO9E1iaCZasX5wwyK0D6g9/CC37-Backend-Routing-Flow?node-id=0-1&t=meCqyS4DR1seJfqG-1"><p>Open on Figma</p></a>

prisma/migrations/20260317045027_merge_payment_and_total_score/migration.sql

@@ -0,0 +1,32 @@
+-- CreateTable
+CREATE TABLE "ApplicationPaymentEvidence" (
+    "pe_id" TEXT NOT NULL,
+    "pe_transaction_ref" TEXT NOT NULL,
+    "pe_transaction_date" TIMESTAMP(3) NOT NULL,
+    "pe_transaction_expect_amount" DOUBLE PRECISION NOT NULL DEFAULT 500.00,
+    "pe_transaction_actual_amount" DOUBLE PRECISION NOT NULL,
+    "pe_json" TEXT NOT NULL,
+    "pe_sender_account_name" TEXT NOT NULL,
+    "pe_sender_account_number" TEXT NOT NULL,
+    "pe_sender_bank_id" TEXT NOT NULL,
+    "pe_sender_bank_name" TEXT NOT NULL,
+    "pe_reciever_account_name" TEXT NOT NULL,
+    "pe_reciever_account_number" TEXT NOT NULL,
+    "pe_reciever_bank_id" TEXT NOT NULL,
+    "pe_reciever_bank_name" TEXT NOT NULL,
+    "std_file_key" TEXT NOT NULL,
+    "std_application_id" TEXT NOT NULL,
+    "created_at" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updated_at" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "ApplicationPaymentEvidence_pkey" PRIMARY KEY ("pe_id")
+);
+
+-- CreateIndex
+CREATE UNIQUE INDEX "ApplicationPaymentEvidence_std_file_key_key" ON "ApplicationPaymentEvidence"("std_file_key");
+
+-- AddForeignKey
+ALTER TABLE "ApplicationPaymentEvidence" ADD CONSTRAINT "ApplicationPaymentEvidence_std_file_key_fkey" FOREIGN KEY ("std_file_key") REFERENCES "ApplicationFile"("std_file_key") ON DELETE RESTRICT ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "ApplicationPaymentEvidence" ADD CONSTRAINT "ApplicationPaymentEvidence_std_application_id_fkey" FOREIGN KEY ("std_application_id") REFERENCES "StudentApplication"("std_application_id") ON DELETE RESTRICT ON UPDATE CASCADE;

prisma/schema.prisma

@@ -22,6 +22,38 @@ model ApplicationTotalScore {
   updated_at                              DateTime              @updatedAt
 }
 
+model ApplicationPaymentEvidence {
+  pe_id                                   String                @id @default(uuid())
+  pe_transaction_ref                      String
+  pe_transaction_date                     DateTime
+
+  pe_transaction_expect_amount                        Float                 @default(500.00)
+  pe_transaction_actual_amount                        Float
+
+  pe_json                                 String                @db.Text
+
+  pe_sender_account_name                  String                
+  pe_sender_account_number                String
+
+  pe_sender_bank_id                       String                
+  pe_sender_bank_name                     String
+
+  pe_reciever_account_name                String                
+  pe_reciever_account_number              String
+
+  pe_reciever_bank_id                     String                
+  pe_reciever_bank_name                   String
+
+  std_file_key                            String                @unique
+  std_file                                ApplicationFile       @relation(fields: [std_file_key], references: [std_file_key])
+  
+  std_application_id                      String               
+  std_application                         StudentApplication    @relation(fields: [std_application_id], references: [std_application_id])
+
+  created_at                              DateTime              @default(now())
+  updated_at                              DateTime              @updatedAt
+}
+
 model StaffEmailHistory {
   email_id                                String                @default(uuid()) @id
   
@@ -123,6 +155,8 @@ model ApplicationFile {
   std_file_size                           Int?
   std_file_key                            String                    @id
   std_file_type                           FileType
+
+  pe_payment_evidence                     ApplicationPaymentEvidence?
   
   std_file_disabled                       Boolean                   @default(false)
 
@@ -303,6 +337,8 @@ model StudentApplication {
   
   std_status                              ApplicationStatus?
 
+  pe_payment_evidence                     ApplicationPaymentEvidence[]
+
   created_at                              DateTime                  @default(now())
   updated_at                              DateTime                  @updatedAt
 }

src/app.module.ts

@@ -20,6 +20,7 @@ import { auth } from "./lib/auth";
 import { ApplicationConfirmationModule } from "./modules/application-confirmation/application-confirmation.module";
 import { ApplicationFileModule } from "./modules/application-file/application-file.module";
 import { ApplicationInfoModule } from "./modules/application-info/application-info.module";
+import { ApplicationPaymentEvidenceModule } from "./modules/application-payment-evidence/application-payment-evidence.module";
 import { ApplicationQuestionModule } from "./modules/application-question/application-question.module";
 import { ApplicationStatusModule } from "./modules/application-status/application-status.module";
 import { ApplicationSubmitModule } from "./modules/application-submit/application-submit.module";
@@ -89,6 +90,7 @@ import { UtilModule } from "./modules/util/util.module";
 		StaffEmailModule,
 		StaffTotalScoreModule,
 		StaffLeaderboardModule,
+		ApplicationPaymentEvidenceModule,
 	],
 
 	controllers: [AppController],

src/common/guards/announce-period.guard.ts

@@ -7,7 +7,7 @@ import { config } from "src/config/app.config";
 import { PrismaService } from "src/core/prisma/prisma.service";
 
 @Injectable()
-export class AnnouncePeriodGuard implements CanActivate {
+export class AnnounceAndConfirmPeriodGuard implements CanActivate {
 	canActivate(context: ExecutionContext): boolean {
 		try {
 			if (config.resultAnnounceAndConfirmPeriod.bypass) {

src/common/guards/application-pass.guard.ts

@@ -0,0 +1,46 @@
+import { Type } from "@aws-sdk/client-s3";
+import { CanActivate, ExecutionContext, ForbiddenException, Injectable, InternalServerErrorException } from "@nestjs/common";
+import type { UserSession } from "@thallesp/nestjs-better-auth";
+import { Session } from "@thallesp/nestjs-better-auth";
+import { Observable, retry } from "rxjs";
+import { PrismaService } from "src/core/prisma/prisma.service";
+
+@Injectable()
+export class ApplicationPassGuard implements CanActivate {
+	constructor(private readonly prisma: PrismaService) {}
+
+	async canActivate(context: ExecutionContext): Promise<boolean> {
+		const request = context.switchToHttp().getRequest();
+		const session = request.session as UserSession;
+
+		try {
+			const studentApplication = await this.prisma.studentApplication.findMany({
+				where: {
+					std_user: {
+						id: session.user.id,
+					},
+				},
+			});
+
+			if (studentApplication.length > 0) {
+				throw "No application found linked with your account";
+			}
+
+			const filterPassApplication = studentApplication.filter((app) => app.std_application_result === "pass");
+
+			if (filterPassApplication.length <= 0) {
+				throw `Your Application in : ${studentApplication.map((app) => app.std_application_result).join(", ")} stage`;
+			}
+
+			const filterAllowConfirm = filterPassApplication.filter((app) => app.stf_application_allow_confirm === true);
+
+			if (filterAllowConfirm.length <= 0) {
+				throw `Please wait staff to allow you to confirm`;
+			}
+
+			return true;
+		} catch (e) {
+			throw new ForbiddenException(e);
+		}
+	}
+}

src/config/app.config.ts

@@ -52,4 +52,7 @@ export const config = {
 			from: process.env.MAIL_FROM || "",
 		},
 	},
+	apis: {
+		slipKey: process.env.API_EASYSLIP_KEY,
+	},
 } as const;

src/modules/application-confirmation/application-confirmation.controller.ts

@@ -1,7 +1,7 @@
 import { Body, Controller, Get, Param, Post, UseGuards } from "@nestjs/common";
 import { ApiBody, ApiOperation, ApiParam, ApiResponse, ApiTags } from "@nestjs/swagger";
 import { Session, type UserSession } from "@thallesp/nestjs-better-auth";
-import { AnnouncePeriodGuard } from "src/common/guards/announce-period.guard";
+import { AnnounceAndConfirmPeriodGuard } from "src/common/guards/announce-period.guard";
 import { RegisterPeriodGuard } from "src/common/guards/register-period.guard";
 import { ApplicationConfirmationService } from "./application-confirmation.service";
 import { ApplicationConfirmationDto } from "./dto/application-confirmation.dto";
@@ -60,7 +60,7 @@ export class ApplicationConfirmationController {
 	}
 
 	@Post("/")
-	@UseGuards(AnnouncePeriodGuard)
+	@UseGuards(AnnounceAndConfirmPeriodGuard)
 	@ApiOperation({
 		description: "Confirm or decline an application. Requires application to be passed and allowed to confirm.",
 	})

src/modules/application-payment-evidence/@types/VerifyBank.type.ts

@@ -0,0 +1,97 @@
+// Request Types
+export interface VerifyBankRequest {
+	// One of the following is required
+	payload?: string; // QR payload (1-128 chars)
+	image?: File; // Image file (multipart/form-data)
+	base64?: string; // Base64 encoded image
+	url?: string; // URL to image (1-2048 chars)
+
+	// Optional parameters
+	remark?: string; // 1-255 chars
+	matchAccount?: boolean;
+	matchAmount?: number;
+	checkDuplicate?: boolean;
+}
+
+// Response Types
+export interface VerifyBankResponse {
+	success: true;
+	data: VerifyBankData;
+	message: string;
+}
+
+export interface VerifyBankData {
+	remark?: string;
+	isDuplicate: boolean;
+	matchedAccount: MatchedAccount | null;
+	amountInOrder?: number;
+	amountInSlip: number;
+	isAmountMatched?: boolean;
+	rawSlip: RawSlip;
+}
+
+export interface MatchedAccount {
+	bank: {
+		nameTh: string;
+		nameEn: string;
+		code: string;
+		shortCode: string;
+	};
+	nameTh: string;
+	nameEn: string;
+	type: "PERSONAL" | "JURISTIC";
+	bankNumber: string;
+}
+
+export interface RawSlip {
+	payload: string;
+	transRef: string;
+	date: string; // ISO 8601
+	countryCode: string;
+	amount: Amount;
+	fee: number;
+	ref1: string;
+	ref2: string;
+	ref3: string;
+	sender: Party;
+	receiver: Party & { merchantId?: string | null };
+}
+
+export interface Amount {
+	amount: number;
+	local: {
+		amount: number;
+		currency: string;
+	};
+}
+
+export interface Party {
+	bank: {
+		id: string;
+		name: string;
+		short: string;
+	};
+	account: {
+		name: {
+			th?: string;
+			en?: string;
+		};
+		bank?: {
+			type: "BANKAC" | "TOKEN" | "DUMMY";
+			account: string;
+		};
+		proxy?: {
+			type: "NATID" | "MSISDN" | "EWALLETID" | "EMAIL" | "BILLERID";
+			account: string;
+		};
+	};
+}
+
+// Error Response
+export interface ErrorResponse {
+	success: false;
+	error: {
+		code: string;
+		message: string;
+	};
+}

src/modules/application-payment-evidence/application-payment-evidence.controller.ts

@@ -0,0 +1,29 @@
+import { Body, Controller, FileTypeValidator, MaxFileSizeValidator, ParseFilePipe, Post, UploadedFile, UseGuards, UseInterceptors } from "@nestjs/common";
+import { FileInterceptor } from "@nestjs/platform-express";
+import { Session, type UserSession } from "@thallesp/nestjs-better-auth";
+import { AnnounceAndConfirmPeriodGuard } from "src/common/guards/announce-period.guard";
+import { ApplicationPassGuard } from "src/common/guards/application-pass.guard";
+import { ApplicationPaymentEvidenceService } from "./application-payment-evidence.service";
+import { ApplicationPaymentEvidenceDto } from "./dto/application-payment-evidence.dto";
+
+@Controller("/api/application/payment-evidence")
+export class ApplicationPaymentEvidenceController {
+	constructor(private readonly applicationPaymentEvidenceService: ApplicationPaymentEvidenceService) {}
+
+	@Post("/upload")
+	// @UseGuards(AnnounceAndConfirmPeriodGuard)
+	// @UseGuards(ApplicationPassGuard)
+	@UseInterceptors(FileInterceptor("file"))
+	uploadEvidence(
+		@Session() session: UserSession,
+		@Body() applicationPaymentEvidenceDto: ApplicationPaymentEvidenceDto,
+		@UploadedFile(
+			new ParseFilePipe({
+				validators: [new MaxFileSizeValidator({ maxSize: 3 * 1024 * 1024 }), new FileTypeValidator({ fileType: "image/*" })],
+			}),
+		)
+		file: Express.Multer.File,
+	) {
+		return this.applicationPaymentEvidenceService.uploadEvidence(session.user.id, applicationPaymentEvidenceDto, file);
+	}
+}