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

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "tango-app-api-payment-subscription",
-    "version": "3.5.9",
+    "version": "3.5.11",
     "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/scripts/seed-payment-reminders.js

@@ -19,7 +19,12 @@ dotenv.config();
 
 const args = process.argv.slice( 2 );
 const dryRun = args.includes( '--dry-run' );
-const STATIC_EMAIL = args.find( ( a ) => a.includes( '@' ) ) || 'ayyanarkalusulingam13@gmail.com';
+
+// Default reminder recipients seeded onto every active client. Any email(s)
+// passed as args are added on top, de-duped.
+const DEFAULT_EMAILS = [ 'sathish@tangotech.co.in', 'ayyanarkalusulingam13@gmail.com' ];
+const argEmails = args.filter( ( a ) => a.includes( '@' ) );
+const REMINDER_EMAILS = [ ...new Set( [ ...DEFAULT_EMAILS, ...argEmails ] ) ];
 
 // Mirrors the app's DEFAULTS() in paymentReminder.controller.js.
 const DEFAULT_TEMPLATES = {
@@ -34,7 +39,7 @@ async function run() {
   // Reuse the app's own connection builder (reads mongo_* env config).
   const { uri, options } = getConnection();
   await mongoose.connect( uri, options );
-  console.log( `Connected. Static recipient: ${STATIC_EMAIL}${dryRun ? '  (DRY RUN — no writes)' : ''}\n` );
+  console.log( `Connected. Recipients: ${REMINDER_EMAILS.join( ', ' )}${dryRun ? '  (DRY RUN — no writes)' : ''}\n` );
 
   const clients = await model.clientModel.find(
       { status: 'active' },
@@ -60,7 +65,7 @@ async function run() {
         {
           $set: {
             clientId: c.clientId,
-            reminderEmails: [ STATIC_EMAIL ],
+            reminderEmails: REMINDER_EMAILS,
             templates: DEFAULT_TEMPLATES,
             updatedBy: 'seed-script',
           },

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/billing.controllers.js

@@ -106,6 +106,29 @@ export const subscribedStoreList = async ( req, res ) => {
 
     );
 
+    // Selected stores for the group being edited. The backend resolves these
+    // itself from the group's `stores` (by groupId) so the FE doesn't have to
+    // send/compute them. It can also accept an explicit selectedStoreIds list.
+    // Each returned store gets an `isSelected` flag (drives the checkbox), and
+    // selected stores are floated to the top across ALL pages (before
+    // pagination) so they appear first.
+    // The live form selection (selectedStoreIds) is authoritative — it matches
+    // exactly what's checked in the UI (including unsaved edits). Only fall back
+    // to the saved group's stores when the FE didn't send a selection.
+    let selectedStoreIds = Array.isArray( req.body.selectedStoreIds ) ? req.body.selectedStoreIds : [];
+    if ( !selectedStoreIds.length && req.body.groupId ) {
+      const group = await findOne( { _id: req.body.groupId }, { stores: 1 } );
+      if ( group && Array.isArray( group.stores ) ) {
+        selectedStoreIds = group.stores;
+      }
+    }
+    // Always tag isSelected (false when nothing is selected) + sort selected
+    // first; storeId secondary keeps the order stable within each partition.
+    pipeline.push(
+        { $addFields: { isSelected: { $in: [ '$storeId', selectedStoreIds ] } } },
+        { $sort: { isSelected: -1, storeId: 1 } },
+    );
+
     const facetStage = {
       $facet: {
         data: [

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.
@@ -386,6 +426,13 @@ export async function brandInvoiceList( req, res ) {
       },
     } ];
 
+    // Client users only ever see APPROVED invoices — the approval pipeline
+    // (pendingCsm/pendingFinance/pendingApproval/pending) is internal to tango
+    // and must not be exposed to clients, even in the raw list response.
+    if ( req.user?.userType === 'client' ) {
+      query.push( { $match: { status: 'approved' } } );
+    }
+
     // If the user picked an explicit Month or Year, ignore durationFilter so the
     // two ranges don't conflict (e.g. "current month" + April would always 0).
     const hasMonthYear = ( req.body.monthFilter && String( req.body.monthFilter ) !== '' ) || ( req.body.yearFilter && String( req.body.yearFilter ) !== '' );
@@ -610,8 +657,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 !== '' ) {
@@ -631,6 +684,76 @@ export async function latestDailyPricing( req, res ) {
       } );
     }
 
+    // Per-product price (basepricing) + month length, used to prorate the
+    // invoice amount: (price / daysInMonth) * workingDays. Computed once here so
+    // BOTH the export and the on-screen table use the same numbers.
+    const priceByProduct = {};
+    let bpCurrency = 'inr';
+    try {
+      const bp = await basePriceService.findOne(
+          { clientId: req.body.clientId },
+          { standard: 1, currency: 1 },
+      );
+      bpCurrency = bp?.currency || 'inr';
+      for ( const p of ( bp?.standard || [] ) ) {
+        const price = Number( p.negotiatePrice ) || Number( p.basePrice ) || 0;
+        if ( p.productName ) {
+          priceByProduct[p.productName] = price;
+        }
+      }
+    } catch ( bpErr ) {
+      logger.error( { error: bpErr, function: 'latestDailyPricing.basePrice', clientId: req.body.clientId } );
+    }
+    // Billing type per product (perStore / perZone / perCamera) from the client
+    // plan — drives whether the amount multiplies by camera/zone count.
+    const billingTypeByProduct = {};
+    try {
+      const planClient = await clientService.findOne(
+          { clientId: req.body.clientId },
+          { 'planDetails.product.productName': 1, 'planDetails.product.billingType': 1 },
+      );
+      for ( const p of ( planClient?.planDetails?.product || [] ) ) {
+        if ( p.productName ) {
+          billingTypeByProduct[p.productName] = p.billingType || 'perStore';
+        }
+      }
+    } catch ( btErr ) {
+      logger.error( { error: btErr, function: 'latestDailyPricing.billingType', clientId: req.body.clientId } );
+    }
+    const daysInMonth = dayjs( record.dateISO ).daysInMonth();
+    const prettyProduct = ( name ) => String( name || '' )
+        .replace( /^tango/i, '' )
+        .replace( /([a-z])([A-Z])/g, '$1 $2' )
+        .replace( /^./, ( ch ) => ch.toUpperCase() );
+    // Units to bill: perZone/perCamera multiply by the store's zone/camera
+    // count (same rule as invoice generation + the annexure); else per-store=1.
+    const productUnits = ( store, product ) => {
+      const billingType = billingTypeByProduct[product.productName] || 'perStore';
+      if ( product.productName === 'tangoZone' ) {
+        if ( billingType === 'perZone' && ( store.zoneCount || 0 ) > 0 ) {
+          return store.zoneCount;
+        }
+        if ( billingType === 'perCamera' && ( store.zoneCameraCount || 0 ) > 0 ) {
+          return store.zoneCameraCount;
+        }
+      } else if ( product.productName === 'tangoTraffic' ) {
+        if ( billingType === 'perCamera' && ( store.trafficCameraCount || 0 ) > 0 ) {
+          return store.trafficCameraCount;
+        }
+      }
+      return 1;
+    };
+    const productInvoiceAmount = ( store, product ) => {
+      const price = priceByProduct[product.productName] || 0;
+      const workingDays = Number( product.workingdays ) || 0;
+      if ( price <= 0 || workingDays <= 0 ) {
+        return 0;
+      }
+      const units = productUnits( store, product );
+      const days = Math.min( workingDays, daysInMonth );
+      return Math.round( ( ( price / daysInMonth ) * days * units ) * 100 ) / 100;
+    };
+
     if ( req.body.export ) {
       const exportdata = [];
       stores.forEach( ( store ) => {
@@ -651,6 +774,7 @@ export async function latestDailyPricing( req, res ) {
               'Zone Camera Count': isZone ? ( store.zoneCameraCount || 0 ) : 0,
               'Zone Count': isZone ? ( store.zoneCount || 0 ) : 0,
               'Working Days': product.workingdays || 0,
+              'Invoice Amount': productInvoiceAmount( store, product ),
               'Status': store.status || '',
             } );
           } );
@@ -665,6 +789,7 @@ export async function latestDailyPricing( req, res ) {
             'Zone Camera Count': 0,
             'Zone Count': 0,
             'Working Days': 0,
+            'Invoice Amount': 0,
             'Status': store.status || '',
           } );
         }
@@ -679,6 +804,34 @@ export async function latestDailyPricing( req, res ) {
       storeList = stores.slice( skip, skip + Number( req.body.limit ) );
     }
 
+    // Invoice Amount per store: prorate each product by the days it ran this
+    // month — (price / daysInMonth) * workingDays — summed across the store's
+    // products, plus a per-product breakdown for the UI. Uses the shared
+    // priceByProduct / daysInMonth / productInvoiceAmount computed above.
+    storeList = storeList.map( ( store ) => {
+      let invoiceAmount = 0;
+      const invoiceBreakdown = [];
+      for ( const product of ( store.products || [] ) ) {
+        const amount = productInvoiceAmount( store, product );
+        invoiceAmount += amount;
+        // One breakdown row per product on the store (so the UI can show
+        // Traffic: ₹x, Zone: ₹y …).
+        invoiceBreakdown.push( {
+          productName: product.productName,
+          label: prettyProduct( product.productName ),
+          price: priceByProduct[product.productName] || 0,
+          workingDays: Number( product.workingdays ) || 0,
+          amount,
+        } );
+      }
+      return {
+        ...( store._doc || store ),
+        invoiceAmount: Math.round( invoiceAmount * 100 ) / 100,
+        invoiceBreakdown,
+        invoiceCurrency: bpCurrency,
+      };
+    } );
+
     // Monthly Billing Summary — one row per month of the brand's invoice
     // history (stores billed + invoice amount), newest first. The UI tags the
     // current/last-generated rows and computes month-over-month deltas.
@@ -1573,6 +1726,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 +1951,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

@@ -286,6 +286,12 @@ export const subscribedStoreListBody = joi.object( {
   state: joi.array().optional(),
   city: joi.array().optional(),
   getFilters: joi.boolean().optional(),
+  // Storeids selected in the group being edited — backend floats them to the
+  // top (selected-first ordering across pages).
+  selectedStoreIds: joi.array().items( joi.string() ).optional(),
+  // Group being edited — backend resolves its selected stores and tags each
+  // returned store with isSelected (drives checkbox + selected-first order).
+  groupId: joi.string().optional().allow( '' ),
 } );
 
 export const subscribedStoreListSchema = {
@@ -329,6 +335,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 +375,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 +409,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(),
 } );
 

package/src/routes/brandsBilling.routes.js

@@ -6,12 +6,12 @@ import { isAllowedSessionHandler, accessVerification } from 'tango-app-api-middl
 export const brandsBillingRouter = express.Router();
 
 brandsBillingRouter.post( '/brandsBillingList', isAllowedSessionHandler, accessVerification( { userType: [ 'tango' ], access: [ { featureName: 'TangoAdmin', name: 'invoiceApproval', permissions: [] } ] } ), brandsBillingList );
-brandsBillingRouter.post( '/brandInvoiceList', isAllowedSessionHandler, accessVerification( { userType: [ 'tango' ], access: [ { featureName: 'TangoAdmin', name: 'invoiceApproval', permissions: [] } ] } ), brandInvoiceList );
+brandsBillingRouter.post( '/brandInvoiceList', isAllowedSessionHandler, accessVerification( { userType: [ 'tango', 'client' ], access: [ ] } ), brandInvoiceList );
 brandsBillingRouter.post( '/latestDailyPricing', isAllowedSessionHandler, accessVerification( { userType: [ 'tango' ], access: [ { featureName: 'TangoAdmin', name: 'invoiceApproval', permissions: [] } ] } ), latestDailyPricing );
 brandsBillingRouter.post( '/brandBillingGroups', isAllowedSessionHandler, accessVerification( { userType: [ 'tango' ], access: [ { featureName: 'TangoAdmin', name: 'invoiceApproval', permissions: [] } ] } ), brandBillingGroups );
 brandsBillingRouter.put( '/updateDailyPricingWorkingDays', isAllowedSessionHandler, accessVerification( { userType: [ 'tango' ], access: [ { featureName: 'TangoAdmin', name: 'invoiceApproval', permissions: [ 'isEdit' ] } ] } ), updateDailyPricingWorkingDays );
 brandsBillingRouter.put( '/updateDailyPricingStoreField', isAllowedSessionHandler, accessVerification( { userType: [ 'tango' ], access: [ { featureName: 'TangoAdmin', name: 'invoiceApproval', permissions: [ 'isEdit' ] } ] } ), updateDailyPricingStoreField );
-brandsBillingRouter.post( '/getClientBillingInfo', isAllowedSessionHandler, accessVerification( { userType: [ 'tango' ], access: [ { featureName: 'TangoAdmin', name: 'invoiceApproval', permissions: [] } ] } ), getClientBillingInfo );
+brandsBillingRouter.post( '/getClientBillingInfo', isAllowedSessionHandler, accessVerification( { userType: [ 'tango', 'client' ], access: [ { featureName: 'TangoAdmin', name: 'invoiceApproval', permissions: [] } ] } ), getClientBillingInfo );
 brandsBillingRouter.get( '/bulk-download-billing-groups', isAllowedSessionHandler, accessVerification( { userType: [ 'tango' ], access: [ { featureName: 'TangoAdmin', name: 'invoiceApproval', permissions: [ 'isEdit' ] } ] } ), bulkDownloadBillingGroups );
 brandsBillingRouter.post( '/bulk-update-billing-groups', isAllowedSessionHandler, accessVerification( { userType: [ 'tango' ], access: [ { featureName: 'TangoAdmin', name: 'invoiceApproval', permissions: [ 'isEdit' ] } ] } ), bulkUpdateBillingGroups );
 brandsBillingRouter.post( '/billingSummary', isAllowedSessionHandler, accessVerification( { userType: [ 'tango' ], access: [ { featureName: 'TangoAdmin', name: 'invoiceApproval', permissions: [] } ] } ), billingSummary );

package/src/routes/invoice.routes.js

@@ -21,11 +21,11 @@ function superadminBypass( accessConfig ) {
 }
 
 
-invoiceRouter.post( '/createInvoice', isAllowedSessionHandler, createInvoice );
-invoiceRouter.post( '/regerateInvoice', isAllowedSessionHandler, createInvoice );
+invoiceRouter.post( '/createInvoice', isAllowedSessionHandler, superadminBypass( { userType: [ 'tango' ], access: [ { featureName: 'TangoAdmin', name: 'invoiceApproval', permissions: [ 'isEdit' ] } ] } ), createInvoice );
+invoiceRouter.post( '/regerateInvoice', isAllowedSessionHandler, superadminBypass( { userType: [ 'tango' ], access: [ { featureName: 'TangoAdmin', name: 'invoiceApproval', permissions: [ 'isEdit' ] } ] } ), createInvoice );
 invoiceRouter.post( '/invoiceDownload/bulk', isAllowedSessionHandler, accessVerification( { userType: [ 'tango' ], access: [ { featureName: 'TangoAdmin', name: 'invoiceApproval', permissions: [] } ] } ), invoiceDownloadBulk );
 invoiceRouter.post( '/invoiceDownload/:invoiceId', isAllowedSessionHandler, invoiceDownload );
-invoiceRouter.post( '/clientInvoiceList', isAllowedSessionHandler, accessVerification( { userType: [ 'tango' ], access: [ { featureName: 'TangoAdmin', name: 'invoiceApproval', permissions: [] } ] } ), clientInvoiceList );
+invoiceRouter.post( '/clientInvoiceList', isAllowedSessionHandler, accessVerification( { userType: [ 'tango', 'client' ], access: [ { featureName: 'TangoAdmin', name: 'invoiceApproval', permissions: [] } ] } ), clientInvoiceList );
 invoiceRouter.post( '/creditTransactionlist', isAllowedSessionHandler, accessVerification( { userType: [ 'tango' ], access: [ { featureName: 'TangoAdmin', name: 'invoiceApproval', permissions: [] } ] } ), creditTransactionlist );
 invoiceRouter.post( '/pendingInvoices', isAllowedSessionHandler, pendingInvoices );
 invoiceRouter.post( '/applyDiscount', isAllowedSessionHandler, superadminBypass( { userType: [ 'tango' ], access: [ { featureName: 'TangoAdmin', name: 'invoiceApproval', permissions: [ 'isEdit' ] } ] } ), applyDiscount );
@@ -33,9 +33,9 @@ invoiceRouter.post( '/migrateInvoice', migrateInvoice );
 invoiceRouter.post( '/PaymentStatusChange', isAllowedSessionHandler, superadminBypass( { userType: [ 'tango' ], access: [ { featureName: 'TangoAdmin', name: 'invoiceApproval', permissions: [ 'isEdit' ] } ] } ), PaymentStatusChange );
 invoiceRouter.post( '/recordPayment', isAllowedSessionHandler, superadminBypass( { userType: [ 'tango' ], access: [ { featureName: 'TangoAdmin', name: 'invoiceApproval', permissions: [ 'isEdit' ] } ] } ), recordPayment );
 invoiceRouter.post( '/checkPaymentStatus', checkPaymentStatus );
-invoiceRouter.get( '/getInvoice/:invoiceId', isAllowedSessionHandler, superadminBypass( { userType: [ 'tango' ], access: [ { featureName: 'TangoAdmin', name: 'invoiceApproval', permissions: [] } ] } ), getInvoice );
-invoiceRouter.get( '/invoiceAnnexure/:invoiceId', isAllowedSessionHandler, superadminBypass( { userType: [ 'tango' ], access: [ { featureName: 'TangoAdmin', name: 'invoiceApproval', permissions: [] } ] } ), invoiceAnnexure );
-invoiceRouter.get( '/invoiceBankDetails/:invoiceId', isAllowedSessionHandler, superadminBypass( { userType: [ 'tango' ], access: [ { featureName: 'TangoAdmin', name: 'invoiceApproval', permissions: [] } ] } ), invoiceBankDetails );
+invoiceRouter.get( '/getInvoice/:invoiceId', isAllowedSessionHandler, superadminBypass( { userType: [ 'tango', 'client' ], access: [ ] } ), getInvoice );
+invoiceRouter.get( '/invoiceAnnexure/:invoiceId', isAllowedSessionHandler, superadminBypass( { userType: [ 'tango', 'client' ], access: [ { featureName: 'TangoAdmin', name: 'invoiceApproval', permissions: [] } ] } ), invoiceAnnexure );
+invoiceRouter.get( '/invoiceBankDetails/:invoiceId', isAllowedSessionHandler, superadminBypass( { userType: [ 'tango', 'client' ], access: [ { featureName: 'TangoAdmin', name: 'invoiceApproval', permissions: [] } ] } ), invoiceBankDetails );
 invoiceRouter.put( '/updateInvoice', isAllowedSessionHandler, superadminBypass( { userType: [ 'tango' ], access: [ { featureName: 'TangoAdmin', name: 'invoiceApproval', permissions: [ 'isEdit' ] } ] } ), updateInvoice );
 invoiceRouter.get( '/getClientBasePricing/:clientId', isAllowedSessionHandler, getClientBasePricing );
 invoiceRouter.delete( '/deleteInvoice/:invoiceId', isAllowedSessionHandler, superadminBypass( { userType: [ 'tango' ], access: [ { featureName: 'TangoAdmin', name: 'invoiceApproval', permissions: [ 'isEdit' ] } ] } ), deleteInvoice );