feat(P15B-1,P15B-6): 完成请假V1闭环

server/src/app.js

@@ -21,6 +21,7 @@ const reimbursementRoutes = require("./routes/reimbursements");
 const invoicePoolRoutes = require("./routes/invoicePool");
 const workflowRoutes = require("./routes/workflow");
 const leaveRoutes = require("./routes/leave");
+const leaveTypesRoutes = require("./routes/leave-types");
 const delegationRoutes = require("./routes/delegations");
 const auditRoutes = require("./routes/audit");
 const usersRoutes = require("./routes/users");
@@ -274,6 +275,7 @@ async function buildApp() {
   await app.register(reimbursementRoutes, { prefix: "/api" });
   await app.register(invoicePoolRoutes, { prefix: "/api" });
   await app.register(workflowRoutes, { prefix: "/api" });
+  await app.register(leaveTypesRoutes, { prefix: "/api" });
   await app.register(leaveRoutes, { prefix: "/api" });
   await app.register(delegationRoutes, { prefix: "/api" });
   await app.register(auditRoutes, { prefix: "/api" });

server/src/routes/leave-types.js

@@ -0,0 +1,314 @@
+const { z } = require("zod");
+
+const { AppError } = require("../utils/AppError");
+const { sendData } = require("../utils/reply");
+const { mapLeaveTypeResponse } = require("../services/leave");
+
+const LEAVE_TYPE_ID_SCHEMA = z.string().uuid();
+const LEAVE_TYPE_QUERY_SCHEMA = z.object({
+  enabled: z
+    .enum(["true", "false"])
+    .transform((value) => value === "true")
+    .optional(),
+});
+
+const LEAVE_TYPE_BODY_SCHEMA = z
+  .object({
+    code: z
+      .string()
+      .trim()
+      .min(1)
+      .max(64)
+      .regex(/^[a-z][a-z0-9_]*$/i),
+    name: z.string().trim().min(1).max(64),
+    description: z.string().trim().max(500).nullable().optional(),
+    enabled: z.boolean().optional(),
+    requiresAttachment: z.boolean().optional(),
+    attachmentMimeTypes: z.array(z.string().trim().min(1).max(128)).max(10).optional(),
+    sortOrder: z.number().int().min(0).max(9999).optional(),
+    annualQuotaDays: z
+      .number()
+      .min(0)
+      .max(365)
+      .refine((value) => Math.round(value * 2) === value * 2, "half_day_only"),
+    policyDescription: z.string().trim().max(500).nullable().optional(),
+  })
+  .strict();
+
+const LEAVE_TYPE_PATCH_SCHEMA = LEAVE_TYPE_BODY_SCHEMA.partial();
+
+function buildValidationError(details, statusCode = 400) {
+  return new AppError({
+    code: "VALID_001",
+    message: "参数校验失败",
+    statusCode,
+    details,
+  });
+}
+
+function parseTypeId(value) {
+  const parsed = LEAVE_TYPE_ID_SCHEMA.safeParse(value);
+  if (!parsed.success) {
+    throw buildValidationError({ id: "invalid_uuid" });
+  }
+  return parsed.data;
+}
+
+function parseTypeQuery(query) {
+  const parsed = LEAVE_TYPE_QUERY_SCHEMA.safeParse(query ?? {});
+  if (!parsed.success) {
+    throw buildValidationError(parsed.error.flatten());
+  }
+  return parsed.data;
+}
+
+function parseTypeBody(schema, body) {
+  const parsed = schema.safeParse(body ?? {});
+  if (!parsed.success) {
+    throw buildValidationError(parsed.error.flatten());
+  }
+
+  return {
+    code: typeof parsed.data.code === "string" ? parsed.data.code.trim().toLowerCase() : undefined,
+    name: typeof parsed.data.name === "string" ? parsed.data.name.trim() : undefined,
+    description:
+      parsed.data.description === undefined ? undefined : parsed.data.description?.trim() ?? null,
+    enabled: parsed.data.enabled,
+    requiresAttachment: parsed.data.requiresAttachment,
+    attachmentMimeTypes: parsed.data.attachmentMimeTypes,
+    sortOrder: parsed.data.sortOrder,
+    annualQuotaDays: parsed.data.annualQuotaDays,
+    policyDescription:
+      parsed.data.policyDescription === undefined
+        ? undefined
+        : parsed.data.policyDescription?.trim() ?? null,
+  };
+}
+
+function normalizePrismaLeaveType(record) {
+  return mapLeaveTypeResponse({
+    ...record,
+    leave_policy: record.leave_policy,
+  });
+}
+
+function isUniqueConstraint(error, targetField) {
+  if (!error || error.code !== "P2002") {
+    return false;
+  }
+
+  const target = error.meta?.target;
+  if (Array.isArray(target)) {
+    return target.includes(targetField);
+  }
+
+  return typeof target === "string" && target.includes(targetField);
+}
+
+async function leaveTypesRoutes(fastify) {
+  fastify.get(
+    "/leave-types",
+    {
+      schema: { tags: ["Leave"], summary: "List Leave Types" },
+      preHandler: fastify.requireEntityPermission("leave", "view_own"),
+    },
+    async (request, reply) => {
+      const query = parseTypeQuery(request.query);
+      const canManage = fastify.hasPermission(request.employee, "leave.manage");
+
+      const items = await fastify.prisma.leaveType.findMany({
+        where: {
+          ...(canManage
+            ? query.enabled == null
+              ? {}
+              : { enabled: query.enabled }
+            : { enabled: true }),
+        },
+        orderBy: [{ sort_order: "asc" }, { code: "asc" }],
+        select: {
+          id: true,
+          code: true,
+          name: true,
+          description: true,
+          enabled: true,
+          requires_attachment: true,
+          attachment_mime_types: true,
+          sort_order: true,
+          created_at: true,
+          updated_at: true,
+          leave_policy: {
+            select: {
+              id: true,
+              annual_quota_days: true,
+              enabled: true,
+              description: true,
+            },
+          },
+        },
+      });
+
+      return sendData(reply, request, {
+        items: items.map(normalizePrismaLeaveType),
+      });
+    },
+  );
+
+  fastify.post(
+    "/leave-types",
+    {
+      schema: { tags: ["Leave"], summary: "Create Leave Type" },
+      preHandler: fastify.requireEntityPermission("leave", "manage"),
+    },
+    async (request, reply) => {
+      const body = parseTypeBody(LEAVE_TYPE_BODY_SCHEMA, request.body);
+
+      try {
+        const leaveType = await fastify.prisma.leaveType.create({
+          data: {
+            code: body.code,
+            name: body.name,
+            description: body.description ?? null,
+            enabled: body.enabled ?? true,
+            requires_attachment: body.requiresAttachment ?? false,
+            attachment_mime_types: body.attachmentMimeTypes ?? null,
+            sort_order: body.sortOrder ?? 100,
+            created_by: request.employee.id,
+            updated_by: request.employee.id,
+            leave_policy: {
+              create: {
+                annual_quota_days: body.annualQuotaDays,
+                enabled: body.enabled ?? true,
+                description: body.policyDescription ?? null,
+                created_by: request.employee.id,
+                updated_by: request.employee.id,
+              },
+            },
+          },
+          select: {
+            id: true,
+            code: true,
+            name: true,
+            description: true,
+            enabled: true,
+            requires_attachment: true,
+            attachment_mime_types: true,
+            sort_order: true,
+            created_at: true,
+            updated_at: true,
+            leave_policy: {
+              select: {
+                id: true,
+                annual_quota_days: true,
+                enabled: true,
+                description: true,
+              },
+            },
+          },
+        });
+
+        return sendData(reply, request, normalizePrismaLeaveType(leaveType));
+      } catch (error) {
+        if (isUniqueConstraint(error, "code")) {
+          throw buildValidationError({ code: "duplicate" }, 409);
+        }
+        throw error;
+      }
+    },
+  );
+
+  fastify.patch(
+    "/leave-types/:id",
+    {
+      schema: { tags: ["Leave"], summary: "Patch Leave Type" },
+      preHandler: fastify.requireEntityPermission("leave", "manage"),
+    },
+    async (request, reply) => {
+      const leaveTypeId = parseTypeId(request.params?.id);
+      const body = parseTypeBody(LEAVE_TYPE_PATCH_SCHEMA, request.body);
+
+      const existing = await fastify.prisma.leaveType.findUnique({
+        where: { id: leaveTypeId },
+        select: {
+          id: true,
+          leave_policy: {
+            select: {
+              id: true,
+            },
+          },
+        },
+      });
+
+      if (!existing) {
+        throw new AppError({
+          code: "SYS_404",
+          message: "Not Found",
+          statusCode: 404,
+        });
+      }
+
+      try {
+        const leaveType = await fastify.prisma.leaveType.update({
+          where: { id: leaveTypeId },
+          data: {
+            ...(body.code !== undefined ? { code: body.code } : {}),
+            ...(body.name !== undefined ? { name: body.name } : {}),
+            ...(body.description !== undefined ? { description: body.description } : {}),
+            ...(body.enabled !== undefined ? { enabled: body.enabled } : {}),
+            ...(body.requiresAttachment !== undefined
+              ? { requires_attachment: body.requiresAttachment }
+              : {}),
+            ...(body.attachmentMimeTypes !== undefined
+              ? { attachment_mime_types: body.attachmentMimeTypes }
+              : {}),
+            ...(body.sortOrder !== undefined ? { sort_order: body.sortOrder } : {}),
+            updated_by: request.employee.id,
+            leave_policy:
+              body.annualQuotaDays !== undefined || body.policyDescription !== undefined || body.enabled !== undefined
+                ? {
+                    update: {
+                      ...(body.annualQuotaDays !== undefined
+                        ? { annual_quota_days: body.annualQuotaDays }
+                        : {}),
+                      ...(body.policyDescription !== undefined
+                        ? { description: body.policyDescription }
+                        : {}),
+                      ...(body.enabled !== undefined ? { enabled: body.enabled } : {}),
+                      updated_by: request.employee.id,
+                    },
+                  }
+                : undefined,
+          },
+          select: {
+            id: true,
+            code: true,
+            name: true,
+            description: true,
+            enabled: true,
+            requires_attachment: true,
+            attachment_mime_types: true,
+            sort_order: true,
+            created_at: true,
+            updated_at: true,
+            leave_policy: {
+              select: {
+                id: true,
+                annual_quota_days: true,
+                enabled: true,
+                description: true,
+              },
+            },
+          },
+        });
+
+        return sendData(reply, request, normalizePrismaLeaveType(leaveType));
+      } catch (error) {
+        if (isUniqueConstraint(error, "code")) {
+          throw buildValidationError({ code: "duplicate" }, 409);
+        }
+        throw error;
+      }
+    },
+  );
+}
+
+module.exports = leaveTypesRoutes;

server/src/routes/leave.js

@@ -3,17 +3,54 @@ const { z } = require("zod");
 const { AppError } = require("../utils/AppError");
 const { sendData } = require("../utils/reply");
 const { resolveActionableStep } = require("../utils/workflow");
+const {
+  DEFAULT_ATTACHMENT_MIME_TYPES,
+  calculateRequestedDays,
+  createLeaveLedgerEntry,
+  formatDateOnly,
+  leaveRangesOverlap,
+  loadLeaveBalanceItems,
+  loadLeaveBalanceSnapshot,
+  loadLeaveLedgerSummaryForRequest,
+  lockEmployeeForLeave,
+  normalizeAttachmentMimeTypes,
+  persistLeaveAttachment,
+  releaseReservedLeave,
+  toHalfDayUnits,
+} = require("../services/leave");
 
 const DATE_ONLY_SCHEMA = z.string().regex(/^\d{4}-\d{2}-\d{2}$/);
+const SESSION_SCHEMA = z.enum(["am", "pm"]);
+const STATUS_SCHEMA = z.enum(["draft", "reviewing", "approved", "rejected", "cancelled"]);
 
 const createLeaveSchema = z
   .object({
+    leaveTypeId: z.string().uuid(),
     startDate: DATE_ONLY_SCHEMA,
     endDate: DATE_ONLY_SCHEMA,
+    startSession: SESSION_SCHEMA.optional(),
+    endSession: SESSION_SCHEMA.optional(),
     reason: z.string().trim().max(500).optional(),
   })
   .strict();
 
+const leaveListQuerySchema = z.object({
+  status: STATUS_SCHEMA.optional(),
+  scope: z.enum(["own", "all"]).optional(),
+  page: z.coerce.number().int().min(1).optional(),
+  pageSize: z.coerce.number().int().min(1).max(100).optional(),
+});
+
+const leaveBalanceQuerySchema = z.object({
+  employeeId: z.string().uuid().optional(),
+});
+
+const withdrawBodySchema = z
+  .object({
+    comment: z.string().trim().max(500).optional(),
+  })
+  .strict();
+
 const LEAVE_WORKFLOW_STEPS_V1 = [
   {
     id: "leave_approval_manager",
@@ -23,53 +60,185 @@ const LEAVE_WORKFLOW_STEPS_V1 = [
   },
 ];
 
+const LEAVE_TYPE_SELECT = {
+  id: true,
+  code: true,
+  name: true,
+  description: true,
+  enabled: true,
+  requires_attachment: true,
+  attachment_mime_types: true,
+  sort_order: true,
+  created_at: true,
+  updated_at: true,
+  leave_policy: {
+    select: {
+      id: true,
+      annual_quota_days: true,
+      enabled: true,
+      description: true,
+    },
+  },
+};
+
+function buildValidationError(details, statusCode = 400) {
+  return new AppError({
+    code: "VALID_001",
+    message: "参数校验失败",
+    statusCode,
+    details,
+  });
+}
+
 function parseLeaveId(value) {
   const parsed = z.string().uuid().safeParse(value);
   if (!parsed.success) {
-    throw new AppError({
-      code: "VALID_001",
-      message: "参数校验失败",
-      statusCode: 400,
-      details: { id: "invalid_uuid" },
-    });
+    throw buildValidationError({ id: "invalid_uuid" });
   }
   return parsed.data;
 }
 
+function parseLeaveListQuery(query) {
+  const parsed = leaveListQuerySchema.safeParse(query ?? {});
+  if (!parsed.success) {
+    throw buildValidationError(parsed.error.flatten());
+  }
+
+  return {
+    status: parsed.data.status,
+    scope: parsed.data.scope ?? "own",
+    page: parsed.data.page ?? 1,
+    pageSize: parsed.data.pageSize ?? 20,
+  };
+}
+
+function parseLeaveBalanceQuery(query) {
+  const parsed = leaveBalanceQuerySchema.safeParse(query ?? {});
+  if (!parsed.success) {
+    throw buildValidationError(parsed.error.flatten());
+  }
+
+  return parsed.data;
+}
+
+function parseWithdrawBody(body) {
+  const parsed = withdrawBodySchema.safeParse(body ?? {});
+  if (!parsed.success) {
+    throw buildValidationError(parsed.error.flatten());
+  }
+
+  return {
+    comment: parsed.data.comment?.trim() ?? null,
+  };
+}
+
 function parseCreateBody(body) {
   const parsed = createLeaveSchema.safeParse(body ?? {});
   if (!parsed.success) {
-    throw new AppError({
-      code: "VALID_001",
-      message: "参数校验失败",
-      statusCode: 400,
-      details: parsed.error.flatten(),
-    });
+    throw buildValidationError(parsed.error.flatten());
   }
 
-  const start = new Date(`${parsed.data.startDate}T00:00:00.000Z`);
-  const end = new Date(`${parsed.data.endDate}T00:00:00.000Z`);
-  if (Number.isNaN(start.getTime()) || Number.isNaN(end.getTime())) {
-    throw new AppError({
-      code: "VALID_001",
-      message: "参数校验失败",
-      statusCode: 400,
-      details: { date: "invalid" },
-    });
+  const startDate = new Date(`${parsed.data.startDate}T00:00:00.000Z`);
+  const endDate = new Date(`${parsed.data.endDate}T00:00:00.000Z`);
+
+  if (Number.isNaN(startDate.getTime()) || Number.isNaN(endDate.getTime())) {
+    throw buildValidationError({ date: "invalid" });
   }
-  if (end.getTime() < start.getTime()) {
-    throw new AppError({
-      code: "VALID_001",
-      message: "参数校验失败",
-      statusCode: 409,
-      details: { endDate: "before_start" },
-    });
+
+  const startSession = parsed.data.startSession ?? "am";
+  const endSession = parsed.data.endSession ?? "pm";
+  const requestedDays = calculateRequestedDays({
+    startDate,
+    endDate,
+    startSession,
+    endSession,
+  });
+
+  return {
+    leaveTypeId: parsed.data.leaveTypeId,
+    startDate,
+    endDate,
+    startSession,
+    endSession,
+    requestedDays,
+    reason: parsed.data.reason?.trim() ?? null,
+  };
+}
+
+async function collectCreatePayload(request) {
+  if (typeof request.isMultipart === "function" && request.isMultipart()) {
+    const fields = {};
+    let filePart = null;
+
+    try {
+      for await (const part of request.parts()) {
+        if (part.type === "file") {
+          if (filePart) {
+            throw buildValidationError({ file: "only_single_file_supported" });
+          }
+          filePart = part;
+        } else {
+          fields[part.fieldname] = part.value;
+        }
+      }
+    } catch (error) {
+      if (error?.code === "FST_REQ_FILE_TOO_LARGE") {
+        throw buildValidationError({ file: "file_too_large" });
+      }
+      throw error;
+    }
+
+    return {
+      body: parseCreateBody(fields),
+      filePart,
+    };
   }
 
   return {
-    startDate: start,
-    endDate: end,
-    reason: parsed.data.reason?.trim() ?? null,
+    body: parseCreateBody(request.body),
+    filePart: null,
+  };
+}
+
+function mapLeaveTypeSummary(leaveType) {
+  return {
+    id: leaveType.id,
+    code: leaveType.code,
+    name: leaveType.name,
+    requiresAttachment: Boolean(leaveType.requires_attachment),
+    attachmentMimeTypes: normalizeAttachmentMimeTypes(leaveType.attachment_mime_types),
+  };
+}
+
+function mapLeaveRequestResponse(leave) {
+  return {
+    id: leave.id,
+    ownerId: leave.owner_id,
+    departmentId: leave.department_id,
+    status: leave.status,
+    startDate: formatDateOnly(leave.start_date),
+    endDate: formatDateOnly(leave.end_date),
+    startSession: leave.start_session,
+    endSession: leave.end_session,
+    requestedDays: Number(leave.requested_days),
+    reason: leave.reason ?? null,
+    attachment:
+      leave.attachment_original_name || leave.attachment_mime_type
+        ? {
+            originalName: leave.attachment_original_name ?? null,
+            mimeType: leave.attachment_mime_type ?? null,
+          }
+        : null,
+    leaveType: leave.leave_type ? mapLeaveTypeSummary(leave.leave_type) : null,
+    owner: leave.owner
+      ? {
+          id: leave.owner.id,
+          employeeNo: leave.owner.employee_no,
+          name: leave.owner.name,
+        }
+      : null,
+    createdAt: leave.created_at?.toISOString?.() ?? null,
+    updatedAt: leave.updated_at?.toISOString?.() ?? null,
   };
 }
 
@@ -91,7 +260,158 @@ async function createSkipHistoryRecords(tx, workflowInstanceId, actorId, ownerId
   }
 }
 
+async function loadLeaveTypeOrThrow(prisma, leaveTypeId) {
+  const leaveType = await prisma.leaveType.findUnique({
+    where: { id: leaveTypeId },
+    select: LEAVE_TYPE_SELECT,
+  });
+
+  if (!leaveType || !leaveType.enabled || !leaveType.leave_policy || !leaveType.leave_policy.enabled) {
+    throw buildValidationError({ leaveTypeId: "missing_active_policy" }, 409);
+  }
+
+  return leaveType;
+}
+
+async function assertLeaveTypeAttachment(fastify, leaveType, filePart, employeeId) {
+  const requiresAttachment = Boolean(leaveType.requires_attachment);
+  const allowedMimeTypes = normalizeAttachmentMimeTypes(leaveType.attachment_mime_types);
+
+  if (!filePart) {
+    if (requiresAttachment) {
+      throw buildValidationError({ file: "required" }, 422);
+    }
+    return null;
+  }
+
+  const mimeAllowlist = new Set(allowedMimeTypes.length ? allowedMimeTypes : DEFAULT_ATTACHMENT_MIME_TYPES);
+  if (!mimeAllowlist.has(filePart.mimetype)) {
+    throw buildValidationError({ file: "unsupported_mime_type" });
+  }
+
+  return persistLeaveAttachment({
+    config: fastify.config,
+    employeeId,
+    filePart,
+  });
+}
+
 async function leaveRoutes(fastify) {
+  fastify.get(
+    "/leave-balances",
+    {
+      schema: { tags: ["Leave"], summary: "Get Leave Balances" },
+      preHandler: fastify.requireEntityPermission("leave", "view_own"),
+    },
+    async (request, reply) => {
+      const query = parseLeaveBalanceQuery(request.query);
+      const canViewAll =
+        fastify.hasPermission(request.employee, "leave.view_all") ||
+        fastify.hasPermission(request.employee, "leave.manage");
+      const targetEmployeeId = query.employeeId ?? request.employee.id;
+
+      if (targetEmployeeId !== request.employee.id && !canViewAll) {
+        throw new AppError({
+          code: "PERM_001",
+          message: "无权限",
+          statusCode: 403,
+        });
+      }
+
+      let items = [];
+      await fastify.prisma.$transaction(async (tx) => {
+        await lockEmployeeForLeave(tx, targetEmployeeId);
+        items = await loadLeaveBalanceItems(tx, {
+          employeeId: targetEmployeeId,
+          actorId: request.employee.id,
+        });
+      });
+
+      return sendData(reply, request, {
+        employeeId: targetEmployeeId,
+        items,
+      });
+    },
+  );
+
+  fastify.get(
+    "/leave-requests",
+    {
+      schema: { tags: ["Leave"], summary: "List Leave Requests" },
+      preHandler: fastify.requireEntityPermission("leave", "view_own"),
+    },
+    async (request, reply) => {
+      const query = parseLeaveListQuery(request.query);
+      const canViewAll = fastify.hasPermission(request.employee, "leave.view_all");
+      if (query.scope === "all" && !canViewAll) {
+        throw new AppError({
+          code: "PERM_001",
+          message: "无权限",
+          statusCode: 403,
+        });
+      }
+
+      const page = query.page;
+      const pageSize = query.pageSize;
+      const skip = (page - 1) * pageSize;
+      const where = {
+        ...(query.status ? { status: query.status } : {}),
+        ...(query.scope === "all" && canViewAll ? {} : { owner_id: request.employee.id }),
+      };
+
+      const [items, total] = await Promise.all([
+        fastify.prisma.leaveRequest.findMany({
+          where,
+          orderBy: { updated_at: "desc" },
+          skip,
+          take: pageSize,
+          select: {
+            id: true,
+            owner_id: true,
+            department_id: true,
+            leave_type_id: true,
+            start_date: true,
+            end_date: true,
+            start_session: true,
+            end_session: true,
+            requested_days: true,
+            reason: true,
+            attachment_original_name: true,
+            attachment_mime_type: true,
+            status: true,
+            created_at: true,
+            updated_at: true,
+            leave_type: {
+              select: {
+                id: true,
+                code: true,
+                name: true,
+                requires_attachment: true,
+                attachment_mime_types: true,
+              },
+            },
+            owner: {
+              select: {
+                id: true,
+                employee_no: true,
+                name: true,
+              },
+            },
+          },
+        }),
+        fastify.prisma.leaveRequest.count({ where }),
+      ]);
+
+      return sendData(reply, request, {
+        page,
+        pageSize,
+        total,
+        scope: query.scope === "all" && canViewAll ? "all" : "own",
+        items: items.map(mapLeaveRequestResponse),
+      });
+    },
+  );
+
   fastify.post(
     "/leave-requests",
     {
@@ -99,33 +419,69 @@ async function leaveRoutes(fastify) {
       preHandler: fastify.requireEntityPermission("leave", "create"),
     },
     async (request, reply) => {
-      const body = parseCreateBody(request.body);
+      const { body, filePart } = await collectCreatePayload(request);
+      const leaveType = await loadLeaveTypeOrThrow(fastify.prisma, body.leaveTypeId);
+      const attachment = await assertLeaveTypeAttachment(
+        fastify,
+        leaveType,
+        filePart,
+        request.employee.id,
+      );
 
       const leave = await fastify.prisma.leaveRequest.create({
         data: {
           owner_id: request.employee.id,
           department_id: request.employee.department_id,
+          leave_type_id: body.leaveTypeId,
           start_date: body.startDate,
           end_date: body.endDate,
+          start_session: body.startSession,
+          end_session: body.endSession,
+          requested_days: body.requestedDays,
           reason: body.reason,
+          attachment_storage_path: attachment?.storagePath ?? null,
+          attachment_original_name: attachment?.originalName ?? null,
+          attachment_mime_type: attachment?.mimeType ?? null,
           status: "draft",
           created_by: request.employee.id,
           updated_by: request.employee.id,
         },
         select: {
           id: true,
-          status: true,
+          owner_id: true,
+          department_id: true,
+          leave_type_id: true,
           start_date: true,
           end_date: true,
+          start_session: true,
+          end_session: true,
+          requested_days: true,
+          reason: true,
+          attachment_original_name: true,
+          attachment_mime_type: true,
+          status: true,
+          created_at: true,
+          updated_at: true,
+          leave_type: {
+            select: {
+              id: true,
+              code: true,
+              name: true,
+              requires_attachment: true,
+              attachment_mime_types: true,
+            },
+          },
+          owner: {
+            select: {
+              id: true,
+              employee_no: true,
+              name: true,
+            },
+          },
         },
       });
 
-      return sendData(reply, request, {
-        id: leave.id,
-        status: leave.status,
-        startDate: leave.start_date.toISOString().slice(0, 10),
-        endDate: leave.end_date.toISOString().slice(0, 10),
-      });
+      return sendData(reply, request, mapLeaveRequestResponse(leave));
     },
   );
 
@@ -144,12 +500,34 @@ async function leaveRoutes(fastify) {
           id: true,
           owner_id: true,
           department_id: true,
+          leave_type_id: true,
           start_date: true,
           end_date: true,
+          start_session: true,
+          end_session: true,
+          requested_days: true,
           reason: true,
+          attachment_original_name: true,
+          attachment_mime_type: true,
           status: true,
           created_at: true,
           updated_at: true,
+          leave_type: {
+            select: {
+              id: true,
+              code: true,
+              name: true,
+              requires_attachment: true,
+              attachment_mime_types: true,
+            },
+          },
+          owner: {
+            select: {
+              id: true,
+              employee_no: true,
+              name: true,
+            },
+          },
         },
       });
 
@@ -170,17 +548,7 @@ async function leaveRoutes(fastify) {
         });
       }
 
-      return sendData(reply, request, {
-        id: leave.id,
-        ownerId: leave.owner_id,
-        departmentId: leave.department_id,
-        status: leave.status,
-        startDate: leave.start_date.toISOString().slice(0, 10),
-        endDate: leave.end_date.toISOString().slice(0, 10),
-        reason: leave.reason ?? null,
-        createdAt: leave.created_at.toISOString(),
-        updatedAt: leave.updated_at.toISOString(),
-      });
+      return sendData(reply, request, mapLeaveRequestResponse(leave));
     },
   );
 
