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/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 };