tango-app-api-payment-subscription 3.4.4 → 3.5.1

package/src/controllers/brandsBilling.controller.js

@@ -2,8 +2,12 @@ import * as clientService from '../services/clientPayment.services.js';
 import * as invoiceService from '../services/invoice.service.js';
 import * as billingService from '../services/billing.service.js';
 import * as dailyPriceService from '../services/dailyPrice.service.js';
+import * as storeService from '../services/store.service.js';
 import dayjs from 'dayjs';
 import { logger, checkFileExist, signedUrl, download, insertOpenSearchData } from 'tango-app-api-middleware';
+import * as XLSX from 'xlsx';
+import ExcelJS from 'exceljs';
+import { bulkUpdateBillingGroupRowSchema } from '../dtos/validation.dtos.js';
 
 export async function brandsBillingList( req, res ) {
   try {
@@ -227,7 +231,10 @@ export async function brandInvoiceList( req, res ) {
       },
     } ];
 
-    if ( req.body.durationFilter && req.body.durationFilter !== '' ) {
+    // 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 ) !== '' );
+    if ( !hasMonthYear && req.body.durationFilter && req.body.durationFilter !== '' ) {
       let dateFrom;
       const now = dayjs();
       if ( req.body.durationFilter === 'current' ) {
@@ -244,6 +251,30 @@ export async function brandInvoiceList( req, res ) {
       }
     }
 
+    // Month / Year filters (independent of durationFilter). Both are 1-based:
+    // monthFilter '1'..'12', yearFilter four-digit string like '2026'.
+    // billingDate may be stored as Date OR as a string in some legacy rows, so
+    // coerce to date inside the pipeline before $year/$month.
+    const monthNum = req.body.monthFilter ? parseInt( req.body.monthFilter, 10 ) : null;
+    const yearNum = req.body.yearFilter ? parseInt( req.body.yearFilter, 10 ) : null;
+    if ( ( monthNum && monthNum >= 1 && monthNum <= 12 ) || yearNum ) {
+      const billingDateExpr = {
+        $cond: [
+          { $eq: [ { $type: '$billingDate' }, 'date' ] },
+          '$billingDate',
+          { $toDate: '$billingDate' },
+        ],
+      };
+      const expr = { $and: [] };
+      if ( yearNum ) {
+        expr.$and.push( { $eq: [ { $year: billingDateExpr }, yearNum ] } );
+      }
+      if ( monthNum && monthNum >= 1 && monthNum <= 12 ) {
+        expr.$and.push( { $eq: [ { $month: billingDateExpr }, monthNum ] } );
+      }
+      query.push( { $match: { $expr: expr } } );
+    }
+
     if ( req.body.paymentStatus && req.body.paymentStatus.length > 0 ) {
       query.push( {
         $match: {
@@ -269,13 +300,23 @@ export async function brandInvoiceList( req, res ) {
               {
                 $match: {
                   $expr: {
-                    $eq: [ '$_id', '$$groupId' ],
+                    $eq: [
+                      '$_id',
+                      {
+                        $cond: [
+                          { $eq: [ { $type: '$$groupId' }, 'objectId' ] },
+                          '$$groupId',
+                          { $convert: { input: '$$groupId', to: 'objectId', onError: null, onNull: null } },
+                        ],
+                      },
+                    ],
                   },
                 },
               },
               {
                 $project: {
                   groupName: 1,
+                  registeredCompanyName: 1,
                   stores: { $size: { $ifNull: [ '$stores', [] ] } },
                 },
               },
@@ -303,6 +344,7 @@ export async function brandInvoiceList( req, res ) {
             dueDate: 1,
             products: 1,
             billingGroupStores: '$billingGroup.stores',
+            registeredCompanyName: '$billingGroup.registeredCompanyName',
           },
         },
     );
@@ -335,7 +377,7 @@ export async function brandInvoiceList( req, res ) {
     let summary = {
       totalInvoices: allInvoices.length,
       totalInvoiced: allInvoices.reduce( ( sum, inv ) => sum + ( inv.totalAmount || 0 ), 0 ),
-      pendingApproval: allInvoices.filter( ( inv ) => inv.status === 'pending' ).length,
+      pendingApproval: allInvoices.filter( ( inv ) => [ 'pendingCsm', 'pendingFinance', 'pendingApproval' ].includes( inv.status ) ).length,
       pendingPayment: allInvoices.filter( ( inv ) => inv.paymentStatus === 'unpaid' && inv.status === 'approved' ).length,
       paid: allInvoices.filter( ( inv ) => inv.paymentStatus === 'paid' ).length,
     };
@@ -350,7 +392,7 @@ export async function brandInvoiceList( req, res ) {
           'Generated': dayjs( element.billingDate ).format( 'DD MMM YYYY' ),
           'No of Stores': element.stores,
           'Amount': element.totalAmount,
-          'Status': element.status === 'pending' ? 'Pending Approval' : element.paymentStatus === 'unpaid' ? 'Pending Payment' : 'Paid',
+          'Status': [ 'pendingCsm', 'pendingFinance', 'pendingApproval' ].includes( element.status ) ? 'Pending Approval' : element.paymentStatus === 'unpaid' ? 'Pending Payment' : 'Paid',
         } );
       } );
       await download( exportdata, res );
@@ -706,3 +748,519 @@ export async function getClientBillingInfo( req, res ) {
     return res.sendError( error, 500 );
   }
 }
+
+const COLUMN_HEADERS = [
+  'Group Name',
+  'Group Tag',
+  'Registered Company Name',
+  'GST',
+  'Address Line 1',
+  'Address Line 2',
+  'City',
+  'State',
+  'Country',
+  'Pin Code',
+  'Place Of Supply (read-only)',
+  'PO #',
+  'Pro-Rata',
+  'Payment Category',
+  'Currency',
+  'Payment Cycle',
+  'Payment Term (days)',
+  'Installation Fee',
+  'Is Installation One-Time',
+  'Attach Annexure',
+  'Advance Invoice',
+  'Store ID',
+  'Store Name (read-only)',
+];
+
+const COLUMN_WIDTHS = [
+  22, 12, 28, 18, 22, 22, 16, 16, 16, 12, 22, 14, 14, 18, 12, 16, 18, 16, 22, 18, 16, 16, 28,
+];
+
+// GSTIN state-code prefix → Place of Supply (mirrors the UI map).
+const GST_STATE_CODE_MAP = {
+  '01': 'Jammu and Kashmir',
+  '02': 'Himachal Pradesh',
+  '03': 'Punjab',
+  '04': 'Chandigarh',
+  '05': 'Uttarakhand',
+  '06': 'Haryana',
+  '07': 'Delhi',
+  '08': 'Rajasthan',
+  '09': 'Uttar Pradesh',
+  '10': 'Bihar',
+  '11': 'Sikkim',
+  '12': 'Arunachal Pradesh',
+  '13': 'Nagaland',
+  '14': 'Manipur',
+  '15': 'Mizoram',
+  '16': 'Tripura',
+  '17': 'Meghalaya',
+  '18': 'Assam',
+  '19': 'West Bengal',
+  '20': 'Jharkhand',
+  '21': 'Odisha',
+  '22': 'Chhattisgarh',
+  '23': 'Madhya Pradesh',
+  '24': 'Gujarat',
+  '25': 'Daman and Diu',
+  '26': 'Dadra and Nagar Haveli and Daman and Diu',
+  '27': 'Maharashtra',
+  '28': 'Andhra Pradesh (Old)',
+  '29': 'Karnataka',
+  '30': 'Goa',
+  '31': 'Lakshadweep',
+  '32': 'Kerala',
+  '33': 'Tamil Nadu',
+  '34': 'Puducherry',
+  '35': 'Andaman and Nicobar Islands',
+  '36': 'Telangana',
+  '37': 'Andhra Pradesh',
+  '38': 'Ladakh',
+  '97': 'Other Territory',
+  '99': 'Centre Jurisdiction',
+};
+
+function placeOfSupplyFromGst( gst ) {
+  if ( !gst ) return '';
+  const code = String( gst ).trim().toUpperCase().substring( 0, 2 );
+  const state = GST_STATE_CODE_MAP[code];
+  return state ? `${state} (${code})` : '';
+}
+
+function boolToYesNo( v ) {
+  return v === true ? 'Yes' : 'No';
+}
+
+function yesNoToBool( v ) {
+  if ( typeof v === 'boolean' ) return v;
+  if ( v === undefined || v === null || v === '' ) return undefined;
+  const s = String( v ).trim().toLowerCase();
+  if ( [ 'yes', 'y', 'true', '1' ].includes( s ) ) return true;
+  if ( [ 'no', 'n', 'false', '0' ].includes( s ) ) return false;
+  return undefined;
+}
+
+function trimOrEmpty( v ) {
+  if ( v === undefined || v === null ) return '';
+  return String( v ).trim();
+}
+
+function numberOrUndefined( v ) {
+  if ( v === undefined || v === null || v === '' ) return undefined;
+  const n = Number( v );
+  return Number.isFinite( n ) ? n : NaN;
+}
+
+function normalizeRow( rawRow ) {
+  const gst = trimOrEmpty( rawRow['GST'] );
+  return {
+    groupName: trimOrEmpty( rawRow['Group Name'] ),
+    groupTag: trimOrEmpty( rawRow['Group Tag'] ),
+    registeredCompanyName: trimOrEmpty( rawRow['Registered Company Name'] ),
+    gst,
+    addressLineOne: trimOrEmpty( rawRow['Address Line 1'] ),
+    addressLineTwo: trimOrEmpty( rawRow['Address Line 2'] ),
+    city: trimOrEmpty( rawRow['City'] ),
+    state: trimOrEmpty( rawRow['State'] ),
+    country: trimOrEmpty( rawRow['Country'] ),
+    pinCode: trimOrEmpty( rawRow['Pin Code'] ),
+    // Place of Supply is derived from the GST prefix on the server, ignoring
+    // whatever the cell holds (the column is read-only in the template).
+    placeOfSupply: placeOfSupplyFromGst( gst ),
+    po: trimOrEmpty( rawRow['PO #'] ),
+    proRata: trimOrEmpty( rawRow['Pro-Rata'] ),
+    paymentCategory: trimOrEmpty( rawRow['Payment Category'] ),
+    currency: trimOrEmpty( rawRow['Currency'] ),
+    paymentCycle: trimOrEmpty( rawRow['Payment Cycle'] ),
+    paymentTerm: numberOrUndefined( rawRow['Payment Term (days)'] ),
+    installationFee: numberOrUndefined( rawRow['Installation Fee'] ),
+    isInstallationOneTime: yesNoToBool( rawRow['Is Installation One-Time'] ),
+    attachAnnexure: yesNoToBool( rawRow['Attach Annexure'] ),
+    advanceInvoice: yesNoToBool( rawRow['Advance Invoice'] ),
+    storeId: trimOrEmpty( rawRow['Store ID'] ),
+  };
+}
+
+export async function bulkDownloadBillingGroups( req, res ) {
+  try {
+    const clientId = req.query?.clientId;
+    if ( !clientId ) {
+      return res.sendError( 'clientId query parameter is required', 400 );
+    }
+
+    const groups = await billingService.aggregatebilling( [
+      { $match: { clientId } },
+      { $lookup: {
+        from: 'clientpayments',
+        localField: 'clientId',
+        foreignField: 'clientId',
+        as: '_client',
+      } },
+      { $unwind: { path: '$_client', preserveNullAndEmptyArrays: true } },
+      { $sort: { groupName: 1 } },
+    ] );
+
+    // Build storeId → storeName lookup for this brand so we can show the name
+    // alongside the (editable) store id in the template.
+    const allStoreIds = new Set();
+    groups.forEach( ( g ) => {
+      if ( Array.isArray( g.stores ) ) g.stores.forEach( ( sid ) => allStoreIds.add( String( sid ) ) );
+    } );
+    const storeDocs = allStoreIds.size > 0 ?
+        await storeService.find( { clientId, storeId: { $in: Array.from( allStoreIds ) } }, { storeId: 1, storeName: 1 } ) :
+        [];
+    const storeNameById = new Map( storeDocs.map( ( s ) => [ String( s.storeId ), s.storeName || '' ] ) );
+
+    // Emit one row per store; group columns repeat. Groups with no stores
+    // still produce a single row (with empty store fields) so the user can
+    // see the group and add stores by editing the Store ID cell.
+    const rows = [];
+    for ( const g of groups ) {
+      const groupBase = {
+        [COLUMN_HEADERS[0]]: g.groupName || '',
+        [COLUMN_HEADERS[1]]: g.groupTag || '',
+        [COLUMN_HEADERS[2]]: g.registeredCompanyName || '',
+        [COLUMN_HEADERS[3]]: g.gst || '',
+        [COLUMN_HEADERS[4]]: g.addressLineOne || '',
+        [COLUMN_HEADERS[5]]: g.addressLineTwo || '',
+        [COLUMN_HEADERS[6]]: g.city || '',
+        [COLUMN_HEADERS[7]]: g.state || '',
+        [COLUMN_HEADERS[8]]: g.country || '',
+        [COLUMN_HEADERS[9]]: g.pinCode || '',
+        [COLUMN_HEADERS[10]]: g.placeOfSupply || placeOfSupplyFromGst( g.gst ),
+        [COLUMN_HEADERS[11]]: g.po || '',
+        [COLUMN_HEADERS[12]]: g.proRata || '',
+        [COLUMN_HEADERS[13]]: g.paymentCategory || '',
+        [COLUMN_HEADERS[14]]: g.currency || '',
+        [COLUMN_HEADERS[15]]: g.paymentCycle || '',
+        [COLUMN_HEADERS[16]]: g.paymentTerm ?? '',
+        [COLUMN_HEADERS[17]]: g.installationFee ?? '',
+        [COLUMN_HEADERS[18]]: boolToYesNo( g.isInstallationOneTime ),
+        [COLUMN_HEADERS[19]]: boolToYesNo( g.attachAnnexure ),
+        [COLUMN_HEADERS[20]]: boolToYesNo( g.advanceInvoice ),
+      };
+      const storeIds = Array.isArray( g.stores ) && g.stores.length > 0 ? g.stores : [ '' ];
+      for ( const sid of storeIds ) {
+        rows.push( {
+          ...groupBase,
+          [COLUMN_HEADERS[21]]: sid || '',
+          [COLUMN_HEADERS[22]]: sid ? ( storeNameById.get( String( sid ) ) || '' ) : '',
+        } );
+      }
+    }
+
+    // Build the workbook with ExcelJS so cell protection is actually written
+    // to the file (the community xlsx build strips per-cell styles on write).
+    // Read-only columns by index: 10 (Place Of Supply — derived from GST),
+    //                              22 (Store Name).
+    const READ_ONLY_COLS = new Set( [ 10, 22 ] );
+    const wb = new ExcelJS.Workbook();
+    const ws = wb.addWorksheet( 'Billing Groups' );
+    ws.columns = COLUMN_HEADERS.map( ( header, i ) => ( {
+      header,
+      key: `c${i}`,
+      width: COLUMN_WIDTHS[i],
+    } ) );
+    // Header row: bold, locked (cosmetic — protection blocks edits anyway).
+    ws.getRow( 1 ).font = { bold: true };
+    // Add data rows.
+    for ( const r of rows ) {
+      const values = {};
+      COLUMN_HEADERS.forEach( ( h, i ) => {
+        values[`c${i}`] = r[h];
+      } );
+      ws.addRow( values );
+    }
+    // Set per-cell protection on every cell (header + data).
+    // Note: ExcelJS defaults `locked: true`; we explicitly unlock editable cells.
+    const lastRow = ws.lastRow ? ws.lastRow.number : 1;
+    for ( let r = 1; r <= lastRow; r++ ) {
+      for ( let c = 1; c <= COLUMN_HEADERS.length; c++ ) {
+        const cell = ws.getCell( r, c );
+        cell.protection = { locked: READ_ONLY_COLS.has( c - 1 ) };
+      }
+    }
+    // Enable sheet protection with no password. Users can click
+    // Review → Unprotect Sheet to override (no password prompt).
+    await ws.protect( '', {
+      selectLockedCells: true,
+      selectUnlockedCells: true,
+      formatCells: false,
+      formatColumns: false,
+      formatRows: false,
+      insertColumns: false,
+      insertRows: false,
+      insertHyperlinks: false,
+      deleteColumns: false,
+      deleteRows: false,
+      sort: false,
+      autoFilter: false,
+      pivotTables: false,
+    } );
+    const buf = await wb.xlsx.writeBuffer();
+
+    const filename = `billing-groups-${dayjs().format( 'YYYY-MM-DD' )}.xlsx`;
+    res.set( 'Content-Type', 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet' );
+    res.set( 'Content-Disposition', `attachment; filename="${filename}"` );
+    return res.send( buf );
+  } catch ( error ) {
+    logger.error( { error: error, function: 'bulkDownloadBillingGroups' } );
+    return res.sendError( error, 500 );
+  }
+}
+
+export async function bulkUpdateBillingGroups( req, res ) {
+  try {
+    if ( !req.file?.buffer ) {
+      return res.sendError( 'No file uploaded', 400 );
+    }
+
+    const clientId = req.body?.clientId;
+    if ( !clientId ) {
+      return res.sendError( 'clientId form field is required', 400 );
+    }
+
+    let rawRows;
+    try {
+      const wb = XLSX.read( req.file.buffer, { type: 'buffer' } );
+      const sheet = wb.Sheets[wb.SheetNames[0]];
+      rawRows = XLSX.utils.sheet_to_json( sheet, { defval: '' } );
+    } catch ( parseErr ) {
+      logger.error( { error: parseErr, function: 'bulkUpdateBillingGroups.parse' } );
+      return res.sendError( 'Failed to parse XLSX file', 400 );
+    }
+
+    if ( !Array.isArray( rawRows ) || rawRows.length === 0 ) {
+      return res.sendError( 'Spreadsheet has no data rows', 400 );
+    }
+
+    // First pass: normalize + Joi-validate every row, collecting errors.
+    const normalized = [];
+    const errors = [];
+    for ( let i = 0; i < rawRows.length; i++ ) {
+      const rowNumber = i + 2; // header is row 1
+      const raw = rawRows[i];
+      const row = normalizeRow( raw );
+      const rowErrors = [];
+
+      // Coercion sanity (e.g. "abc" in a number column came back as NaN)
+      if ( Number.isNaN( row.paymentTerm ) ) {
+        rowErrors.push( 'Payment Term (days) must be a number' );
+        row.paymentTerm = undefined;
+      }
+      if ( Number.isNaN( row.installationFee ) ) {
+        rowErrors.push( 'Installation Fee must be a number' );
+        row.installationFee = undefined;
+      }
+
+      // Boolean cells that the user filled in but we couldn't parse → error (not silent skip).
+      const rawIsOneTime = trimOrEmpty( raw['Is Installation One-Time'] );
+      if ( rawIsOneTime !== '' && row.isInstallationOneTime === undefined ) {
+        rowErrors.push( 'Is Installation One-Time must be Yes or No' );
+      }
+      const rawAttachAnnexure = trimOrEmpty( raw['Attach Annexure'] );
+      if ( rawAttachAnnexure !== '' && row.attachAnnexure === undefined ) {
+        rowErrors.push( 'Attach Annexure must be Yes or No' );
+      }
+      const rawAdvanceInvoice = trimOrEmpty( raw['Advance Invoice'] );
+      if ( rawAdvanceInvoice !== '' && row.advanceInvoice === undefined ) {
+        rowErrors.push( 'Advance Invoice must be Yes or No' );
+      }
+
+      const { error: joiError } = bulkUpdateBillingGroupRowSchema.validate( row, { abortEarly: false, stripUnknown: true } );
+      if ( joiError ) {
+        for ( const d of joiError.details ) rowErrors.push( d.message );
+      }
+
+      if ( rowErrors.length > 0 ) {
+        errors.push( {
+          rowNumber,
+          groupName: row.groupName,
+          errors: rowErrors,
+        } );
+        normalized.push( null );
+        continue;
+      }
+      normalized.push( row );
+    }
+
+    // Second pass: resolve each unique Group Name to a DB _id within this brand.
+    const groupNamesToCheck = Array.from( new Set( normalized
+        .filter( ( r ) => r !== null )
+        .map( ( r ) => r.groupName ) ) );
+    const foundDocs = groupNamesToCheck.length > 0 ?
+        await billingService.find( { groupName: { $in: groupNamesToCheck }, clientId } ) :
+        [];
+    const idByGroupName = new Map( foundDocs.map( ( d ) => [ d.groupName, String( d._id ) ] ) );
+    for ( let i = 0; i < normalized.length; i++ ) {
+      const row = normalized[i];
+      if ( !row ) continue;
+      if ( !idByGroupName.has( row.groupName ) ) {
+        errors.push( {
+          rowNumber: i + 2,
+          groupName: row.groupName,
+          errors: [ `Billing group "${row.groupName}" not found for this brand` ],
+        } );
+        normalized[i] = null;
+      }
+    }
+
+    // Third pass: aggregate rows by Group Name. Each group's stores[] is the
+    // union of the Store ID cells across all of its rows. Group-level fields
+    // are taken from the FIRST row for that group.
+    const groupedByName = new Map(); // groupName → { _id, firstRowIndex, payload, storeIds: [] }
+    for ( let i = 0; i < normalized.length; i++ ) {
+      const row = normalized[i];
+      if ( !row ) continue;
+      const key = row.groupName;
+      // eslint-disable-next-line no-unused-vars
+      const { storeId, ...groupFields } = row;
+      if ( !groupedByName.has( key ) ) {
+        groupedByName.set( key, {
+          _id: idByGroupName.get( key ),
+          groupName: key,
+          firstRowIndex: i,
+          payload: groupFields,
+          storeIds: [],
+          storeIdSet: new Set(),
+        } );
+      }
+      const entry = groupedByName.get( key );
+      if ( storeId ) {
+        if ( entry.storeIdSet.has( storeId ) ) {
+          errors.push( {
+            rowNumber: i + 2,
+            groupName: key,
+            errors: [ `Store ID ${storeId} is listed more than once for this billing group` ],
+          } );
+          continue;
+        }
+        entry.storeIdSet.add( storeId );
+        entry.storeIds.push( storeId );
+      }
+    }
+
+    // Fourth pass: cross-group uniqueness — same Store ID may NOT appear in
+    // two different groups in the upload.
+    const storeIdToGroup = new Map(); // storeId → groupName
+    for ( const entry of groupedByName.values() ) {
+      for ( const sid of entry.storeIds ) {
+        if ( storeIdToGroup.has( sid ) && storeIdToGroup.get( sid ) !== entry.groupName ) {
+          errors.push( {
+            rowNumber: entry.firstRowIndex + 2,
+            groupName: entry.groupName,
+            errors: [ `Store ID ${sid} is assigned to another billing group in this upload ("${storeIdToGroup.get( sid )}")` ],
+          } );
+        } else {
+          storeIdToGroup.set( sid, entry.groupName );
+        }
+      }
+    }
+
+    // Fifth pass: store existence — every Store ID must exist for this clientId.
+    const allStoreIds = Array.from( storeIdToGroup.keys() );
+    const existingStoreDocs = allStoreIds.length > 0 ?
+        await storeService.find( { clientId, storeId: { $in: allStoreIds } }, { storeId: 1 } ) :
+        [];
+    const existingStoreIds = new Set( existingStoreDocs.map( ( s ) => String( s.storeId ) ) );
+    for ( const entry of groupedByName.values() ) {
+      const missing = entry.storeIds.filter( ( sid ) => !existingStoreIds.has( String( sid ) ) );
+      if ( missing.length > 0 ) {
+        errors.push( {
+          rowNumber: entry.firstRowIndex + 2,
+          groupName: entry.groupName,
+          errors: [ `Store ID${missing.length > 1 ? 's' : ''} ${missing.join( ', ' )} not found for this brand` ],
+        } );
+      }
+    }
+
+    // Sixth pass: cross-group conflict with OTHER existing groups in the DB.
+    // A store already assigned to a different billing group cannot be claimed
+    // by this upload.
+    const idsInUpload = Array.from( groupedByName.values() ).map( ( e ) => e._id );
+    if ( allStoreIds.length > 0 ) {
+      const conflictDocs = await billingService.find(
+          { clientId, stores: { $in: allStoreIds }, _id: { $nin: idsInUpload } },
+          { _id: 1, groupName: 1, stores: 1 },
+      );
+      for ( const doc of conflictDocs ) {
+        const conflictIds = ( doc.stores || [] ).filter( ( sid ) => allStoreIds.includes( String( sid ) ) );
+        for ( const sid of conflictIds ) {
+          const claimingGroupName = storeIdToGroup.get( String( sid ) );
+          const claimingEntry = groupedByName.get( claimingGroupName );
+          if ( claimingEntry ) {
+            errors.push( {
+              rowNumber: claimingEntry.firstRowIndex + 2,
+              groupName: claimingEntry.groupName,
+              errors: [ `Store ID ${sid} is already assigned to billing group "${doc.groupName}"` ],
+            } );
+          }
+        }
+      }
+    }
+
+    if ( errors.length > 0 ) {
+      errors.sort( ( a, b ) => a.rowNumber - b.rowNumber );
+      return res.sendError(
+          { summary: { total: rawRows.length, failed: errors.length }, errors },
+          422,
+      );
+    }
+
+    const openSearchActivityLog = JSON.parse( process.env.OPENSEARCH ).activityLog;
+
+    // Seventh pass: serial DB writes — one per billing group.
+    let updated = 0;
+    let aborted = null;
+    for ( const entry of groupedByName.values() ) {
+      try {
+        await billingService.updateOne( { _id: entry._id }, { ...entry.payload, stores: entry.storeIds } );
+        updated++;
+        insertOpenSearchData( openSearchActivityLog, {
+          userName: req.user?.userName,
+          email: req.user?.email,
+          clientId,
+          logSubType: 'billingGroupUpdate',
+          logType: 'billing',
+          date: new Date(),
+          changes: [ `Billing group "${entry.groupName}" updated via bulk upload (stores=${entry.storeIds.length})` ],
+          eventType: '',
+          timestamp: new Date(),
+          showTo: [ 'tango' ],
+        } );
+      } catch ( writeErr ) {
+        logger.error( { error: writeErr, function: 'bulkUpdateBillingGroups.write', groupName: entry.groupName } );
+        aborted = { rowNumber: entry.firstRowIndex + 2, groupName: entry.groupName, message: writeErr?.message || String( writeErr ) };
+        break;
+      }
+    }
+
+    insertOpenSearchData( openSearchActivityLog, {
+      userName: req.user?.userName,
+      email: req.user?.email,
+      clientId: '',
+      logSubType: 'billingGroupBulkUpdate',
+      logType: 'billing',
+      date: new Date(),
+      changes: [ `Bulk billing-group update: ${updated} of ${groupedByName.size} groups updated by ${req.user?.email}` ],
+      eventType: '',
+      timestamp: new Date(),
+      showTo: [ 'tango' ],
+    } );
+
+    if ( aborted ) {
+      return res.sendError(
+          { summary: { total: groupedByName.size, updated, remaining: groupedByName.size - updated }, aborted },
+          207,
+      );
+    }
+
+    return res.sendSuccess( { summary: { total: groupedByName.size, updated } } );
+  } catch ( error ) {
+    logger.error( { error: error, function: 'bulkUpdateBillingGroups' } );
+    return res.sendError( error, 500 );
+  }
+}