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/paymentController.js

@@ -58,3 +58,9 @@ exports.updateTransaction = catchAsync(async (req, res, next) => {
   const payment = await paymentService.updateTransaction(req.params.transactionId, req.body, actorId);
   return successResponse(res, 200, 'Transaction updated successfully', payment);
 });
+
+exports.cancelTransaction = catchAsync(async (req, res, next) => {
+  const actorId = req.user?._id;
+  const payment = await paymentService.cancelTransaction(req.params.transactionId, actorId);
+  return successResponse(res, 200, 'Transaction cancelled successfully', payment);
+});

components/payments/paymentRoutes.js

@@ -27,6 +27,7 @@ router.get('/admin/search', perm.requires(PERMISSIONS.PAYMENTS_SEARCH), paymentC
 router.get('/admin/get-one/:id', perm.requires(PERMISSIONS.PAYMENTS_READ), paymentController.getOne);
 router.put('/admin/update/:id', perm.requires(PERMISSIONS.PAYMENTS_UPDATE), validateUpdatePayment, paymentController.update);
 router.put('/admin/transactions/:transactionId', perm.requires(PERMISSIONS.PAYMENTS_UPDATE), validateUpdateTransaction, paymentController.updateTransaction);
+router.post('/admin/transactions/:transactionId/cancel', perm.requires(PERMISSIONS.PAYMENTS_UPDATE), paymentController.cancelTransaction);
 router.post('/admin/transactions/:paymentId', perm.requires(PERMISSIONS.PAYMENTS_UPDATE), validateAddTransaction, paymentController.createTransaction);
 router.delete('/admin/delete/:id', perm.requires(PERMISSIONS.PAYMENTS_DELETE), paymentController.delete);
 

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,

components/payments/transactionModel.js

@@ -35,7 +35,7 @@ const transactionSchema = new mongoose.Schema({
   },
   status: {
     type: String,
-    enum: ['pending', 'paid'],
+    enum: ['pending', 'paid', 'cancelled'],
     default: 'pending',
     index: true
   }