@classytic/payroll 1.0.0

package/src/schemas/employment.schema.js

@@ -0,0 +1,126 @@
+import mongoose from 'mongoose';
+import {
+  EMPLOYMENT_TYPE_VALUES,
+  EMPLOYEE_STATUS_VALUES,
+  DEPARTMENT_VALUES,
+  PAYMENT_FREQUENCY_VALUES,
+  ALLOWANCE_TYPE_VALUES,
+  DEDUCTION_TYPE_VALUES,
+  TERMINATION_REASON_VALUES,
+} from '../enums.js';
+
+const { Schema } = mongoose;
+
+const allowanceSchema = new Schema({
+  type: { type: String, enum: ALLOWANCE_TYPE_VALUES, required: true },
+  amount: { type: Number, required: true, min: 0 },
+  taxable: { type: Boolean, default: true },
+  recurring: { type: Boolean, default: true },
+  effectiveFrom: { type: Date, default: () => new Date() },
+  effectiveTo: { type: Date },
+}, { _id: false });
+
+const deductionSchema = new Schema({
+  type: { type: String, enum: DEDUCTION_TYPE_VALUES, required: true },
+  amount: { type: Number, required: true, min: 0 },
+  auto: { type: Boolean, default: false },
+  recurring: { type: Boolean, default: true },
+  effectiveFrom: { type: Date, default: () => new Date() },
+  effectiveTo: { type: Date },
+  description: { type: String },
+}, { _id: false });
+
+const compensationSchema = new Schema({
+  baseAmount: { type: Number, required: true, min: 0 },
+  frequency: { type: String, enum: PAYMENT_FREQUENCY_VALUES, default: 'monthly' },
+  currency: { type: String, default: 'BDT' },
+
+  allowances: [allowanceSchema],
+  deductions: [deductionSchema],
+
+  grossSalary: { type: Number, default: 0 },
+  netSalary: { type: Number, default: 0 },
+
+  effectiveFrom: { type: Date, default: () => new Date() },
+  lastModified: { type: Date, default: () => new Date() },
+}, { _id: false });
+
+const workScheduleSchema = new Schema({
+  hoursPerWeek: { type: Number, min: 0, max: 168 },
+  hoursPerDay: { type: Number, min: 0, max: 24 },  // 🆕 Standard hours per day (e.g., 8 for full-time, 4 for part-time)
+  workingDays: [{ type: Number, min: 0, max: 6 }],  // Array of days (0=Sunday, 6=Saturday)
+  shiftStart: { type: String },  // e.g., "09:00"
+  shiftEnd: { type: String },    // e.g., "17:00"
+}, { _id: false });
+
+const bankDetailsSchema = new Schema({
+  accountName: { type: String },
+  accountNumber: { type: String },
+  bankName: { type: String },
+  branchName: { type: String },
+  routingNumber: { type: String },
+}, { _id: false });
+
+const employmentHistorySchema = new Schema({
+  hireDate: { type: Date, required: true },
+  terminationDate: { type: Date, required: true },
+  reason: { type: String, enum: TERMINATION_REASON_VALUES },
+  finalSalary: { type: Number },
+  position: { type: String },
+  department: { type: String },
+  notes: { type: String },
+}, { timestamps: true });
+
+const payrollStatsSchema = new Schema({
+  totalPaid: { type: Number, default: 0, min: 0 },
+  lastPaymentDate: { type: Date },
+  nextPaymentDate: { type: Date },
+  paymentsThisYear: { type: Number, default: 0, min: 0 },
+  averageMonthly: { type: Number, default: 0, min: 0 },
+  updatedAt: { type: Date, default: () => new Date() },
+}, { _id: false });
+
+export const employmentFields = {
+  userId: { type: Schema.Types.ObjectId, ref: 'User', required: true },
+  organizationId: { type: Schema.Types.ObjectId, ref: 'Organization', required: true },
+
+  employeeId: { type: String, required: true },
+
+  employmentType: {
+    type: String,
+    enum: EMPLOYMENT_TYPE_VALUES,
+    default: 'full_time'
+  },
+
+  status: {
+    type: String,
+    enum: EMPLOYEE_STATUS_VALUES,
+    default: 'active'
+  },
+
+  department: { type: String, enum: DEPARTMENT_VALUES },
+  position: { type: String, required: true },
+
+  hireDate: { type: Date, required: true },
+  terminationDate: { type: Date },
+  probationEndDate: { type: Date },
+
+  employmentHistory: [employmentHistorySchema],
+
+  compensation: { type: compensationSchema, required: true },
+  workSchedule: workScheduleSchema,
+  bankDetails: bankDetailsSchema,
+  payrollStats: { type: payrollStatsSchema, default: () => ({}) },
+};
+
+export {
+  allowanceSchema,
+  deductionSchema,
+  compensationSchema,
+  workScheduleSchema,
+  bankDetailsSchema,
+  employmentHistorySchema,
+  payrollStatsSchema,
+};
+
+export default employmentFields;

