Add admin transaction cancellation without deleting history.

Cancelled transactions are excluded from paid totals and due-date
calculations while remaining visible for audit purposes.

components/payments/paymentService.js

@@ -20,6 +20,8 @@ const {
   normalizeDiscount,
   sanitizeNotes,
   isPaidTransaction,
+  isCancelledTransaction,
+  isActiveTransaction,
   sumPaidTransactions
 } = require('../../utils/paymentAmount');
 const logger = require('../../utils/logger');
@@ -56,7 +58,7 @@ const refreshPaymentTotals = async (payment) => {
   const transactions = await Transaction.find({ payment: payment._id }).lean();
   payment.paidAmount = sumPaidTransactions(transactions);
   const pending = transactions
-    .filter((trx) => !isPaidTransaction(trx))
+    .filter((trx) => isActiveTransaction(trx) && !isPaidTransaction(trx))
     .sort((a, b) => new Date(a.dueDate || 0) - new Date(b.dueDate || 0));
   payment.dueDate = pending[0]?.dueDate || payment.dueDate;
   await payment.save();
@@ -333,6 +335,9 @@ const addTransaction = async (paymentId, trxData, actorId = null) => {
 const updateTransaction = async (transactionId, body, actorId = null) => {
   const trx = await Transaction.findById(transactionId);
   if (!trx) throw new AppError('TRANSACTION_NOT_FOUND');
+  if (trx.status === 'cancelled') {
+    throw new AppError('VALIDATION_FAILED', {}, 'تراکنش لغوشده قابل ویرایش نیست.');
+  }
 
   const payment = await Payment.findById(trx.payment);
   if (!payment) throw new AppError('PAYMENT_NOT_FOUND');
@@ -373,6 +378,27 @@ const updateTransaction = async (transactionId, body, actorId = null) => {
   return getPaymentById(payment._id);
 };
 
+const cancelTransaction = async (transactionId, actorId = null) => {
+  const trx = await Transaction.findById(transactionId);
+  if (!trx) throw new AppError('TRANSACTION_NOT_FOUND');
+  if (trx.status === 'cancelled') {
+    throw new AppError('VALIDATION_FAILED', {}, 'این تراکنش قبلاً لغو شده است.');
+  }
+
+  const payment = await Payment.findById(trx.payment);
+  if (!payment) throw new AppError('PAYMENT_NOT_FOUND');
+
+  const previousStatus = payment.status;
+  trx.status = 'cancelled';
+  if (actorId) trx.recordedBy = actorId;
+  await trx.save();
+
+  await refreshPaymentTotals(payment);
+  emitPaymentStatusChangedIfNeeded(payment, previousStatus, actorId);
+
+  return getPaymentById(payment._id);
+};
+
 const getMyPayments = async (userId, query = {}) => {
   return getAllPayments({ ...query, userId });
 };
@@ -386,6 +412,7 @@ module.exports = {
   searchPayments,
   addTransaction,
   updateTransaction,
+  cancelTransaction,
   getMyPayments,
   createTransactionsForPayment,
   refreshPaymentTotals,