@@ -196,7 +564,18 @@ async function leaveRoutes(fastify) {
 
       await fastify.prisma.$transaction(async (tx) => {
         const leaveRows = await tx.$queryRaw`
-          SELECT id, owner_id, department_id, status
+          SELECT
+            id,
+            owner_id,
+            department_id,
+            leave_type_id,
+            start_date,
+            end_date,
+            start_session::text AS start_session,
+            end_session::text AS end_session,
+            requested_days::text AS requested_days,
+            attachment_storage_path,
+            status
           FROM "leave_requests"
           WHERE id = ${leaveId}::uuid
           FOR UPDATE
@@ -219,12 +598,7 @@ async function leaveRoutes(fastify) {
         }
 
         if (!["draft", "rejected"].includes(leave.status)) {
-          throw new AppError({
-            code: "VALID_001",
-            message: "参数校验失败",
-            statusCode: 409,
-            details: { status: "invalid_submit_status" },
-          });
+          throw buildValidationError({ status: "invalid_submit_status" }, 409);
         }
 
         const activeInstance = await tx.workflowInstance.findFirst({
@@ -236,12 +610,66 @@ async function leaveRoutes(fastify) {
           select: { id: true },
         });
         if (activeInstance) {
-          throw new AppError({
-            code: "VALID_001",
-            message: "参数校验失败",
-            statusCode: 409,
-            details: { submit: "already_in_review" },
-          });
+          throw buildValidationError({ submit: "already_in_review" }, 409);
+        }
+
+        const leaveType = await loadLeaveTypeOrThrow(tx, leave.leave_type_id);
+        if (leaveType.requires_attachment && !leave.attachment_storage_path) {
+          throw buildValidationError({ file: "required" }, 422);
+        }
+
+        const overlappingRequests = await tx.leaveRequest.findMany({
+          where: {
+            owner_id: leave.owner_id,
+            id: { not: leaveId },
+            status: { in: ["reviewing", "approved"] },
+            start_date: { lte: leave.end_date },
+            end_date: { gte: leave.start_date },
+          },
+          select: {
+            id: true,
+            start_date: true,
+            end_date: true,
+            start_session: true,
+            end_session: true,
+          },
+        });
+
+        const conflicting = overlappingRequests.find((item) =>
+          leaveRangesOverlap(
+            {
+              startDate: leave.start_date,
+              endDate: leave.end_date,
+              startSession: leave.start_session,
+              endSession: leave.end_session,
+            },
+            {
+              startDate: item.start_date,
+              endDate: item.end_date,
+              startSession: item.start_session,
+              endSession: item.end_session,
+            },
+          ),
+        );
+        if (conflicting) {
+          throw buildValidationError(
+            { leave: "conflict_range", conflictLeaveRequestId: conflicting.id },
+            422,
+          );
+        }
+
+        await lockEmployeeForLeave(tx, leave.owner_id);
+        const balanceSnapshot = await loadLeaveBalanceSnapshot(tx, {
+          employeeId: leave.owner_id,
+          leaveType,
+          actorId: request.employee.id,
+          referenceDate: leave.start_date,
+        });
+
+        if (
+          toHalfDayUnits(balanceSnapshot.summary.available) < toHalfDayUnits(leave.requested_days)
+        ) {
+          throw buildValidationError({ leave: "insufficient_balance" }, 422);
         }
 
         const workflowDefinition = await tx.workflowDefinition.findFirst({
@@ -250,12 +678,7 @@ async function leaveRoutes(fastify) {
           select: { id: true },
         });
         if (!workflowDefinition) {
-          throw new AppError({
-            code: "VALID_001",
-            message: "参数校验失败",
-            statusCode: 400,
-            details: { workflow: "missing_definition" },
-          });
+          throw buildValidationError({ workflow: "missing_definition" });
         }
 
         const { actionable, skipped } = await resolveActionableStep({
@@ -266,12 +689,7 @@ async function leaveRoutes(fastify) {
           logger: fastify.log,
         });
         if (!actionable) {
-          throw new AppError({
-            code: "VALID_001",
-            message: "参数校验失败",
-            statusCode: 409,
-            details: { workflow: "no_actionable_approver" },
-          });
+          throw buildValidationError({ workflow: "no_actionable_approver" }, 409);
         }
 
         await tx.leaveRequest.update({
@@ -338,6 +756,23 @@ async function leaveRoutes(fastify) {
           },
         });
 
+        await createLeaveLedgerEntry(tx, {
+          employeeId: leave.owner_id,
+          leaveTypeId: leave.leave_type_id,
+          leavePolicyId: balanceSnapshot.policy.id,
+          leaveRequestId: leaveId,
+          entryType: "reserve",
+          days: Number(leave.requested_days),
+          periodStart: balanceSnapshot.periodStart,
+          periodEnd: balanceSnapshot.periodEnd,
+          note: "submit_reserve_leave",
+          payload: {
+            source: "leave_submit",
+            workflow_instance_id: workflowInstance.id,
+          },
+          createdBy: request.employee.id,
+        });
+
         submitResult = {
           leaveRequestId: leaveId,
           workflowInstanceId: workflowInstance.id,
@@ -349,7 +784,144 @@ async function leaveRoutes(fastify) {
       return sendData(reply, request, submitResult);
     },
   );
+
+  fastify.post(
+    "/leave-requests/:id/withdraw",
+    {
+      schema: { tags: ["Leave"], summary: "Withdraw Leave Request" },
+      preHandler: fastify.requireEntityPermission("leave", "submit"),
+    },
+    async (request, reply) => {
+      const leaveId = parseLeaveId(request.params?.id);
+      const { comment } = parseWithdrawBody(request.body);
+      let response = null;
+
+      await fastify.prisma.$transaction(async (tx) => {
+        const leaveRows = await tx.$queryRaw`
+          SELECT
+            id,
+            owner_id,
+            leave_type_id,
+            requested_days::text AS requested_days,
+            status
+          FROM "leave_requests"
+          WHERE id = ${leaveId}::uuid
+          FOR UPDATE
+        `;
+
+        if (!Array.isArray(leaveRows) || leaveRows.length === 0) {
+          throw new AppError({
+            code: "SYS_404",
+            message: "Not Found",
+            statusCode: 404,
+          });
+        }
+
+        const leave = leaveRows[0];
+        if (leave.owner_id !== request.employee.id) {
+          throw new AppError({
+            code: "PERM_001",
+            message: "无权限",
+            statusCode: 403,
+          });
+        }
+
+        if (leave.status !== "reviewing") {
+          throw buildValidationError({ status: "invalid_withdraw_status" }, 409);
+        }
+
+        const activeInstance = await tx.workflowInstance.findFirst({
+          where: {
+            entity_type: "leave",
+            entity_id: leaveId,
+            current_status: "pending",
+          },
+          orderBy: { created_at: "desc" },
+          select: { id: true },
+        });
+
+        if (!activeInstance) {
+          throw buildValidationError({ withdraw: "no_pending_instance" }, 409);
+        }
+
+        const processedTaskCount = await tx.workflowTask.count({
+          where: {
+            instance_id: activeInstance.id,
+            status: { in: ["completed", "rejected"] },
+          },
+        });
+        if (processedTaskCount > 0) {
+          throw buildValidationError({ withdraw: "already_processed_by_approver" }, 409);
+        }
+
+        const ledger = await loadLeaveLedgerSummaryForRequest(tx, leaveId);
+        const reserveAnchor = ledger.entries.find((item) => item.entry_type === "reserve") ?? null;
+        const now = new Date();
+
+        await tx.workflowTask.updateMany({
+          where: {
+            instance_id: activeInstance.id,
+            status: "pending",
+          },
+          data: {
+            status: "cancelled",
+            completed_at: now,
+            completed_by: request.employee.id,
+          },
+        });
+
+        await tx.workflowInstance.update({
+          where: { id: activeInstance.id },
+          data: {
+            current_status: "cancelled",
+            completed_at: now,
+            updated_by: request.employee.id,
+          },
+        });
+
+        await tx.leaveRequest.update({
+          where: { id: leaveId },
+          data: {
+            status: "draft",
+            updated_by: request.employee.id,
+          },
+        });
+
+        await releaseReservedLeave(tx, {
+          leaveRequestId: leaveId,
+          employeeId: leave.owner_id,
+          leaveTypeId: leave.leave_type_id,
+          leavePolicyId: reserveAnchor?.leave_policy_id ?? null,
+          periodStart: reserveAnchor?.period_start ?? null,
+          periodEnd: reserveAnchor?.period_end ?? null,
+          note: "withdraw_release_leave",
+          payload: { source: "leave_withdraw" },
+          createdBy: request.employee.id,
+        });
+
+        await tx.workflowHistory.create({
+          data: {
+            instance_id: activeInstance.id,
+            actor_id: request.employee.id,
+            action: "withdraw",
+            comment: comment ?? null,
+            payload: {
+              leave_request_id: leaveId,
+            },
+          },
+        });
+
+        response = {
+          leaveRequestId: leaveId,
+          outcome: "withdrawn",
+          workflowInstanceId: activeInstance.id,
+          leaveStatus: "draft",
+        };
+      });
+
+      return sendData(reply, request, response);
+    },
+  );
 }
 
 module.exports = leaveRoutes;
-

server/src/routes/workflow.js

@@ -3,6 +3,7 @@ const { AppError } = require("../utils/AppError");
 const { sendData } = require("../utils/reply");
 const { resolvePermissionsForRoles, hasPermission, ROLE_PERMISSIONS, resolveEntityPermission } = require("../constants/permissions");
 const { getWorkflowStepsSnapshot, resolveActionableStep, toMoneyString } = require("../utils/workflow");
+const { consumeReservedLeave, releaseReservedLeave, formatDateOnly } = require("../services/leave");
 const {
   createNotifications,
   resolveRecipientsForAssignee,
@@ -538,6 +539,34 @@ async function workflowRoutes(fastify) {
                   },
                 },
               },
+              leave_request: {
+                select: {
+                  id: true,
+                  status: true,
+                  start_date: true,
+                  end_date: true,
+                  start_session: true,
+                  end_session: true,
+                  requested_days: true,
+                  reason: true,
+                  attachment_original_name: true,
+                  attachment_mime_type: true,
+                  leave_type: {
+                    select: {
+                      id: true,
+                      code: true,
+                      name: true,
+                    },
+                  },
+                  owner: {
+                    select: {
+                      id: true,
+                      employee_no: true,
+                      name: true,
+                    },
+                  },
+                },
+              },
             },
           },
         },
@@ -616,6 +645,7 @@ async function workflowRoutes(fastify) {
         workflowInstance: task.workflow_instance
           ? {
             id: task.workflow_instance.id,
+            entityType: task.workflow_instance.entity_type,
             currentStatus: task.workflow_instance.current_status,
             currentStepId: task.workflow_instance.current_step_id,
             startedAt: isoOrNull(task.workflow_instance.started_at),
@@ -649,6 +679,40 @@ async function workflowRoutes(fastify) {
               : null,
           }
           : null,
+        leaveRequest: task.workflow_instance?.leave_request
+          ? {
+            id: task.workflow_instance.leave_request.id,
+            status: task.workflow_instance.leave_request.status,
+            startDate: formatDateOnly(task.workflow_instance.leave_request.start_date),
+            endDate: formatDateOnly(task.workflow_instance.leave_request.end_date),
+            startSession: task.workflow_instance.leave_request.start_session,
+            endSession: task.workflow_instance.leave_request.end_session,
+            requestedDays: Number(task.workflow_instance.leave_request.requested_days),
+            reason: task.workflow_instance.leave_request.reason ?? null,
+            attachment:
+              task.workflow_instance.leave_request.attachment_original_name ||
+              task.workflow_instance.leave_request.attachment_mime_type
+                ? {
+                    originalName: task.workflow_instance.leave_request.attachment_original_name ?? null,
+                    mimeType: task.workflow_instance.leave_request.attachment_mime_type ?? null,
+                  }
+                : null,
+            leaveType: task.workflow_instance.leave_request.leave_type
+              ? {
+                  id: task.workflow_instance.leave_request.leave_type.id,
+                  code: task.workflow_instance.leave_request.leave_type.code,
+                  name: task.workflow_instance.leave_request.leave_type.name,
+                }
+              : null,
+            owner: task.workflow_instance.leave_request.owner
+              ? {
+                  id: task.workflow_instance.leave_request.owner.id,
+                  employeeNo: task.workflow_instance.leave_request.owner.employee_no,
+                  name: task.workflow_instance.leave_request.owner.name,
+                }
+              : null,
+          }
+          : null,
         allowedActions: listAllowedActionsForTask(request, task, actionable),
         history: historyItems.map((item) => ({
           id: item.id,
@@ -885,6 +949,28 @@ async function workflowRoutes(fastify) {
             },
           });
         } else if (workflowInstance.entity_type === "leave") {
+          const leaveRequest = await tx.leaveRequest.findUnique({
+            where: { id: workflowInstance.entity_id },
+            select: {
+              id: true,
+              owner_id: true,
+              leave_type_id: true,
+              requested_days: true,
+            },
+          });
+          const reserveAnchor = await tx.leaveLedger.findFirst({
+            where: {
+              leave_request_id: workflowInstance.entity_id,
+              entry_type: "reserve",
+            },
+            orderBy: { created_at: "desc" },
+            select: {
+              leave_policy_id: true,
+              period_start: true,
+              period_end: true,
+            },
+          });
+
           await tx.leaveRequest.update({
             where: { id: workflowInstance.entity_id },
             data: {
@@ -892,6 +978,19 @@ async function workflowRoutes(fastify) {
               updated_by: request.employee.id,
             },
           });
+
+          if (leaveRequest) {
+            await consumeReservedLeave(tx, {
+              leaveRequestId: workflowInstance.entity_id,
+              employeeId: leaveRequest.owner_id,
+              leaveTypeId: leaveRequest.leave_type_id,
+              leavePolicyId: reserveAnchor?.leave_policy_id ?? null,
+              periodStart: reserveAnchor?.period_start ?? null,
+              periodEnd: reserveAnchor?.period_end ?? null,
+              requestedDays: leaveRequest.requested_days,
+              createdBy: request.employee.id,
+            });
+          }
         }
 
         await tx.workflowHistory.create({
@@ -1016,6 +1115,27 @@ async function workflowRoutes(fastify) {
             },
           });
         } else if (workflowInstance.entity_type === "leave") {
+          const leaveRequest = await tx.leaveRequest.findUnique({
+            where: { id: workflowInstance.entity_id },
+            select: {
+              id: true,
+              owner_id: true,
+              leave_type_id: true,
+            },
+          });
+          const reserveAnchor = await tx.leaveLedger.findFirst({
+            where: {
+              leave_request_id: workflowInstance.entity_id,
+              entry_type: "reserve",
+            },
+            orderBy: { created_at: "desc" },
+            select: {
+              leave_policy_id: true,
+              period_start: true,
+              period_end: true,
+            },
+          });
+
           await tx.leaveRequest.update({
             where: { id: workflowInstance.entity_id },
             data: {
@@ -1023,6 +1143,20 @@ async function workflowRoutes(fastify) {
               updated_by: request.employee.id,
             },
           });
+
+          if (leaveRequest) {
+            await releaseReservedLeave(tx, {
+              leaveRequestId: workflowInstance.entity_id,
+              employeeId: leaveRequest.owner_id,
+              leaveTypeId: leaveRequest.leave_type_id,
+              leavePolicyId: reserveAnchor?.leave_policy_id ?? null,
+              periodStart: reserveAnchor?.period_start ?? null,
+              periodEnd: reserveAnchor?.period_end ?? null,
+              note: "rejected_release_leave",
+              payload: { source: "workflow_reject" },
+              createdBy: request.employee.id,
+            });
+          }
         }
 
         await tx.workflowHistory.create({
@@ -1146,6 +1280,27 @@ async function workflowRoutes(fastify) {
             },
           });
         } else if (workflowInstance.entity_type === "leave") {
+          const leaveRequest = await tx.leaveRequest.findUnique({
+            where: { id: workflowInstance.entity_id },
+            select: {
+              id: true,
+              owner_id: true,
+              leave_type_id: true,
+            },
+          });
+          const reserveAnchor = await tx.leaveLedger.findFirst({
+            where: {
+              leave_request_id: workflowInstance.entity_id,
+              entry_type: "reserve",
+            },
+            orderBy: { created_at: "desc" },
+            select: {
+              leave_policy_id: true,
+              period_start: true,
+              period_end: true,
+            },
+          });
+
           await tx.leaveRequest.update({
             where: { id: workflowInstance.entity_id },
             data: {
@@ -1153,6 +1308,20 @@ async function workflowRoutes(fastify) {
               updated_by: request.employee.id,
             },
           });
+
+          if (leaveRequest) {
+            await releaseReservedLeave(tx, {
+              leaveRequestId: workflowInstance.entity_id,
+              employeeId: leaveRequest.owner_id,
+              leaveTypeId: leaveRequest.leave_type_id,
+              leavePolicyId: reserveAnchor?.leave_policy_id ?? null,
+              periodStart: reserveAnchor?.period_start ?? null,
+              periodEnd: reserveAnchor?.period_end ?? null,
+              note: "returned_release_leave",
+              payload: { source: "workflow_return" },
+              createdBy: request.employee.id,
+            });
+          }
         }
 
         await tx.workflowHistory.create({

server/src/scripts/seed-config.js

@@ -105,6 +105,43 @@ const DEFAULT_LEAVE_WORKFLOW_DEFINITION = {
   ],
 };
 
+
+const DEFAULT_LEAVE_TYPES = [
+  {
+    code: "annual_leave",
+    name: "年假",
+    description: "按自然日+半天粒度扣减。",
+    enabled: true,
+    requires_attachment: false,
+    attachment_mime_types: null,
+    sort_order: 10,
+    annual_quota_days: "15.0",
+    policy_description: "默认年度授予 15 天。",
+  },
+  {
+    code: "sick_leave",
+    name: "病假",
+    description: "病假需上传诊断或病历附件。",
+    enabled: true,
+    requires_attachment: true,
+    attachment_mime_types: ["application/pdf", "image/jpeg", "image/png"],
+    sort_order: 20,
+    annual_quota_days: "10.0",
+    policy_description: "默认年度授予 10 天。",
+  },
+  {
+    code: "personal_leave",
+    name: "事假",
+    description: "事假默认走经理审批。",
+    enabled: true,
+    requires_attachment: false,
+    attachment_mime_types: null,
+    sort_order: 30,
+    annual_quota_days: "5.0",
+    policy_description: "默认年度授予 5 天。",
+  },
+];
+
 async function seedExpenseTypes(prisma) {
   const now = new Date();
   const allTypes = [
@@ -179,6 +216,61 @@ async function seedDocumentSequence(prisma) {
   });
 }
 
+async function seedLeaveTypes(prisma) {
+  const now = new Date();
+
+  for (const item of DEFAULT_LEAVE_TYPES) {
+    const leaveType = await prisma.leaveType.upsert({
+      where: { code: item.code },
+      update: {
+        name: item.name,
+        description: item.description,
+        enabled: item.enabled,
+        requires_attachment: item.requires_attachment,
+        attachment_mime_types: item.attachment_mime_types,
+        sort_order: item.sort_order,
+        updated_at: now,
+        updated_by: null,
+      },
+      create: {
+        code: item.code,
+        name: item.name,
+        description: item.description,
+        enabled: item.enabled,
+        requires_attachment: item.requires_attachment,
+        attachment_mime_types: item.attachment_mime_types,
+        sort_order: item.sort_order,
+        created_at: now,
+        created_by: null,
+        updated_at: now,
+        updated_by: null,
+      },
+      select: { id: true },
+    });
+
+    await prisma.leavePolicy.upsert({
+      where: { leave_type_id: leaveType.id },
+      update: {
+        annual_quota_days: item.annual_quota_days,
+        enabled: item.enabled,
+        description: item.policy_description,
+        updated_at: now,
+        updated_by: null,
+      },
+      create: {
+        leave_type_id: leaveType.id,
+        annual_quota_days: item.annual_quota_days,
+        enabled: item.enabled,
+        description: item.policy_description,
+        created_at: now,
+        created_by: null,
+        updated_at: now,
+        updated_by: null,
+      },
+    });
+  }
+}
+
 async function seedWorkflowDefinition(prisma) {
   await prisma.workflowDefinition.updateMany({
     where: {
@@ -254,6 +346,7 @@ async function main() {
     await seedApprovalRules(prisma);
     await seedDocumentSequence(prisma);
     await seedWorkflowDefinition(prisma);
+    await seedLeaveTypes(prisma);
 
     // eslint-disable-next-line no-console
     console.log("Seeded config data:");
@@ -267,6 +360,8 @@ async function main() {
     console.log("- workflow definition: reimbursement v1 (1-step role=ceo)");
     // eslint-disable-next-line no-console
     console.log("- workflow definition: leave v1 (1-step department_manager)");
+    // eslint-disable-next-line no-console
+    console.log(`- leave types: ${DEFAULT_LEAVE_TYPES.length} seeded with default policies`);
   } finally {
     await prisma.$disconnect();
     await pool.end();

server/src/services/leave.js

@@ -0,0 +1,496 @@
+const crypto = require("node:crypto");
+const path = require("node:path");
+
+const { AppError } = require("../utils/AppError");
+const { compactDateString } = require("../utils/date");
+const { writeBuffer } = require("./storage");
+
+const DEFAULT_ATTACHMENT_MIME_TYPES = [
+  "application/pdf",
+  "image/jpeg",
+  "image/png",
+  "image/webp",
+];
+
+const SESSION_ORDER = {
+  am: 0,
+  pm: 1,
+};
+
+function buildLeaveValidationError(details, statusCode = 422) {
+  return new AppError({
+    code: "VALID_001",
+    message: "参数校验失败",
+    statusCode,
+    details,
+  });
+}
+
+function normalizeDateOnly(value) {
+  if (value instanceof Date) {
+    return new Date(`${value.toISOString().slice(0, 10)}T00:00:00.000Z`);
+  }
+
+  if (typeof value === "string" && /^\d{4}-\d{2}-\d{2}$/.test(value)) {
+    return new Date(`${value}T00:00:00.000Z`);
+  }
+
+  throw buildLeaveValidationError({ date: "invalid" }, 400);
+}
+
+function formatDateOnly(value) {
+  if (!value) {
+    return null;
+  }
+
+  return normalizeDateOnly(value).toISOString().slice(0, 10);
+}
+
+function toHalfDayUnits(value) {
+  const numeric = Number(value ?? 0);
+  if (!Number.isFinite(numeric)) {
+    return 0;
+  }
+
+  return Math.round(numeric * 2);
+}
+
+function fromHalfDayUnits(units) {
+  return Number((units / 2).toFixed(1));
+}
+
+function toHalfDaySlot(dateValue, session) {
+  const date = normalizeDateOnly(dateValue);
+  const sessionIndex = SESSION_ORDER[session];
+
+  if (sessionIndex == null) {
+    throw buildLeaveValidationError({ session: "invalid" }, 400);
+  }
+
+  const dayIndex = Math.floor(date.getTime() / 86400000);
+  return dayIndex * 2 + sessionIndex;
+}
+
+function calculateRequestedDays({ startDate, endDate, startSession, endSession }) {
+  const startSlot = toHalfDaySlot(startDate, startSession);
+  const endSlot = toHalfDaySlot(endDate, endSession);
+
+  if (endSlot < startSlot) {
+    throw buildLeaveValidationError({ leave: "invalid_range" });
+  }
+
+  return fromHalfDayUnits(endSlot - startSlot + 1);
+}
+
+function leaveRangesOverlap(left, right) {
+  const leftStart = toHalfDaySlot(left.startDate, left.startSession);
+  const leftEnd = toHalfDaySlot(left.endDate, left.endSession);
+  const rightStart = toHalfDaySlot(right.startDate, right.startSession);
+  const rightEnd = toHalfDaySlot(right.endDate, right.endSession);
+
+  return leftStart <= rightEnd && rightStart <= leftEnd;
+}
+
+function normalizeAttachmentMimeTypes(value) {
+  if (!Array.isArray(value)) {
+    return [...DEFAULT_ATTACHMENT_MIME_TYPES];
+  }
+
+  const items = value
+    .map((item) => (typeof item === "string" ? item.trim() : ""))
+    .filter(Boolean);
+
+  return items.length ? items : [...DEFAULT_ATTACHMENT_MIME_TYPES];
+}
+
+function summarizeLeaveLedgerEntries(entries) {
+  const totals = {
+    grant: 0,
+    reserve: 0,
+    consume: 0,
+    release: 0,
+    adjust: 0,
+  };
+
+  for (const entry of entries ?? []) {
+    if (!entry?.entry_type || !(entry.entry_type in totals)) {
+      continue;
+    }
+
+    totals[entry.entry_type] += toHalfDayUnits(entry.days);
+  }
+
+  const reservedUnits = Math.max(0, totals.reserve - totals.release);
+  const availableUnits =
+    totals.grant + totals.adjust - totals.reserve + totals.release - totals.consume;
+
+  return {
+    granted: fromHalfDayUnits(totals.grant),
+    adjusted: fromHalfDayUnits(totals.adjust),
+    reserved: fromHalfDayUnits(reservedUnits),
+    used: fromHalfDayUnits(totals.consume),
+    released: fromHalfDayUnits(totals.release),
+    available: fromHalfDayUnits(availableUnits),
+  };
+}
+
+function currentLeavePeriod(referenceDate = new Date()) {
+  const date = normalizeDateOnly(referenceDate);
+  const year = date.getUTCFullYear();
+  return {
+    periodStart: new Date(`${year}-01-01T00:00:00.000Z`),
+    periodEnd: new Date(`${year}-12-31T00:00:00.000Z`),
+  };
+}
+
+function mapLeaveTypeResponse(leaveType) {
+  const policy = leaveType.leave_policy ?? null;
+
+  return {
+    id: leaveType.id,
+    code: leaveType.code,
+    name: leaveType.name,
+    description: leaveType.description ?? null,
+    enabled: Boolean(leaveType.enabled),
+    requiresAttachment: Boolean(leaveType.requires_attachment),
+    attachmentMimeTypes: normalizeAttachmentMimeTypes(leaveType.attachment_mime_types),
+    sortOrder: leaveType.sort_order,
+    policy: policy
+      ? {
+          id: policy.id,
+          annualQuotaDays: Number(policy.annual_quota_days),
+          enabled: Boolean(policy.enabled),
+          description: policy.description ?? null,
+        }
+      : null,
+    createdAt: leaveType.created_at?.toISOString?.() ?? null,
+    updatedAt: leaveType.updated_at?.toISOString?.() ?? null,
+  };
+}
+
+async function lockEmployeeForLeave(tx, employeeId) {
+  await tx.$queryRaw`
+    SELECT id
+    FROM "employees"
+    WHERE id = ${employeeId}::uuid
+    FOR UPDATE
+  `;
+}
+
+async function ensureAnnualLeaveGrant(tx, { employeeId, leaveType, actorId, referenceDate = new Date() }) {
+  const policy = leaveType?.leave_policy;
+  if (!leaveType || !leaveType.enabled || !policy || !policy.enabled) {
+    throw buildLeaveValidationError({ leaveTypeId: "missing_active_policy" }, 409);
+  }
+
+  const { periodStart, periodEnd } = currentLeavePeriod(referenceDate);
+
+  const existingGrant = await tx.leaveLedger.findFirst({
+    where: {
+      employee_id: employeeId,
+      leave_type_id: leaveType.id,
+      entry_type: "grant",
+      period_start: periodStart,
+      period_end: periodEnd,
+    },
+    select: { id: true },
+  });
+
+  if (!existingGrant) {
+    await tx.leaveLedger.create({
+      data: {
+        employee_id: employeeId,
+        leave_type_id: leaveType.id,
+        leave_policy_id: policy.id,
+        entry_type: "grant",
+        days: policy.annual_quota_days,
+        period_start: periodStart,
+        period_end: periodEnd,
+        note: `auto_grant_${periodStart.getUTCFullYear()}`,
+        payload: {
+          source: "leave_policy",
+          annual_quota_days: Number(policy.annual_quota_days),
+        },
+        created_by: actorId ?? null,
+      },
+    });
+  }
+
+  return { policy, periodStart, periodEnd };
+}
+
+async function loadLeaveBalanceSnapshot(tx, { employeeId, leaveType, actorId, referenceDate = new Date() }) {
+  const { policy, periodStart, periodEnd } = await ensureAnnualLeaveGrant(tx, {
+    employeeId,
+    leaveType,
+    actorId,
+    referenceDate,
+  });
+
+  const entries = await tx.leaveLedger.findMany({
+    where: {
+      employee_id: employeeId,
+      leave_type_id: leaveType.id,
+      period_start: periodStart,
+      period_end: periodEnd,
+    },
+    orderBy: { created_at: "asc" },
+    select: {
+      id: true,
+      entry_type: true,
+      days: true,
+      leave_request_id: true,
+      created_at: true,
+    },
+  });
+
+  return {
+    policy,
+    periodStart,
+    periodEnd,
+    entries,
+    summary: summarizeLeaveLedgerEntries(entries),
+  };
+}
+
+async function loadLeaveBalanceItems(tx, { employeeId, actorId, referenceDate = new Date(), includeDisabled = false }) {
+  const leaveTypes = await tx.leaveType.findMany({
+    where: includeDisabled ? undefined : { enabled: true },
+    orderBy: [{ sort_order: "asc" }, { code: "asc" }],
+    select: {
+      id: true,
+      code: true,
+      name: true,
+      description: true,
+      enabled: true,
+      requires_attachment: true,
+      attachment_mime_types: true,
+      sort_order: true,
+      created_at: true,
+      updated_at: true,
+      leave_policy: {
+        select: {
+          id: true,
+          annual_quota_days: true,
+          enabled: true,
+          description: true,
+        },
+      },
+    },
+  });
+
+  const items = [];
+  for (const leaveType of leaveTypes) {
+    if (!leaveType.leave_policy || !leaveType.leave_policy.enabled) {
+      continue;
+    }
+
+    const snapshot = await loadLeaveBalanceSnapshot(tx, {
+      employeeId,
+      leaveType,
+      actorId,
+      referenceDate,
+    });
+
+    items.push({
+      leaveType: mapLeaveTypeResponse(leaveType),
+      policy: {
+        id: snapshot.policy.id,
+        annualQuotaDays: Number(snapshot.policy.annual_quota_days),
+        enabled: Boolean(snapshot.policy.enabled),
+        description: snapshot.policy.description ?? null,
+      },
+      granted: snapshot.summary.granted,
+      adjusted: snapshot.summary.adjusted,
+      reserved: snapshot.summary.reserved,
+      used: snapshot.summary.used,
+      available: snapshot.summary.available,
+      periodStart: formatDateOnly(snapshot.periodStart),
+      periodEnd: formatDateOnly(snapshot.periodEnd),
+    });
+  }
+
+  return items;
+}
+
+async function createLeaveLedgerEntry(tx, data) {
+  return tx.leaveLedger.create({
+    data: {
+      employee_id: data.employeeId,
+      leave_type_id: data.leaveTypeId,
+      leave_policy_id: data.leavePolicyId ?? null,
+      leave_request_id: data.leaveRequestId ?? null,
+      entry_type: data.entryType,
+      days: data.days,
+      period_start: data.periodStart ?? null,
+      period_end: data.periodEnd ?? null,
+      note: data.note ?? null,
+      payload: data.payload ?? null,
+      created_by: data.createdBy ?? null,
+    },
+  });
+}
+
+async function loadLeaveLedgerSummaryForRequest(tx, leaveRequestId) {
+  const entries = await tx.leaveLedger.findMany({
+    where: { leave_request_id: leaveRequestId },
+    orderBy: { created_at: "asc" },
+    select: {
+      id: true,
+      entry_type: true,
+      days: true,
+      period_start: true,
+      period_end: true,
+      leave_policy_id: true,
+    },
+  });
+
+  return {
+    entries,
+    summary: summarizeLeaveLedgerEntries(entries),
+  };
+}
+
+async function releaseReservedLeave(tx, {
+  leaveRequestId,
+  employeeId,
+  leaveTypeId,
+  leavePolicyId,
+  periodStart,
+  periodEnd,
+  note,
+  payload,
+  createdBy,
+}) {
+  const ledger = await loadLeaveLedgerSummaryForRequest(tx, leaveRequestId);
+  const reservedUnits = toHalfDayUnits(ledger.summary.reserved);
+
+  if (reservedUnits <= 0) {
+    return null;
+  }
+
+  return createLeaveLedgerEntry(tx, {
+    employeeId,
+    leaveTypeId,
+    leavePolicyId,
+    leaveRequestId,
+    entryType: "release",
+    days: fromHalfDayUnits(reservedUnits),
+    periodStart,
+    periodEnd,
+    note,
+    payload,
+    createdBy,
+  });
+}
+
+async function consumeReservedLeave(tx, {
+  leaveRequestId,
+  employeeId,
+  leaveTypeId,
+  leavePolicyId,
+  periodStart,
+  periodEnd,
+  requestedDays,
+  createdBy,
+}) {
+  const ledger = await loadLeaveLedgerSummaryForRequest(tx, leaveRequestId);
+  const reservedUnits = toHalfDayUnits(ledger.summary.reserved);
+  const requestedUnits = toHalfDayUnits(requestedDays);
+
+  if (reservedUnits < requestedUnits || requestedUnits <= 0) {
+    throw buildLeaveValidationError({ leave: "missing_reserve_ledger" }, 409);
+  }
+
+  await createLeaveLedgerEntry(tx, {
+    employeeId,
+    leaveTypeId,
+    leavePolicyId,
+    leaveRequestId,
+    entryType: "release",
+    days: fromHalfDayUnits(requestedUnits),
+    periodStart,
+    periodEnd,
+    note: "approved_release_reserve",
+    payload: { source: "workflow_approve" },
+    createdBy,
+  });
+
+  await createLeaveLedgerEntry(tx, {
+    employeeId,
+    leaveTypeId,
+    leavePolicyId,
+    leaveRequestId,
+    entryType: "consume",
+    days: fromHalfDayUnits(requestedUnits),
+    periodStart,
+    periodEnd,
+    note: "approved_consume_leave",
+    payload: { source: "workflow_approve" },
+    createdBy,
+  });
+}
+
+async function persistLeaveAttachment({ config, employeeId, filePart }) {
+  const chunks = [];
+  let fileSize = 0;
+
+  for await (const chunk of filePart.file) {
+    fileSize += chunk.length;
+    if (fileSize > config.maxUploadSizeBytes) {
+      throw buildLeaveValidationError({ file: "file_too_large" }, 400);
+    }
+    chunks.push(chunk);
+  }
+
+  if (fileSize <= 0) {
+    throw buildLeaveValidationError({ file: "empty" }, 400);
+  }
+
+  const buffer = Buffer.concat(chunks);
+  const safeName = (filePart.filename || "attachment")
+    .replace(/[^a-zA-Z0-9._-]+/g, "_")
+    .replace(/^_+|_+$/g, "") || "attachment";
+  const extension = path.extname(safeName);
+  const basename = extension ? safeName.slice(0, -extension.length) : safeName;
+  const key = path.posix.join(
+    "leave-attachments",
+    compactDateString(config.appTimezone),
+    employeeId,
+    `${basename}-${crypto.randomUUID()}${extension}`,
+  );
+
+  const storagePath = await writeBuffer({
+    config,
+    key,
+    buffer,
+    contentType: filePart.mimetype,
+  });
+
+  return {
+    storagePath,
+    originalName: filePart.filename || safeName,
+    mimeType: filePart.mimetype,
+    fileSize,
+  };
+}
+
+module.exports = {
+  DEFAULT_ATTACHMENT_MIME_TYPES,
+  calculateRequestedDays,
+  createLeaveLedgerEntry,
+  consumeReservedLeave,
+  currentLeavePeriod,
+  formatDateOnly,
+  leaveRangesOverlap,
+  loadLeaveBalanceItems,
+  loadLeaveBalanceSnapshot,
+  loadLeaveLedgerSummaryForRequest,
+  lockEmployeeForLeave,
+  mapLeaveTypeResponse,
+  normalizeAttachmentMimeTypes,
+  persistLeaveAttachment,
+  releaseReservedLeave,
+  summarizeLeaveLedgerEntries,
+  toHalfDayUnits,
+};