package/src/services/compensation.service.js

@@ -0,0 +1,231 @@
+/**
+ * Compensation Service - Beautiful Compensation Management
+ * Clean abstraction for salary adjustments and calculations
+ */
+
+import {
+  CompensationFactory,
+  CompensationPresets,
+} from '../factories/compensation.factory.js';
+
+export class CompensationService {
+  constructor(EmployeeModel) {
+    this.EmployeeModel = EmployeeModel;
+  }
+
+  async getEmployeeCompensation(employeeId) {
+    const employee = await this.EmployeeModel.findById(employeeId);
+    if (!employee) throw new Error('Employee not found');
+
+    return employee.compensation;
+  }
+
+  async calculateBreakdown(employeeId) {
+    const compensation = await this.getEmployeeCompensation(employeeId);
+    return CompensationFactory.calculateBreakdown(compensation);
+  }
+
+  async updateBaseAmount(employeeId, newAmount, effectiveFrom) {
+    const employee = await this.EmployeeModel.findById(employeeId);
+    if (!employee) throw new Error('Employee not found');
+
+    const updatedCompensation = CompensationFactory.updateBaseAmount(
+      employee.compensation,
+      newAmount,
+      effectiveFrom
+    );
+
+    employee.compensation = updatedCompensation;
+    await employee.save();
+
+    return this.calculateBreakdown(employeeId);
+  }
+
+  async applyIncrement(employeeId, { percentage, amount, effectiveFrom }) {
+    const employee = await this.EmployeeModel.findById(employeeId);
+    if (!employee) throw new Error('Employee not found');
+
+    const updatedCompensation = CompensationFactory.applyIncrement(
+      employee.compensation,
+      { percentage, amount, effectiveFrom }
+    );
+
+    employee.compensation = updatedCompensation;
+    employee.incrementHistory = employee.incrementHistory || [];
+    employee.incrementHistory.push({
+      previousAmount: employee.compensation.baseAmount,
+      newAmount: updatedCompensation.baseAmount,
+      percentage,
+      amount,
+      effectiveFrom: effectiveFrom || new Date(),
+      appliedAt: new Date(),
+    });
+
+    await employee.save();
+
+    return this.calculateBreakdown(employeeId);
+  }
+
+  async addAllowance(employeeId, allowance) {
+    const employee = await this.EmployeeModel.findById(employeeId);
+    if (!employee) throw new Error('Employee not found');
+
+    const updatedCompensation = CompensationFactory.addAllowance(
+      employee.compensation,
+      allowance
+    );
+
+    employee.compensation = updatedCompensation;
+    await employee.save();
+
+    return this.calculateBreakdown(employeeId);
+  }
+
+  async removeAllowance(employeeId, allowanceType) {
+    const employee = await this.EmployeeModel.findById(employeeId);
+    if (!employee) throw new Error('Employee not found');
+
+    const updatedCompensation = CompensationFactory.removeAllowance(
+      employee.compensation,
+      allowanceType
+    );
+
+    employee.compensation = updatedCompensation;
+    await employee.save();
+
+    return this.calculateBreakdown(employeeId);
+  }
+
+  async addDeduction(employeeId, deduction) {
+    const employee = await this.EmployeeModel.findById(employeeId);
+    if (!employee) throw new Error('Employee not found');
+
+    const updatedCompensation = CompensationFactory.addDeduction(
+      employee.compensation,
+      deduction
+    );
+
+    employee.compensation = updatedCompensation;
+    await employee.save();
+
+    return this.calculateBreakdown(employeeId);
+  }
+
+  async removeDeduction(employeeId, deductionType) {
+    const employee = await this.EmployeeModel.findById(employeeId);
+    if (!employee) throw new Error('Employee not found');
+
+    const updatedCompensation = CompensationFactory.removeDeduction(
+      employee.compensation,
+      deductionType
+    );
+
+    employee.compensation = updatedCompensation;
+    await employee.save();
+
+    return this.calculateBreakdown(employeeId);
+  }
+
+  async setStandardCompensation(employeeId, baseAmount) {
+    const employee = await this.EmployeeModel.findById(employeeId);
+    if (!employee) throw new Error('Employee not found');
+
+    employee.compensation = CompensationPresets.standard(baseAmount);
+    await employee.save();
+
+    return this.calculateBreakdown(employeeId);
+  }
+
+  async compareCompensation(employeeId1, employeeId2) {
+    const breakdown1 = await this.calculateBreakdown(employeeId1);
+    const breakdown2 = await this.calculateBreakdown(employeeId2);
+
+    return {
+      employee1: breakdown1,
+      employee2: breakdown2,
+      difference: {
+        base: breakdown2.baseAmount - breakdown1.baseAmount,
+        gross: breakdown2.grossAmount - breakdown1.grossAmount,
+        net: breakdown2.netAmount - breakdown1.netAmount,
+      },
+      ratio: {
+        base: breakdown2.baseAmount / breakdown1.baseAmount,
+        gross: breakdown2.grossAmount / breakdown1.grossAmount,
+        net: breakdown2.netAmount / breakdown1.netAmount,
+      },
+    };
+  }
+
+  async getDepartmentCompensationStats(organizationId, department) {
+    const employees = await this.EmployeeModel.find({
+      organizationId,
+      department,
+      status: { $in: ['active', 'on_leave'] },
+    });
+
+    const breakdowns = employees.map((emp) =>
+      CompensationFactory.calculateBreakdown(emp.compensation)
+    );
+
+    const totals = breakdowns.reduce(
+      (acc, breakdown) => ({
+        totalBase: acc.totalBase + breakdown.baseAmount,
+        totalGross: acc.totalGross + breakdown.grossAmount,
+        totalNet: acc.totalNet + breakdown.netAmount,
+      }),
+      { totalBase: 0, totalGross: 0, totalNet: 0 }
+    );
+
+    return {
+      department,
+      employeeCount: employees.length,
+      ...totals,
+      averageBase: totals.totalBase / employees.length,
+      averageGross: totals.totalGross / employees.length,
+      averageNet: totals.totalNet / employees.length,
+    };
+  }
+
+  async getOrganizationCompensationStats(organizationId) {
+    const employees = await this.EmployeeModel.find({
+      organizationId,
+      status: { $in: ['active', 'on_leave'] },
+    });
+
+    const breakdowns = employees.map((emp) =>
+      CompensationFactory.calculateBreakdown(emp.compensation)
+    );
+
+    const totals = breakdowns.reduce(
+      (acc, breakdown) => ({
+        totalBase: acc.totalBase + breakdown.baseAmount,
+        totalGross: acc.totalGross + breakdown.grossAmount,
+        totalNet: acc.totalNet + breakdown.netAmount,
+      }),
+      { totalBase: 0, totalGross: 0, totalNet: 0 }
+    );
+
+    const byDepartment = {};
+    employees.forEach((emp) => {
+      const dept = emp.department || 'unassigned';
+      if (!byDepartment[dept]) {
+        byDepartment[dept] = { count: 0, totalNet: 0 };
+      }
+      const breakdown = CompensationFactory.calculateBreakdown(emp.compensation);
+      byDepartment[dept].count++;
+      byDepartment[dept].totalNet += breakdown.netAmount;
+    });
+
+    return {
+      employeeCount: employees.length,
+      ...totals,
+      averageBase: totals.totalBase / employees.length,
+      averageGross: totals.totalGross / employees.length,
+      averageNet: totals.totalNet / employees.length,
+      byDepartment,
+    };
+  }
+}
+
+export const createCompensationService = (EmployeeModel) =>
+  new CompensationService(EmployeeModel);

