tango-app-api-payment-subscription 3.5.9 → 3.5.10

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "tango-app-api-payment-subscription",
-    "version": "3.5.9",
+    "version": "3.5.10",
     "description": "paymentSubscription",
     "main": "index.js",
     "type": "module",
@@ -29,7 +29,7 @@
         "nodemon": "^3.1.0",
         "puppeteer": "^24.41.0",
         "swagger-ui-express": "^5.0.0",
-        "tango-api-schema": "^2.6.28",
+        "tango-api-schema": "^2.6.29",
         "tango-app-api-middleware": "^3.6.18",
         "winston": "^3.12.0",
         "winston-daily-rotate-file": "^5.0.0",

package/src/controllers/bankTransaction.controller.js

@@ -467,69 +467,118 @@ export async function resolveBankTransaction( req, res ) {
     }
 
     // ---- reconcile ----
-    const invoiceId = req.body?.invoiceId;
-    if ( !invoiceId ) {
-      return res.sendError( 'invoiceId is required to reconcile', 400 );
-    }
-    const invoice = await invoiceService.findOne( { _id: invoiceId } );
-    if ( !invoice ) {
-      return res.sendError( 'Invoice not found', 404 );
+    // Accept either a single invoiceId (legacy) or a list of invoiceIds. One
+    // payment can settle multiple invoices: the amount auto-fills them in the
+    // order given, each settled fully until the money runs out.
+    const invoiceIds = Array.isArray( req.body?.invoiceIds ) && req.body.invoiceIds.length ?
+      req.body.invoiceIds.map( String ) :
+      ( req.body?.invoiceId ? [ String( req.body.invoiceId ) ] : [] );
+    if ( !invoiceIds.length ) {
+      return res.sendError( 'invoiceIds is required to reconcile', 400 );
     }
 
-    const prevPaid = Number( invoice.paidAmount ) || 0;
-    const totalAmount = Number( invoice.totalAmount ) || 0;
-    const outstanding = round2( totalAmount - prevPaid );
-    const diff = round2( txn.amount - outstanding );
-
-    let note;
-    let newStatus;
-    if ( Math.abs( diff ) <= AMOUNT_TOLERANCE ) {
-      newStatus = 'paid';
-      note = `Manually reconciled to ${invoice.invoice} — invoice marked Paid`;
-    } else if ( diff < 0 ) {
-      newStatus = 'partial';
-      note = `Partial — ${round2( -diff )} balance remains on ${invoice.invoice}`;
-    } else {
-      newStatus = 'paid';
-      note = `Overpayment — ${invoice.invoice} settled, ${round2( diff )} excess to follow up`;
+    // EDIT case: this transaction was ALREADY reconciled, so its amount was
+    // previously applied to one or more invoices. Reverse each prior allocation
+    // first so re-reconciling never double-counts. Prefer the recorded
+    // per-invoice allocations; fall back to the single invoiceId for older rows.
+    if ( txn.status === 'reconciled' ) {
+      const priorAllocations = ( Array.isArray( txn.appliedInvoices ) && txn.appliedInvoices.length ) ?
+        txn.appliedInvoices :
+        ( txn.invoiceId ? [ { invoiceId: txn.invoiceId, amount: txn.amount } ] : [] );
+      for ( const alloc of priorAllocations ) {
+        const prevInvoice = await invoiceService.findOne( { _id: alloc.invoiceId } );
+        if ( !prevInvoice ) {
+          continue;
+        }
+        const revertedPaid = round2( Math.max( 0, ( Number( prevInvoice.paidAmount ) || 0 ) - ( Number( alloc.amount ) || 0 ) ) );
+        const prevTotal = Number( prevInvoice.totalAmount ) || 0;
+        const revertedStatus = revertedPaid <= AMOUNT_TOLERANCE ? 'unpaid' :
+          ( round2( prevTotal - revertedPaid ) > AMOUNT_TOLERANCE ? 'partial' : 'paid' );
+        await invoiceService.invoiceUpdateOne(
+            { _id: prevInvoice._id },
+            {
+              $set: { paymentStatus: revertedStatus, paidAmount: revertedPaid },
+              $pull: { paymentHistory: { reference: txn.refNo || undefined, method: 'bank-statement' } },
+            },
+        );
+      }
     }
-    const newPaid = round2( prevPaid + txn.amount );
-
-    await invoiceService.invoiceUpdateOne(
-        { _id: invoice._id },
-        {
-          $set: {
-            paymentStatus: newStatus,
-            paidAmount: newPaid,
-            ...( newStatus === 'paid' ? { paidDate: new Date() } : {} ),
-          },
-          $push: {
-            paymentHistory: {
-              amount: txn.amount,
-              date: txn.valueDate || new Date(),
-              method: 'bank-statement',
-              reference: txn.refNo || undefined,
-              notes: `Manually reconciled from "${txn.fileName || 'statement'}"`,
-              recordedBy: req.user?.email || req.user?.userName || 'bank-reconciliation',
-              recordedAt: new Date(),
+
+    // Apply the payment across the selected invoices in order (auto-fill).
+    let remaining = round2( txn.amount );
+    const appliedInvoices = [];
+    const settledLabels = [];
+    let firstInvoice = null;
+    for ( const id of invoiceIds ) {
+      const invoice = await invoiceService.findOne( { _id: id } );
+      if ( !invoice ) {
+        continue;
+      }
+      if ( !firstInvoice ) {
+        firstInvoice = invoice;
+      }
+      const prevPaid = Number( invoice.paidAmount ) || 0;
+      const totalAmount = Number( invoice.totalAmount ) || 0;
+      const outstanding = round2( Math.max( 0, totalAmount - prevPaid ) );
+      const applied = round2( Math.max( 0, Math.min( remaining, outstanding ) ) );
+      if ( applied <= 0 && outstanding > 0 ) {
+        // No money left for this invoice — record it as selected but unfunded.
+        continue;
+      }
+      remaining = round2( remaining - applied );
+      const newPaid = round2( prevPaid + applied );
+      const fullySettled = round2( totalAmount - newPaid ) <= AMOUNT_TOLERANCE;
+      await invoiceService.invoiceUpdateOne(
+          { _id: invoice._id },
+          {
+            $set: {
+              paymentStatus: fullySettled ? 'paid' : 'partial',
+              paidAmount: newPaid,
+              ...( fullySettled ? { paidDate: new Date() } : {} ),
+            },
+            $push: {
+              paymentHistory: {
+                amount: applied,
+                date: txn.valueDate || new Date(),
+                method: 'bank-statement',
+                reference: txn.refNo || undefined,
+                notes: `Manually reconciled from "${txn.fileName || 'statement'}"`,
+                recordedBy: req.user?.email || req.user?.userName || 'bank-reconciliation',
+                recordedAt: new Date(),
+              },
             },
           },
-        },
-    );
+      );
+      appliedInvoices.push( { invoiceId: String( invoice._id ), invoice: invoice.invoice, amount: applied } );
+      settledLabels.push( `${invoice.invoice} (${fullySettled ? 'Paid' : 'Partial'})` );
+    }
+
+    if ( !appliedInvoices.length ) {
+      return res.sendError( 'None of the selected invoices could be reconciled.', 400 );
+    }
+
+    const pending = round2( remaining );
+    let note = appliedInvoices.length > 1 ?
+      `Reconciled across ${appliedInvoices.length} invoices: ${settledLabels.join( ', ' )}` :
+      `Manually reconciled to ${settledLabels[0]}`;
+    if ( pending > AMOUNT_TOLERANCE ) {
+      note += ` — ₹${pending} excess to follow up`;
+    }
 
-    // Brand name for the table's Brand Name column.
-    const client = await clientService.findOne( { clientId: invoice.clientId }, { clientName: 1 } );
+    // Brand name for the table's Brand Name column (from the first invoice).
+    const client = await clientService.findOne( { clientId: firstInvoice.clientId }, { clientName: 1 } );
     await bankTransactionService.updateOne( { _id: txnId }, { $set: {
       status: 'reconciled',
       contacted: false,
-      invoice: invoice.invoice,
-      invoiceId: String( invoice._id ),
-      identifiedClientId: String( invoice.clientId ?? '' ),
-      identifiedClientName: client?.clientName || invoice.companyName || '',
+      invoice: appliedInvoices.map( ( a ) => a.invoice ).join( ', ' ),
+      invoiceId: appliedInvoices[0].invoiceId,
+      appliedInvoices,
+      identifiedClientId: String( firstInvoice.clientId ?? '' ),
+      identifiedClientName: client?.clientName || firstInvoice.companyName || '',
       resultNote: note,
     } } );
 
-    return res.sendSuccess( { status: 'reconciled', note, invoice: invoice.invoice } );
+    return res.sendSuccess( { status: 'reconciled', note, invoices: appliedInvoices.map( ( a ) => a.invoice ), pending } );
   } catch ( error ) {
     logger.error( { error: error, function: 'resolveBankTransaction' } );
     return res.sendError( error, 500 );

package/src/controllers/brandsBilling.controller.js

@@ -30,11 +30,36 @@ export async function brandsBillingList( req, res ) {
     }
 
     if ( req.body.paymentStatus && req.body.paymentStatus.length > 0 ) {
-      query.push( {
-        $match: {
-          'planDetails.paymentStatus': { $in: req.body.paymentStatus },
-        },
-      } );
+      // Filter by the SAME derived buckets the pills use (see payBucketExpr),
+      // so a selected pill returns exactly the rows it counts:
+      //   trial     -> paymentStatus == 'trial'
+      //   free      -> paymentStatus == 'free'
+      //   paid      -> paymentStatus in {paid,unbilled,due} AND no trial product
+      //   trialPaid -> paymentStatus in {paid,unbilled,due} AND has a trial product
+      // 'trialPaid' is a derived bucket — there is no stored 'trialPaid'
+      // status — which is why a plain $in match returned no data.
+      const buckets = req.body.paymentStatus;
+      const paidLike = [ 'paid', 'unbilled', 'due' ];
+      const hasTrialProduct = { $gt: [ { $size: { $filter: {
+        input: { $ifNull: [ '$planDetails.product', [] ] },
+        as: 'p',
+        cond: { $eq: [ '$$p.status', 'trial' ] },
+      } } }, 0 ] };
+      const ors = [];
+      for ( const b of buckets ) {
+        if ( b === 'trial' || b === 'free' ) {
+          ors.push( { $eq: [ '$planDetails.paymentStatus', b ] } );
+        } else if ( b === 'paid' ) {
+          ors.push( { $and: [ { $in: [ '$planDetails.paymentStatus', paidLike ] }, { $not: hasTrialProduct } ] } );
+        } else if ( b === 'trialPaid' ) {
+          ors.push( { $and: [ { $in: [ '$planDetails.paymentStatus', paidLike ] }, hasTrialProduct ] } );
+        } else {
+          ors.push( { $eq: [ '$planDetails.paymentStatus', b ] } );
+        }
+      }
+      if ( ors.length ) {
+        query.push( { $match: { $expr: ors.length === 1 ? ors[0] : { $or: ors } } } );
+      }
     }
 
     query.push(
@@ -203,7 +228,21 @@ export async function brandsBillingList( req, res ) {
             dueInr: 1,
             dueUsd: 1,
             status: 1,
-            paymentStatus: '$planDetails.paymentStatus',
+            // Display mapping for the Payment Status column: an 'unbilled' or
+            // 'due' plan is shown as 'paid'; any other status is shown as-is.
+            paymentStatus: {
+              $cond: {
+                if: { $eq: [ '$planDetails.paymentStatus', 'unbilled' ] },
+                then: 'paid',
+                else: {
+                  $cond: {
+                    if: { $eq: [ '$planDetails.paymentStatus', 'due' ] },
+                    then: 'paid',
+                    else: '$planDetails.paymentStatus',
+                  },
+                },
+              },
+            },
             nextBillingDate: 1,
             currencyType: '$paymentInvoice.currencyType',
           },
@@ -265,9 +304,11 @@ export async function brandsBillingList( req, res ) {
             branches: [
               { case: { $eq: [ '$$ps', 'trial' ] }, then: 'trial' },
               { case: { $eq: [ '$$ps', 'free' ] }, then: 'free' },
-              { case: { $and: [ { $eq: [ '$$ps', 'paid' ] }, '$$hasTrialProduct' ] }, then: 'trialPaid' },
-              { case: { $eq: [ '$$ps', 'paid' ] }, then: 'paid' },
-              { case: { $eq: [ '$$ps', 'unbilled' ] }, then: 'unbilled' },
+              // 'unbilled' and 'due' are treated as PAID (same mapping as the
+              // Payment Status column). A paid/unbilled/due plan that still has
+              // a product on trial is bucketed as trialPaid.
+              { case: { $and: [ { $in: [ '$$ps', [ 'paid', 'unbilled', 'due' ] ] }, '$$hasTrialProduct' ] }, then: 'trialPaid' },
+              { case: { $in: [ '$$ps', [ 'paid', 'unbilled', 'due' ] ] }, then: 'paid' },
             ],
             default: 'other',
           },
@@ -284,7 +325,7 @@ export async function brandsBillingList( req, res ) {
     // regardless of the selected tab, and show even when the Active tab is
     // empty.
     const lifecycle = { active: 0, hold: 0, suspended: 0, deactive: 0 };
-    const payTotals = { trial: 0, paid: 0, free: 0, trialPaid: 0, unbilled: 0 };
+    const payTotals = { trial: 0, paid: 0, free: 0, trialPaid: 0 };
     const paymentByStatus = {};
     let totalBrands = 0;
     matrixAgg.forEach( ( row ) => {
@@ -299,7 +340,7 @@ export async function brandsBillingList( req, res ) {
         payTotals[pay] += n;
       }
       if ( !paymentByStatus[st] ) {
-        paymentByStatus[st] = { trial: 0, paid: 0, free: 0, trialPaid: 0, unbilled: 0 };
+        paymentByStatus[st] = { trial: 0, paid: 0, free: 0, trialPaid: 0 };
       }
       if ( paymentByStatus[st][pay] != null ) {
         paymentByStatus[st][pay] += n;
@@ -316,7 +357,6 @@ export async function brandsBillingList( req, res ) {
       paid: payTotals.paid,
       free: payTotals.free,
       trialPaid: payTotals.trialPaid,
-      unbilled: payTotals.unbilled,
       paymentByStatus,
       // Money/store totals stay tied to the filtered view so they match the
       // rows on screen.
@@ -610,8 +650,14 @@ export async function latestDailyPricing( req, res ) {
     let stores = record.stores || [];
     let count = stores.length;
 
-    if ( req.body.statusFilter && req.body.statusFilter !== '' ) {
-      stores = stores.filter( ( s ) => s.status === req.body.statusFilter );
+    // statusFilter may be an array (multi-select) or a legacy string. An empty
+    // value / empty array means "all statuses".
+    const statusFilterList = Array.isArray( req.body.statusFilter ) ?
+      req.body.statusFilter.filter( Boolean ) :
+      ( req.body.statusFilter ? [ req.body.statusFilter ] : [] );
+    if ( statusFilterList.length ) {
+      const allowed = new Set( statusFilterList );
+      stores = stores.filter( ( s ) => allowed.has( s.status ) );
     }
 
     if ( req.body.searchValue && req.body.searchValue !== '' ) {
@@ -1573,6 +1619,18 @@ export async function billingSummary( req, res ) {
     } );
     const clientById = new Map( clients.map( ( c ) => [ String( c.clientId ), c ] ) );
 
+    // Registered Entity comes from the billings collection (each billing group's
+    // registeredCompanyName). A client can have multiple groups/names, so
+    // collect the distinct list per client — the UI shows the first and reveals
+    // the rest on hover.
+    const billingNameAgg = await billingService.aggregatebilling( [
+      { $match: { registeredCompanyName: { $exists: true, $nin: [ '', null ] } } },
+      { $group: { _id: '$clientId', names: { $addToSet: '$registeredCompanyName' } } },
+    ] );
+    const regNamesByClient = new Map(
+        billingNameAgg.map( ( b ) => [ String( b._id ), ( b.names || [] ).filter( Boolean ) ] ),
+    );
+
     // Per-client CSM (userAssignedStore, tangoUserType 'csm'); display the
     // email's local part since the collection carries no display name.
     const usdRate = await getUsdInrRate();
@@ -1786,10 +1844,17 @@ export async function billingSummary( req, res ) {
       revCur = revCur == null ? null : Math.round( revCur );
       const revPrevOut = revPrev == null ? null : Math.round( revPrev );
       const installationOut = r.installationFee ? Math.round( r.installationFee ) : null;
+      // Registered Entity from the billings collection (distinct group names).
+      // First name shown in the column; the full list is sent so the UI can
+      // reveal the others on hover. Fall back to the invoice company name when
+      // a client has no billing-group registered name.
+      const regNames = regNamesByClient.get( r.clientId ) || [];
+      const registeredEntity = regNames[0] || r.registeredEntity || '';
       return {
         clientId: r.clientId,
-        clientName: r.clientName || r.registeredEntity || r.clientId,
-        registeredEntity: r.registeredEntity,
+        clientName: r.clientName || registeredEntity || r.clientId,
+        registeredEntity,
+        registeredEntities: regNames.length ? regNames : ( r.registeredEntity ? [ r.registeredEntity ] : [] ),
         status: r.status,
         products: r.products,
         csm: r.csm,

package/src/controllers/invoice.controller.js

@@ -17,6 +17,7 @@ import { symbolFor } from '../utils/currency.js';
 import { invoiceStatusEnum } from '../dtos/validation.dtos.js';
 import { findOneApplicationDefault } from '../services/applicationDefault.service.js';
 import * as assignedStoreService from '../services/assignedStore.service.js';
+import * as bankTransactionService from '../services/bankTransaction.service.js';
 import { getUsdInrRate } from './brandsBilling.controller.js';
 
 // Pulls CSM + Finance head emails (stored under applicationDefault
@@ -136,6 +137,35 @@ export async function createInvoice( req, res ) {
         invoiceNo = invoiceNo.toString().padStart( 5, '0' );
       }
       const baseDate = req.body.billingDate ? dayjs( req.body.billingDate ) : dayjs();
+      let customProducts = Array.isArray( req.body.products ) ? req.body.products : [];
+
+      // Advance billing: monthly = 1, half-yearly = 6, yearly = 12. For a
+      // multi-month advance invoice, each month becomes its own line item —
+      // every posted product is repeated once per month, labelled with that
+      // month, so one invoice bills the whole period upfront (same logic as
+      // the auto-generated advance invoices).
+      const customAdvanceMonths = req.body.advanceInvoice ?
+        ( { quarterly: 3, halfyearly: 6, yearly: 12 }[req.body.advancePeriod] || 1 ) : 1;
+      if ( customAdvanceMonths > 1 ) {
+        const expanded = [];
+        for ( let m = 0; m < customAdvanceMonths; m++ ) {
+          const monthLabel = baseDate.add( m, 'month' ).format( 'MMM YYYY' );
+          for ( const p of customProducts ) {
+            expanded.push( { ...p, month: monthLabel } );
+          }
+        }
+        customProducts = expanded;
+      }
+      // Recompute totals from the (possibly expanded) line items so a
+      // multi-month advance invoice bills the full period.
+      const customAmount = customAdvanceMonths > 1 ?
+        Math.round( customProducts.reduce( ( s, p ) => s + ( Number( p.amount ) || 0 ), 0 ) ) :
+        Math.round( Number( req.body.amount ) || 0 );
+      const customTotal = customAdvanceMonths > 1 ?
+        Math.round( customProducts.reduce( ( s, p ) => s + ( Number( p.amount ) || 0 ), 0 ) +
+          ( Array.isArray( req.body.tax ) ? req.body.tax.reduce( ( s, t ) => s + ( Number( t.taxAmount ) || 0 ) * customAdvanceMonths, 0 ) : 0 ) ) :
+        Math.round( Number( req.body.totalAmount ) || 0 );
+
       const data = {
         invoice: `INV-${Finacialyear}-${invoiceNo}`,
         invoiceIndex: invoiceNo,
@@ -147,10 +177,10 @@ export async function createInvoice( req, res ) {
         companyAddress: req.body.companyAddress || '',
         GSTNumber: req.body.GSTNumber || '',
         PlaceOfSupply: req.body.PlaceOfSupply || '',
-        products: Array.isArray( req.body.products ) ? req.body.products : [],
+        products: customProducts,
         tax: Array.isArray( req.body.tax ) ? req.body.tax : [],
-        amount: Math.round( Number( req.body.amount ) || 0 ),
-        totalAmount: Math.round( Number( req.body.totalAmount ) || 0 ),
+        amount: customAmount,
+        totalAmount: customTotal,
         stores: Number( req.body.stores ) || 0,
         currency: req.body.currency || 'inr',
         billingDate: baseDate.toDate(),
@@ -159,6 +189,9 @@ export async function createInvoice( req, res ) {
         paymentMethod: 'Online',
         status: 'pendingCsm',
         paymentStatus: 'unpaid',
+        advanceInvoice: req.body.advanceInvoice || false,
+        advancePeriod: req.body.advanceInvoice ? ( req.body.advancePeriod || 'monthly' ) : undefined,
+        advanceMonths: customAdvanceMonths,
       };
       const created = await invoiceService.create( data );
       const logObj = {
@@ -207,6 +240,32 @@ export async function createInvoice( req, res ) {
       } else {
         products = await stepPrice( group, getClient );
       }
+
+      // Billing horizon in months. Advance and normal cycle are independent —
+      // only one drives the span per generation:
+      //   advanceInvoice ON  -> advancePeriod (advance future billing)
+      //   advanceInvoice OFF -> paymentCycle  (normal billing cycle)
+      // For a multi-month span, each month becomes its own line item: every
+      // product is repeated once per month, labelled with that month, at the
+      // normal monthly amount. One invoice then bills the whole period.
+      // (advancePeriod uses 'halfyearly'; paymentCycle uses 'quarter'/'halfYearly'
+      // — map both spellings.)
+      const advancePeriodMonths = { quarterly: 3, halfyearly: 6, yearly: 12 };
+      const paymentCycleMonths = { quarter: 3, quarterly: 3, halfYearly: 6, halfyearly: 6, yearly: 12 };
+      const advanceMonths = group.advanceInvoice ?
+        ( advancePeriodMonths[group.advancePeriod] || 1 ) :
+        ( paymentCycleMonths[group.paymentCycle] || 1 );
+      if ( advanceMonths > 1 ) {
+        const expanded = [];
+        for ( let m = 0; m < advanceMonths; m++ ) {
+          const monthLabel = baseDate.add( m, 'month' ).format( 'MMM YYYY' );
+          for ( const p of products ) {
+            expanded.push( { ...p, month: monthLabel } );
+          }
+        }
+        products = expanded;
+      }
+
       let amount = products.reduce( ( sum, product ) => sum + product.amount, 0 );
       let taxList = [];
       let totalAmount = 0;
@@ -305,6 +364,8 @@ export async function createInvoice( req, res ) {
         monthOfbilling: baseDate.format( 'MM' ),
         dueDate: dueDate,
         advanceInvoice: group.advanceInvoice || false,
+        advancePeriod: group.advanceInvoice ? ( group.advancePeriod || 'monthly' ) : undefined,
+        advanceMonths: advanceMonths,
       };
 
       if ( req.body.invoiceId ) {
@@ -2211,6 +2272,18 @@ export async function migrateInvoice( req, res ) {
 export async function PaymentStatusChange( req, res ) {
   try {
     let invoice = await invoiceService.findOne( { invoice: req.body.invoiceId } );
+    if ( !invoice ) {
+      return res.sendError( 'Invoice not found', 404 );
+    }
+    // Payment can only be recorded on an APPROVED invoice — block while it's
+    // still in the approval pipeline.
+    if ( invoice.status !== 'approved' ) {
+      return res.sendError( 'Payment status can be changed only after the invoice is approved.', 409 );
+    }
+    // A paid invoice is locked — its payment status cannot be changed.
+    if ( invoice.paymentStatus === 'paid' ) {
+      return res.sendError( 'This invoice is already paid; its payment status cannot be changed.', 409 );
+    }
     let updateInvoice = await invoiceService.updateOne( { invoice: req.body.invoiceId }, { paymentStatus: req.body.status } );
     let logObj = {
       userName: req.user?.userName,
@@ -2255,6 +2328,14 @@ export async function recordPayment( req, res ) {
     if ( !invoice ) {
       return res.sendError( 'Invoice not found', 404 );
     }
+    // Payment can only be recorded on an APPROVED invoice.
+    if ( invoice.status !== 'approved' ) {
+      return res.sendError( 'Payment can be recorded only after the invoice is approved.', 409 );
+    }
+    // A paid invoice is locked — no further payment / status change.
+    if ( invoice.paymentStatus === 'paid' ) {
+      return res.sendError( 'This invoice is already paid; its payment status cannot be changed.', 409 );
+    }
 
     const previousPaid = Number( invoice.paidAmount ) || 0;
     const newPaid = Math.round( ( previousPaid + amountNum ) * 100 ) / 100;
@@ -2305,6 +2386,32 @@ export async function recordPayment( req, res ) {
     const result = await invoiceService.invoiceUpdateOne( { invoice: invoiceId }, update );
     logger.info?.( { function: 'recordPayment', invoiceId, matched: result?.matchedCount, modified: result?.modifiedCount } );
 
+    // Mirror the manual payment into the Transactions section as a reconciled
+    // row with source 'manual', so manually-recorded payments are visible
+    // alongside bank/VA/gateway transactions.
+    try {
+      const clientForName = await clientService.findOne( { clientId: invoice.clientId }, { clientName: 1 } );
+      await bankTransactionService.insertMany( [ {
+        valueDate: historyEntry.date,
+        narration: notes || `Manual payment recorded for ${invoiceId}`,
+        refNo: reference || '',
+        amount: amountNum,
+        payer: clientForName?.clientName || invoice.companyName || '',
+        source: 'manual',
+        status: 'reconciled',
+        identifiedClientId: String( invoice.clientId ?? '' ),
+        identifiedClientName: clientForName?.clientName || invoice.companyName || '',
+        invoice: invoice.invoice,
+        invoiceId: String( invoice._id ),
+        appliedInvoices: [ { invoiceId: String( invoice._id ), invoice: invoice.invoice, amount: amountNum } ],
+        resultNote: `Manually recorded - ${derivedStatus === 'paid' ? 'invoice marked Paid' : 'partial payment'}`,
+        fileName: 'manual-entry',
+      } ] );
+    } catch ( txnErr ) {
+      // Non-fatal: the payment is already recorded; the mirror row is best-effort.
+      logger.error( { error: txnErr, function: 'recordPayment.mirrorTransaction', invoiceId } );
+    }
+
     try {
       const logObj = {
         userName: req.user?.userName,

package/src/dtos/validation.dtos.js

@@ -329,6 +329,7 @@ export const createBillingGroupBody = joi.object(
       attachAnnexure: joi.boolean().optional(),
       isPrimary: joi.boolean().optional(),
       advanceInvoice: joi.boolean().optional(),
+      advancePeriod: joi.string().valid( 'monthly', 'quarterly', 'halfyearly', 'yearly' ).optional().allow( '' ),
       products: joi.array().items( joi.object( {
         productName: joi.string().required(),
         billingMethod: joi.string().valid( 'eachStore', 'overallStore' ).required(),
@@ -368,6 +369,7 @@ export const updateBillingGroupBody = joi.object(
       attachAnnexure: joi.boolean().optional(),
       isPrimary: joi.boolean().optional(),
       advanceInvoice: joi.boolean().optional(),
+      advancePeriod: joi.string().valid( 'monthly', 'quarterly', 'halfyearly', 'yearly' ).optional().allow( '' ),
       products: joi.array().items( joi.object( {
         _id: joi.any().optional(),
         productName: joi.string().required(),
@@ -401,6 +403,7 @@ export const bulkUpdateBillingGroupRowSchema = joi.object( {
   isInstallationOneTime: joi.boolean().optional(),
   attachAnnexure: joi.boolean().optional(),
   advanceInvoice: joi.boolean().optional(),
+  advancePeriod: joi.string().valid( 'monthly', 'quarterly', 'halfyearly', 'yearly' ).optional().allow( '' ),
   storeId: joi.string().allow( '' ).optional(),
 } );