Add professor share calculation and financial reporting feature

Introduces per-class payout configuration (percentage or hourly rate,
plus an optional per-session expense allowance), pure calculation
utilities for professor payout/net profit/receivables, and a new
financial-reports API surface with per-class, per-session, and
date-range/monthly reports. Also adds full CRUD for institutional
expenses used in the range report, and wires up the new permissions
and roles. Fixes a pre-existing ReferenceError (missing
parseImportDate import) in paymentService that blocked creating
payments with dated transactions.

components/classes/classModel.js

@@ -79,6 +79,31 @@ const classSchema = new mongoose.Schema({
     min: 1,
     default: null
   },
+  /** Professor compensation model for this class */
+  payoutType: {
+    type: String,
+    enum: ['percentage', 'hourly'],
+    default: 'percentage'
+  },
+  /** Used when payoutType === 'percentage' — professor's share of class revenue (0-100) */
+  payoutPercentage: {
+    type: Number,
+    default: 0,
+    min: 0,
+    max: 100
+  },
+  /** Used when payoutType === 'hourly' — professor's rate per teaching hour (Toman) */
+  payoutHourlyRate: {
+    type: Number,
+    default: 0,
+    min: 0
+  },
+  /** Optional flat allowance (travel/catering/etc.) paid per session held, regardless of payout model */
+  extraExpensePerSession: {
+    type: Number,
+    default: 0,
+    min: 0
+  },
   isActive: {
     type: Boolean,
     default: true

components/classes/classService.js

@@ -19,7 +19,7 @@ const applyScheduleFields = (payload, body) => {
   return payload;
 };
 
-const CLASS_LIST_FIELDS = 'name course professor students capacity tuitionFee hasDiscount discount freeSpots showOnFrontend startDate endDate days startTime endTime numberOfSessions isActive adminNotes createdAt updatedAt';
+const CLASS_LIST_FIELDS = 'name course professor students capacity tuitionFee hasDiscount discount freeSpots showOnFrontend startDate endDate days startTime endTime numberOfSessions payoutType payoutPercentage payoutHourlyRate extraExpensePerSession isActive adminNotes createdAt updatedAt';
 
 const normalizePricingFields = (body = {}) => {
   const tuitionFee = Math.max(0, Number(body.tuitionFee) || 0);
@@ -30,6 +30,14 @@ const normalizePricingFields = (body = {}) => {
   return { tuitionFee, hasDiscount, discount };
 };
 
+const normalizePayoutFields = (body = {}) => {
+  const payoutType = body.payoutType === 'hourly' ? 'hourly' : 'percentage';
+  const payoutPercentage = Math.min(100, Math.max(0, Number(body.payoutPercentage) || 0));
+  const payoutHourlyRate = Math.max(0, Number(body.payoutHourlyRate) || 0);
+  const extraExpensePerSession = Math.max(0, Number(body.extraExpensePerSession) || 0);
+  return { payoutType, payoutPercentage, payoutHourlyRate, extraExpensePerSession };
+};
+
 const normalizeNumberOfSessions = (value) => {
   if (value === '' || value === null || value === undefined) return null;
   const parsed = Number(value);
@@ -65,7 +73,7 @@ const getAll = async (query) => {
   const [items, total] = await Promise.all([
     Class.find(filter)
       .select(CLASS_LIST_FIELDS)
-      .populate({ path: 'course', select: 'title type price' })
+      .populate({ path: 'course', select: 'title type price sectionCount hoursPerSection' })
       .populate({ path: 'professor', select: 'name surname' })
       .skip(skip).limit(limit).sort({ createdAt: -1 }).lean(),
     Class.countDocuments(filter)
@@ -76,7 +84,7 @@ const getAll = async (query) => {
 
 const getOne = async (id) => {
   const cls = await Class.findById(id)
-    .populate({ path: 'course', select: 'title type price' })
+    .populate({ path: 'course', select: 'title type price sectionCount hoursPerSection' })
     .populate({ path: 'professor', select: 'name surname phoneNumber' })
       .populate({ path: 'students', select: 'name phoneNumber gender' })
     .lean();
@@ -88,6 +96,7 @@ const create = async (body) => {
   const payload = applyScheduleFields({
     ...body,
     ...normalizePricingFields(body),
+    ...normalizePayoutFields(body),
     numberOfSessions: normalizeNumberOfSessions(body.numberOfSessions)
   }, body);
   if (body.freeSpots === '' || body.freeSpots === null || body.freeSpots === undefined) {
@@ -103,6 +112,7 @@ const update = async (id, body) => {
   const payload = applyScheduleFields({
     ...body,
     ...normalizePricingFields(body),
+    ...normalizePayoutFields(body),
     ...(body.numberOfSessions !== undefined
       ? { numberOfSessions: normalizeNumberOfSessions(body.numberOfSessions) }
       : {})

components/expenses/expenseController.js

@@ -0,0 +1,31 @@
+// /components/expenses/expenseController.js
+'use strict';
+
+const catchAsync = require('../../utils/catchAsync');
+const expenseService = require('./expenseService');
+const { successResponse, listResponse } = require('../../utils/apiResponse');
+
+exports.getAll = catchAsync(async (req, res) => {
+  const { data, meta } = await expenseService.getAllExpenses(req.query);
+  return listResponse(res, 200, data, meta);
+});
+
+exports.getOne = catchAsync(async (req, res) => {
+  const expense = await expenseService.getExpenseById(req.params.id);
+  return successResponse(res, 200, 'Expense retrieved successfully', expense);
+});
+
+exports.create = catchAsync(async (req, res) => {
+  const expense = await expenseService.createExpense(req.body, req.user?._id);
+  return successResponse(res, 201, 'Expense created successfully', expense);
+});
+
+exports.update = catchAsync(async (req, res) => {
+  const expense = await expenseService.updateExpense(req.params.id, req.body);
+  return successResponse(res, 200, 'Expense updated successfully', expense);
+});
+
+exports.delete = catchAsync(async (req, res) => {
+  await expenseService.deleteExpense(req.params.id);
+  return successResponse(res, 200, 'Expense deleted successfully');
+});

components/expenses/expenseModel.js

@@ -0,0 +1,43 @@
+// /components/expenses/expenseModel.js
+'use strict';
+
+const mongoose = require('mongoose');
+
+const expenseSchema = new mongoose.Schema({
+  title: {
+    type: String,
+    required: true,
+    trim: true
+  },
+  /** Free-form category label (e.g. "اجاره", "قبوض", "تجهیزات") */
+  category: {
+    type: String,
+    trim: true,
+    default: 'عمومی'
+  },
+  amount: {
+    type: Number,
+    required: true,
+    min: 0
+  },
+  /** Date the expense applies to — used to bucket expenses into date-range/monthly reports */
+  date: {
+    type: Date,
+    required: true
+  },
+  notes: {
+    type: String,
+    trim: true,
+    maxlength: 2000
+  },
+  recordedBy: {
+    type: mongoose.Schema.Types.ObjectId,
+    ref: 'User'
+  }
+}, {
+  timestamps: true
+});
+
+expenseSchema.index({ date: -1 });
+
+module.exports = mongoose.model('Expense', expenseSchema);

components/expenses/expenseRoutes.js

@@ -0,0 +1,21 @@
+// /components/expenses/expenseRoutes.js
+'use strict';
+
+const express = require('express');
+const expenseController = require('./expenseController');
+const { validateCreateExpense, validateUpdateExpense } = require('./expenseValidator');
+const authMiddleware = require('../../middlewares/authMiddleware');
+const perm = require('../../middlewares/permissionMiddleware');
+const { PERMISSIONS } = require('../../constants/permissions');
+
+const router = express.Router();
+
+router.use(authMiddleware);
+
+router.get('/admin/get-all', perm.requires(PERMISSIONS.EXPENSES_READ), expenseController.getAll);
+router.get('/admin/get-one/:id', perm.requires(PERMISSIONS.EXPENSES_READ), expenseController.getOne);
+router.post('/admin/create', perm.requires(PERMISSIONS.EXPENSES_CREATE), validateCreateExpense, expenseController.create);
+router.put('/admin/update/:id', perm.requires(PERMISSIONS.EXPENSES_UPDATE), validateUpdateExpense, expenseController.update);
+router.delete('/admin/delete/:id', perm.requires(PERMISSIONS.EXPENSES_DELETE), expenseController.delete);
+
+module.exports = router;

components/expenses/expenseService.js

@@ -0,0 +1,87 @@
+// /components/expenses/expenseService.js
+'use strict';
+
+const Expense = require('./expenseModel');
+const AppError = require('../../utils/AppError');
+const { parsePaginationAndSort, buildFilterQuery, calculateMeta } = require('../../utils/pagination');
+const { resolveDateRange } = require('../../utils/financialRange');
+
+const sanitizePayload = (body = {}) => {
+  const payload = {
+    title: String(body.title || '').trim(),
+    category: body.category ? String(body.category).trim() : 'عمومی',
+    amount: Math.max(0, Number(body.amount) || 0),
+    date: body.date ? new Date(body.date) : new Date(),
+    notes: body.notes ? String(body.notes).trim().slice(0, 2000) : ''
+  };
+  return payload;
+};
+
+const createExpense = async (body, actorId = null) => {
+  const payload = sanitizePayload(body);
+  const expense = await Expense.create({ ...payload, recordedBy: actorId || undefined });
+  return expense;
+};
+
+const getAllExpenses = async (queryParams) => {
+  const { page, limit, skip, sort } = parsePaginationAndSort(queryParams, 'date', 'desc');
+  const filter = buildFilterQuery(queryParams, ['title', 'category', 'notes'], [
+    'page', 'limit', 'sortBy', 'sortOrder', 'q', 'search', 'lang', 'startDate', 'endDate'
+  ]);
+
+  if (queryParams.startDate || queryParams.endDate) {
+    const { start, end } = resolveDateRange(queryParams);
+    filter.date = { $gte: start, $lte: end };
+  }
+
+  const [items, total] = await Promise.all([
+    Expense.find(filter).populate('recordedBy', 'name').sort(sort).skip(skip).limit(limit).lean(),
+    Expense.countDocuments(filter)
+  ]);
+
+  return { data: items, meta: calculateMeta(total, page, limit) };
+};
+
+const getExpenseById = async (id) => {
+  const expense = await Expense.findById(id).populate('recordedBy', 'name').lean();
+  if (!expense) throw new AppError('EXPENSE_NOT_FOUND');
+  return expense;
+};
+
+const updateExpense = async (id, body) => {
+  const expense = await Expense.findById(id);
+  if (!expense) throw new AppError('EXPENSE_NOT_FOUND');
+
+  if (body.title !== undefined) expense.title = String(body.title).trim();
+  if (body.category !== undefined) expense.category = String(body.category).trim() || 'عمومی';
+  if (body.amount !== undefined) expense.amount = Math.max(0, Number(body.amount) || 0);
+  if (body.date !== undefined) expense.date = new Date(body.date);
+  if (body.notes !== undefined) expense.notes = String(body.notes).trim().slice(0, 2000);
+
+  await expense.save();
+  return expense;
+};
+
+const deleteExpense = async (id) => {
+  const expense = await Expense.findByIdAndDelete(id);
+  if (!expense) throw new AppError('EXPENSE_NOT_FOUND');
+  return null;
+};
+
+/** Sum of expense amounts whose `date` falls within [start, end] — used by date-range financial reports. */
+const sumExpensesInRange = async (start, end) => {
+  const result = await Expense.aggregate([
+    { $match: { date: { $gte: start, $lte: end } } },
+    { $group: { _id: null, total: { $sum: '$amount' } } }
+  ]);
+  return result[0]?.total || 0;
+};
+
+module.exports = {
+  createExpense,
+  getAllExpenses,
+  getExpenseById,
+  updateExpense,
+  deleteExpense,
+  sumExpensesInRange
+};

components/expenses/expenseValidator.js

@@ -0,0 +1,50 @@
+// /components/expenses/expenseValidator.js
+'use strict';
+
+const AppError = require('../../utils/AppError');
+
+const validateBody = (body, { isUpdate = false } = {}) => {
+  const details = {};
+
+  if (!isUpdate || body.title !== undefined) {
+    if (!body.title || !String(body.title).trim()) {
+      details.title = 'عنوان هزینه الزامی است';
+    }
+  }
+
+  if (!isUpdate || body.amount !== undefined) {
+    if (body.amount === undefined || body.amount === null || Number(body.amount) <= 0) {
+      details.amount = 'مبلغ هزینه باید بیشتر از صفر باشد';
+    }
+  }
+
+  if (!isUpdate || body.date !== undefined) {
+    if (!body.date || Number.isNaN(new Date(body.date).getTime())) {
+      details.date = 'تاریخ هزینه الزامی و باید معتبر باشد';
+    }
+  }
+
+  if (Object.keys(details).length) {
+    throw new AppError('VALIDATION_FAILED', details);
+  }
+};
+
+const validateCreateExpense = (req, res, next) => {
+  try {
+    validateBody(req.body, { isUpdate: false });
+    next();
+  } catch (err) {
+    next(err);
+  }
+};
+
+const validateUpdateExpense = (req, res, next) => {
+  try {
+    validateBody(req.body, { isUpdate: true });
+    next();
+  } catch (err) {
+    next(err);
+  }
+};
+
+module.exports = { validateCreateExpense, validateUpdateExpense };

components/financialReports/financialReportController.js

@@ -0,0 +1,21 @@
+// /components/financialReports/financialReportController.js
+'use strict';
+
+const catchAsync = require('../../utils/catchAsync');
+const financialReportService = require('./financialReportService');
+const { successResponse } = require('../../utils/apiResponse');
+
+exports.getClassReport = catchAsync(async (req, res) => {
+  const report = await financialReportService.getClassReport(req.params.classId);
+  return successResponse(res, 200, 'Class financial report retrieved successfully', report);
+});
+
+exports.getSessionReport = catchAsync(async (req, res) => {
+  const report = await financialReportService.getSessionReport(req.params.sessionId);
+  return successResponse(res, 200, 'Session financial report retrieved successfully', report);
+});
+
+exports.getRangeReport = catchAsync(async (req, res) => {
+  const report = await financialReportService.getRangeReport(req.query);
+  return successResponse(res, 200, 'Date-range financial report retrieved successfully', report);
+});

components/financialReports/financialReportRoutes.js

@@ -0,0 +1,19 @@
+// /components/financialReports/financialReportRoutes.js
+'use strict';
+
+const express = require('express');
+const financialReportController = require('./financialReportController');
+const authMiddleware = require('../../middlewares/authMiddleware');
+const perm = require('../../middlewares/permissionMiddleware');
+const { PERMISSIONS } = require('../../constants/permissions');
+
+const router = express.Router();
+
+router.use(authMiddleware);
+router.use(perm.requires(PERMISSIONS.FINANCIAL_REPORTS_READ));
+
+router.get('/admin/range', financialReportController.getRangeReport);
+router.get('/admin/classes/:classId', financialReportController.getClassReport);
+router.get('/admin/sessions/:sessionId', financialReportController.getSessionReport);
+
+module.exports = router;

components/financialReports/financialReportService.js

@@ -0,0 +1,342 @@
+// /components/financialReports/financialReportService.js
+'use strict';
+
+const Class = require('../classes/classModel');
+const Session = require('../sessions/sessionModel');
+const Payment = require('../payments/paymentModel');
+const Transaction = require('../payments/transactionModel');
+const AppError = require('../../utils/AppError');
+const { resolveDateRange, isWithinRange } = require('../../utils/financialRange');
+const {
+  getPayableAmount,
+  isPaidTransaction,
+  isActiveTransaction
+} = require('../../utils/paymentAmount');
+const {
+  resolveSessionDurationHours,
+  calculateSessionDurationHours,
+  calculateBaseShare,
+  calculateExtraExpenses,
+  calculateProfessorPayout,
+  calculateNetProfit,
+  calculatePendingReceivables,
+  calculateOverpaidAmount,
+  calculateStudentRevenuePerSession
+} = require('../../utils/professorShare');
+const { sumExpensesInRange } = require('../expenses/expenseService');
+
+const normalizeId = (value) => {
+  if (value == null) return '';
+  if (typeof value === 'object' && value._id != null) return String(value._id);
+  return String(value);
+};
+
+/** Revenue collected/owed for a set of classIds, derived from Payment records (one payment ~ one class enrollment). */
+const getRevenueByClass = async (classIds) => {
+  const payments = await Payment.find({ classes: { $in: classIds } })
+    .select('classes amount discount paidAmount')
+    .lean();
+
+  const byClass = new Map(classIds.map((id) => [String(id), { expectedRevenue: 0, actualReceivedRevenue: 0 }]));
+  for (const payment of payments) {
+    const payable = getPayableAmount(payment);
+    const paid = Math.max(0, Number(payment.paidAmount) || 0);
+    for (const classRef of payment.classes || []) {
+      const key = String(classRef);
+      if (!byClass.has(key)) continue;
+      const entry = byClass.get(key);
+      entry.expectedRevenue += payable;
+      entry.actualReceivedRevenue += paid;
+    }
+  }
+  return byClass;
+};
+
+const getSessionCountsByClass = async (classIds) => {
+  const sessions = await Session.find({ class: { $in: classIds } }).select('class status').lean();
+  const byClass = new Map(classIds.map((id) => [String(id), { total: 0, held: 0, scheduled: 0, cancelled: 0 }]));
+  for (const session of sessions) {
+    const key = String(session.class);
+    if (!byClass.has(key)) continue;
+    const entry = byClass.get(key);
+    entry.total += 1;
+    if (session.status === 'held') entry.held += 1;
+    else if (session.status === 'cancelled') entry.cancelled += 1;
+    else entry.scheduled += 1;
+  }
+  return byClass;
+};
+
+/**
+ * Per-Class Report (Lifetime): aggregates all sessions, student payments (received vs.
+ * pending), professor payout (share + expenses), and net class profit.
+ */
+const getClassReport = async (classId) => {
+  const cls = await Class.findById(classId)
+    .populate({ path: 'course', select: 'title hoursPerSection sectionCount' })
+    .populate({ path: 'professor', select: 'name surname' })
+    .lean();
+  if (!cls) throw new AppError('CLASS_NOT_FOUND');
+
+  const [revenueByClass, sessionCountsByClass] = await Promise.all([
+    getRevenueByClass([cls._id]),
+    getSessionCountsByClass([cls._id])
+  ]);
+
+  const revenue = revenueByClass.get(String(cls._id)) || { expectedRevenue: 0, actualReceivedRevenue: 0 };
+  const sessionCounts = sessionCountsByClass.get(String(cls._id)) || { total: 0, held: 0, scheduled: 0, cancelled: 0 };
+
+  const sessionDurationHours = resolveSessionDurationHours(cls);
+  const payout = calculateProfessorPayout({
+    payoutType: cls.payoutType,
+    payoutPercentage: cls.payoutPercentage,
+    payoutHourlyRate: cls.payoutHourlyRate,
+    revenue: revenue.actualReceivedRevenue,
+    sessionDurationHours,
+    sessionsCount: sessionCounts.held,
+    extraExpensePerSession: cls.extraExpensePerSession
+  });
+
+  const netProfit = calculateNetProfit({
+    totalIncome: revenue.actualReceivedRevenue,
+    professorTotalPayout: payout.totalPayout
+  });
+
+  return {
+    class: {
+      _id: cls._id,
+      name: cls.name,
+      course: cls.course,
+      professor: cls.professor,
+      numberOfSessions: cls.numberOfSessions,
+      studentsCount: (cls.students || []).length,
+      payoutType: cls.payoutType,
+      payoutPercentage: cls.payoutPercentage,
+      payoutHourlyRate: cls.payoutHourlyRate,
+      extraExpensePerSession: cls.extraExpensePerSession,
+      sessionDurationHours
+    },
+    sessions: {
+      planned: cls.numberOfSessions ?? sessionCounts.total,
+      held: sessionCounts.held,
+      scheduled: sessionCounts.scheduled,
+      cancelled: sessionCounts.cancelled
+    },
+    revenue: {
+      expectedRevenue: revenue.expectedRevenue,
+      actualReceivedRevenue: revenue.actualReceivedRevenue,
+      pendingReceivables: calculatePendingReceivables(revenue.expectedRevenue, revenue.actualReceivedRevenue),
+      overpaidAmount: calculateOverpaidAmount(revenue.expectedRevenue, revenue.actualReceivedRevenue)
+    },
+    professorPayout: payout,
+    netProfit
+  };
+};
+
+/**
+ * Per-Session Report: evaluates one specific session — student revenue attributable to
+ * this session, the professor's session-level share/expenses, and the session net margin.
+ */
+const getSessionReport = async (sessionId) => {
+  const session = await Session.findById(sessionId)
+    .populate({
+      path: 'class',
+      populate: [
+        { path: 'course', select: 'title hoursPerSection sectionCount' },
+        { path: 'professor', select: 'name surname' }
+      ]
+    })
+    .lean();
+  if (!session) throw new AppError('SESSION_NOT_FOUND');
+
+  const cls = session.class;
+  if (!cls) throw new AppError('CLASS_NOT_FOUND');
+
+  const studentsCount = (cls.students || []).length;
+  const plannedSessions = cls.numberOfSessions || (await Session.countDocuments({ class: cls._id }));
+
+  const revenueByClass = await getRevenueByClass([cls._id]);
+  const revenue = revenueByClass.get(String(cls._id)) || { expectedRevenue: 0, actualReceivedRevenue: 0 };
+
+  // Prefer real payment data (handles per-student discounts); fall back to the class tuition when no payments exist yet.
+  const finalTuitionFee = cls.hasDiscount ? Math.max(0, (cls.tuitionFee || 0) - (cls.discount || 0)) : (cls.tuitionFee || 0);
+  const assignedTuitionPerStudent = studentsCount > 0 && revenue.expectedRevenue > 0
+    ? revenue.expectedRevenue / studentsCount
+    : finalTuitionFee;
+
+  const studentRevenuePerSession = calculateStudentRevenuePerSession(assignedTuitionPerStudent, plannedSessions);
+  const sessionIncome = studentRevenuePerSession * studentsCount;
+
+  const sessionDurationHours = calculateSessionDurationHours(session.startTime, session.endTime)
+    || resolveSessionDurationHours(cls);
+
+  const sessionShare = calculateBaseShare({
+    payoutType: cls.payoutType,
+    payoutPercentage: cls.payoutPercentage,
+    revenue: sessionIncome,
+    payoutHourlyRate: cls.payoutHourlyRate,
+    sessionDurationHours,
+    sessionsCount: 1
+  });
+  const sessionExtraExpense = calculateExtraExpenses({
+    extraExpensePerSession: cls.extraExpensePerSession,
+    sessionsCount: 1
+  });
+
+  const sessionNetMargin = calculateNetProfit({
+    totalIncome: sessionIncome,
+    professorTotalPayout: sessionShare + sessionExtraExpense
+  });
+
+  return {
+    session: {
+      _id: session._id,
+      topic: session.topic,
+      day: session.day,
+      startTime: session.startTime,
+      endTime: session.endTime,
+      status: session.status
+    },
+    class: {
+      _id: cls._id,
+      name: cls.name,
+      course: cls.course,
+      professor: cls.professor,
+      studentsCount,
+      plannedSessions
+    },
+    financials: {
+      studentRevenuePerSession,
+      sessionIncome,
+      sessionDurationHours,
+      professorSessionShare: sessionShare,
+      sessionExtraExpense,
+      sessionTotalPayout: sessionShare + sessionExtraExpense,
+      sessionNetMargin
+    }
+  };
+};
+
+/**
+ * Date-Range / Monthly Report: sessions held across all active classes within [start, end],
+ * combined with general institutional expenses recorded in that same window.
+ */
+const getRangeReport = async (query = {}) => {
+  const { start, end } = resolveDateRange(query);
+
+  const classFilter = { isActive: { $ne: false } };
+  if (query.classId) classFilter._id = query.classId;
+
+  const classes = await Class.find(classFilter)
+    .populate({ path: 'course', select: 'title hoursPerSection' })
+    .populate({ path: 'professor', select: 'name surname' })
+    .lean();
+  const classIds = classes.map((c) => c._id);
+
+  if (!classIds.length) {
+    const generalExpenses = await sumExpensesInRange(start, end);
+    return {
+      range: { start, end },
+      classes: [],
+      totals: {
+        totalReceived: 0,
+        totalOutstanding: 0,
+        totalProfessorPayouts: 0,
+        generalExpenses,
+        netProfit: -generalExpenses
+      }
+    };
+  }
+
+  const sessions = await Session.find({ class: { $in: classIds }, day: { $gte: start, $lte: end } })
+    .select('class status day')
+    .lean();
+
+  const heldByClass = new Map();
+  for (const session of sessions) {
+    if (session.status !== 'held') continue;
+    const key = String(session.class);
+    heldByClass.set(key, (heldByClass.get(key) || 0) + 1);
+  }
+
+  const payments = await Payment.find({ classes: { $in: classIds } }).select('_id classes').lean();
+  const paymentClassByPaymentId = new Map();
+  const paymentIds = [];
+  for (const payment of payments) {
+    paymentIds.push(payment._id);
+    const matchedClassId = (payment.classes || []).map(normalizeId).find((id) => classIds.some((c) => String(c) === id));
+    paymentClassByPaymentId.set(String(payment._id), matchedClassId);
+  }
+
+  const transactions = paymentIds.length
+    ? await Transaction.find({ payment: { $in: paymentIds } }).select('payment amount status date dueDate').lean()
+    : [];
+
+  const receivedByClass = new Map();
+  const outstandingByClass = new Map();
+  for (const trx of transactions) {
+    const classKey = paymentClassByPaymentId.get(String(trx.payment));
+    if (!classKey) continue;
+
+    if (isPaidTransaction(trx) && isWithinRange(trx.date, start, end)) {
+      receivedByClass.set(classKey, (receivedByClass.get(classKey) || 0) + (Number(trx.amount) || 0));
+    } else if (isActiveTransaction(trx) && !isPaidTransaction(trx) && isWithinRange(trx.dueDate, start, end)) {
+      outstandingByClass.set(classKey, (outstandingByClass.get(classKey) || 0) + (Number(trx.amount) || 0));
+    }
+  }
+
+  const classRows = classes.map((cls) => {
+    const key = String(cls._id);
+    const sessionsHeldInRange = heldByClass.get(key) || 0;
+    const receivedInRange = receivedByClass.get(key) || 0;
+    const outstandingInRange = outstandingByClass.get(key) || 0;
+    const sessionDurationHours = resolveSessionDurationHours(cls);
+
+    const payout = calculateProfessorPayout({
+      payoutType: cls.payoutType,
+      payoutPercentage: cls.payoutPercentage,
+      payoutHourlyRate: cls.payoutHourlyRate,
+      revenue: receivedInRange,
+      sessionDurationHours,
+      sessionsCount: sessionsHeldInRange,
+      extraExpensePerSession: cls.extraExpensePerSession
+    });
+
+    return {
+      class: {
+        _id: cls._id,
+        name: cls.name,
+        course: cls.course,
+        professor: cls.professor
+      },
+      sessionsHeldInRange,
+      receivedInRange,
+      outstandingInRange,
+      professorPayout: payout
+    };
+  });
+
+  const generalExpenses = await sumExpensesInRange(start, end);
+  const totalReceived = classRows.reduce((sum, row) => sum + row.receivedInRange, 0);
+  const totalOutstanding = classRows.reduce((sum, row) => sum + row.outstandingInRange, 0);
+  const totalProfessorPayouts = classRows.reduce((sum, row) => sum + row.professorPayout.totalPayout, 0);
+  const netProfit = totalReceived - totalProfessorPayouts - generalExpenses;
+
+  return {
+    range: { start, end },
+    classes: classRows,
+    totals: {
+      totalReceived,
+      totalOutstanding,
+      totalProfessorPayouts,
+      generalExpenses,
+      netProfit
+    }
+  };
+};
+
+module.exports = {
+  getClassReport,
+  getSessionReport,
+  getRangeReport
+};

components/payments/paymentService.js

@@ -12,6 +12,7 @@ const Course = require('../courses/courseModel');
 const Class = require('../classes/classModel');
 const Session = require('../sessions/sessionModel');
 const { omitNotifyFields } = require('../../utils/notifyFlags');
+const { parseImportDate } = require('../../utils/jalaliDate');
 const { resolveNotifyFlags } = require('../../utils/notifyResolver');
 const { notifyAction } = require('../../utils/actionNotify');
 const {