package/src/services/employee.service.js

@@ -0,0 +1,162 @@
+/**
+ * Employee Service - Clean Abstraction for Employee Operations
+ * Dependency injection, testable, beautiful API
+ */
+
+import { EmployeeFactory } from '../factories/employee.factory.js';
+import { employee as employeeQuery } from '../utils/query-builders.js';
+import {
+  isActive,
+  isEmployed,
+  canReceiveSalary,
+} from '../utils/validation.utils.js';
+
+export class EmployeeService {
+  constructor(EmployeeModel) {
+    this.EmployeeModel = EmployeeModel;
+  }
+
+  async findById(employeeId) {
+    return this.EmployeeModel.findById(employeeId);
+  }
+
+  async findByUserId(userId, organizationId) {
+    const query = employeeQuery()
+      .forUser(userId)
+      .forOrganization(organizationId)
+      .build();
+
+    return this.EmployeeModel.findOne(query);
+  }
+
+  async findActive(organizationId, options = {}) {
+    const query = employeeQuery()
+      .forOrganization(organizationId)
+      .active()
+      .build();
+
+    return this.EmployeeModel.find(query, options.projection);
+  }
+
+  async findEmployed(organizationId, options = {}) {
+    const query = employeeQuery()
+      .forOrganization(organizationId)
+      .employed()
+      .build();
+
+    return this.EmployeeModel.find(query, options.projection);
+  }
+
+  async findByDepartment(organizationId, department) {
+    const query = employeeQuery()
+      .forOrganization(organizationId)
+      .inDepartment(department)
+      .active()
+      .build();
+
+    return this.EmployeeModel.find(query);
+  }
+
+  async findEligibleForPayroll(organizationId, month, year) {
+    const query = employeeQuery()
+      .forOrganization(organizationId)
+      .employed()
+      .build();
+
+    const employees = await this.EmployeeModel.find(query);
+    return employees.filter(canReceiveSalary);
+  }
+
+  async create(data) {
+    const employeeData = EmployeeFactory.create(data);
+    return this.EmployeeModel.create(employeeData);
+  }
+
+  async updateStatus(employeeId, status, context = {}) {
+    const employee = await this.findById(employeeId);
+    if (!employee) throw new Error('Employee not found');
+
+    employee.status = status;
+    employee.statusHistory = employee.statusHistory || [];
+    employee.statusHistory.push({
+      status,
+      changedAt: new Date(),
+      changedBy: {
+        userId: context.userId,
+        name: context.userName,
+      },
+      reason: context.reason,
+    });
+
+    return employee.save();
+  }
+
+  async terminate(employeeId, reason, context = {}) {
+    const employee = await this.findById(employeeId);
+    if (!employee) throw new Error('Employee not found');
+
+    const terminationData = EmployeeFactory.createTermination({
+      reason,
+      notes: context.notes,
+      context,
+    });
+
+    employee.status = 'terminated';
+    Object.assign(employee, terminationData);
+
+    return employee.save();
+  }
+
+  async updateCompensation(employeeId, compensation) {
+    return this.EmployeeModel.findByIdAndUpdate(
+      employeeId,
+      { compensation, updatedAt: new Date() },
+      { new: true, runValidators: true }
+    );
+  }
+
+  async getEmployeeStats(organizationId) {
+    const query = employeeQuery().forOrganization(organizationId).build();
+
+    const employees = await this.EmployeeModel.find(query);
+
+    return {
+      total: employees.length,
+      active: employees.filter(isActive).length,
+      employed: employees.filter(isEmployed).length,
+      canReceiveSalary: employees.filter(canReceiveSalary).length,
+      byStatus: this.groupByStatus(employees),
+      byDepartment: this.groupByDepartment(employees),
+    };
+  }
+
+  groupByStatus(employees) {
+    return employees.reduce((acc, emp) => {
+      acc[emp.status] = (acc[emp.status] || 0) + 1;
+      return acc;
+    }, {});
+  }
+
+  groupByDepartment(employees) {
+    return employees.reduce((acc, emp) => {
+      const dept = emp.department || 'unassigned';
+      acc[dept] = (acc[dept] || 0) + 1;
+      return acc;
+    }, {});
+  }
+
+  isActive(employee) {
+    return isActive(employee);
+  }
+
+  isEmployed(employee) {
+    return isEmployed(employee);
+  }
+
+  canReceiveSalary(employee) {
+    return canReceiveSalary(employee);
+  }
+}
+
+export const createEmployeeService = (EmployeeModel) =>
+  new EmployeeService(EmployeeModel);