Feat/72 add tutor balance withdrawal

apps/api/prisma/schema/migrations/20260908000000_add_withdrawal_transaction_type/migration.sql

@@ -0,0 +1 @@
+ALTER TYPE "TransactionType" ADD VALUE 'withdrawal';

apps/api/prisma/schema/transaction.prisma

@@ -2,6 +2,7 @@ enum TransactionType {
   topup
   session_charge
   earning
+  withdrawal
 }
 
 model Transaction {

apps/api/src/common/utils/withdrawal-metadata.ts

@@ -0,0 +1,88 @@
+import { createHash } from "node:crypto";
+import type { Transaction } from "@prisma/client";
+import { z } from "zod";
+
+// Supported mock destinations, not bank ownership or bank-specific account verification.
+export const THAI_BANK_CODES = [
+  "BBL",
+  "KBANK",
+  "KTB",
+  "SCB",
+  "BAY",
+  "TTB",
+  "GSB",
+  "BAAC",
+  "GHB",
+  "KKP",
+  "TISCO",
+  "CIMBT",
+  "UOB",
+] as const;
+
+const metadataSchema = z
+  .object({
+    kind: z.literal("withdrawal"),
+    version: z.literal(1),
+    requestId: z
+      .string()
+      .uuid()
+      .regex(/^[0-9a-f-]+$/),
+    requestFingerprint: z.string().regex(/^[0-9a-f]{64}$/),
+    currency: z.literal("THB"),
+    status: z.literal("completed"),
+    destination: z
+      .object({
+        bankCode: z.enum(THAI_BANK_CODES),
+        accountNumberMasked: z.string().regex(/^\*{2,16}\d{4}$/),
+        accountHolderName: z
+          .string()
+          .min(1)
+          .max(100)
+          .refine((name) => name === name.trim().replace(/\s+/g, " ")),
+      })
+      .strict(),
+    balanceAfter: z.string().regex(/^(0|[1-9]\d{0,9})\.\d{2}$/),
+  })
+  .strict();
+
+export type WithdrawalMetadata = z.infer<typeof metadataSchema>;
+
+// UUIDv5 with the fixed standard URL namespace. No secret or amount in the ID:
+// changing details must collide with the original request, never create another debit.
+export function withdrawalTransactionId(userId: string, requestId: string): string {
+  const namespace = Buffer.from("6ba7b8119dad11d180b400c04fd430c8", "hex");
+  const hash = createHash("sha1")
+    .update(namespace)
+    .update(`tutorist:withdrawal:${userId}:${requestId.toLowerCase()}`, "utf8")
+    .digest();
+  hash[6] = (hash[6] & 0x0f) | 0x50;
+  hash[8] = (hash[8] & 0x3f) | 0x80;
+  const hex = hash.subarray(0, 16).toString("hex");
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+
+export function serializeWithdrawalMetadata(metadata: WithdrawalMetadata): string {
+  return JSON.stringify(metadataSchema.parse(metadata));
+}
+
+export function readWithdrawalMetadata(transaction: Transaction): WithdrawalMetadata | null {
+  if (
+    transaction.type !== "withdrawal" ||
+    transaction.relatedSessionId !== null ||
+    !transaction.amount.greaterThan(0) ||
+    transaction.note === null
+  )
+    return null;
+  try {
+    const result = metadataSchema.safeParse(JSON.parse(transaction.note));
+    if (
+      !result.success ||
+      transaction.id !== withdrawalTransactionId(transaction.userId, result.data.requestId)
+    ) {
+      return null;
+    }
+    return result.data;
+  } catch {
+    return null;
+  }
+}

apps/api/src/controller/withdrawal.controller.ts

@@ -0,0 +1,87 @@
+import { Prisma } from "@prisma/client";
+import type { NextFunction, Response } from "express";
+import { z } from "zod";
+import type { AuthRequest } from "../common/middleware/auth.middleware.js";
+import { ForbiddenError, UnauthorizedError } from "../common/errors/app-error.js";
+import { successResponse } from "../common/utils/response.js";
+import { withdrawalService } from "../service/withdrawal.service.js";
+import { THAI_BANK_CODES } from "../common/utils/withdrawal-metadata.js";
+
+export const withdrawalSchema = z
+  .object({
+    requestId: z
+      .string()
+      .uuid("Request ID must be a UUID")
+      .transform((id) => id.toLowerCase()),
+    amount: z
+      .number()
+      .finite()
+      .positive("Withdrawal amount must be greater than zero")
+      .max(9999999999.99, "Withdrawal amount exceeds the supported precision")
+      .refine(
+        (amount) => new Prisma.Decimal(amount).decimalPlaces() <= 2,
+        "Withdrawal amount must have at most two decimal places"
+      ),
+    password: z.string().min(1, "Confirmation password is required"),
+    bankCode: z.enum(THAI_BANK_CODES, { message: "Please select a supported Thai bank" }),
+    accountNumber: z
+      .string()
+      .max(64)
+      .trim()
+      .transform((value) => value.replace(/[ -]/g, ""))
+      .pipe(z.string().regex(/^\d{6,20}$/, "Bank account number must contain 6 to 20 digits")),
+    accountHolderName: z
+      .string()
+      .trim()
+      .min(1, "Account holder name is required")
+      .max(100)
+      .transform((name) => name.replace(/\s+/g, " ")),
+  })
+  .strict();
+
+function tutorId(req: AuthRequest) {
+  if (!req.user) throw new UnauthorizedError();
+  if (req.user.role !== "tutor") throw new ForbiddenError("Only tutors can withdraw balance");
+  return req.user.id;
+}
+
+export const withdrawalController = {
+  async getByRequest(req: AuthRequest, res: Response, next: NextFunction) {
+    try {
+      const userId = tutorId(req);
+      const requestId = z.string().uuid("Request ID must be a UUID").parse(req.params.requestId);
+      const withdrawal = await withdrawalService.getByRequest(userId, requestId);
+      res
+        .set("Cache-Control", "no-store")
+        .json(successResponse(withdrawal, "Withdrawal retrieved"));
+    } catch (error) {
+      next(error);
+    }
+  },
+  async submit(req: AuthRequest, res: Response, next: NextFunction) {
+    try {
+      const userId = tutorId(req);
+      const input = withdrawalSchema.parse(req.body);
+      const result = await withdrawalService.submit(userId, input);
+      res
+        .set("Cache-Control", "no-store")
+        .status(result.replayed ? 200 : 201)
+        .json(successResponse(result.data, "Mock withdrawal completed"));
+    } catch (error) {
+      next(error);
+    }
+  },
+
+  async get(req: AuthRequest, res: Response, next: NextFunction) {
+    try {
+      const userId = tutorId(req);
+      const id = z.string().uuid("Withdrawal ID must be a UUID").parse(req.params.id);
+      const withdrawal = await withdrawalService.get(userId, id);
+      res
+        .set("Cache-Control", "no-store")
+        .json(successResponse(withdrawal, "Withdrawal retrieved"));
+    } catch (error) {
+      next(error);
+    }
+  },
+};

apps/api/src/repository/user.repository.ts

@@ -49,6 +49,22 @@ export type ExistingProfileUpdate =
     });
 
 export const userRepository = {
+  async findForPasswordVerification(
+    userId: string
+  ): Promise<Pick<User, "role" | "passwordHash"> | null> {
+    return prisma.user.findUnique({
+      where: { id: userId },
+      select: { role: true, passwordHash: true },
+    });
+  },
+
+  async findRoleById(userId: string): Promise<Pick<User, "role"> | null> {
+    return prisma.user.findUnique({
+      where: { id: userId },
+      select: { role: true },
+    });
+  },
+
   async updateProfile(userId: string, data: Partial<User>): Promise<PublicUser> {
     return prisma.user.update({
       where: { id: userId },

apps/api/src/repository/withdrawal.repository.ts

@@ -0,0 +1,93 @@
+import { Prisma } from "@prisma/client";
+import { prisma } from "../config/prisma.js";
+import {
+  readWithdrawalMetadata,
+  serializeWithdrawalMetadata,
+  withdrawalTransactionId,
+  type WithdrawalMetadata,
+} from "../common/utils/withdrawal-metadata.js";
+
+type WithdrawalInput = {
+  userId: string;
+  requestId: string;
+  requestFingerprint: string;
+  passwordHash: string;
+  amount: Prisma.Decimal;
+  bankCode: WithdrawalMetadata["destination"]["bankCode"];
+  accountNumberMasked: string;
+  accountHolderName: string;
+};
+
+export const withdrawalRepository = {
+  findOwned(userId: string, id: string) {
+    return prisma.transaction.findFirst({ where: { id, userId, type: "withdrawal" } });
+  },
+
+  submit(input: WithdrawalInput) {
+    return prisma.$transaction(
+      async (tx) => {
+        // Serialize requests for this wallet before checking idempotency or balance.
+        // Parameterized SQL; the lock also coordinates with other wallet updates.
+        const users = await tx.$queryRaw<{ role: string; passwordHash: string }[]>`
+        SELECT "role", "passwordHash" FROM "users" WHERE "id" = ${input.userId} FOR UPDATE
+      `;
+        const user = users[0];
+        if (!user) return { kind: "missing-user" } as const;
+        if (user.role !== "tutor") return { kind: "forbidden" } as const;
+        if (user.passwordHash !== input.passwordHash) return { kind: "password-changed" } as const;
+
+        const id = withdrawalTransactionId(input.userId, input.requestId);
+        const existing = await tx.transaction.findUnique({ where: { id } });
+        if (existing) {
+          const metadata = readWithdrawalMetadata(existing);
+          if (
+            existing.userId !== input.userId ||
+            !metadata ||
+            metadata.requestId !== input.requestId ||
+            metadata.requestFingerprint !== input.requestFingerprint ||
+            !existing.amount.equals(input.amount)
+          ) {
+            return { kind: "conflict" } as const;
+          }
+          return { kind: "success", withdrawal: existing, replayed: true } as const;
+        }
+
+        const updated = await tx.user.updateMany({
+          where: { id: input.userId, role: "tutor", walletBalance: { gte: input.amount } },
+          data: { walletBalance: { decrement: input.amount } },
+        });
+        if (updated.count !== 1) return { kind: "insufficient-balance" } as const;
+
+        const wallet = await tx.user.findUniqueOrThrow({
+          where: { id: input.userId },
+          select: { walletBalance: true },
+        });
+        const withdrawal = await tx.transaction.create({
+          data: {
+            id,
+            userId: input.userId,
+            type: "withdrawal",
+            amount: input.amount,
+            relatedSessionId: null,
+            note: serializeWithdrawalMetadata({
+              kind: "withdrawal",
+              version: 1,
+              requestId: input.requestId,
+              requestFingerprint: input.requestFingerprint,
+              currency: "THB",
+              status: "completed",
+              balanceAfter: wallet.walletBalance.toFixed(2),
+              destination: {
+                bankCode: input.bankCode,
+                accountNumberMasked: input.accountNumberMasked,
+                accountHolderName: input.accountHolderName,
+              },
+            }),
+          },
+        });
+        return { kind: "success", withdrawal, replayed: false } as const;
+      },
+      { isolationLevel: Prisma.TransactionIsolationLevel.ReadCommitted }
+    );
+  },
+};